@bnbagent/studio-cli 0.0.6-alpha.1 → 0.0.6-alpha.3

package/dist/bag.js

@@ -2,6 +2,8 @@
 import {
   B402_RUNTIME_KEYS,
   CliExit,
+  DEFAULT_B402_PRICE_USD,
+  DEFAULT_B402_TESTNET_BASE_URL,
   act,
   agentcoreFlavor,
   b402Credentials,
@@ -18,7 +20,9 @@ import {
   hasA2aFace,
   hasMcpFace,
   hasX402Face,
+  isB402TestnetBaseUrl,
   nativeProtocolOf,
+  normalizeB402PriceUsd,
   normalizeProtocolFaces,
   printErr,
   printOut,
@@ -34,8 +38,11 @@ import {
   trialFromDeployCliJson,
   whichBin,
   withDeployFiles,
-  x402DeploySummary
-} from "./chunk-M3ODFCA7.js";
+  x402DeploySummary,
+  x402SellerIsFree,
+  x402SellerPricingState,
+  x402SellerUsesB402
+} from "./chunk-A7NAGZHR.js";
 import {
   TWAK_CLI_MIN_VERSION,
   TWAK_CLI_VERSION,
@@ -97,7 +104,7 @@ import {
 var CAMPAIGN_DOC_URL = "https://www.bnbchain.org/en/blog/bnb-agent-studio-is-live-on-bnb-chain-ai-agents-from-one-prompt";
 var CAMPAIGN_CHECK_TIMEOUT_MS = 6e3;
 async function fetchCampaignActive() {
-  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-N6TPN6XA.js");
+  const { bnbPlatformApiUrl: bnbPlatformApiUrl2 } = await import("./deployCli-264UE6KB.js");
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), CAMPAIGN_CHECK_TIMEOUT_MS);
   try {
@@ -2095,6 +2102,77 @@ function devPortInUse(port = 9e3, timeoutMs = 250) {
   });
 }
 
+// src/cli/_erc8183Config.ts
+var ERC8183_ADDRESS_OVERRIDE_KEYS = [
+  "ERC8183_COMMERCE_ADDRESS",
+  "ERC8183_ROUTER_ADDRESS",
+  "ERC8183_POLICY_ADDRESS"
+];
+var MAX_UINT256 = 2n ** 256n - 1n;
+function erc8183PricingState(pay) {
+  const priceRaw = pay.price;
+  const price = String(priceRaw ?? "").trim();
+  if (!price) return { kind: "unset" };
+  if (typeof priceRaw !== "string") {
+    return { kind: "invalid", field: "price", value: price };
+  }
+  const minRaw = pay.min_price;
+  const maxRaw = pay.max_price;
+  const minPrice = String(minRaw ?? "").trim() || "0";
+  const maxPrice = String(maxRaw ?? "").trim();
+  if (minRaw !== void 0 && typeof minRaw !== "string") {
+    return { kind: "invalid", field: "min_price", value: minPrice };
+  }
+  if (maxRaw !== void 0 && typeof maxRaw !== "string") {
+    return { kind: "invalid", field: "max_price", value: maxPrice };
+  }
+  for (const [field, value] of [
+    ["price", price],
+    ["min_price", minPrice],
+    ["max_price", maxPrice]
+  ]) {
+    if ((field !== "max_price" || value !== "") && !/^\d+$/.test(value)) {
+      return { kind: "invalid", field, value };
+    }
+  }
+  const list = BigInt(price);
+  const min = BigInt(minPrice);
+  const max = maxPrice ? BigInt(maxPrice) : MAX_UINT256;
+  if (list > MAX_UINT256 || min > MAX_UINT256 || max > MAX_UINT256) {
+    const [field, value] = list > MAX_UINT256 ? ["price", price] : min > MAX_UINT256 ? ["min_price", minPrice] : ["max_price", maxPrice];
+    return { kind: "invalid", field, value };
+  }
+  const clampedToMax = list < max ? list : max;
+  const effective = min > clampedToMax ? min : clampedToMax;
+  const base = {
+    listPrice: list,
+    minPrice: min,
+    maxPrice: max,
+    effectivePrice: effective
+  };
+  if (list > 0n && effective === 0n) {
+    return { kind: "clamped_to_zero", ...base };
+  }
+  return { kind: effective === 0n ? "free" : "paid", ...base };
+}
+function erc8183ContractOverrideState(env = process.env) {
+  const present = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => Boolean(env[key]?.trim())
+  );
+  const missing = ERC8183_ADDRESS_OVERRIDE_KEYS.filter(
+    (key) => !env[key]?.trim()
+  );
+  const invalid = present.filter(
+    (key) => !/^0x[0-9a-fA-F]{40}$/.test(env[key]?.trim() ?? "")
+  );
+  return {
+    mode: present.length === 0 ? "canonical" : invalid.length > 0 ? "invalid" : missing.length === 0 ? "custom" : "partial",
+    present: [...present],
+    missing: [...missing],
+    invalid
+  };
+}
+
 // src/cli/config.ts
 var MAX_QUOTE_TTL_SECONDS = NegotiationHandler.MAX_QUOTE_TTL_SECONDS;
 function registerConfig(program) {
@@ -2273,6 +2351,38 @@ function validateKnownKey(parts, value) {
   }
   return null;
 }
