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

package/dist/{chunk-M3ODFCA7.js → chunk-A7NAGZHR.js}

@@ -293,6 +293,53 @@ function mb(n) {
   return `${(n / (1024 * 1024)).toFixed(1)}MB`;
 }
 
+// src/cli/_x402SellerConfig.ts
+var DEFAULT_B402_PRICE_USD = "0.01";
+var DEFAULT_B402_TESTNET_BASE_URL = "https://qacb.sdtaop.com";
+var PRICE_USD_RE = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
+var ZERO_PRICE_USD_RE = /^0(?:\.0+)?$/;
+function x402SellerPricingState(seller) {
+  const raw = seller.price_usd;
+  const priceUsd = raw === void 0 ? DEFAULT_B402_PRICE_USD : typeof raw === "string" ? raw : "";
+  if (!PRICE_USD_RE.test(priceUsd)) {
+    return { kind: "invalid", value: String(raw ?? "") };
+  }
+  return {
+    kind: ZERO_PRICE_USD_RE.test(priceUsd) ? "free" : "paid",
+    priceUsd
+  };
+}
+function normalizeB402PriceUsd(value) {
+  const normalized = value.trim();
+  if (!PRICE_USD_RE.test(normalized)) {
+    throw new Error(
+      `B402 price must be a non-negative decimal USD string; got ${JSON.stringify(value)}.`
+    );
+  }
+  return normalized;
+}
+function isB402TestnetBaseUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.origin === DEFAULT_B402_TESTNET_BASE_URL) return true;
+  } catch {
+  }
+  return /sandbox|test/.test(value.toLowerCase());
+}
+function x402SellerUsesB402(cfg) {
+  const payments = table2(cfg.payments);
+  const seller = table2(payments.x402_seller);
+  return seller.enabled === true && x402SellerPricingState(seller).kind === "paid";
+}
+function x402SellerIsFree(cfg) {
+  const payments = table2(cfg.payments);
+  const seller = table2(payments.x402_seller);
+  return seller.enabled === true && x402SellerPricingState(seller).kind === "free";
+}
+function table2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
 // src/cli/exit.ts
 var CliExit = class extends Error {
   constructor(code) {
@@ -597,10 +644,10 @@ var B402_RUNTIME_KEYS = [
   "B402_PRIVATE_KEY_B64"
 ];
 function commerceRails(cfg) {
-  const payments = table2(cfg.payments);
+  const payments = table3(cfg.payments);
   return {
     erc8183: isTable(payments.erc8183),
-    x402: table2(payments.x402_seller).enabled === true
+    x402: table3(payments.x402_seller).enabled === true
   };
 }
 function b402Credentials(agentRoot) {
@@ -611,10 +658,14 @@ function b402Credentials(agentRoot) {
     if (value) values.set(key, value);
   }
   const privateKey = values.has("B402_PRIVATE_KEY") || values.has("B402_PRIVATE_KEY_B64");
+  const onlyDefaultBaseUrl = values.size === 1 && values.get("B402_BASE_URL")?.replace(/\/+$/, "") === DEFAULT_B402_TESTNET_BASE_URL;
   return {
     presentKeys: [...values.keys()],
     complete: values.has("B402_BASE_URL") && values.has("B402_CLIENT_ID") && values.has("B402_ACCESS_TOKEN") && privateKey,
-    any: values.size > 0,
+    // The testnet facilitator URL is a non-secret platform default. On its own it must not turn an
+    // otherwise dormant rail into a "partial credentials" deployment failure. Any custom URL or
+    // merchant credential still preserves the existing partial/unused checks.
+    any: values.size > 0 && !onlyDefaultBaseUrl,
     bothPrivateKeyFormats: values.has("B402_PRIVATE_KEY") && values.has("B402_PRIVATE_KEY_B64"),
     baseUrl: values.get("B402_BASE_URL") ?? null
   };
@@ -633,15 +684,36 @@ function loadDeployConfig(root) {
 function x402DeploySummary(root, destination, publicUrl) {
   const { agentRoot, cfg } = loadDeployConfig(root);
   if (!commerceRails(cfg).x402) return "";
+  const seller = table3(table3(cfg.payments).x402_seller);
+  const pricing = x402SellerPricingState(seller);
   const credentials = b402Credentials(agentRoot);
   const activation = "run the bnbagent-studio-selling-via-b402 skill, fill the four B402_* variables in .studio/.env.local, then redeploy.";
-  if (!credentials.complete) {
-    return `x402 rail is DORMANT. To activate: ${activation}`;
-  }
-  const runtime = String(table2(cfg.stack).runtime ?? "agentcore");
+  const runtime = String(table3(cfg.stack).runtime ?? "agentcore");
   if (destination !== "platform" && runtime !== "agentcore") {
     return `x402 rail is FORCED DORMANT: the ${runtime} runtime has no x402 path. Deploy to AgentCore (managed platform or self-hosted) to activate the rail.`;
   }
+  if (pricing.kind === "invalid") {
+    return "x402 rail is DORMANT: price_usd is invalid; run `bag doctor`.";
+  }
+  if (pricing.kind === "free") {
+    if (destination !== "platform") {
+      return [
+        "x402 rail is ACTIVE in FREE mode (self-hosted AgentCore).",
+        "B402 verify/settle is bypassed; no credentials, token payment, or settlement audit is used.",
+        "This target has no anonymous public URL; expose /x402 with your own HTTP front.",
+        'The front reaches the agent by wrapping each request as envelope-v1 JSON \u2014 {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"} \u2014 inside a SigV4-signed (or JWT bearer) InvokeAgentRuntime call. Limits: 1 MiB request, 5 MiB response, no streaming.'
+      ].join("\n");
+    }
+    const url2 = publicUrl ?? "<available after the platform agentId is assigned>";
+    return [
+      "x402 rail is ACTIVE in FREE mode.",
+      `Anonymous FREE URL: ${url2}`,
+      "B402 verify/settle is bypassed; no credentials, token payment, or settlement audit is used."
+    ].join("\n");
+  }
+  if (!credentials.complete) {
+    return `x402 rail is DORMANT. To activate: ${activation}`;
+  }
   const settlement = [
     "B402 settlement runs inside every paid request and normally adds 10\u201345 s; buyer timeout must be at least 120 s.",
     "Settlement happens before work. If work later fails, the payment is retained and is not refunded automatically."
@@ -663,7 +735,7 @@ function x402DeploySummary(root, destination, publicUrl) {
     ...settlement
   ].join("\n");
 }
-function table2(value) {
+function table3(value) {
   return isTable(value) ? value : {};
 }
 function isTable(value) {
@@ -735,14 +807,14 @@ function deployCommand(environment = process.env) {
   }
   return ["bunx", "--bun", DEPLOY_CLI_PACKAGE];
 }
-function providerPassthrough(studio, table3) {
-  const raw = tableOf(studio, "deploy")[table3];
+function providerPassthrough(studio, table4) {
+  const raw = tableOf(studio, "deploy")[table4];
   if (raw === void 0 || raw === null) {
     return {};
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
     throw new Error(
-      `studio.toml [deploy.${table3}] must be a TOML table of deploy-spec keys`
+      `studio.toml [deploy.${table4}] must be a TOML table of deploy-spec keys`
     );
   }
   return { ...raw };
@@ -835,10 +907,10 @@ function buildDeploySpec(root, opts) {
     }
     doc.foundry = foundry;
   } else {
-    for (const table3 of ["agentcore", "foundry"]) {
-      if (Object.keys(providerPassthrough(studio, table3)).length > 0) {
+    for (const table4 of ["agentcore", "foundry"]) {
+      if (Object.keys(providerPassthrough(studio, table4)).length > 0) {
         printErr(
-          `note: the bnb/trial platform does not allow custom provider configuration; [deploy.${table3}] ignored`
+          `note: the bnb/trial platform does not allow custom provider configuration; [deploy.${table4}] ignored`
         );
       }
     }
@@ -848,7 +920,7 @@ function buildDeploySpec(root, opts) {
   if (opts.inlineSecrets) {
     Object.assign(env, opts.inlineSecrets);
   }
-  if (opts.target === "bnb/trial" && tableOf(studio, "deploy").destination === "platform" && (!hasProtocolsArray || hasX402Face(faces)) && commerceRails(studio).x402 && b402Credentials(agentRoot).complete) {
+  if (opts.target === "bnb/trial" && tableOf(studio, "deploy").destination === "platform" && (!hasProtocolsArray || hasX402Face(faces)) && commerceRails(studio).x402 && (x402SellerIsFree(studio) || b402Credentials(agentRoot).complete)) {
     doc.x402 = {
       publicPaths: ["/x402"],
       tunnel: "http-envelope-v1"
@@ -1019,6 +1091,13 @@ export {
   entryStemOf,
   devPortOf,
   recipeModeOf,
+  DEFAULT_B402_PRICE_USD,
+  DEFAULT_B402_TESTNET_BASE_URL,
+  x402SellerPricingState,
+  normalizeB402PriceUsd,
+  isB402TestnetBaseUrl,
+  x402SellerUsesB402,
+  x402SellerIsFree,
   whichBin,
   agentcoreFlavor,
   checkDocker,

package/dist/{deployCli-N6TPN6XA.js → deployCli-264UE6KB.js}

@@ -17,7 +17,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-M3ODFCA7.js";
+} from "./chunk-A7NAGZHR.js";
 import "./chunk-7RAKL4AS.js";
 export {
   BNB_PLATFORM_API_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.6-alpha.1",
+  "version": "0.0.6-alpha.3",
   "description": "The `bag` CLI: scaffold, run, deploy, and monetize a single seller agent on BNB Chain (ERC-8004 identity, ERC-8183 commerce, x402 payments).",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,7 @@
     "bag": "./dist/bag.js"
   },
   "dependencies": {
-    "@bnbagent/sdk": "0.5.0-alpha.1",
+    "@bnbagent/sdk": "0.5.0-alpha.2",
     "ai": "^7.0.29",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
@@ -37,7 +37,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.6-alpha.1"
+    "@bnbagent/studio-runtime": "0.0.6-alpha.3"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

package/recipes/agent/code/{{PKG}}/signing.ts.tmpl

@@ -111,6 +111,17 @@ function defaultNetworkName(): string {
   return String(((cfg.network ?? {}) as TomlTable).default ?? "bsc-testnet");
 }
 
+/**
+ * Bind provider_sig to the same Commerce deployment used by the runtime
+ * client. QA/custom stacks override the canonical SDK registry via env.
+ */
+export function commerceVerifyingContract(
+  chainId: number,
+): `0x${string}` {
+  const override = process.env.ERC8183_COMMERCE_ADDRESS?.trim();
+  return (override || deployedAddresses(chainId).commerceProxy) as `0x${string}`;
+}
+
 /**
  * Return `[minPrice, maxPrice]` in raw wei from studio.toml.
  *
@@ -182,7 +193,7 @@ function getHandler(): NegotiationHandlerLike {
       ...negotiationSignerOptions(wallet),
       quoteTtlSeconds: ttl,
       chainId: network.chainId,
-      verifyingContract: deployedAddresses(network.chainId).commerceProxy,
+      verifyingContract: commerceVerifyingContract(network.chainId),
     });
   }
   return handler;

package/recipes/runtimes/agentcore/code/{{PKG}}/dualMain.ts.tmpl

@@ -159,8 +159,9 @@ function defaultNetwork(): string {
 // the ONLY automatic signing path outside signing.ts — it is budget-gated and
 // is NOT an LLM tool. It rides transparently into the delivery step.
 //
-// The LLM runs ONLY in the delivery step (the value hook). `negotiate` is
-// rule-based and never touches the LLM. The read-only chain tools are
+// The LLM runs only in an authorized value step: verified ERC-8183 delivery
+// or x402 work after its payment/free gate. `negotiate` is rule-based and
+// never touches the LLM. The read-only chain tools are
 // attached so the work can read on-chain context if it needs to — drop them
 // from `tools.ts` if your work doesn't read chain. Signing / settle are NEVER
 // tools — they are fixed code in signing.ts, triggered by the A2A skills,
@@ -178,7 +179,9 @@ export function buildRunWork(): RunWork {
     const result = await generateText({
       model,
       system:
-        "You are a seller agent. You do the actual work once a job is funded. " +
+        "You are a seller agent. The runtime has already authorized this task " +
+        "through its configured commerce rail. Complete the user's task now; " +
+        "do not ask for a job ID or additional payment. " +
         "Be concrete and concise. Use the read-only chain tools when on-chain " +
         "context helps. If a paid-data tool such as `buy_with_x402` is available " +
         "to you, USE IT to fetch the data a task needs — those merchants (e.g. " +

package/recipes/runtimes/agentcore/code/{{PKG}}/main.ts.tmpl

@@ -150,8 +150,9 @@ function defaultNetwork(): string {
 // the ONLY automatic signing path outside signing.ts — it is budget-gated and
 // is NOT an LLM tool. It rides transparently into the delivery step.
 //
-// The LLM runs ONLY in the delivery step (the value hook). `negotiate` is
-// rule-based and never touches the LLM. The read-only chain tools are
+// The LLM runs only in an authorized value step: verified ERC-8183 delivery
+// or x402 work after its payment/free gate. `negotiate` is rule-based and
+// never touches the LLM. The read-only chain tools are
 // attached so the work can read on-chain context if it needs to — drop them
 // from `tools.ts` if your work doesn't read chain. Signing / settle are NEVER
 // tools — they are fixed code in signing.ts, triggered by the A2A skills,
@@ -169,7 +170,9 @@ export function buildRunWork(): RunWork {
     const result = await generateText({
       model,
       system:
-        "You are a seller agent. You do the actual work once a job is funded. " +
+        "You are a seller agent. The runtime has already authorized this task " +
+        "through its configured commerce rail. Complete the user's task now; " +
+        "do not ask for a job ID or additional payment. " +
         "Be concrete and concise. Use the read-only chain tools when on-chain " +
         "context helps. If a paid-data tool such as `buy_with_x402` is available " +
         "to you, USE IT to fetch the data a task needs — those merchants (e.g. " +

package/recipes/runtimes/agentcore/code/{{PKG}}/mcpMain.ts.tmpl

@@ -184,10 +184,10 @@ function flatQuery(query: Record<string, unknown>): Record<string, string> {
   return out;
 }
 
-// ── LLM work hook (lazy: built on first delivery; negotiate never needs it) ──
-// Deferred construction keeps the negotiate-only path (and a cold start that
-// only quotes) from building the model, and keeps this module importable
-// without the provider env until a deliverable is actually produced.
+// ── LLM work hook (lazy: built on first authorized task) ─────────────────────
+// Deferred construction keeps negotiate and unpaid x402 quote paths from
+// building the model, and keeps this module importable without the provider
+// env until a deliverable is actually produced.
 type RunLlm = (prompt: string) => Promise<string>;
 let cachedRunLlm: RunLlm | null = null;
 
@@ -200,7 +200,9 @@ async function runLlm(prompt: string): Promise<string> {
       const result = await generateText({
         model,
         system:
-          "You are a seller agent. You do the actual work once a job is funded. " +
+          "You are a seller agent. The runtime has already authorized this task " +
+          "through its configured commerce rail. Complete the user's task now; " +
+          "do not ask for a job ID or additional payment. " +
           "Be concrete and concise. Use the read-only chain tools when on-chain " +
           "context helps. If a paid-data tool such as `buy_with_x402` is " +
           "available to you, USE IT to fetch the data a task needs — those " +

package/recipes/runtimes/agentcore/code/{{PKG}}/sellerCore.ts.tmpl

@@ -105,8 +105,9 @@ async function withTimeout<T>(
  * The LLM work hook: produce the deliverable text for a prompt.
  *
  * Built in `main.ts` from the AI SDK (`generateText` + the read-only chain
- * tools); called ONLY inside the background delivery. `abortSignal` is wired
- * to the delivery timeout so a hung LLM call is actually cancelled.
+ * tools); called by verified ERC-8183 delivery and, through the runtime
+ * adapter, by x402 only after its commerce gate. `abortSignal` is wired to
+ * the delivery timeout so a hung LLM call is actually cancelled.
  */
 export type RunWork = (
   prompt: string,

package/skills/bnbagent-studio.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio
-description: The single entry point for bnbagent-studio — a TypeScript CLI (`bag`) for building a blockchain SELLER agent that earns $U on BNB Chain via ERC-8004 + ERC-8183 + x402 (Pieverse LLM inside). Load this skill whenever the user works in a bnbagent-studio / `bag` project, or wants to create/scaffold, deploy, run, debug, operate, or monetize such a seller agent (composable A2A, MCP, and X402 faces; BNB Chain trial, AWS AgentCore, or Azure Foundry). All detailed playbooks ship as references/ files inside this skill — route via the decision tree in the body. When invoked with arguments, treat them as the user's intent and route the same way.
+description: The single entry point for bnbagent-studio — a TypeScript CLI (`bag`) for building a blockchain SELLER agent that earns $U on BNB Chain via ERC-8004 + ERC-8183 + x402 (Pieverse LLM inside). Load this skill whenever the user works in a bnbagent-studio / `bag` project, or wants to create/scaffold, deploy, run, debug, operate, or monetize such a seller agent (composable A2A, MCP, and X402 faces; BNB Chain trial or AWS AgentCore). All detailed playbooks ship as references/ files inside this skill — route via the decision tree in the body. When invoked with arguments, treat them as the user's intent and route the same way.
 ---
 
 # bnbagent-studio (the single entry point)
@@ -10,15 +10,13 @@ ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploy
 as a **single blockchain seller runtime**. A2A, MCP, and X402 are composable
 public faces selected with `--protocols`; A2A is the default. `bag deploy` uses
 **scheme C**: every new deploy
-or redeploy explicitly selects BNB, AWS, or Azure; a recorded deployment is
+or redeploy explicitly selects BNB or AWS; a recorded deployment is
 used only to offer an explicit update action, never as a silent default. BNB is
-a 48h testnet trial and is disabled after expiry. AWS and Azure deploy into the
+a 48h testnet trial and is disabled after expiry. AWS deploys into the
 user's own account. All cloud lifecycle calls go through the pinned
-`@bnbagent/deploy-cli`; never require `aws`, `az`, or `azd` CLIs.
-BNB/AWS share the agentcore scaffold; Azure requires the azure-foundry
-container scaffold and currently deploys A2A projects only (Foundry's
-Invocations contract is not the native MCP transport). Treat an incompatible provider row as unavailable—do not
-force through it or mutate the scaffold during deploy.
+`@bnbagent/deploy-cli`; never require the `aws` CLI.
+BNB/AWS share the agentcore scaffold. Treat an incompatible provider row as
+unavailable—do not force through it or mutate the scaffold during deploy.
 
 Invoked as `/bnbagent-studio <ask>`? Treat `<ask>` as the user's intent and
 route it through the decision tree below, exactly like a natural-language ask.
@@ -33,8 +31,9 @@ bounded operations — **`negotiate`** (rule-based price clamp + EIP-191 sign;
 **no LLM touches money**) and **`notify_funded`** (verify the funded job →
 produce the deliverable → submit on-chain; A2A acks then delivers in the
 background, MCP delivers synchronously in the tool call). The optional x402
-rail adds an anonymous paid HTTP request at `/x402`; it settles through B402
-before running work and does not expose a general signing tool. Read-only chain
+rail adds an anonymous HTTP request at `/x402`; positive prices settle through
+B402 before work, while explicit zero is FREE passthrough and bypasses the
+facilitator. It does not expose a general signing tool. Read-only chain
 tools remain available. ALL signing is fixed entrypoint code in
 `app/agent/src/signing.ts` or the runtime's bounded x402 payment handler, never
 an LLM-callable tool. The encrypted keystore lives at the workspace root
@@ -55,8 +54,8 @@ not answer from memory.
 | Add wallet / the single seller runtime to an existing TypeScript agent | `references/bnbagent-studio-adding-to-project.md` |
 | Run / debug / dev / doctor / RPC / balance / incident triage | `references/bnbagent-studio-operating.md` |
 | Implement what the Agent sells, tune pricing, publish over A2A and/or MCP, defend disputes (seller flow) | `references/bnbagent-studio-selling-via-8183.md` |
-| Sell one paid HTTP request through the B402-backed x402 rail (merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
-| Deploy / redeploy / status / logs / destroy | Run `bag deploy` and explicitly choose a provider. Non-interactive deploy requires `--provider bnb\|aws\|azure --yes` (and `--allow-multiple` when keeping another provider active). Read `references/bnbagent-studio-use-bnb-trial.md`, `references/bnbagent-studio-use-aws-agentcore.md`, or `references/bnbagent-studio-use-azure-foundry.md` for the selected provider. `bag deploy status` lists every recorded provider; multi-deployment logs/verify/destroy require `--provider`. |
+| Sell one paid or FREE HTTP request through the B402-backed x402 rail (pricing choice; paid merchant application, RSA key, credentials, IP allowlist, activation) | `references/bnbagent-studio-selling-via-b402.md` |
+| Deploy / redeploy / status / logs / destroy | Run `bag deploy` and explicitly choose a provider. Non-interactive deploy requires `--provider bnb\|aws --yes` (and `--allow-multiple` when keeping another provider active). Read `references/bnbagent-studio-use-bnb-trial.md` or `references/bnbagent-studio-use-aws-agentcore.md` for the selected provider. `bag deploy status` lists every recorded provider; multi-deployment logs/verify/destroy require `--provider`. |
 | Wire chain-read tools into the Agent's LLM (AI SDK `tool()` wrappers, or any TS agent framework) | `references/bnbagent-studio-wiring-llm-tools.md` |
 | Buy a service from another ERC-8183 seller via CLI — incl. testing your own seller from the buyer side (v2/internal — NOT the v1 seller product flow) | `references/bnbagent-studio-buying-via-8183.md` |
 | Give the agent a PAID x402 capability — CMC market data / Binance Bazaar (B402) merchants / any pay-per-call API (`bag x402 trust`, x402-buyer recipe, 402 buyer errors) | `references/bnbagent-studio-buying-from-bazaar.md` |
@@ -84,13 +83,21 @@ must NOT be added to the description — see docs/design/decisions.md §14. -->
 
 1. **Agent project code is user-owned** — recipe-emitted files are theirs to edit; studio doesn't auto-rewrite them.
 2. **Private keys live in a user-controlled environment, never transmitted to studio or third parties** — the encrypted keystore lives at the workspace root, outside the deploy codeLocation (no packaging path can bundle it). Altana keeps its admin keystore there and gives local runtime only a bounded session; deployment is blocked. Other supported deploy paths inject only their required wallet material into the selected runtime secret channel. (Scoped, consented exception: provider `bnb`, the 48h testnet trial — testnet-forced, throwaway wallet recommended.)
-3. **Signing is fixed handler code, never an LLM-callable tool** — the ERC-8183 rail exposes bounded `negotiate` / `notify_funded` flows and the x402 rail exposes a bounded paid-request handler; raw/arbitrary signing is never exposed. Read-only chain queries remain read-only tools.
+3. **Signing is fixed handler code, never an LLM-callable tool** — the ERC-8183 rail exposes bounded `negotiate` / `notify_funded` flows and the x402 rail exposes a bounded request handler; raw/arbitrary signing is never exposed. Read-only chain queries remain read-only tools.
 4. **SDK protocol layer stays pure** — studio's opinions don't pollute `bnbagent-sdk`.
 5. **The user can jump ship at any point** — emitted code is theirs to edit / fork / migrate; studio depends on no closed SaaS. Emitted code imports from `@bnbagent/studio-runtime` and depends on that runtime lib (not the CLI), so uninstalling the `@bnbagent/studio-cli` package never breaks a deployed agent.
 
+Treat ERC-8183 amounts as decimal strings at CLI/config boundaries and
+`bigint` internally. `price = "0"` is an explicit FREE choice, not a missing
+value; it requires all three contract-address overrides from one verified
+zero-price-compatible stack.
+Treat B402 `price_usd` as a decimal string too. `"0"` is explicit anonymous
+FREE passthrough: B402 verify/settle and secret injection are skipped. Positive
+prices retain the paid merchant flow.
+
 ## CLI groups at a glance
 
-`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` — see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure]` is the primary deploy command; `prepare`, `verify`, `status`, `info`, `destroy`, `logs`, `fix-gitignore`, and `provision-cognito` remain lifecycle subcommands (`deploy agent` is a deprecated compatibility alias). Provider deploy/status/logs/destroy and deploy-time credential validation are delegated to pinned `@bnbagent/deploy-cli@0.4.14`.
+`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` — see `bag --help` for details. `bag deploy [--provider bnb\|aws]` is the primary deploy command; `prepare`, `verify`, `status`, `info`, `destroy`, `logs`, `fix-gitignore`, and `provision-cognito` remain lifecycle subcommands (`deploy agent` is a deprecated compatibility alias). Provider deploy/status/logs/destroy and deploy-time credential validation are delegated to pinned `@bnbagent/deploy-cli@0.4.14`.
 
 ## Tool surface
 

package/skills/references/bnbagent-studio-adding-to-project.md

@@ -131,6 +131,22 @@ the configured list price, clamps it to `[min_price, max_price]`, then
 from the request *before* clamping — the LLM still never sets the price. The
 buyer anchors the signed envelope on-chain via `createJob` + `fund`.
 
+Use `bag config set payments.erc8183.price 0` only for an explicit FREE
+product decision. Studio stores ERC-8183 amounts as decimal strings and reports
+FREE in `bag doctor`. Zero funding also requires commerce, router, and policy
+from one compatible stack: set all three `ERC8183_*_ADDRESS` overrides, then
+require `bag doctor` and `bag deploy prepare` to pass. The buyer still runs
+`setBudget(0)` and `fund(0)`, but no ERC-20 approval or token escrow occurs.
+
+For an X402 face, choose its request price independently. Use
+`bag config set payments.x402_seller.price_usd 0` only when the existing agent
+is intentionally becoming an unrestricted anonymous FREE API. This path
+bypasses B402 verify/settle, payment, and settlement audit; it needs no merchant
+credentials and Studio will not synchronize any configured B402 secrets.
+Positive prices retain the paid B402 onboarding and settle-before-work flow.
+Verify the choice with `bag x402 sell status`, `bag doctor`, and
+`bag deploy prepare`.
+
 ## Step 4c — LLM credit continuity (automatic, NOT an LLM tool)
 
 For Pieverse projects, the Agent's `buildModel()` factory in the emitted
@@ -155,7 +171,7 @@ refill with `bag llm topup` or enable the budget with `bag budget enable`.
 
 ## Step 5 — Deploy the agent
 
-`bag deploy` always asks the operator to choose BNB, AWS, or Azure; it never
+`bag deploy` always asks the operator to choose BNB or AWS; it never
 silently reuses `[deploy].destination` or the last provider.
 
 **Platform scaffold** (the bare-init default while the campaign runs) — one

package/skills/references/bnbagent-studio-buying-via-8183.md

@@ -56,13 +56,17 @@ flow now auto-adds dispute_window).
 ## Preconditions
 
 - `bag doctor` is clean (or only warns on LLM key)
-- Wallet has ≥ 0.05 tBNB (gas) and ≥ 0.2 U (token + slack). On BSC testnet the
+- For a paid job, the wallet has ≥ 0.05 tBNB (gas) and enough U for the budget
+  plus slack. On BSC testnet the
   ERC-8183 kernel writes (`createJob` / `fund` deposit / `settle` …) are
   gas-sponsored via the SDK's MegaFuel paymaster, so you spend far less tBNB than
   that — but **not zero**: `fund` sends an ERC-20 `approve` (a token call, not
   sponsored) when the token allowance is too low — typically just the first fund,
   since studio approves a floored cap that later jobs reuse. Keep a little tBNB for
-  it. (Mainnet is never sponsored.)
+  it. (Mainnet is never sponsored.) For a FREE job, use `--budget-u 0`: no U
+  balance, ERC-20 approval, or token escrow is needed, but the ERC-8183 writes
+  still need the selected gas/paymaster path and a zero-price-compatible
+  commerce/router/policy stack.
 - You know the **provider's wallet address** (the seller agent's address)
 - The seller is **reachable** (its A2A agent is deployed somewhere); discoverable
   via the provider's `bag erc8004 resolve <agent_id>` endpoint URI
@@ -110,6 +114,13 @@ bag erc8183 buy --provider <provider_addr> "<task description>" \
 # `--agent-id` resolves the endpoint + negotiates first.
 ```
 
+For a signed FREE quote:
+
+```bash
+bag erc8183 buy --provider <provider_addr> "<task description>" \
+  --budget-u 0 --deadline-min 30 --network bsc-testnet
+```
+
 > **Task can be passed two ways** (both accepted): as a positional argument
 > `bag erc8183 buy --provider <addr> "<task>"` OR via the flag
 > `bag erc8183 buy --provider <addr> --task "<task>"`. Pass it once — supplying
@@ -120,7 +131,8 @@ The 4 on-chain steps run sequentially:
 1. `createJob(provider, expiredAt, description)` → returns `job_id`
 2. `registerJob(jobId)`
 3. `setBudget(jobId, rawBudget)`
-4. `fund(jobId, rawBudget, approveFloor=rawBudget)` — auto-approves U
+4. `fund(jobId, rawBudget, approveFloor=rawBudget)` — auto-approves U only
+   when the positive budget needs allowance; budget 0 skips approval and escrow
 
 Output prints 4 tx hashes + `job_id`. Note the `job_id` for later.
 
@@ -212,6 +224,10 @@ bag erc8183 status $JOB
 bag erc8183 settle $JOB --action dispute
 ```
 
+For the FREE regression, change the budget to `0` and confirm the compatible
+contract job still reaches `FUNDED` and `SUBMITTED` without an ERC-20 approval
+or balance change.
+
 This is the exact end-to-end flow used to validate real-chain buying. See the
 references below for the canonical picture.
 

package/skills/references/bnbagent-studio-operating.md

@@ -27,11 +27,11 @@ directory (Claude Code: `~/.claude/skills/bnbagent-studio/references/`; Cursor:
 the file when the topic comes up — don't answer from memory:
 - `bnbagent-studio-use-aws-agentcore.md` — the delegated AgentCore lifecycle (`bag deploy --provider aws` / `status` / `logs` / `verify` / `destroy`, `provision-cognito`) + AWS prerequisites
 - `bnbagent-studio-use-bnb-trial.md` — GitHub device login, 48h eligibility, staging verification, and the delegated BNB trial lifecycle
-- `bnbagent-studio-use-azure-foundry.md` — the delegated Azure Foundry lifecycle (`bag deploy --provider azure`; no `az`/`azd` CLI)
 - `bnbagent-studio-using-twak-wallet.md` — `[wallet].kind = "twak"` create / fund / SIWE-bind / container deploy / limitations
 - `bnbagent-studio-extending-signing.md` — `PolicyViolation` / `X402PolicyError` diagnosis + extending the EIP-712 allowlist
 - `bnbagent-studio-adding-to-project.md` — adding the seller runtime to an existing TypeScript project
 - `bnbagent-studio-buying-via-8183.md` — buyer flow (find provider → buy → fetch → settle)
+- `bnbagent-studio-selling-via-b402.md` — inbound x402 pricing mode, paid merchant setup, and B402 settlement operations
 
 This playbook covers **generic ops**: dev / doctor / balances / RPC / incident triage.
 For seller job-lifecycle decisions (settle / submit / dispute defense), read
@@ -49,12 +49,13 @@ For seller job-lifecycle decisions (settle / submit / dispute defense), read
 | "how much have I approved 0x... for?" | ⚠️ **v0.2 backlog — `bag erc20 allowance` does not exist in v0.0.x** |
 | "is my agent registered?" | `bag erc8004 show` (note: registration is normally automatic at `bag deploy verify` — manual `bag erc8004 register` only if you need an identity before deploy) |
 | "what's the status of job X?" | `bag erc8183 status <id>` (read-only — neutral) |
+| "is `/x402` paid or free?" | `bag x402 sell status` (`Rail state: paid` probes B402 unless `--no-probe`; `free` skips B402) |
 | "settle job X" | `bag erc8183 settle <id> --action approve\|reject\|dispute` (default `approve`) — **seller's manual step** after the dispute window; deeper context in `bnbagent-studio-selling-via-8183.md` (same directory) |
 | "submit work for job X" | **seller action** — read `bnbagent-studio-selling-via-8183.md` (same directory) for the submit/dispute flow |
 | "tx not confirming" | Read BscScan link from prior tx output + check `eth_getTransactionCount` |
 | "wallet balance is wrong" | Check both tBNB (gas) and U (token); see balance section |
-| "is it deployed?" / "deploy status" | `bag deploy status` lists every locally recorded BNB/AWS/Azure deployment and asks `bnbagent-deploy` for live state; add `--no-probe` for record-only output |
-| "deploy logs" / "verify" / "tear it down" | With one recorded deployment, `bag deploy {logs,verify,destroy}` selects it automatically. With multiple, choose interactively or pass `--provider bnb\|aws\|azure` in automation. Cloud calls always go through `bnbagent-deploy`. `bag platform credit` shows the BNB trial countdown. |
+| "is it deployed?" / "deploy status" | `bag deploy status` lists every locally recorded BNB/AWS deployment and asks `bnbagent-deploy` for live state; add `--no-probe` for record-only output |
+| "deploy logs" / "verify" / "tear it down" | With one recorded deployment, `bag deploy {logs,verify,destroy}` selects it automatically. With multiple, choose interactively or pass `--provider bnb\|aws` in automation. Cloud calls always go through `bnbagent-deploy`. `bag platform credit` shows the BNB trial countdown. |
 
 ## Common ops procedures
 
@@ -158,6 +159,19 @@ The `--all` form is the right move when `app/agent/studio.toml`'s
 testnet U pays ERC-8183 jobs, mainnet U pays the Pieverse LLM auto-renew.
 Same wallet address on both chains.
 
+`bag doctor` prints ERC-8183 pricing as `PAID` or `FREE`. FREE is not ready on
+the canonical contract stack: select one zero-price-compatible custom stack
+by setting `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and
+`ERC8183_POLICY_ADDRESS` together. A partial set fails because it can mix
+incompatible commerce, router, and policy deployments.
+
+For the inbound x402 seller rail, `bag doctor` also prints `PAID` or `FREE`.
+PAID requires the complete B402 merchant credential set and an `evm-local` or
+`twak` payout wallet. Explicit zero is anonymous FREE passthrough: it does not
+read B402 credentials, call the facilitator, settle a payment, or apply the
+paid-mode payout-wallet allowlist. Confirm the same state with
+`bag x402 sell status`.
+
 > ⚠️ **v0.2 backlog — not in v0.0.x.** There is **no** `bag wallet transfer`,
 > no `bag erc20 approve/allowance` group, and no `bag wallet balance --address`
 > / `--token` flag in v0.0.x — running any of them errors with
@@ -201,6 +215,10 @@ covered in `bnbagent-studio-selling-via-8183.md` (same directory).
 | `notify_funded` replies `{"status":"rejected","reason":...}` | `verifySignedJob` failed synchronously in the ack — a **permanent** failure | `reason` names it: not our signature / tampered terms / underfunded / expired (or `error` for a malformed `job_id`). The job is refused outright; re-fund/re-notify with a correct, fully-funded job |
 | Job stays `FUNDED`, never reaches `SUBMITTED` after an `accepted` ack | Background delivery failed (`runWork` / `submitResult` raised) — **not** visible in the A2A reply | The ack only confirms verify passed; delivery runs in the background. Observe the failure via the chain (job never leaves `FUNDED`) + CloudWatch logs; a later `notify_funded` re-attempts it via the sweep |
 | `ERC8183JobOps` has no such export from `@bnbagent/sdk` | package.json pinned an old `@bnbagent/sdk` (missing class) | Bump the dependency and reinstall |
+| FREE price fails doctor/prepare on canonical contracts | `price = "0"` is selected without a zero-price-compatible stack | Set all three `ERC8183_*_ADDRESS` overrides from one compatible custom deployment, then rerun `bag doctor` and `bag deploy prepare` |
+| ERC-8183 contract override is incomplete | Only one or two of commerce/router/policy were selected | Set or remove all three together; never mix stacks |
+| `/x402` is public without a 402 challenge | `payments.x402_seller.price_usd = "0"` selected anonymous FREE passthrough | If payment is intended, set a positive decimal price, configure the complete B402 credential set, rerun `bag doctor`, and redeploy |
+| B402 credentials are missing but x402 reports FREE | Expected: FREE bypasses B402 and does not synchronize its secrets | No credential fix is needed; change to a positive price only when the route should charge |
 | `OPENROUTER_API_KEY env var is required` | Loading the entrypoint triggers the emitted `buildModel()` factory | Set the env var even for `bag dev --help` smoke |
 | RPC `limit exceeded` | Public RPC throttle | Retry, or set `STUDIO_BSC_TESTNET_RPC=<private rpc>` |
 

package/skills/references/bnbagent-studio-scaffolding-agent.md

@@ -117,6 +117,8 @@ The fields (give the user all of them at once):
 | 7 | **LLM model** | provider catalogue; for `pieverse-llm` the default `auto/free` runs at $0/token | `auto/free` |
 | 8 | **Auto-topup** | `enable` / `disable` — lets the Agent auto-pay $U from the wallet when LLM credits run low | deferred (non-interactive `bag init` records no `[budget]`; enable later with `bag budget enable`) |
 | 9 | **Scaffold destination** (`--destination`) | `self` (prepare the AgentCore scaffold for **your own** AWS account; runtime material stays under your cloud-account control) / `platform` (prepare for a 48h **testnet-only** trial on the BNB Chain managed platform — runs the *same* agent in the **operator's** AWS, so a wallet key **leaves your control**; it hard-forces `[network].default = bsc-testnet`, pins runtime=`agentcore`, packages an artifact, and auth is GitHub device flow. Use a **throwaway** `bag wallet new`, never your main wallet). This is scaffold intent only; deploy still explicitly selects `--provider`. | `platform` while the trial campaign runs (bare init falls back to `self` once it ends, or when `--network bsc-mainnet` / a non-agentcore `--runtime` is passed) |
+| 10 | **ERC-8183 price** (`--erc8183-price`) | non-negative integer string in token base units; `0` explicitly selects FREE | `100000000000000000` (0.1 U) |
+| 11 | **B402/x402 price** (`--b402-price`, when the b402 rail is selected) | non-negative decimal USD string; `0` explicitly selects anonymous FREE passthrough and bypasses B402 | `0.01` |
 
 v1 is **seller-only** — there is no role to choose. `bag init` scaffolds the
 single seller agent under `app/agent/` (serves the selected public faces,
@@ -215,7 +217,7 @@ Step 6b when `storage=ipfs`):
 > keep steps 3/4/6 below. Pass `--no-onboard` to `bag init` to make this
 > explicit and deterministic regardless of how the shell wires stdin.
 
-1. `bag init <name> --llm-provider <p> --network <n> --storage-provider <s> --wallet-kind <k> --no-onboard`
+1. `bag init <name> --llm-provider <p> --network <n> --storage-provider <s> --wallet-kind <k> --rails <8183|b402|both> [--erc8183-price <base-units>] [--b402-price <usd>] --no-onboard`
    — scaffold the v0.0.1 workspace. **`<name>` must start with a letter and be
    ≤23 chars after sanitizing** — `bag init` auto-drops `-`/`_` for the
    AgentCore name (printing what it used) but errors if the alphanumeric form
@@ -229,7 +231,16 @@ Step 6b when `storage=ipfs`):
    faces (omit for A2A default; `--protocol <one>` is only a legacy alias), add
    `--model <m>` only if the user overrode the provider default, and
    `--enable-auto-topup` / `--no-auto-topup` only if they made an explicit
-   choice (otherwise omit — consent stays deferred). **Destination:** while the
+   choice (otherwise omit — consent stays deferred). Pass
+   `--erc8183-price 0` only when the user explicitly chose FREE; omitting the
+   flag preserves the paid 0.1 U default. FREE additionally requires all three
+   `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and
+   `ERC8183_POLICY_ADDRESS` values from one zero-price-compatible custom
+   stack; set them with `bag env set` after scaffolding. For B402, pass
+   `--b402-price 0` only after the user explicitly accepts an unrestricted
+   anonymous FREE `/x402` endpoint. FREE bypasses B402 verify/settle and needs
+   no merchant credentials; a positive price keeps the `$0.01` default and
+   requires the paid onboarding playbook. **Destination:** while the
    trial campaign runs, bare `bag init` (no `--destination`) defaults to
    `platform` — so pass `--destination self` **explicitly** whenever the user
    chose their own AWS, otherwise studio.toml silently records `platform` and the
@@ -344,7 +355,11 @@ Step 6b when `storage=ipfs`):
    brand-new seller can scaffold, run `bag dev`, and deploy with an empty
    wallet. `bag doctor` and `bag deploy` only **WARN** (never block) on zero
    balance. Funding is needed later only for: a paid LLM model, on-chain
-   settle, or paying ERC-8183 job buys. When that time comes, the wallet uses
+   settle, paying positive-price ERC-8183 job buys, or buying/smoking a PAID
+   B402 request. A FREE ERC-8183 buy needs no U
+   escrow or ERC-20 approval, but still needs the ERC-8183 state-changing calls
+   and their gas/paymaster path. A FREE B402/x402 request needs neither token
+   funding nor a facilitator call. When funding is needed, the wallet uses
    **TWO distinct U balances on TWO chains** (same wallet address, same private
    key, different chains):