@bnbagent/studio-cli 0.0.11-alpha.2 → 0.0.11-alpha.3

package/dist/{chunk-TTPOH453.js → chunk-MIYN6U2D.js}

@@ -8,9 +8,9 @@ import {
 } from "./chunk-RO726HJG.js";
 
 // src/cli/_deploy/deployCli.ts
-import * as fs4 from "fs";
+import * as fs5 from "fs";
 import * as os from "os";
-import * as path5 from "path";
+import * as path6 from "path";
 import {
   findSubProjectRoot as findSubProjectRoot2,
   loadStudioToml as loadStudioToml3
@@ -662,36 +662,82 @@ function readAwsTarget(root, targetName = DEFAULT_TARGET_NAME) {
 }
 
 // src/cli/_deploy/x402.ts
-import * as path4 from "path";
+import * as path5 from "path";
 import {
   envLocalPath,
   findSubProjectRoot,
   loadStudioToml as loadStudioToml2
 } from "@bnbagent/studio-runtime/config";
 
-// src/cli/utils/envFile.ts
+// src/cli/_packageMetadata.ts
 import * as fs3 from "fs";
 import * as path3 from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  let dir = path3.dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    const packageJson = path3.join(dir, "package.json");
+    if (fs3.existsSync(packageJson)) return dir;
+    const parent = path3.dirname(dir);
+    if (parent === dir) {
+      throw new Error("cannot locate the studio-cli package root");
+    }
+    dir = parent;
+  }
+}
+function studioCliVersion() {
+  if ("0.0.11-alpha.3") {
+    return "0.0.11-alpha.3";
+  }
+  const file = path3.join(packageRoot(), "package.json");
+  const pkg = JSON.parse(fs3.readFileSync(file, "utf-8"));
+  const value = String(pkg.version ?? "");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(value)) {
+    throw new Error(
+      `studio-cli package.json must contain a valid version in ${file}`
+    );
+  }
+  return value;
+}
+function pnpmVersion() {
+  if ("10.24.0") {
+    return "10.24.0";
+  }
+  const file = path3.join(packageRoot(), "package.json");
+  const pkg = JSON.parse(fs3.readFileSync(file, "utf-8"));
+  const value = String(pkg.packageManager ?? "");
+  const match = /^pnpm@(.+)$/u.exec(value);
+  if (!match?.[1]) {
+    throw new Error(
+      `studio-cli packageManager must pin pnpm (expected "pnpm@<version>" in ${file})`
+    );
+  }
+  return match[1];
+}
+
+// src/cli/utils/envFile.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
 var KEY_LINE_RE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/;
 function isValidKey(key) {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
 }
 function writePrivate(filePath, text) {
-  fs3.writeFileSync(filePath, text, { encoding: "utf-8", mode: 384 });
-  fs3.chmodSync(filePath, 384);
+  fs4.writeFileSync(filePath, text, { encoding: "utf-8", mode: 384 });
+  fs4.chmodSync(filePath, 384);
 }
 function setEnvVar(filePath, key, value) {
   if (!isValidKey(key)) {
     throw new Error(`invalid env var name: '${key}'`);
   }
   const newLine = `${key}=${value}`;
-  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
-  if (!fs3.existsSync(filePath)) {
+  fs4.mkdirSync(path4.dirname(filePath), { recursive: true });
+  if (!fs4.existsSync(filePath)) {
     writePrivate(filePath, `${newLine}
 `);
     return true;
   }
-  const original = fs3.readFileSync(filePath, "utf-8");
+  const original = fs4.readFileSync(filePath, "utf-8");
   const lines = original.split(/\r?\n/);
   if (lines.length > 0 && lines[lines.length - 1] === "") {
     lines.pop();
@@ -722,10 +768,10 @@ function setEnvVar(filePath, key, value) {
   return true;
 }
 function getEnvVar(filePath, key) {
-  if (!fs3.existsSync(filePath)) {
+  if (!fs4.existsSync(filePath)) {
     return null;
   }
-  for (const line of fs3.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
+  for (const line of fs4.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
     const m = KEY_LINE_RE.exec(line);
     if (m && m[1] === key) {
       const eq = line.indexOf("=");
@@ -779,7 +825,7 @@ function loadDeployConfig(root) {
   try {
     return {
       agentRoot,
-      cfg: loadStudioToml2(path4.join(agentRoot, "studio.toml"))
+      cfg: loadStudioToml2(path5.join(agentRoot, "studio.toml"))
     };
   } catch {
     return { agentRoot, cfg: {} };
@@ -799,7 +845,7 @@ function x402DeploySummary(root, destination, publicUrl) {
   const azure = runtime === "azure-foundry";
   const runtimeLabel = azure ? "Azure Foundry" : "AgentCore";
   const tunnelLine = azure ? 'The front wraps each request as envelope-v1 JSON, {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"}, inside an Entra-authenticated Foundry invocation (POST \u2026/agents/<name>/endpoint/protocols/invocations with an https://ai.azure.com bearer). Limits: 1 MiB request, 5 MiB response, no streaming.' : 'The front wraps each request as envelope-v1 JSON, {"v":1,"method":"POST","path":"/x402","headers":{...},"body":"<base64>"}, inside an authenticated AgentCore invocation. The default Bag self-deploy uses Cognito OAuth over HTTPS; IAM runtimes may use SDK/SigV4. Limits: 1 MiB request, 5 MiB response, no streaming.';
-  const gatewayDocLine = azure ? "Gateway example: https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway-azure.md" : "Gateway example: https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md";
+  const gatewayDocLine = azure ? `Gateway example: https://unpkg.com/@bnbagent/studio-cli@${studioCliVersion()}/skills/references/bnbagent-studio-use-azure-foundry.md#x402-external-gateway` : "Gateway example: https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md";
   if (pricing.kind === "invalid") {
     return "x402 rail is DORMANT: price_usd is invalid; run `bag doctor`.";
   }
@@ -899,7 +945,7 @@ function tableOf(data, key) {
 function descriptorName(root) {
   try {
     const raw = JSON.parse(
-      fs4.readFileSync(path5.join(root, "agentcore", "agentcore.json"), "utf-8")
+      fs5.readFileSync(path6.join(root, "agentcore", "agentcore.json"), "utf-8")
     );
     if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
       const name = raw.name;
@@ -936,9 +982,9 @@ function providerPassthrough(studio, table4) {
 }
 function buildDeploySpec(root, opts) {
   const agentRoot = findSubProjectRoot2("agent", root) ?? root;
-  const studio = loadStudioToml3(path5.join(agentRoot, "studio.toml"));
+  const studio = loadStudioToml3(path6.join(agentRoot, "studio.toml"));
   const name = String(
-    opts.nameOverride || descriptorName(root) || tableOf(studio, "project").name || path5.basename(root)
+    opts.nameOverride || descriptorName(root) || tableOf(studio, "project").name || path6.basename(root)
   );
   const stack = tableOf(studio, "stack");
   const payments = tableOf(studio, "payments");
@@ -960,7 +1006,7 @@ function buildDeploySpec(root, opts) {
     OTEL_TRACES_EXPORTER: "none"
   };
   if (isContainer) {
-    deploy.dockerfile = path5.join(agentRoot, "Dockerfile");
+    deploy.dockerfile = path6.join(agentRoot, "Dockerfile");
   } else {
     if (!opts.zip) {
       throw new Error("zip packaging requires a prebuilt zip artifact");
@@ -1066,27 +1112,27 @@ function renderSecretEnvFile(payload) {
 `).join("");
 }
 function writePrivateSync(filePath, content) {
-  fs4.writeFileSync(filePath, content, { mode: 384 });
-  fs4.chmodSync(filePath, 384);
+  fs5.writeFileSync(filePath, content, { mode: 384 });
+  fs5.chmodSync(filePath, 384);
 }
 async function withDeployFiles(root, opts, fn) {
-  const scratch = fs4.mkdtempSync(path5.join(os.tmpdir(), "bag-deploy-"));
+  const scratch = fs5.mkdtempSync(path6.join(os.tmpdir(), "bag-deploy-"));
   try {
     let zip;
     if (opts.packaging === "zip") {
       const agentRoot = findSubProjectRoot2("agent", root) ?? root;
       const studio = loadStudioToml3(
-        path5.join(agentRoot, "studio.toml")
+        path6.join(agentRoot, "studio.toml")
       );
       const stack = tableOf(studio, "stack");
       const faces = stackFaces(stack, tableOf(studio, "payments"));
-      const outZip = path5.join(scratch, "code.zip");
+      const outZip = path6.join(scratch, "code.zip");
       const built = await (opts.buildZipFn ?? buildZip)(agentRoot, outZip, {
         protocols: faces
       });
       zip = { path: outZip, entrypoint: built.entrypoint };
     }
-    const secretFile = path5.join(scratch, "secrets.env");
+    const secretFile = path6.join(scratch, "secrets.env");
     const inline = opts.inlineSecrets;
     const payload = opts.secrets ?? {};
     const spec = buildDeploySpec(root, {
@@ -1100,11 +1146,11 @@ async function withDeployFiles(root, opts, fn) {
     if (!inline && Object.keys(payload).length > 0) {
       writePrivateSync(secretFile, renderSecretEnvFile(payload));
     }
-    const configPath = path5.join(scratch, "agent-deploy.toml");
+    const configPath = path6.join(scratch, "agent-deploy.toml");
     writePrivateSync(configPath, tomlStringify(spec.doc));
     return await fn({ configPath, scratchDir: scratch }, spec);
   } finally {
-    fs4.rmSync(scratch, { recursive: true, force: true });
+    fs5.rmSync(scratch, { recursive: true, force: true });
   }
 }
 var BUNX_HINT = "error: could not start bnbagent-deploy (bunx not found); install Bun 1.3+ or set BNBAGENT_DEPLOY_COMMAND.";
@@ -1129,7 +1175,7 @@ function bunxInstallDir(environment = process.env) {
     return null;
   }
   const uid = typeof process.getuid === "function" ? process.getuid() : null;
-  return uid === null ? null : path5.join(os.tmpdir(), `bunx-${uid}-${DEPLOY_CLI_PACKAGE}`);
+  return uid === null ? null : path6.join(os.tmpdir(), `bunx-${uid}-${DEPLOY_CLI_PACKAGE}`);
 }
 async function bunxTreeIsIncomplete() {
   const [bin, ...prefix] = deployCommand();
@@ -1148,14 +1194,14 @@ async function withBunxSelfHeal(hasFailed, attempt) {
   if (dir === null || !await bunxTreeIsIncomplete()) {
     return first;
   }
-  if (!fs4.existsSync(dir)) {
+  if (!fs5.existsSync(dir)) {
     printErr(BUNX_TREE_HINT);
     return first;
   }
   printErr(
     `note: ${DEPLOY_CLI_PACKAGE} failed to load its dependencies; clearing its incomplete bunx install and retrying once (${dir}).`
   );
-  fs4.rmSync(dir, { recursive: true, force: true });
+  fs5.rmSync(dir, { recursive: true, force: true });
   const second = await attempt();
   if (hasFailed(second)) {
     printErr(BUNX_TREE_HINT);
@@ -1228,9 +1274,9 @@ async function runPlatformAccountCommand(argv, opts = {}) {
   if (!opts.slug) {
     return run([...argv, "--provider", "bnb"]);
   }
-  const scratch = fs4.mkdtempSync(path5.join(os.tmpdir(), "bag-platform-"));
+  const scratch = fs5.mkdtempSync(path6.join(os.tmpdir(), "bag-platform-"));
   try {
-    const configPath = path5.join(scratch, "agent-deploy.toml");
+    const configPath = path6.join(scratch, "agent-deploy.toml");
     writePrivateSync(
       configPath,
       tomlStringify({
@@ -1241,7 +1287,7 @@ async function runPlatformAccountCommand(argv, opts = {}) {
     );
     return await run([...argv, "--provider", "bnb", "-f", configPath], scratch);
   } finally {
-    fs4.rmSync(scratch, { recursive: true, force: true });
+    fs5.rmSync(scratch, { recursive: true, force: true });
   }
 }
 
@@ -1281,6 +1327,8 @@ export {
   deployChecks,
   render,
   readAwsTarget,
+  studioCliVersion,
+  pnpmVersion,
   B402_RUNTIME_KEYS,
   X402_CAPABLE_RUNTIMES,
   commerceRails,

package/dist/{deployCli-K55GXDVO.js → deployCli-AED2MLUB.js}

@@ -18,7 +18,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-TTPOH453.js";
+} from "./chunk-MIYN6U2D.js";
 import "./chunk-RO726HJG.js";
 export {
   BNB_PLATFORM_API_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.11-alpha.2",
+  "version": "0.0.11-alpha.3",
   "description": "Skills-first toolkit and bag CLI for BNB Chain seller agents: ERC-8004 identity, ERC-8183 escrowed commerce, and x402 payments.",
   "keywords": [
     "bnb-chain",
@@ -54,7 +54,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.11-alpha.2"
+    "@bnbagent/studio-runtime": "0.0.11-alpha.3"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

package/skills/references/bnbagent-studio-selling-via-b402.md

@@ -1,6 +1,6 @@
 ---
 name: bnbagent-studio-selling-via-b402
-description: When the user wants a bnbagent-studio agent to sell paid or FREE HTTP requests through the B402-backed x402 rail. Owns the explicit pricing choice and, for PAID mode, per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
+description: When the user wants a bnbagent-studio agent to sell paid or FREE HTTP requests through the B402-backed x402 rail. Owns the explicit pricing choice and, for PAID mode, per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform, self-hosted AgentCore, or self-hosted Azure Foundry).
 ---
 
 > **Reference file** of the `bnbagent-studio` router skill, installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
@@ -30,7 +30,7 @@ bag config set payments.x402_seller.price_usd 0
 
 `"0"` means anonymous FREE passthrough. The runtime returns work directly and does not issue a 402 challenge, call B402 `/supported`/verify/settle, transfer U, or write an `x402_sell` settlement audit. B402 credentials are ignored and not synchronized. Run `bag x402 sell status`, `bag doctor`, and `bag deploy prepare`; all must label the route FREE.
 
-This is unrestricted public access. Confirm that intent before continuing. Managed platform still publishes the route through its gateway; self-hosted AgentCore still needs an envelope-v1 front; Azure Foundry remains unsupported. If FREE is the selected product, skip the merchant/RSA/IP sections below.
+This is unrestricted public access. Confirm that intent before continuing. Managed platform still publishes the route through its gateway; self-hosted AgentCore and Azure Foundry deploys still need an envelope-v1 front. If FREE is the selected product, skip the merchant/RSA/IP sections below.
 
 ## Generate the agent's RSA material
 
@@ -64,7 +64,7 @@ The current B402 request-signing contract explicitly requires a 1024-bit RSA key
 
 B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the agent's facilitator calls come FROM. Submit every part that applies to your deployment target:
 
-1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses that the platform B402 Relay uses to reach the facilitator. The managed deployment worker points only the AgentCore runtime copy of `B402_BASE_URL` at this Relay. Refresh and read the interactive session without printing its bearer:
+1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses that the platform B402 Relay uses to reach the facilitator. The managed deployment worker points the runtime copy of `B402_BASE_URL` at this Relay on both managed backends (AgentCore and Azure Foundry). Refresh and read the interactive session without printing its bearer:
 
    ```bash
    bag platform whoami >/dev/null
@@ -89,6 +89,8 @@ B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the agen
 
    As an alternative, use AWS-supported AgentCore VPC mode with a private subnet, NAT Gateway, and Elastic IP. Submit the Elastic IP and keep `B402_BASE_URL` pointed at the facilitator. Studio does not deploy or manage that AWS network.
 
+4. **Self-hosted Azure Foundry egress (self-deploys)**: Foundry hosted-agent containers have floating egress just like AgentCore, so the agent must NOT call the facilitator directly. Run the envelope gateway on a Container Apps workload-profiles environment whose subnet has a NAT Gateway with a Standard static public IP, co-host a restricted B402 forwarder there (the AWS guide's Relay example works verbatim — the NAT Gateway replaces its fixed-IP host requirement), point the runtime `B402_BASE_URL` at that forwarder, and submit the NAT Gateway IP. The environment type and VNet cannot be changed after creation; see the [Azure external-gateway reference](bnbagent-studio-use-azure-foundry.md#x402-external-gateway). Studio does not deploy or manage that Azure network.
+
 Do not add the public inbound gateway IP, a transient build-runner IP, or guessed addresses. If the whitelist endpoint is unreachable, stop onboarding and confirm the platform environment with the operator.
 
 ## Submit the B402 merchant application
@@ -101,7 +103,7 @@ Apply through the [B402 developer account application](https://developers.binanc
 | Email | Primary contact email address |
 | Wallet address | The agent wallet for that environment |
 | Public key | The contents of `.studio/b402/<environment>/public.der.b64` |
-| IP allowlist | For managed deploys, every platform Relay IP from `/v1/b402/whitelist-ips`; for self-hosted deploys, the user's Relay or NAT Elastic IP; add the local public IP when `bag dev` must reach B402 directly |
+| IP allowlist | For managed deploys (both backends), every platform Relay IP from `/v1/b402/whitelist-ips`; for self-hosted AgentCore, the user's Relay or VPC NAT Elastic IP; for self-hosted Azure Foundry, the ACA NAT Gateway static IP; add the local public IP when `bag dev` must reach B402 directly |
 | Webhook callback URL | Supply only when the integration uses callbacks |
 
 Keep the two environments isolated:

package/skills/references/bnbagent-studio-use-azure-foundry.md

@@ -7,7 +7,9 @@ description: When the user wants to deploy or operate a bnbagent-studio project
 
 # bnbagent-studio-use-azure-foundry
 
-> **Preview - not advertised in this release.** Azure Foundry support is fully wired but hidden from the `--runtime` menu and the deploy provider menu; these steps still work if you select `azure-foundry` / `--provider azure` explicitly. The most recent end-to-end live verification predates the TypeScript rewrite - treat your first deploy as a verification run.
+Azure Foundry is listed in `bag init --help` and the deploy provider menu. The
+Foundry data plane, Entra scope, unified entrypoint, deployment flow, and x402
+envelope tunnel were verified end to end in 2026-08.
 
 Procedure for deploying and operating the seller Agent on **Azure AI Foundry Hosted Agents** (`[stack].runtime = "azure-foundry"`). ALL cloud execution is **delegated to the pinned `@bnbagent/deploy-cli`** (run via `bunx --bun`; override with `BNBAGENT_DEPLOY_COMMAND`), whose Azure provider is **SDK/REST-only**. Studio never shells out to (or requires) the `az` / `azd` CLIs. Direct user-owned deployment uses browser/local credentials and may self-heal RBAC; the managed platform uses environment credentials in `ambient-only` mode and only probes RBAC.
 
@@ -21,15 +23,15 @@ Procedure for deploying and operating the seller Agent on **Azure AI Foundry Hos
 
 > **Deploy model: CONTAINER-ONLY.** The deploy-cli Azure provider rejects Node zip artifacts, so every azure-foundry deploy builds the scaffolded `app/agent/Dockerfile` **locally with Docker** (linux/amd64) and pushes it to the auto-provisioned Azure Container Registry; Foundry Agent Service pulls and runs the image. A running Docker daemon is required.
 
-> **Protocol: A2A projects only for now.** The deployed Node host speaks both Foundry container contracts on `:8088`: `GET /readiness`, pass-through `POST /invocations` for user-owned Azure, and OpenAI-compatible `POST /responses` for managed incoming A2A. Neither endpoint is native MCP streamable HTTP; `bag init` and provider selection reject azure-foundry + MCP instead of deploying a container that can never become ready.
+> **Protocol:** A2A, X402-only, and A2A+X402 projects are supported. The deployed Node host speaks both Foundry container contracts on `:8088`: `GET /readiness`, pass-through `POST /invocations` for user-owned Azure, and OpenAI-compatible `POST /responses` for managed incoming A2A. Neither endpoint is native MCP streamable HTTP; `bag init` and provider selection reject azure-foundry + MCP instead of deploying a container that can never become ready.
 
-> **Auth is a browser login.** The first delegated run opens a browser to sign in to the right tenant/subscription - there is no `az login` / `azd auth login` step and no CLI to install.
+> **Auth is explicit.** User-owned Azure needs a saved delegated browser sign-in, or an ambient Azure credential chain in CI. Deployment itself never shells out to `az` or `azd`, and a non-interactive deploy cannot open a browser.
 
 ## Prerequisites
 
 1. **Bun 1.3+ (`bunx`) on PATH** - the pinned `@bnbagent/deploy-cli` runs through it.
 2. **Docker running** - the image is built locally (linux/amd64) before push.
-3. **An Azure subscription** the operator may provision in (Foundry account/project, container registry, hosted agent); sign-in happens via the browser at deploy time.
+3. **An Azure subscription** the operator may provision in (Foundry account/project, container registry, hosted agent). Before a local self-deploy, run `bunx --bun @bnbagent/deploy-cli@0.5.10 login --provider azure`; use OIDC/service-principal credentials in CI.
 
 ## ⚠️ Foundry gotchas (read before deploying)
 
@@ -67,7 +69,7 @@ bag init myagent --runtime azure-foundry
 
 ```bash
 bag deploy prepare --runtime azure-foundry   # local readiness gate (region/subdomain/Dockerfile)
-bag deploy --provider azure                  # delegated: login → onboard → build+push → CustomKeys → deploy [--smoke]
+bag deploy --provider azure                  # delegated: onboard → build+push → CustomKeys → deploy [--smoke]
 ```
 
 `bag deploy --provider azure` runs an HTTP contract smoke by default (pass `--skip-smoke` to omit it) and captures the Foundry endpoint into `app/agent/studio.toml [azure].agent_endpoint`. If Foundry creates the resource but that post-create check fails, Studio still records the discovered endpoint so `status`, `logs`, and `destroy` can manage the resource; the deploy command continues to return non-zero.
@@ -76,11 +78,11 @@ bag deploy --provider azure                  # delegated: login → onboard →
 
 ```bash
 bag deploy status                            # all recorded providers + live state
-bag deploy info --with-curl                  # endpoint + Entra token shortcut + request body
+bag deploy info --provider azure --with-curl # endpoint + Entra token shortcut + request body
 bag deploy logs --provider azure --limit 50 # delegated Hosted Agent logs
 ```
 
-`bag deploy info` reads the recorded Azure endpoint without recreating the
+`bag deploy info --provider azure` reads the recorded Azure endpoint without recreating the
 temporary deploy spec. `--with-curl` adds an optional `az account
 get-access-token --resource https://ai.azure.com` shortcut and a complete
 Invocations request. This does not make the Azure CLI a deploy prerequisite;
@@ -89,6 +91,31 @@ with `DefaultAzureCredential` or `ClientSecretCredential`.
 
 The built-in smoke proves the container contract, not the seller signature. For a release E2E, invoke with a complete `negotiate` envelope and require `response.accepted=true`, a non-empty `negotiation_hash`, and `provider_sig`. The Invocations body is `{"input":"<serialized skill JSON>"}`.
 
+### X402 external gateway
+
+Foundry does not expose a raw anonymous `/x402` URL. An operator-run HTTPS
+gateway authenticates to the recorded Invocations endpoint with an Entra token
+for `https://ai.azure.com/.default`, wraps the incoming HTTP request as
+`http-envelope-v1`, and unwraps the returned inner status, headers, and base64
+body:
+
+```json
+{
+  "v": 1,
+  "method": "POST",
+  "path": "/x402",
+  "query": {},
+  "headers": { "content-type": "application/json" },
+  "body": "<base64-encoded request body>"
+}
+```
+
+`bag deploy info --provider azure --json` reports the deployed face snapshot,
+seller state, carrier contract, and a no-work route probe. A PAID seller also
+needs fixed facilitator egress; use an Azure Container Apps workload-profiles
+environment with VNet integration and a NAT Gateway static IP, then allowlist
+that IP with B402. Studio does not deploy or manage the gateway or network.
+
 ### D. Tear down
 
 ```bash