+function isErc8183AmountKey(parts) {
+  return parts.length === 3 && parts[0] === "payments" && parts[1] === "erc8183" && ["price", "min_price", "max_price"].includes(parts[2]);
+}
+function isB402PriceKey(parts) {
+  return parts.length === 3 && parts[0] === "payments" && parts[1] === "x402_seller" && parts[2] === "price_usd";
+}
+function coerceKnownValue(parts, rawValue, typeFlag) {
+  if (!isErc8183AmountKey(parts) && !isB402PriceKey(parts)) {
+    return coerceValue(rawValue, typeFlag);
+  }
+  if (isB402PriceKey(parts)) {
+    if (typeFlag !== "auto" && typeFlag !== "string") {
+      throw new Error(
+        `${parts.join(".")} is stored as a decimal string; use --type string or omit --type.`
+      );
+    }
+    return normalizeB402PriceUsd(rawValue);
+  }
+  if (typeFlag !== "auto" && typeFlag !== "string") {
+    throw new Error(
+      `${parts.join(".")} is stored as a decimal string; use --type string or omit --type.`
+    );
+  }
+  const value = rawValue.trim();
+  const isUnboundedMax = parts[2] === "max_price" && value === "";
+  if (!isUnboundedMax && !/^\d+$/.test(value)) {
+    throw new Error(
+      `${parts.join(".")} must be a non-negative integer string in token base units; got ${JSON.stringify(rawValue)}.`
+    );
+  }
+  return value;
+}
 function setDottedKey(text2, parts, value) {
   const key = parts[parts.length - 1];
   const section = parts.slice(0, -1).join(".");
@@ -2347,7 +2457,7 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
   }
   let value;
   try {
-    value = coerceValue(rawValue, typeFlag);
+    value = coerceKnownValue(parts, rawValue, typeFlag);
   } catch (err) {
     printErr(`error: ${err instanceof Error ? err.message : String(err)}`);
     return 2;
@@ -2357,8 +2467,64 @@ async function cmdSet(key, rawValue, typeFlag, projectRoot) {
     printErr(`error: ${validationError}`);
     return 2;
   }
-  fs9.writeFileSync(tomlPath, setDottedKey(text2, parts, value), "utf-8");
+  const updatedText = setDottedKey(text2, parts, value);
+  fs9.writeFileSync(tomlPath, updatedText, "utf-8");
   printOut(`set ${key} = ${JSON.stringify(plainValue(value))}`);
+  if (parts.length === 3 && parts[0] === "payments" && parts[1] === "erc8183" && parts[2] === "price") {
+    const updated = parse4(updatedText);
+    const payments = updated.payments !== null && typeof updated.payments === "object" && !Array.isArray(updated.payments) ? updated.payments : {};
+    const erc = payments.erc8183 !== null && typeof payments.erc8183 === "object" && !Array.isArray(payments.erc8183) ? payments.erc8183 : {};
+    const pricing = erc8183PricingState(erc);
+    if (pricing.kind === "invalid" || pricing.kind === "unset") {
+      printErr(
+        "warning: price was saved, but existing min_price/max_price is invalid; run `bag doctor`."
+      );
+    }
+    if (pricing.kind === "free") {
+      printOut("pricing: FREE \u2014 buyers fund 0 token units; zero token escrow.");
+      const contracts = erc8183ContractOverrideState();
+      if (contracts.mode === "custom") {
+        printOut(
+          "ERC-8183 contracts: custom contract stack selected with all three address overrides."
+        );
+      } else if (contracts.mode === "partial") {
+        printErr(
+          `warning: ERC-8183 contract override is incomplete; set ${contracts.missing.join(", ")} before running a job.`
+        );
+      } else if (contracts.mode === "invalid") {
+        printErr(
+          `warning: invalid ERC-8183 address override(s): ${contracts.invalid.join(", ")}.`
+        );
+      } else {
+        printErr(
+          "warning: FREE requires a zero-price-compatible contract stack; set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together before deploy."
+        );
+      }
+    } else if (pricing.kind === "clamped_to_zero") {
+      printErr(
+        "warning: PAID list price is clamped to 0; this is not an explicit FREE choice. Fix max_price or set price to 0."
+      );
+    } else if (pricing.kind === "paid") {
+      printOut(
+        `pricing: PAID \u2014 effective price ${pricing.effectivePrice} token base units after clamping.`
+      );
+    }
+  }
+  if (isB402PriceKey(parts)) {
+    const pricing = x402SellerPricingState({ price_usd: value });
+    if (pricing.kind === "free") {
+      printOut(
+        "x402 pricing: FREE \u2014 B402 verify/settle is bypassed; no payment or settlement audit."
+      );
+      printErr(
+        "warning: /x402 is now an anonymous FREE endpoint. Confirm that unrestricted public access is intended."
+      );
+    } else if (pricing.kind === "paid") {
+      printOut(
+        `x402 pricing: PAID \u2014 $${pricing.priceUsd} per request through B402.`
+      );
+    }
+  }
   if (parts[0] === "network") {
     if (await devPortInUse(8080)) {
       printErr(
@@ -3033,6 +3199,9 @@ function packageRoot() {
   }
 }
 function pnpmVersion() {
+  if ("10.24.0") {
+    return "10.24.0";
+  }
   const file = path12.join(packageRoot(), "package.json");
   const pkg = JSON.parse(fs13.readFileSync(file, "utf-8"));
   const value = String(pkg.packageManager ?? "");
@@ -3061,6 +3230,46 @@ import * as fs14 from "fs";
 import * as path13 from "path";
 import { envLocalPath as envLocalPath7 } from "@bnbagent/studio-runtime/config";
 import { resolveTwakHome } from "@bnbagent/studio-runtime/wallet";
+
+// src/cli/_twakContractTargets.ts
+import { resolveNetwork } from "@bnbagent/sdk";
+var CONTRACT_OVERRIDES = [
+  ["ERC8004_REGISTRY_ADDRESS", "registryContract"],
+  ["ERC8183_COMMERCE_ADDRESS", "commerceContract"],
+  ["ERC8183_ROUTER_ADDRESS", "routerContract"],
+  ["ERC8183_POLICY_ADDRESS", "policyContract"]
+];
+function twakCustomContractOverrides(networkName, env = process.env) {
+  let network;
+  try {
+    network = resolveNetwork(networkName);
+  } catch {
+    return [];
+  }
+  const erc8183 = erc8183ContractOverrideState(env);
+  const out = [];
+  for (const [envKey, field] of CONTRACT_OVERRIDES) {
+    if (envKey.startsWith("ERC8183_") && erc8183.mode !== "custom") {
+      continue;
+    }
+    const configured = env[envKey]?.trim() ?? "";
+    if (!/^0x[0-9a-fA-F]{40}$/u.test(configured)) {
+      continue;
+    }
+    const canonical = network[field];
+    if (configured.toLowerCase() !== canonical.toLowerCase()) {
+      out.push({ envKey, configured, canonical });
+    }
+  }
+  return out;
+}
+function twakUnsupportedContractOverrides(networkName, env = process.env) {
+  return twakCustomContractOverrides(networkName, env).filter(
+    (item) => item.envKey.startsWith("ERC8183_")
+  );
+}
+
+// src/cli/_deploy/checks/twak.ts
 var AGENTCORE_DESCRIPTOR = path13.join("agentcore", "agentcore.json");
 function isTwak(data) {
   return tableOf2(data, "wallet").kind === "twak";
@@ -3165,6 +3374,26 @@ async function checkTwakCliPresent(root, _target) {
   }
   return [];
 }
+function checkTwakCustomContractsUnsupported(root, _target) {
+  const data = loadAgentToml(root);
+  if (!isTwak(data)) {
+    return [];
+  }
+  const networkName = String(tableOf2(data, "network").default ?? "bsc-testnet");
+  const overrides = twakUnsupportedContractOverrides(networkName);
+  if (overrides.length === 0) {
+    return [];
+  }
+  const keys = overrides.map((item) => item.envKey);
+  return [
+    {
+      level: Level.CRITICAL,
+      name: "twak_custom_contracts_unsupported",
+      message: `wallet.kind='twak' cannot use the selected custom ERC-8183 targets (${keys.join(", ")}): twak v0.20.0 has no Commerce/Router/Policy address option and would otherwise execute against the wrong canonical contracts. Use wallet.kind='evm-local' for custom ERC-8183 contracts, or remove the overrides and use the canonical stack. ERC8004_REGISTRY_ADDRESS is supported.`,
+      details: { network: networkName, override_keys: keys }
+    }
+  ];
+}
 async function checkTwakWalletExists(root, _target) {
   const data = loadAgentToml(root);
   if (!isTwak(data)) {
@@ -5197,7 +5426,9 @@ var LEGACY_SKILL_NAMES = [
 ];
 var ROUTER_SKILL_NAME = "bnbagent-studio";
 var META_FILENAME = ".bag-meta.json";
-var HIDDEN_SKILL_NAMES = /* @__PURE__ */ new Set();
+var HIDDEN_SKILL_NAMES = /* @__PURE__ */ new Set([
+  "bnbagent-studio-use-azure-foundry"
+]);
 function isDir3(p) {
   try {
     return fs19.statSync(p).isDirectory();
@@ -5603,6 +5834,19 @@ function installSkills(opts) {
   };
 }
 
+// src/cli/utils/options.ts
+import { InvalidArgumentError } from "commander";
+function acceptChoices(option, accepted, advertised) {
+  return option.argParser((value) => {
+    if (!accepted.includes(value)) {
+      throw new InvalidArgumentError(
+        `Allowed choices are ${advertised.join(", ")}.`
+      );
+    }
+    return value;
+  });
+}
+
 // src/cli/wallet.ts
 import * as fs21 from "fs";
 import * as path20 from "path";
@@ -6712,7 +6956,7 @@ var SUPPORTED_STORAGE_PROVIDERS = ["ipfs", "local"];
 var SUPPORTED_DESTINATIONS = ["self", "platform"];
 var RUNTIMES = {
   agentcore: { label: "AWS Bedrock AgentCore", hidden: false },
-  "azure-foundry": { label: "Azure AI Foundry", hidden: false }
+  "azure-foundry": { label: "Azure AI Foundry", hidden: true }
 };
 var SUPPORTED_RUNTIMES = Object.keys(RUNTIMES);
 var APP_DIR = "app";
@@ -6789,7 +7033,7 @@ every intent to the right playbook via its references.
    lives in \`src/signing.ts\`.
 4. **The quote path is deterministic** (fixed list price, clamp + sign).
    Never put an LLM in the quote path.
-5. **Deploy with \`bag deploy --provider bnb|aws|azure\`.** Every deploy or
+5. **Deploy with \`bag deploy --provider bnb|aws\`.** Every deploy or
    redeploy requires a visible provider choice. Studio runs its local business
    gates, then delegates cloud credentials, secrets, packaging and lifecycle
    calls to the pinned bnbagent-deploy CLI. Do not bypass this boundary with
@@ -6931,7 +7175,7 @@ function validateProjectName(basename16) {
   }
   if (safe !== basename16) {
     throw new Error(
-      `Project name '${basename16}' is not a valid AgentCore runtime name: the default runtime (AWS Bedrock AgentCore) requires ASCII letters and digits only ('-', '_', '.' and other characters are not allowed) \u2014 this is an AgentCore naming constraint, not a general bag restriction. Re-run with an alphanumeric name, e.g. \`bag init ${safe}\` \u2014 or, if this project is not for AgentCore, keep the original name on a runtime that allows it: \`bag init --runtime azure-foundry ${basename16}\`.`
+      `Project name '${basename16}' is not a valid AgentCore runtime name: the default runtime (AWS Bedrock AgentCore) requires ASCII letters and digits only ('-', '_', '.' and other characters are not allowed) \u2014 this is an AgentCore naming constraint, not a general bag restriction. Re-run with an alphanumeric name, e.g. \`bag init ${safe}\`.`
     );
   }
   return basename16;
@@ -6944,21 +7188,15 @@ function registerInit(program) {
     "<name>",
     "Project directory name (created in cwd). Becomes the AgentCore runtime name: ASCII alphanumerics only, must start with a letter, \u226423 chars. Names with '-'/'_'/'.' are rejected (not auto-renamed)."
   ).addOption(
-    new Option2(
-      "--runtime <name>",
-      `Runtime / deploy target to scaffold for (choices: ${visibleRuntimes.join(", ")}); recorded in studio.toml [stack].runtime.`
-    ).default("agentcore").choices(SUPPORTED_RUNTIMES)
-  ).addOption(
-    new Option2(
-      "--azure-account <name>",
-      "azure-foundry only: Azure AI Foundry account (resource) name used by the delegated deploy."
+    acceptChoices(
+      new Option2(
+        "--runtime <name>",
+        `Runtime / deploy target to scaffold for (choices: ${visibleRuntimes.join(", ")}); recorded in studio.toml [stack].runtime.`
+      ).default("agentcore"),
+      SUPPORTED_RUNTIMES,
+      visibleRuntimes
     )
-  ).addOption(
-    new Option2(
-      "--azure-project <name>",
-      "azure-foundry only: Azure AI Foundry project name used by the delegated deploy."
-    )
-  ).addOption(
+  ).addOption(new Option2("--azure-account <name>").hideHelp()).addOption(new Option2("--azure-project <name>").hideHelp()).addOption(
     new Option2(
       "--destination <dest>",
       "Where the agent deploys; recorded in studio.toml [deploy].destination (default: platform while the trial campaign runs; self once it has ended, or when a non-agentcore --runtime or --network bsc-mainnet is passed). 'platform' is a 48h testnet trial on the BNB Chain managed platform (forces runtime=agentcore + bsc-testnet; a trial wallet key is transmitted to the operator \u2014 run `bag wallet new` for a throwaway). 'self' deploys to YOUR own cloud."
@@ -6983,6 +7221,12 @@ function registerInit(program) {
       "--rails <rails>",
       "Commerce rail(s) to scaffold: 8183 (default), b402, or both."
     ).choices(["8183", "b402", "both"])
+  ).option(
+    "--erc8183-price <base-units>",
+    "ERC-8183 list price as a non-negative integer string in token base units. Use 0 for FREE. Default: 100000000000000000 (0.1 U)."
+  ).option(
+    "--b402-price <usd>",
+    "B402/x402 per-request price as a non-negative decimal USD string. Use 0 for FREE passthrough (no B402 verify/settle). Default: 0.01."
   ).addOption(
     new Option2(
       "--llm-provider <provider>",
@@ -7099,6 +7343,45 @@ async function cmdInit(nameArg, opts) {
     opts.llmProviderSource,
     isTty
   );
+  let rails = await resolveRails(opts.rails, isTty);
+  if (hasX402Face(faces) && rails === "8183") {
+    rails = "both";
+  } else if (hasX402Face(faces) && rails !== "both") {
+    rails = "b402";
+  }
+  if ((rails === "b402" || rails === "both") && !hasX402Face(faces)) {
+    faces = normalizeProtocolFaces([...faces, "X402"]);
+  }
+  if (opts.erc8183Price !== void 0 && rails === "b402") {
+    printErr(
+      "error: --erc8183-price requires the 8183 rail; use --rails 8183 or --rails both."
+    );
+    return 2;
+  }
+  if (opts.b402Price !== void 0 && rails === "8183") {
+    printErr(
+      "error: --b402-price requires the b402 rail; use --rails b402 or --rails both."
+    );
+    return 2;
+  }
+  let erc8183Price = DEFAULT_ERC8183_PRICE;
+  if (rails === "8183" || rails === "both") {
+    try {
+      erc8183Price = await resolveErc8183Price(opts.erc8183Price, isTty);
+    } catch (exc) {
+      printErr(`error: ${exc instanceof Error ? exc.message : exc}`);
+      return 2;
+    }
+  }
+  let b402Price = DEFAULT_B402_PRICE_USD;
+  if (rails === "b402" || rails === "both") {
+    try {
+      b402Price = await resolveB402Price(opts.b402Price, isTty);
+    } catch (exc) {
+      printErr(`error: ${exc instanceof Error ? exc.message : exc}`);
+      return 2;
+    }
+  }
   const enclosing = enclosingProjectRoot(path21.dirname(target));
   if (enclosing !== null) {
     printErr(
@@ -7196,16 +7479,7 @@ async function cmdInit(nameArg, opts) {
   }
   const budgetFlag = opts.enableAutoTopup ? "enable" : opts.autoTopup === false ? "disable" : null;
   const budgetChoice = walletKind2 === "altana" && llmProvider !== "pieverse-llm" && budgetFlag === null ? null : await resolveBudgetChoice(budgetFlag);
-  let rails = await resolveRails(opts.rails, isTty);
-  if (hasX402Face(faces) && rails === "8183") {
-    rails = "both";
-  } else if (hasX402Face(faces) && rails !== "both") {
-    rails = "b402";
-  }
-  if ((rails === "b402" || rails === "both") && !hasX402Face(faces)) {
-    faces = normalizeProtocolFaces([...faces, "X402"]);
-  }
-  if ((rails === "b402" || rails === "both") && !["evm-local", "twak"].includes(walletKind2)) {
+  if ((rails === "b402" || rails === "both") && x402SellerPricingState({ price_usd: b402Price }).kind === "paid" && !["evm-local", "twak"].includes(walletKind2)) {
     printErr(
       `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet. Re-run with --rails 8183 or a supported --wallet-kind.`
     );
@@ -7220,6 +7494,8 @@ async function cmdInit(nameArg, opts) {
       runtime,
       faces,
       rails,
+      erc8183Price,
+      b402Price,
       budgetChoice,
       ides,
       storageProvider: opts.storageProvider,
@@ -7318,8 +7594,9 @@ async function cmdInit(nameArg, opts) {
       "info: X402-only publishes only the /x402 gateway face; the native AgentCore A2A protocol declaration is suppressed from discovery."
     );
   } else if (faces.length === 1 && hasX402Face(faces) && destination === "self") {
+    const free = x402SellerPricingState({ price_usd: b402Price }).kind === "free";
     printErr(
-      "warning: X402-only uses an A2A-native AgentCore process internally, but exposes no public A2A face; the seller stays dormant until the B402 credentials are filled, and a self-hosted AgentCore target needs your own HTTP front to reach /x402."
+      free ? "warning: X402-only FREE mode uses an A2A-native AgentCore process internally, but exposes no public A2A face; a self-hosted AgentCore target still needs your own HTTP front to reach the anonymous /x402 passthrough." : "warning: X402-only uses an A2A-native AgentCore process internally, but exposes no public A2A face; the seller stays dormant until the B402 credentials are filled, and a self-hosted AgentCore target needs your own HTTP front to reach /x402."
     );
   }
   printConfigSummary(agentDir);
@@ -7379,9 +7656,10 @@ function derivePackaging(walletKind2, destination, platformArtifact2 = "zip", ru
   return "codezip";
 }
 function scaffold(target, name, o) {
+  const packageManagerVersion = pnpmVersion();
   fs22.writeFileSync(
     path21.join(target, "package.json"),
-    renderWorkspacePackageJson(name)
+    renderWorkspacePackageJson(name, packageManagerVersion)
   );
   fs22.writeFileSync(
     path21.join(target, "pnpm-workspace.yaml"),
@@ -7438,7 +7716,14 @@ function scaffold(target, name, o) {
   fs22.mkdirSync(path21.dirname(envLocal), { recursive: true });
   fs22.writeFileSync(
     envLocal,
-    renderAgentEnvLocal(o.provider, o.storageProvider, o.walletKind, o.rails)
+    renderAgentEnvLocal(
+      o.provider,
+      o.storageProvider,
+      o.walletKind,
+      o.rails,
+      o.b402Price,
+      o.network
+    )
   );
   fs22.writeFileSync(path21.join(agentRoot2, ".gitignore"), renderAgentGitignore());
   fs22.writeFileSync(
@@ -7458,7 +7743,7 @@ function scaffold(target, name, o) {
   const runtimeCtx = {
     PKG: AGENT_SRC,
     TWAK_CLI_VERSION,
-    PNPM_VERSION: pnpmVersion(),
+    PNPM_VERSION: packageManagerVersion,
     DEPLOYMENT_TYPE: isContainer ? "container" : "direct_code_deploy",
     ENTRYPOINT: o.runtime === "azure-foundry" ? a2aEntry : `dist/${stem2}.js`,
     // Foundry Hosted Agents have a provider-level container contract that is
@@ -7547,11 +7832,12 @@ ${deployLine}
 In Claude Code / Cursor, type \`/bnbagent-studio\` \u2014 the skill drives every step.
 `;
 }
-function renderWorkspacePackageJson(name) {
+function renderWorkspacePackageJson(name, packageManagerVersion) {
   return `${JSON.stringify(
     {
       name: `${name}-workspace`,
-      private: true
+      private: true,
+      packageManager: `pnpm@${packageManagerVersion}`
       // NOT a publishable package — the agent lives at app/agent (see
       // pnpm-workspace.yaml); this root only anchors the pnpm workspace.
     },
@@ -7755,14 +8041,14 @@ expected_recipient = ""
 allowed_hosts = ["llm.pieverse.io"]
 `;
 }
-function renderX402SellerSection() {
+function renderX402SellerSection(priceUsd) {
   return `
 [payments.x402_seller]
 # Public seller rail mounted at /x402. Credentials stay in
 # <workspace>/.studio/.env.local and are issued per B402 environment.
 enabled = true
-# Decimal USD string; "0" serves the work for free without a facilitator.
-price_usd = "0.01"
+# Decimal USD string; "0" is explicit FREE passthrough and bypasses B402.
+price_usd = "${priceUsd}"
 # v1 supports United Stables (U) through EIP-3009 only.
 assets = ["U"]
 # Empty means the agent wallet receives payment.
@@ -7817,7 +8103,7 @@ function renderAgentStudioToml(name, o) {
   const model = o.model ?? PROVIDER_DEFAULT_MODEL[o.provider] ?? "";
   const pieverseSection = o.provider === "pieverse-llm" ? renderPieverseSections() : "";
   const x402Section = o.provider === "pieverse-llm" ? renderX402Section() : "";
-  const x402SellerSection = o.rails === "b402" || o.rails === "both" || hasX402Face(o.faces) ? renderX402SellerSection() : "";
+  const x402SellerSection = o.rails === "b402" || o.rails === "both" || hasX402Face(o.faces) ? renderX402SellerSection(o.b402Price) : "";
   const budgetSection = renderBudgetSection(o.budgetChoice);
   const storageSection = renderAgentStorageSection(o.storageProvider);
   const azureSection = o.runtime === "azure-foundry" ? renderAzureSection(name, o.azureAccount, o.azureProject) : "";
@@ -7828,9 +8114,10 @@ function renderAgentStudioToml(name, o) {
 [payments.erc8183]
 # Read by the Agent: it quotes the FIXED \`price\`, CLAMPS it to [min,max],
 # freezes a short-TTL offer, and EIP-191 signs it \u2014 pricing is rule-based, the
-# LLM never prices.
+# LLM never prices. price=0 is FREE and needs a zero-price-compatible
+# ERC-8183 stack selected with all three ERC8183_*_ADDRESS overrides.
 currency = "${currencyAddr}"   # $U token address \u2014 prefilled from [network].default
-price = "100000000000000000"                   # wei \u2014 your list price (0.1 U); what every quote charges
+price = "${o.erc8183Price}"                    # token base units; 0 = FREE (zero token escrow)
 min_price = "0"                                # wei \u2014 clamp floor
 max_price = ""                                 # wei \u2014 clamp ceiling; SET before going live
 quote_ttl_seconds = 900                        # seconds a signed quote stays valid; SDK caps at 900 (~15min work window)
@@ -7868,7 +8155,7 @@ ${pieverseSection}${erc8183Section}
 ${storageSection}
 ${x402Section}${x402SellerSection}${budgetSection}${azureSection}`;
 }
-function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails) {
+function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails, b402Price, network) {
   const keyEnv = PROVIDER_KEY_ENV[provider];
   const lines = [
     "# \u26A0\uFE0F  SECRETS \u2014 do NOT paste this file into issue trackers, logs, or AI chats.",
@@ -7931,17 +8218,30 @@ function renderAgentEnvLocal(provider, storageProvider, walletKind2, rails) {
     );
   }
   if (rails === "b402" || rails === "both") {
+    const free = x402SellerPricingState({ price_usd: b402Price }).kind === "free";
+    const baseUrl = !free && network === "bsc-testnet" ? DEFAULT_B402_TESTNET_BASE_URL : "";
     lines.push(
       "",
       "# B402 merchant credentials (issued per environment after manual approval).",
-      "# All four absent = x402 rail dormant; partial = boot error naming the missing vars.",
-      "B402_BASE_URL=",
+      free ? "# FREE price 0 does not use these credentials; leave them empty until switching to PAID." : "# PAID requires all four; all absent = dormant, partial = boot error.",
+      `B402_BASE_URL=${baseUrl}`,
       "B402_CLIENT_ID=",
       "B402_ACCESS_TOKEN=",
       "B402_PRIVATE_KEY=",
       "# (alternative one-line PKCS#8 DER: B402_PRIVATE_KEY_B64=)"
     );
   }
+  if (rails === "8183" || rails === "both") {
+    lines.push(
+      "",
+      "# Optional ERC-8183 custom contract-stack override. Set all three",
+      "# together; partial overrides can mix incompatible deployments.",
+      "# Required for price=0 while canonical contracts reject zero funding.",
+      "# ERC8183_COMMERCE_ADDRESS=",
+      "# ERC8183_ROUTER_ADDRESS=",
+      "# ERC8183_POLICY_ADDRESS="
+    );
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -8183,6 +8483,69 @@ async function resolveRails(flagValue, isTty) {
   }
   return "8183";
 }
+var DEFAULT_ERC8183_PRICE = "100000000000000000";
+async function resolveErc8183Price(flagValue, isTty) {
+  if (flagValue !== void 0) {
+    const value = flagValue.trim();
+    if (!/^\d+$/.test(value)) {
+      throw new Error(
+        `--erc8183-price must be a non-negative integer string in token base units; got ${JSON.stringify(flagValue)}.`
+      );
+    }
+    return value;
+  }
+  if (!isTty) {
+    return DEFAULT_ERC8183_PRICE;
+  }
+  const choice = (await promptUser(
+    "ERC-8183 pricing [paid/free/custom, Enter = paid (0.1 U)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") {
+    return "0";
+  }
+  if (choice === "custom") {
+    const custom = (await promptUser(
+      "ERC-8183 list price in token base units (non-negative integer): "
+    )).trim();
+    if (!/^\d+$/.test(custom)) {
+      throw new Error(
+        `custom ERC-8183 price must be a non-negative integer string; got ${JSON.stringify(custom)}.`
+      );
+    }
+    return custom;
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(`hint: unknown ERC-8183 pricing choice '${choice}' \u2014 using paid.`);
+  }
+  return DEFAULT_ERC8183_PRICE;
+}
+async function resolveB402Price(flagValue, isTty) {
+  if (flagValue !== void 0) {
+    return normalizeB402PriceUsd(flagValue);
+  }
+  if (!isTty) {
+    return DEFAULT_B402_PRICE_USD;
+  }
+  const choice = (await promptUser(
+    "B402/x402 pricing [paid/free/custom, Enter = paid ($0.01)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") {
+    return "0";
+  }
+  if (choice === "custom") {
+    return normalizeB402PriceUsd(
+      await promptUser(
+        "B402/x402 per-request price in USD (non-negative decimal): "
+      )
+    );
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(
+      `hint: unknown B402/x402 pricing choice '${choice}' \u2014 using paid.`
+    );
+  }
+  return DEFAULT_B402_PRICE_USD;
+}
 async function promptPassword() {
   printOut("");
   printOut("Onboarding (TTY) \u2014 set a wallet password to finish in one go.");
@@ -8940,10 +9303,10 @@ function printNextSteps(name, provider, o = {}) {
     nextStep = 4;
   }
   printOut(
-    `  # ${nextStep}. set ERC-8183 pricing in studio.toml [payments.erc8183]`
+    `  # ${nextStep}. review ERC-8183 pricing in studio.toml [payments.erc8183]`
   );
   printOut(
-    "  #    (currency = $U token; price = list price in wei; min/max_price clamp before sign)"
+    "  #    (price was selected at init; `bag config set payments.erc8183.price 0` explicitly switches to FREE)"
   );
   nextStep += 1;
   printOut(`  # ${nextStep}. verify + run the agent locally`);
@@ -9011,13 +9374,26 @@ function printConfigSummary(agentRoot2) {
   const shown = (v, unset = "<unset \u2014 fill before going live>") => v === void 0 || v === null || v === "" ? unset : String(v);
   const table = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
   const faces = stackFaces(table(agent.stack), table(agent.payments));
+  const payments = table(agent.payments);
+  const erc8183 = table(payments.erc8183);
+  const x402Seller = table(payments.x402_seller);
+  const hasErc8183 = Object.keys(erc8183).length > 0;
+  const hasX402Seller = x402Seller.enabled === true;
+  const x402Pricing = x402SellerPricingState(x402Seller);
+  const isFreeX402 = hasX402Seller && x402Pricing.kind === "free";
+  const onlyX402 = hasX402Seller && !hasErc8183;
   const network = shown(g(agent, "network", "default"), "?");
   const provider = shown(g(agent, "llm", "provider"), "?");
   const model = shown(g(agent, "llm", "model"), "?");
   const modelTag = isFreeModel(String(model)) ? "Free, $0/token" : "paid \u2014 fund + topup to use";
   const currency = g(agent, "payments", "erc8183", "currency");
-  const price = shown(g(agent, "payments", "erc8183", "price"), "0");
+  const priceValue = g(agent, "payments", "erc8183", "price");
+  const price = shown(priceValue);
+  const minPrice = shown(g(agent, "payments", "erc8183", "min_price"), "0");
   const maxPrice = g(agent, "payments", "erc8183", "max_price");
+  const pricingState = erc8183PricingState(erc8183);
+  const isFreePrice = pricingState.kind === "free";
+  const contractOverrides = erc8183ContractOverrideState();
   const storageKind2 = shown(g(agent, "storage", "kind"), "?");
   const storageDesc = storageKind2 === "ipfs" ? "IPFS (durable, public)" : "local disk (offline dev only)";
   const walletKind2 = shown(g(agent, "wallet", "kind"), "evm-local");
@@ -9030,16 +9406,41 @@ function printConfigSummary(agentRoot2) {
   printOut("Your agent's configuration  (studio.toml, in plain language)");
   printOut(bar);
   printOut("");
-  printOut("Per task \u2014 how this seller earns $U:");
   printOut(
-    "  buyer negotiates \u2192 the Agent (sole signer) QUOTES a signed price \u2192"
-  );
-  printOut(
-    "  on payment the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
-  );
-  printOut(
-    "  after the dispute window, SETTLE releases the $U to your wallet."
+    onlyX402 && isFreeX402 ? "Per request \u2014 how this FREE x402 seller delivers work:" : onlyX402 ? "Per request \u2014 how this x402 seller earns $U:" : isFreePrice ? "Per task \u2014 how this FREE seller delivers work:" : "Per task \u2014 how this seller earns $U:"
   );
+  if (onlyX402 && isFreeX402) {
+    printOut(
+      "  anonymous request reaches /x402 \u2192 B402 verify/settle is bypassed \u2192"
+    );
+    printOut(
+      "  the Agent runs the work and returns the result with no payment."
+    );
+  } else if (onlyX402) {
+    printOut(
+      "  anonymous request receives a 402 challenge \u2192 B402 verifies and settles $U \u2192"
+    );
+    printOut("  the Agent runs the work and returns the paid result.");
+  } else {
+    printOut(
+      "  buyer negotiates \u2192 the Agent (sole signer) QUOTES a signed price \u2192"
+    );
+    if (isFreePrice) {
+      printOut(
+        "  buyer funds 0 token units \u2192 the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
+      );
+      printOut(
+        "  after the dispute window, SETTLE completes the job with no token payout."
+      );
+    } else {
+      printOut(
+        "  on payment the Agent FULFILLS (runs the LLM, stores the deliverable) \u2192"
+      );
+      printOut(
+        "  after the dispute window, SETTLE releases the $U to your wallet."
+      );
+    }
+  }
   printOut("");
   printOut("Agent (the value + the ONLY key-holder/signer)");
   printOut(`  project   : ${shown(g(agent, "project", "name"), "?")}`);
@@ -9086,19 +9487,35 @@ function printConfigSummary(agentRoot2) {
     const ar = autoRenew ? "on \u2014 tops the API key up from your Pieverse balance (no wallet spend)" : "off";
     printOut(`  auto-alloc: ${ar}`);
   }
-  printOut(
-    `  pricing   : list price ${weiToU(String(price))} per job; clamp ceiling ${shown(maxPrice)}`
-  );
-  printOut(
-    `              quote frozen ${shown(
-      g(agent, "payments", "erc8183", "quote_ttl_seconds"),
-      "?"
-    )}s; job timeout ${shown(
-      g(agent, "payments", "erc8183", "default_estimated_completion_seconds"),
-      "?"
-    )}s`
-  );
-  printOut(`              currency ($U token): ${shown(currency)}`);
+  if (hasErc8183) {
+    if (isFreePrice) {
+      printOut(
+        `  pricing   : FREE \u2014 ${weiToU(String(price))} per job; zero token escrow`
+      );
+      printOut(
+        contractOverrides.mode === "custom" ? "              contracts: custom stack selected (all three address overrides)" : "              contracts: configure all three ERC8183_*_ADDRESS overrides before deploy"
+      );
+    } else {
+      printOut(
+        `  pricing   : list price ${weiToU(String(price))} per job; clamp ceiling ${shown(maxPrice)}`
+      );
+    }
+    printOut(
+      `              quote frozen ${shown(
+        g(agent, "payments", "erc8183", "quote_ttl_seconds"),
+        "?"
+      )}s; job timeout ${shown(
+        g(agent, "payments", "erc8183", "default_estimated_completion_seconds"),
+        "?"
+      )}s`
+    );
+    printOut(`              currency ($U token): ${shown(currency)}`);
+  }
+  if (hasX402Seller) {
+    printOut(
+      isFreeX402 ? "  x402      : FREE \u2014 anonymous passthrough; B402 verify/settle is bypassed" : `  x402      : PAID \u2014 $${shown(x402Seller.price_usd, DEFAULT_B402_PRICE_USD)} per request through B402`
+    );
+  }
   printOut(
     `  storage   : ${storageDesc}  (options: local | ipfs \u2014 ipfs required to deploy)`
   );
@@ -9108,12 +9525,22 @@ function printConfigSummary(agentRoot2) {
   }
   printOut("");
   const todo = [];
-  if (!currency) {
+  if (hasErc8183 && !currency) {
     todo.push("[payments.erc8183].currency \u2014 the $U token address");
   }
-  if (!maxPrice) {
+  if (hasErc8183 && !maxPrice && !isFreePrice) {
     todo.push("[payments.erc8183].max_price \u2014 the price clamp ceiling");
   }
+  if (hasErc8183 && isFreePrice && contractOverrides.mode !== "custom") {
+    todo.push(
+      "ERC8183_COMMERCE_ADDRESS / ROUTER_ADDRESS / POLICY_ADDRESS \u2014 select one zero-price-compatible custom contract stack"
+    );
+  }
+  if (hasX402Seller && !isFreeX402) {
+    todo.push(
+      "B402_BASE_URL / CLIENT_ID / ACCESS_TOKEN / private key \u2014 required for PAID /x402"
+    );
+  }
   if (storageKind2 === "local") {
     todo.push(
       "[storage].kind \u2014 switch to 'ipfs' + set STORAGE_API_URL/STORAGE_API_KEY before deploy (local disk is NOT deployable)"
@@ -9392,8 +9819,13 @@ function runtimeEnvKeys(agentDir) {
   if (resolvable("RPC_URL")) {
     keys.push("RPC_URL");
   }
+  if (commerceRails(cfg).erc8183) {
+    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
   const runtime = String(tableOf7(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && commerceRails(cfg).x402) {
+  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
     for (const key of B402_RUNTIME_KEYS) {
       if (resolvable(key)) keys.push(key);
     }
@@ -9777,8 +10209,11 @@ Switch to Node \u226522 so it wins on PATH, then reopen the shell and retry. Ver
     );
   }
   if (hasX402Face(faces)) {
+    const free = x402SellerIsFree(
+      loadStudioToml10(path22.join(agentDir, "studio.toml"))
+    );
     printOut(
-      `bag dev: x402 seller at http://localhost:${agentPort}/x402 (active when B402 credentials are configured)`
+      free ? `bag dev: x402 seller at http://localhost:${agentPort}/x402 (FREE \u2014 anonymous passthrough; B402 bypassed)` : `bag dev: x402 seller at http://localhost:${agentPort}/x402 (PAID \u2014 active when B402 credentials are configured)`
     );
   }
   await launch();
@@ -9885,8 +10320,13 @@ function runtimeEnvKeys2(agentRoot2) {
   if (resolvable("RPC_URL")) {
     keys.push("RPC_URL");
   }
+  if (commerceRails(cfg).erc8183) {
+    for (const key of ERC8183_ADDRESS_OVERRIDE_KEYS) {
+      if (resolvable(key)) keys.push(key);
+    }
+  }
   const runtime = String(tableOf2(cfg, "stack").runtime ?? "agentcore");
-  if (runtime === "agentcore" && commerceRails(cfg).x402) {
+  if (runtime === "agentcore" && x402SellerUsesB402(cfg)) {
     for (const key of B402_RUNTIME_KEYS) {
       if (resolvable(key)) keys.push(key);
     }
@@ -10226,51 +10666,76 @@ async function checkPieverseKeyHash(root, _target) {
     }
   ];
 }
-var MIN_PRICE_WEI = 1000000000n;
-var MAX_UINT256 = 2n ** 256n - 1n;
 function erc8183RailChecks(cfg) {
   const c2 = tableOf2(tableOf2(cfg, "payments"), "erc8183");
-  const raw = (key, dflt) => {
-    const s = String(c2[key] ?? "").trim();
-    if (!s) {
-      return dflt;
-    }
-    try {
-      return BigInt(s);
-    } catch {
-      return dflt;
-    }
-  };
   const out = [];
-  const minPrice = raw("min_price", 0n);
-  const maxPrice = raw("max_price", MAX_UINT256);
-  const listPrice = raw("price", 0n);
-  const clampedToMax = listPrice < maxPrice ? listPrice : maxPrice;
-  const effective = minPrice > clampedToMax ? minPrice : clampedToMax;
-  if (effective < MIN_PRICE_WEI) {
-    const priceUnset = !String(c2.price ?? "").trim();
-    const clamped = listPrice >= MIN_PRICE_WEI && MIN_PRICE_WEI > effective;
-    let cause;
-    if (priceUnset) {
-      cause = "[payments.erc8183].price is unset, so every quote defaults to 0";
-    } else if (clamped) {
-      cause = `the list price (${listPrice} wei) is clamped to ${effective} wei by [payments.erc8183].max_price`;
-    } else {
-      cause = `the effective quote price is ${effective} wei`;
-    }
+  const contracts = erc8183ContractOverrideState();
+  if (contracts.mode === "partial") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_contract_override_incomplete",
+      message: `The ERC-8183 contract override is incomplete. Set ${contracts.missing.join(", ")} so commerce, router, and policy come from one compatible contract stack.`,
+      details: {
+        present: contracts.present,
+        missing: contracts.missing
+      }
+    });
+  } else if (contracts.mode === "invalid") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_contract_override_invalid",
+      message: `The following ERC-8183 contract overrides are not valid EVM addresses: ${contracts.invalid.join(", ")}.`,
+      details: { invalid: contracts.invalid }
+    });
+  }
+  const pricing = erc8183PricingState(c2);
+  if (pricing.kind === "unset") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_price_unset",
+      message: "[payments.erc8183].price is unset. Set it explicitly to 0 for a free job or to a positive integer amount in token base units.",
+      fixCmd: "bag config set payments.erc8183.price 100000000000000000",
+      details: {}
+    });
+  } else if (pricing.kind === "invalid") {
     out.push({
       level: Level.CRITICAL,
-      name: "commerce_price_below_min",
-      message: `${cause}; the agent would quote for free / below the contract minimum of ${MIN_PRICE_WEI} wei (1 gwei). v1 rejects price-0 / sub-gwei tasks, so no job can ever fund. Set [payments.erc8183].price (and check max_price) in studio.toml.`,
-      fixCmd: "bag config set payments.erc8183.price 1000000000",
+      name: "commerce_price_invalid",
+      message: `[payments.erc8183].${pricing.field} must be a non-negative uint256 decimal string; got ${JSON.stringify(pricing.value)}.`,
+      fixCmd: "bag config set payments.erc8183.price 100000000000000000",
       details: {
-        effective_wei: String(effective),
-        list_price_wei: String(listPrice),
-        min_price_wei: String(minPrice),
-        max_price_wei: String(maxPrice),
-        min_required_wei: String(MIN_PRICE_WEI)
+        configured_field: pricing.field,
+        configured_value: pricing.value
       }
     });
+  } else if (pricing.kind === "clamped_to_zero") {
+    out.push({
+      level: Level.CRITICAL,
+      name: "commerce_price_clamped_to_zero",
+      message: `The list price (${pricing.listPrice} token base units) is clamped to 0 by [payments.erc8183].max_price. Set price explicitly to 0 to opt into free jobs, or fix the clamp.`,
+      details: {
+        effective_wei: "0",
+        list_price_wei: String(pricing.listPrice),
+        min_price_wei: String(pricing.minPrice),
+        max_price_wei: String(pricing.maxPrice)
+      }
+    });
+  } else if (pricing.kind === "free") {
+    if (contracts.mode === "canonical") {
+      out.push({
+        level: Level.CRITICAL,
+        name: "commerce_zero_price_contract_unsupported",
+        message: "ERC-8183 pricing is FREE (zero token escrow), but the canonical contract stack rejects zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible custom stack.",
+        details: { effective_wei: "0", contract_profile: "canonical" }
+      });
+    } else if (contracts.mode === "custom") {
+      out.push({
+        level: Level.INFO,
+        name: "commerce_zero_price_enabled",
+        message: "ERC-8183 pricing is FREE \u2014 buyers fund 0 token units with zero token escrow; a complete custom contract stack is selected.",
+        details: { effective_wei: "0", contract_profile: "custom" }
+      });
+    }
   }
   if (String(c2.currency ?? "").trim() === "") {
     out.push({
@@ -10306,15 +10771,24 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
   const rails = commerceRails(cfg);
   const credentials = b402Credentials(agentRoot2);
   const out = [];
+  const pricing = x402SellerPricingState(seller);
+  const free = rails.x402 && pricing.kind === "free";
+  const paid = rails.x402 && pricing.kind === "paid";
   if (sellerPresent) {
-    const price = seller.price_usd === void 0 ? "0.01" : typeof seller.price_usd === "string" ? seller.price_usd : "";
-    if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(price)) {
+    if (pricing.kind === "invalid") {
       out.push({
         level: Level.CRITICAL,
         name: "x402_price_invalid",
         message: '[payments.x402_seller].price_usd must be a non-negative decimal string; "0" is valid and enables the free passthrough.',
         details: {}
       });
+    } else if (free) {
+      out.push({
+        level: Level.INFO,
+        name: "x402_zero_price_enabled",
+        message: "The x402 seller is explicitly FREE. /x402 is anonymous, and B402 verify/settle, token payment, and settlement audit are bypassed.",
+        details: { price_usd: pricing.priceUsd, facilitator_bypassed: true }
+      });
     }
     const assets = seller.assets ?? ["U"];
     if (!Array.isArray(assets) || assets.length !== 1 || assets[0] !== "U") {
@@ -10336,7 +10810,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
     }
   }
   const walletKind2 = String(tableOf2(cfg, "wallet").kind ?? "evm-local");
-  if (rails.x402 && !["evm-local", "twak"].includes(walletKind2)) {
+  if (paid && !["evm-local", "twak"].includes(walletKind2)) {
     out.push({
       level: Level.CRITICAL,
       name: "x402_wallet_kind_unsupported",
@@ -10344,7 +10818,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: { walletKind: walletKind2 }
     });
   }
-  if (credentials.any && !credentials.complete) {
+  if (paid && credentials.any && !credentials.complete) {
     out.push({
       level: Level.CRITICAL,
       name: "x402_credentials_partial",
@@ -10352,7 +10826,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: { present: credentials.presentKeys }
     });
   }
-  if (credentials.bothPrivateKeyFormats) {
+  if (paid && credentials.bothPrivateKeyFormats) {
     out.push({
       level: Level.WARNING,
       name: "x402_private_key_ambiguous",
@@ -10360,7 +10834,7 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: {}
     });
   }
-  if (rails.x402 && !credentials.any) {
+  if (paid && !credentials.any) {
     out.push({
       level: rails.erc8183 ? Level.WARNING : Level.CRITICAL,
       name: "x402_credentials_missing",
@@ -10368,19 +10842,19 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
       details: {}
     });
   }
-  if (!rails.x402 && credentials.any) {
+  if ((!rails.x402 || free) && credentials.any) {
     out.push({
       level: Level.WARNING,
       name: "x402_credentials_unused",
-      message: "B402 credentials are configured but the x402 seller rail is absent or disabled; they will not be synchronized.",
+      message: free ? "B402 credentials are configured but FREE x402 bypasses the facilitator; they will not be synchronized." : "B402 credentials are configured but the x402 seller rail is absent or disabled; they will not be synchronized.",
       details: { present: credentials.presentKeys }
     });
   }
-  if (credentials.baseUrl !== null) {
+  if (paid && credentials.baseUrl !== null) {
     const network = String(
       tableOf2(cfg, "network").default ?? "bsc-mainnet"
     ).toLowerCase();
-    const testUrl = /sandbox|test/.test(credentials.baseUrl.toLowerCase());
+    const testUrl = isB402TestnetBaseUrl(credentials.baseUrl);
     const testNetwork = network.includes("testnet");
     if (testUrl !== testNetwork) {
       out.push({
@@ -10393,12 +10867,12 @@ function x402SellerRailChecks(agentRoot2, cfg, target) {
   }
   const destination = String(tableOf2(cfg, "deploy").destination ?? "self");
   const stackRuntime2 = String(tableOf2(cfg, "stack").runtime ?? "agentcore");
-  if (rails.x402 && credentials.complete && destination !== "platform" && (target !== "agentcore" || stackRuntime2 !== "agentcore")) {
+  if (rails.x402 && (free || credentials.complete) && destination !== "platform" && (target !== "agentcore" || stackRuntime2 !== "agentcore")) {
     const blocking = target !== "agentcore" ? target : stackRuntime2;
     out.push({
       level: Level.WARNING,
       name: "x402_forced_dormant_runtime",
-      message: `x402 seller credentials are complete, but the ${blocking} runtime has no x402 path; this target is forced dormant. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`,
+      message: `x402 pricing is ready, but the ${blocking} runtime has no x402 path; this target is forced dormant. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`,
       details: { destination, target, stackRuntime: stackRuntime2 }
     });
   }
@@ -10613,6 +11087,7 @@ var allChecks = [
   // gates on the LEVEL, not on which module produced it.
   checkTwakRequiresContainer,
   checkTwakCliPresent,
+  checkTwakCustomContractsUnsupported,
   checkTwakWalletExists,
   checkTwakPasswordEnvSet,
   checkTwakCredentialsAvailable,
@@ -11755,14 +12230,15 @@ async function checkWalletTbnbBalanceSufficient(root, _target) {
     return [];
   }
   const isTwak2 = tableOf2(data, "wallet").kind === "twak";
-  if (isTwak2 && netName === "bsc-testnet") {
+  const customContracts = isTwak2 && twakCustomContractOverrides(netName).length > 0;
+  if (isTwak2 && netName === "bsc-testnet" && !customContracts) {
     return [];
   }
   const bal = await readNativeBalanceRaw(address, netName);
   if (bal >= TBNB_MIN_WEI) {
     return [];
   }
-  const gasNote = isTwak2 ? " (twak: x402 topups are gasless and ERC-8004 registry writes are gas-sponsored, but mainnet ERC-8183 fund/settle self-pay gas)" : "";
+  const gasNote = isTwak2 ? netName === "bsc-testnet" ? " (twak: custom contract sponsorship depends on the paymaster policy; keep fallback tBNB)" : " (twak: x402 topups are gasless and ERC-8004 registry writes are gas-sponsored, but mainnet ERC-8183 fund/settle self-pay gas)" : "";
   return [
     {
       level: Level.WARNING,
@@ -12243,6 +12719,7 @@ async function runPrepare(opts = {}) {
           checkLocalKeystoreExists,
           checkWalletPasswordEnvSet,
           checkLlmProviderKeySet,
+          checkCommerceReady,
           ...azureFoundryChecks
         ],
         root,
@@ -12294,6 +12771,21 @@ var PROVIDER_LABELS = {
   aws: "AWS AgentCore",
   azure: "Azure Foundry"
 };
+var PROVIDER_MENU_ORDER = [
+  "bnb",
+  "aws",
+  "azure"
+];
+var PROVIDER_SHORT_LABELS = {
+  bnb: "BNB",
+  aws: "AWS",
+  azure: "Azure"
+};
+function providerDigit(provider) {
+  return PROVIDER_MENU_ORDER.indexOf(provider) + 1;
+}
+var ADVERTISED_PROVIDERS = ["bnb", "aws"];
+var ADVERTISED_PROVIDERS_HELP = ADVERTISED_PROVIDERS.join("|");
 function tableOf10(data, key) {
   const value = data[key];
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -12386,7 +12878,7 @@ function unavailableProvidersForProject(root) {
     return {};
   }
   if (runtime === "azure-foundry") {
-    const reason = "this project uses the Azure Foundry container adapter; scaffold an agentcore project before selecting BNB or AWS";
+    const reason = "this project uses a different container adapter; scaffold an agentcore project before selecting BNB or AWS";
     return {
       bnb: reason,
       aws: reason,
@@ -12417,9 +12909,12 @@ function unavailableReason(opts, provider) {
   }
   return opts.unavailable?.[provider] ?? null;
 }
+function providerPromptHint() {
+  return PROVIDER_MENU_ORDER.filter((p) => ADVERTISED_PROVIDERS.includes(p)).map((p) => `${providerDigit(p)}=${PROVIDER_SHORT_LABELS[p]}`).join(", ");
+}
 async function promptProvider(opts) {
   for (; ; ) {
-    const answer = (await opts.prompt("Provider [1=BNB, 2=AWS, 3=Azure]: ")).trim().toLowerCase();
+    const answer = (await opts.prompt(`Provider [${providerPromptHint()}]: `)).trim().toLowerCase();
     const provider = answer === "1" || answer === "bnb" ? "bnb" : answer === "2" || answer === "aws" ? "aws" : answer === "3" || answer === "azure" ? "azure" : null;
     if (provider === null) {
       if (answer === "" || answer === "q" || answer === "cancel") {
@@ -13315,6 +13810,8 @@ function printAccessNextSteps(root, _invokeUrl) {
   const agentRoot2 = findSubProjectRoot15("agent", root) ?? root;
   const access = buyerAccess(agentRoot2);
   const x402Only = access.faces.length === 1 && hasX402Face(access.faces);
+  const x402Free = x402SellerIsFree(loadAgentCfg(agentRoot2));
+  const x402RouteLabel = x402Free ? "anonymous FREE route" : "anonymous paid route";
   emit("\nAccess your agent \u2014");
   if (access.agentId) {
     if (!x402Only) {
@@ -13332,7 +13829,7 @@ function printAccessNextSteps(root, _invokeUrl) {
       );
     }
     if (hasX402Face(access.faces)) {
-      emit(`  x402 endpoint:  ${access.x402Url}  (anonymous paid route)`);
+      emit(`  x402 endpoint:  ${access.x402Url}  (${x402RouteLabel})`);
     }
     if (!x402Only) {
       emit(
@@ -13357,7 +13854,7 @@ function printAccessNextSteps(root, _invokeUrl) {
       );
     }
     if (hasX402Face(access.faces)) {
-      emit(`  x402 endpoint:  ${rtTmpl}/x402  (anonymous paid route)`);
+      emit(`  x402 endpoint:  ${rtTmpl}/x402  (${x402RouteLabel})`);
     }
     if (x402Only) {
       emit("  protocol discovery is suppressed for this X402-only deployment.");
@@ -13388,7 +13885,9 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   const tokenSteps = `  1) run \`bag platform invoke-client new\` -> client_id + client_secret (secret shown ONCE).
   2) POST client_credentials to ${tokenUrl} with scope \`${scope}\` -> access_token.
   3) send \`Authorization: Bearer <token>\`.`;
-  const rails = commerceRails(loadAgentCfg(agentRoot2));
+  const agentCfg = loadAgentCfg(agentRoot2);
+  const rails = commerceRails(agentCfg);
+  const x402Free = x402SellerIsFree(agentCfg);
   const x402Only = faces.length === 1 && hasX402Face(faces) || rails.x402 && !rails.erc8183;
   const x402Summary = x402DeploySummary(agentRoot2, "platform", access.x402Url);
   const endpoints = [];
@@ -13406,7 +13905,7 @@ function printAgentClientPrompt(root, invokeUrl, status) {
   }
   if (x402Only) {
     endpoints.push(
-      `  [X402] Anonymous paid endpoint: ${access.x402Url ?? `${rt}/x402`}
+      `  [X402] Anonymous ${x402Free ? "FREE" : "paid"} endpoint: ${access.x402Url ?? `${rt}/x402`}
          Protocol discovery is suppressed.`
     );
   }
@@ -13454,7 +13953,7 @@ function printAgentClientPrompt(root, invokeUrl, status) {
     ] : [],
     "",
     "YOUR TASK",
-    x402Only ? "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
+    x402Only ? x402Free ? "Call the anonymous FREE /x402 endpoint directly. Do not create a payment or call the OAuth2 ERC-8183 endpoint." : "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
     CLIENT_PROMPT_RULE
   ];
   const text2 = lines.join("\n");
@@ -13641,9 +14140,11 @@ function isFile14(p) {
 
 // src/cli/_runtime/base.ts
 var DEPLOY_RUNTIME_TARGETS = ["agentcore", "azure-foundry"];
+var ADVERTISED_DEPLOY_RUNTIME_TARGETS = ["agentcore"];
 
 // src/cli/deploy.ts
 var TARGET_CHOICES = [...DEPLOY_RUNTIME_TARGETS];
+var ADVERTISED_TARGET_CHOICES = [...ADVERTISED_DEPLOY_RUNTIME_TARGETS];
 function isFile15(p) {
   try {
     return fs37.statSync(p).isFile();
@@ -13683,17 +14184,33 @@ function loadAgentCfg2(root) {
 function registerDeploy(program) {
   program.enablePositionalOptions();
   const p = program.command("deploy").description(
-    "Deploy the agent after explicitly selecting BNB, AWS, or Azure; lifecycle subcommands inspect recorded deployments."
-  );
-  const runtimeOption = () => new Option4(
-    "--runtime <name>",
-    "Deploy runtime to validate against (default: studio.toml [stack].runtime, else agentcore)."
-  ).choices(TARGET_CHOICES);
-  const targetAlias = () => new Option4("--target <name>", "Deprecated alias of --runtime.").choices(TARGET_CHOICES).hideHelp();
-  const providerOption = () => new Option4(
-    "--provider <provider>",
-    "Provider: bnb, aws, or azure. Required for non-interactive deploy; lifecycle commands need it only when multiple records exist."
-  ).choices(["bnb", "aws", "azure"]);
+    "Deploy the agent after explicitly selecting BNB or AWS; lifecycle subcommands inspect recorded deployments."
+  );
+  const runtimeOption = () => acceptChoices(
+    new Option4(
+      "--runtime <name>",
+      "Deploy runtime to validate against (default: studio.toml [stack].runtime, else agentcore)."
+    ),
+    TARGET_CHOICES,
+    ADVERTISED_TARGET_CHOICES
+  );
+  const targetAlias = () => acceptChoices(
+    new Option4(
+      "--target <name>",
+      "Deprecated alias of --runtime."
+    ).hideHelp(),
+    TARGET_CHOICES,
+    ADVERTISED_TARGET_CHOICES
+  );
+  const providerOption = () => acceptChoices(
+    new Option4(
+      "--provider <provider>",
+      "Provider: bnb or aws. Required for non-interactive deploy; lifecycle commands need it only when multiple records exist."
+    ),
+    // Unadvertised providers stay parseable (see ADVERTISED_PROVIDERS).
+    PROVIDER_MENU_ORDER,
+    ADVERTISED_PROVIDERS
+  );
   p.addOption(providerOption()).option("--project-root <path>", "Override project root.").option("--skip-prepare", "Skip non-storage local readiness checks.").option(
     "--force-deploy-broken-storage",
     "DANGEROUS: bypass fatal deliverable-storage checks."
@@ -13702,7 +14219,7 @@ function registerDeploy(program) {
   ).option("--accept-risk", "Accept provider risk/terms disclosures.").option("--yes", "Confirm the selected deployment plan non-interactively.").option(
     "--allow-multiple",
     "Allow creating a deployment while another provider remains active."
-  ).option("--skip-smoke", "Skip Azure's delegated post-deploy smoke check.").action(act((opts) => cmdDeploy(opts, [])));
+  ).option("--skip-smoke", "Skip the delegated post-deploy smoke check.").action(act((opts) => cmdDeploy(opts, [])));
   p.command("prepare").description("Run the deploy-readiness sweep on this project.").addOption(runtimeOption()).addOption(targetAlias()).option("--project-root <path>", "Override project root.").option("--json", "Emit JSON instead of a table.").option(
     "--ignore-warnings",
     "Exit 0 even if WARNING-level checks fire (still fails on BLOCKED/CRITICAL)."
@@ -13741,7 +14258,7 @@ function registerDeploy(program) {
     "Allow creating a deployment while another provider remains active."
   ).option(
     "--skip-smoke",
-    "(azure-foundry) Skip the post-deploy smoke check (omit `--smoke` from the delegated bnbagent-deploy invocation)."
+    "Skip the post-deploy smoke check (omit `--smoke` from the delegated bnbagent-deploy invocation)."
   ).argument(
     "[agentcoreArgs...]",
     "Extra args passed straight through to `bnbagent-deploy deploy` (put after `--`)."
@@ -13799,7 +14316,7 @@ function registerDeploy(program) {
       (opts) => cmdDestroy(opts)
     )
   );
-  p.command("logs").description("Show the selected deployment's logs via bnbagent-deploy.").option("--project-root <path>", "Override project root.").addOption(providerOption()).option("--since <dur>", "Lower bound, e.g. 5m/2h/1d (default 10m).", "10m").option("--follow", "Stream new lines (poll ~3s).").option("--limit <n>", "Number of recent lines (Azure; default 50).").option("--session <id>", "Azure container session id.").addOption(
+  p.command("logs").description("Show the selected deployment's logs via bnbagent-deploy.").option("--project-root <path>", "Override project root.").addOption(providerOption()).option("--since <dur>", "Lower bound, e.g. 5m/2h/1d (default 10m).", "10m").option("--follow", "Stream new lines (poll ~3s).").option("--limit <n>", "Number of recent lines (default 50).").option("--session <id>", "Container session id.").addOption(
     new Option4(
       "--job <id>",
       "Deprecated Studio direct-CloudWatch filter."
@@ -14251,14 +14768,18 @@ function renderProviderSelection(deployments, trial, unavailable) {
   }
   const remaining = formatTrialRemaining(trial.remainingSeconds);
   const bnbDetail = unavailable.bnb ? `unavailable \u2014 ${unavailable.bnb}` : trial.state === "expired" ? `unavailable \u2014 trial expired${trial.expiresAt ? ` ${trial.expiresAt}` : ""}` : trial.state === "active" ? `active${remaining ? ` \u2014 ${remaining} remaining` : ""}${trial.expiresAt ? ` \xB7 expires ${trial.expiresAt}` : ""}` : trial.state === "available" ? "available \u2014 free 48h testnet; starts on first successful deploy" : "login required to check trial eligibility";
+  const detail = {
+    bnb: bnbDetail,
+    aws: unavailable.aws ? `unavailable \u2014 ${unavailable.aws}` : "deploy to your AWS account",
+    azure: unavailable.azure ? `unavailable \u2014 ${unavailable.azure}` : "deploy to your Azure account"
+  };
   printOut("Deployment providers");
-  printOut(`  1. BNB Chain Trial   ${bnbDetail}`);
-  printOut(
-    `  2. AWS AgentCore     ${unavailable.aws ? `unavailable \u2014 ${unavailable.aws}` : "deploy to your AWS account"}`
-  );
-  printOut(
-    `  3. Azure Foundry     ${unavailable.azure ? `unavailable \u2014 ${unavailable.azure}` : "deploy to your Azure account"}`
-  );
+  for (const provider of PROVIDER_MENU_ORDER) {
+    if (!ADVERTISED_PROVIDERS.includes(provider)) continue;
+    printOut(
+      `  ${providerDigit(provider)}. ${PROVIDER_LABELS[provider].padEnd(18)}${detail[provider]}`
+    );
+  }
 }
 async function cmdDeploy(opts, deployArgs) {
   const rc = applyProjectRoot(opts.projectRoot);
@@ -14283,7 +14804,7 @@ async function cmdDeploy(opts, deployArgs) {
   });
   if (selection.kind === "selection_required") {
     printErr(
-      "error: deployment provider must be selected explicitly in a non-interactive terminal; pass --provider bnb|aws|azure --yes"
+      `error: deployment provider must be selected explicitly in a non-interactive terminal; pass --provider ${ADVERTISED_PROVIDERS_HELP} --yes`
     );
     return selection.exitCode;
   }
@@ -14706,7 +15227,7 @@ async function printAccessNextSteps2(root, runtime, opts = {}) {
     return;
   }
   printOut(
-    "  Azure Foundry buyer access is in Preview \u2014 see the bnbagent-studio-use-azure-foundry.md reference (skills/references/ in the bnbagent-studio repo) and docs/guides/foundry-a2a-access.md. The per-agent A2A card URL and OAuth scope are confirmed only after a live deploy."
+    "  Azure Foundry buyer access is in Preview \u2014 see docs/guides/foundry-a2a-access.md in the bnbagent-studio repo. The per-agent A2A card URL and OAuth scope are confirmed only after a live deploy."
   );
 }
 var CLIENT_PROMPT_RULE2 = "\u2500".repeat(62);
@@ -14731,7 +15252,9 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
   const tokenSteps = `  1) token endpoint ${tokenUrl} (scope \`${scope}\`); ${credentialStep}.
   2) POST client_credentials -> access_token.
   3) send \`Authorization: Bearer <token>\` AND header \`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <stable id >= 33 chars>\`.`;
-  const rails = commerceRails(loadAgentCfg2(agentRoot2) ?? {});
+  const agentCfg = loadAgentCfg2(agentRoot2) ?? {};
+  const rails = commerceRails(agentCfg);
+  const x402Free = x402SellerIsFree(agentCfg);
   const x402Only = rails.x402 && !rails.erc8183;
   const x402Summary = x402DeploySummary(agentRoot2, destination, null);
   const faces = agentFacesOf(agentRoot2);
@@ -14784,7 +15307,7 @@ async function printAgentClientPrompt2(root, destination, opts = {}) {
     ] : [],
     "",
     "YOUR TASK",
-    x402Only ? "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
+    x402Only ? x402Free ? "Call the anonymous FREE /x402 endpoint directly. Do not create a payment or call the OAuth2 ERC-8183 endpoint." : "Follow the X402 SELLER activation or anonymous paid-request instructions above. Do not call the OAuth2 ERC-8183 endpoint." : "Write and run a client that (1) obtains a token, (2) calls negotiate with a sample task and prints the signed quote, (3) optionally funds a job on-chain (step 2 of the flow above) and calls notify_funded with the resulting job_id. Use the exact endpoint, headers, and message shapes above. If you don't have client_id/client_secret, ask me for them.",
     CLIENT_PROMPT_RULE2
   ];
   const text2 = lines.join("\n");
@@ -14978,7 +15501,9 @@ async function cmdStatus2(opts) {
       printOut(JSON.stringify({ deployments: [] }, null, 2));
     } else {
       printOut(`No recorded deployments${detail}.`);
-      printOut("Start one with `bag deploy --provider bnb|aws|azure`.");
+      printOut(
+        `Start one with \`bag deploy --provider ${ADVERTISED_PROVIDERS_HELP}\`.`
+      );
     }
     return opts.provider ? 2 : 0;
   }
@@ -15135,13 +15660,13 @@ async function selectRecordedForLifecycle(root, requested, operation) {
   if (deployments.length === 1 && soleDeployment) return soleDeployment;
   if (deployments.length === 0) {
     printErr(
-      "error: no deployment is recorded; run `bag deploy --provider bnb|aws|azure` first"
+      `error: no deployment is recorded; run \`bag deploy --provider ${ADVERTISED_PROVIDERS_HELP}\` first`
     );
     return 2;
   }
   if (!stdinIsTty()) {
     printErr(
-      `error: multiple deployments are active; non-interactive \`${operation}\` requires --provider bnb|aws|azure`
+      `error: multiple deployments are active; non-interactive \`${operation}\` requires --provider ${ADVERTISED_PROVIDERS_HELP}`
     );
     return 2;
   }
@@ -15426,7 +15951,9 @@ async function cmdDoctor(opts) {
   checks.push(...await checkLlm(data, projectRoot));
   checks.push(...await checkNetwork(data, opts.network));
   checks.push(...checkCurrency(data));
+  checks.push(...checkErc8183Pricing(data));
   checks.push(...checkPriceBounds(data));
+  checks.push(...checkX402Seller(data, projectRoot));
   checks.push(...checkStorage(data));
   checks.push(...await checkBalances(projectRoot, data, opts.network));
   checks.push(...await checkPieverseMainnetU(projectRoot, data));
@@ -15592,7 +16119,7 @@ function anchoredKeystoreDir(projectRoot, walletCfg) {
 async function checkWallet(projectRoot, data) {
   const walletCfg = tableOf13(data, "wallet");
   if (walletCfg.kind === "twak") {
-    return checkWalletTwak(walletCfg, projectRoot);
+    return checkWalletTwak(walletCfg, projectRoot, data);
   }
   if (walletCfg.kind === "altana") {
     return checkWalletAltana(walletCfg, projectRoot);
@@ -15737,7 +16264,7 @@ function checkWalletAltana(walletCfg, projectRoot) {
   }
   return out;
 }
-async function checkWalletTwak(walletCfg, projectRoot) {
+async function checkWalletTwak(walletCfg, projectRoot, data = {}) {
   const out = [];
   if (await whichTwak() !== null) {
     const version = await twakInstalledVersion();
@@ -15762,6 +16289,15 @@ async function checkWalletTwak(walletCfg, projectRoot) {
       detail: `not on PATH \u2014 npm install -g @trustwallet/cli@${TWAK_CLI_VERSION}`
     });
   }
+  const networkName = String(tableOf13(data, "network").default ?? "bsc-testnet");
+  const unsupportedTargets = twakUnsupportedContractOverrides(networkName);
+  if (unsupportedTargets.length > 0) {
+    out.push({
+      name: "[wallet] twak contract targets",
+      status: FAIL,
+      detail: `twak v0.20.0 cannot target custom ERC-8183 contracts (${unsupportedTargets.map((item) => item.envKey).join(", ")}) and would use canonical contracts instead. Use wallet.kind='evm-local' for custom ERC-8183 contracts, or remove the overrides. ERC8004_REGISTRY_ADDRESS is supported.`
+    });
+  }
   const walletFile = twakWalletFile(walletCfg, projectRoot);
   if (isFile16(walletFile)) {
     out.push({
@@ -16034,10 +16570,94 @@ function checkCurrency(data) {
   }
   return [];
 }
+function checkErc8183Pricing(data) {
+  const payValue = tableOf13(data, "payments").erc8183;
+  if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
+    return [];
+  }
+  const pay = payValue;
+  const pricing = erc8183PricingState(pay);
+  if (pricing.kind === "unset") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: "[payments.erc8183].price is unset \u2014 set it explicitly to 0 for FREE or to a positive integer string in token base units."
+      }
+    ];
+  }
+  if (pricing.kind === "invalid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `[payments.erc8183].${pricing.field} must be a non-negative uint256 decimal string; got ${JSON.stringify(pricing.value)}.`
+      }
+    ];
+  }
+  if (pricing.kind === "clamped_to_zero") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `PAID list price ${pricing.listPrice} is clamped to 0 by max_price. Set price explicitly to 0 for FREE or fix the clamp.`
+      }
+    ];
+  }
+  const contracts = erc8183ContractOverrideState();
+  const priceMode = pricing.kind === "free" ? "FREE \u2014 zero token escrow" : `PAID \u2014 effective list price ${pricing.effectivePrice} token base units`;
+  if (contracts.mode === "partial") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `${priceMode}, but the ERC-8183 contract override is incomplete. Set ${contracts.missing.join(", ")} so commerce, router, and policy come from one compatible stack.`
+      }
+    ];
+  }
+  if (contracts.mode === "invalid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: FAIL,
+        detail: `${priceMode}, but these contract overrides are not valid EVM addresses: ${contracts.invalid.join(", ")}.`
+      }
+    ];
+  }
+  if (pricing.kind === "paid") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: PASS,
+        detail: `${priceMode}.`
+      }
+    ];
+  }
+  if (contracts.mode === "custom") {
+    return [
+      {
+        name: "erc8183 pricing",
+        status: PASS,
+        detail: "FREE \u2014 zero token escrow; custom contract stack selected with all three ERC-8183 address overrides."
+      }
+    ];
+  }
+  return [
+    {
+      name: "erc8183 pricing",
+      status: FAIL,
+      detail: "FREE \u2014 zero token escrow, but the canonical ERC-8183 contracts reject zero funding. Set ERC8183_COMMERCE_ADDRESS, ERC8183_ROUTER_ADDRESS, and ERC8183_POLICY_ADDRESS together to a zero-price-compatible custom stack."
+    }
+  ];
+}
 function checkPriceBounds(data) {
-  const pay = tableOf13(tableOf13(data, "payments"), "erc8183");
+  const payValue = tableOf13(data, "payments").erc8183;
+  if (payValue === null || typeof payValue !== "object" || Array.isArray(payValue)) {
+    return [];
+  }
+  const pay = payValue;
   const maxPrice = String(pay.max_price ?? "").trim();
-  if (!maxPrice || maxPrice === "0") {
+  if (!maxPrice && erc8183PricingState(pay).kind !== "free") {
     return [
       {
         name: "erc8183 price bounds",
@@ -16048,6 +16668,84 @@ function checkPriceBounds(data) {
   }
   return [];
 }
+function checkX402Seller(data, agentRoot2) {
+  const payments = tableOf13(data, "payments");
+  const sellerValue = payments.x402_seller;
+  if (sellerValue === null || typeof sellerValue !== "object" || Array.isArray(sellerValue)) {
+    return [];
+  }
+  const seller = sellerValue;
+  if (seller.enabled !== true) return [];
+  const pricing = x402SellerPricingState(seller);
+  if (pricing.kind === "invalid") {
+    return [
+      {
+        name: "x402 pricing",
+        status: FAIL,
+        detail: "[payments.x402_seller].price_usd must be a non-negative decimal string."
+      }
+    ];
+  }
+  const runtime = String(tableOf13(data, "stack").runtime ?? "agentcore");
+  const hasErc8183 = payments.erc8183 !== null && typeof payments.erc8183 === "object" && !Array.isArray(payments.erc8183);
+  const fallbackStatus = hasErc8183 ? WARN : FAIL;
+  if (pricing.kind === "free") {
+    const out2 = [
+      {
+        name: "x402 pricing",
+        status: PASS,
+        detail: "FREE \u2014 /x402 is anonymous; B402 verify/settle, token payment, and settlement audit are bypassed."
+      }
+    ];
+    const credentials2 = b402Credentials(agentRoot2);
+    if (credentials2.any) {
+      out2.push({
+        name: "x402 credentials",
+        status: INFO,
+        detail: "configured B402 credentials are unused in FREE mode and will not be synchronized."
+      });
+    }
+    if (runtime !== "agentcore") {
+      out2.push({
+        name: "x402 runtime",
+        status: fallbackStatus,
+        detail: `${runtime} has no /x402 route; FREE pricing does not remove that runtime limitation.`
+      });
+    }
+    return out2;
+  }
+  const out = [
+    {
+      name: "x402 pricing",
+      status: PASS,
+      detail: `PAID \u2014 $${pricing.priceUsd} per request through B402.`
+    }
+  ];
+  const walletKind2 = String(tableOf13(data, "wallet").kind ?? "evm-local");
+  if (!["evm-local", "twak"].includes(walletKind2)) {
+    out.push({
+      name: "x402 payout wallet",
+      status: FAIL,
+      detail: `PAID B402 supports evm-local or twak, not ${walletKind2}.`
+    });
+  }
+  const credentials = b402Credentials(agentRoot2);
+  if (!credentials.complete) {
+    out.push({
+      name: "x402 credentials",
+      status: credentials.any ? FAIL : fallbackStatus,
+      detail: credentials.any ? "B402 credentials are partial; set BASE_URL, CLIENT_ID, ACCESS_TOKEN, and exactly one private-key form." : "PAID mode needs the four B402 merchant credentials; without them the rail starts dormant."
+    });
+  }
+  if (runtime !== "agentcore") {
+    out.push({
+      name: "x402 runtime",
+      status: fallbackStatus,
+      detail: `${runtime} has no /x402 route; deploy this rail to AgentCore.`
+    });
+  }
+  return out;
+}
 function checkStorage(data) {
   const kind = String(tableOf13(data, "storage").kind ?? "local").toLowerCase();
   if (kind === "ipfs") {
@@ -16650,7 +17348,7 @@ function loadAgentCfg3() {
     return null;
   }
 }
-function resolveNetwork(override) {
+function resolveNetwork2(override) {
   if (override) {
     return override;
   }
@@ -16840,7 +17538,7 @@ async function cmdRegister2(opts) {
     return 2;
   }
   const wallet = walletRt6.getWallet();
-  const network = resolveNetwork(opts.network);
+  const network = resolveNetwork2(opts.network);
   const gasErr = await precheckRegisterGas(wallet, network);
   if (gasErr !== null) {
     printErr(`error: ${gasErr}`);
@@ -16928,7 +17626,7 @@ async function cmdUpdateEndpoint(opts) {
     return 2;
   }
   const wallet = walletRt6.getWallet();
-  const network = resolveNetwork(opts.network);
+  const network = resolveNetwork2(opts.network);
   const protocol = resolveProtocol(opts.protocol);
   let accessDescription = null;
   const agentRoot2 = findProjectRoot5();
@@ -16971,7 +17669,7 @@ async function cmdUpdateEndpoint(opts) {
 }
 async function cmdUpdateMetadata(opts) {
   const wallet = walletRt6.getWallet();
-  const network = resolveNetwork(opts.network);
+  const network = resolveNetwork2(opts.network);
   let txHash;
   try {
     txHash = await setMetadata(wallet, opts.key, opts.value, {
@@ -17003,7 +17701,7 @@ async function cmdClearPending(opts) {
   }
   const pendingTx = identity.pending_tx ? String(identity.pending_tx) : null;
   if (pendingTx !== null && !opts.force) {
-    const network = resolveNetwork(opts.network);
+    const network = resolveNetwork2(opts.network);
     let seen;
     try {
       seen = await readTransactionSeen(pendingTx, network);
@@ -17034,7 +17732,7 @@ async function cmdGetMetadata(opts) {
   let value;
   try {
     value = await getMetadata(wallet, opts.key, {
-      network: resolveNetwork(opts.network)
+      network: resolveNetwork2(opts.network)
     });
   } catch (exc) {
     printOut(`error: ${errMsg4(exc)}`);
@@ -17047,7 +17745,7 @@ async function cmdShow6(networkArg) {
   const wallet = walletRt6.getWallet();
   let record;
   try {
-    record = await show2(wallet, { network: resolveNetwork(networkArg) });
+    record = await show2(wallet, { network: resolveNetwork2(networkArg) });
   } catch (exc) {
     printOut(`error: ${errMsg4(exc)}`);
     return errName2(exc) === "NotRegisteredError" ? 2 : 1;
@@ -17064,7 +17762,7 @@ async function cmdResolve(agentId, networkArg) {
   try {
     uri = await resolve20(agentId, {
       wallet,
-      network: resolveNetwork(networkArg)
+      network: resolveNetwork2(networkArg)
     });
   } catch (exc) {
     printOut(`error: ${errMsg4(exc)}`);
@@ -18576,7 +19274,10 @@ function registerX402(program) {
       return 1;
     })
   );
-  sell.command("init").description("Add the x402 seller config and missing B402 placeholders.").action(act(() => cmdSellInit()));
+  sell.command("init").description("Add the x402 seller config and missing B402 placeholders.").option(
+    "--price-usd <amount>",
+    "Per-request decimal USD price; use 0 for FREE passthrough."
+  ).action(act((opts) => cmdSellInit(opts.priceUsd)));
   sell.command("status").description("Show x402 seller config and B402 capability status.").option("--no-probe", "Skip the authenticated B402 /supported probe.").action(act((opts) => cmdSellStatus(opts.probe)));
 }
 function hostOf(url) {
@@ -18628,7 +19329,7 @@ function loadSellerConfig() {
     return null;
   }
 }
-function resolveNetwork2(cfg, override) {
+function resolveNetwork3(cfg, override) {
   if (override) {
     return override;
   }
@@ -18661,39 +19362,88 @@ function resolveWallet2() {
 function printScopeError(host) {
   printErr(`error: ${SCOPE_NOTE.replace("{host}", host)}`);
 }
-function cmdSellInit() {
+async function cmdSellInit(priceFlag) {
   const loaded = loadSellerConfig();
   if (loaded === null) return 1;
   const [root, cfg] = loaded;
+  const tomlPath = path46.join(root, "studio.toml");
+  const original = fs44.readFileSync(tomlPath, "utf8");
+  const sellerExists = hasSection(original, "payments.x402_seller");
+  let priceUsd;
+  try {
+    priceUsd = priceFlag !== void 0 ? normalizeB402PriceUsd(priceFlag) : sellerExists ? X402SellerPolicy.fromToml(cfg).priceUsd : await resolveSellInitPrice(stdinIsTty());
+  } catch (exc) {
+    printErr(`error: ${errMsg6(exc)}`);
+    return 2;
+  }
+  const free = x402SellerPricingState({ price_usd: priceUsd }).kind === "free";
   const walletKind2 = String(tableOf15(cfg, "wallet").kind ?? "evm-local");
-  if (!["evm-local", "twak"].includes(walletKind2)) {
+  if (!free && !["evm-local", "twak"].includes(walletKind2)) {
     printErr(
       `error: the b402 seller rail supports wallet.kind evm-local or twak only; '${walletKind2}' cannot act as the b402 payout wallet.`
     );
     return 1;
   }
-  const tomlPath = path46.join(root, "studio.toml");
-  const original = fs44.readFileSync(tomlPath, "utf8");
-  if (!hasSection(original, "payments.x402_seller")) {
+  if (!sellerExists) {
     fs44.writeFileSync(
       tomlPath,
       updateSection(original, "payments.x402_seller", {
         enabled: true,
-        price_usd: "0.01",
+        price_usd: priceUsd,
         assets: ["U"],
         pay_to: "",
         work_timeout_seconds: 60
       }),
       "utf8"
     );
+  } else if (priceFlag !== void 0) {
+    fs44.writeFileSync(
+      tomlPath,
+      updateSection(original, "payments.x402_seller", {
+        price_usd: priceUsd
+      }),
+      "utf8"
+    );
   }
   const envPath = envLocalPath17(root);
   for (const key of B402_ENV_KEYS) {
-    if (getEnvVar(envPath, key) === null) setEnvVar(envPath, key, "");
+    const existing = getEnvVar(envPath, key);
+    if (key === "B402_BASE_URL" && !free && resolveNetwork3(cfg).toLowerCase() === "bsc-testnet" && !process.env.B402_BASE_URL && !existing) {
+      setEnvVar(envPath, key, DEFAULT_B402_TESTNET_BASE_URL);
+    } else if (existing === null) {
+      setEnvVar(envPath, key, "");
+    }
+  }
+  printOut(
+    free ? "\u2713 x402 seller config is ready in FREE mode; B402 credentials are not required." : "\u2713 x402 seller config and B402 placeholders are ready for PAID mode."
+  );
+  if (free) {
+    printErr(
+      "warning: /x402 is an anonymous FREE endpoint; B402 verify/settle and payment audit are bypassed."
+    );
   }
-  printOut("\u2713 x402 seller config and B402 placeholders are ready.");
   return 0;
 }
+async function resolveSellInitPrice(isTty) {
+  if (!isTty) return DEFAULT_B402_PRICE_USD;
+  const choice = (await promptUser(
+    "B402/x402 pricing [paid/free/custom, Enter = paid ($0.01)]: "
+  )).trim().toLowerCase();
+  if (choice === "free") return "0";
+  if (choice === "custom") {
+    return normalizeB402PriceUsd(
+      await promptUser(
+        "B402/x402 per-request price in USD (non-negative decimal): "
+      )
+    );
+  }
+  if (choice !== "" && choice !== "paid") {
+    printErr(
+      `hint: unknown B402/x402 pricing choice '${choice}' \u2014 using paid.`
+    );
+  }
+  return DEFAULT_B402_PRICE_USD;
+}
 async function cmdSellStatus(probe) {
   const loaded = loadSellerConfig();
   if (loaded === null) return 1;
@@ -18714,9 +19464,13 @@ async function cmdSellStatus(probe) {
   };
   const privateKeySet = presence.B402_PRIVATE_KEY || presence.B402_PRIVATE_KEY_B64;
   const credentialsComplete = presence.B402_BASE_URL && presence.B402_CLIENT_ID && presence.B402_ACCESS_TOKEN && privateKeySet;
-  const state = !policy.enabled ? "disabled" : credentialsComplete ? "active-config" : "dormant";
+  const free = x402SellerPricingState({ price_usd: policy.priceUsd }).kind === "free";
+  const state = !policy.enabled ? "disabled" : free ? "free" : credentialsComplete ? "active-config" : "dormant";
   printOut(`Rail state: ${state}`);
   printOut(`  price_usd: ${policy.priceUsd}`);
+  printOut(
+    `  Pricing: ${free ? "FREE \u2014 anonymous passthrough; no payment" : "PAID \u2014 B402 verify/settle required"}`
+  );
   printOut(`  assets: ${JSON.stringify(policy.assets)}`);
   printOut(`  pay_to: ${policy.payTo ?? "(agent wallet)"}`);
   printOut(`  work_timeout_seconds: ${policy.workTimeoutSeconds}`);
@@ -18729,11 +19483,15 @@ async function cmdSellStatus(probe) {
     printOut("B402 probe: skipped (--no-probe)");
     return 0;
   }
+  if (policy.enabled && free) {
+    printOut("B402 probe: skipped (FREE bypasses B402)");
+    return 0;
+  }
   if (!policy.enabled || !credentialsComplete) {
     printOut("B402 probe: skipped (rail disabled or credentials incomplete)");
     return 0;
   }
-  const networkName = resolveNetwork2(cfg);
+  const networkName = resolveNetwork3(cfg);
   const network = caip2(getNetwork11(networkName).chainId);
   const token = SELLER_TOKENS[network];
   if (!token) {
@@ -18827,7 +19585,7 @@ async function cmdBuy2(url, opts) {
     printErr(`error: ${errMsg6(exc)}`);
     return 2;
   }
-  const networkName = resolveNetwork2(cfg, opts.network);
+  const networkName = resolveNetwork3(cfg, opts.network);
   const wallet = resolveWallet2();
   if (wallet === null) {
     return 1;
@@ -19016,7 +19774,7 @@ async function cmdTrust(merchant, opts) {
     host = rec.domain;
     methodHint = rec.probeMethod;
   }
-  const networkName = opts.network || (rec ? rec.network : resolveNetwork2(cfg, null));
+  const networkName = opts.network || (rec ? rec.network : resolveNetwork3(cfg, null));
   const probed = await probeChallenge(probeUrl, methodHint);
   if (probed === null) {
     return 1;
@@ -19162,7 +19920,7 @@ function buildProgram() {
   return program;
 }
 function cliVersion() {
-  return "0.0.6-alpha.1";
+  return "0.0.6-alpha.3";
 }
 
 // src/cli/updateCheck.ts