@bnbagent/studio-cli 0.0.6-alpha.8 → 0.0.6

package/dist/{chunk-JZAW6HMV.js → chunk-ODCZKKZJ.js}

@@ -1203,6 +1203,8 @@ async function runPlatformAccountCommand(argv, opts = {}) {
 }
 
 export {
+  setEnvVar,
+  getEnvVar,
   CliExit,
   act,
   printOut,
@@ -1233,8 +1235,6 @@ export {
   deployChecks,
   render,
   readAwsTarget,
-  setEnvVar,
-  getEnvVar,
   B402_RUNTIME_KEYS,
   commerceRails,
   b402Credentials,

package/dist/{deployCli-AJ25A4VK.js → deployCli-VM5TYKQX.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bnbagent/studio-cli",
-  "version": "0.0.6-alpha.8",
+  "version": "0.0.6",
   "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": {
@@ -9,6 +9,7 @@
     "directory": "packages/studio-cli"
   },
   "type": "module",
+  "packageManager": "pnpm@10.24.0",
   "engines": {
     "node": ">=22"
   },
@@ -25,8 +26,16 @@
   "bin": {
     "bag": "./dist/bag.js"
   },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "biome check src tests",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
   "dependencies": {
-    "@bnbagent/sdk": "0.5.0-alpha.3",
+    "@bnbagent/sdk": "0.5.0",
+    "@bnbagent/studio-runtime": "0.0.6",
     "ai": "^7.0.29",
     "archiver": "^8.0.0",
     "commander": "^15.0.0",
@@ -37,8 +46,7 @@
     "smol-toml": "^1.3.0",
     "tar": "^7.4.0",
     "viem": "^2.54.0",
-    "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.6-alpha.8"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",
@@ -54,12 +62,5 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0",
     "zod": "^3.25.76"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "lint": "biome check src tests",
-    "typecheck": "tsc --noEmit",
-    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
   }
-}
+}

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

@@ -26,12 +26,12 @@ import {
   type NegotiationResult,
   type QuoteSigner,
 } from "@bnbagent/sdk/erc8183";
-import { getAddress as deployedAddresses } from "@bnbagent/sdk/networks";
 import {
   loadStudioToml,
   type TomlTable,
 } from "@bnbagent/studio-runtime/config";
 import {
+  erc8183Network,
   get8183Client,
   settleWorkflow,
   type SubmitResult,
@@ -39,7 +39,6 @@ import {
   type Verdict,
   verifySignedJob as verifySignedJobCore,
 } from "@bnbagent/studio-runtime/erc8183";
-import { getNetwork } from "@bnbagent/studio-runtime/networks";
 import { getWallet } from "@bnbagent/studio-runtime/wallet";
 
 const MAX_UINT256 = (1n << 256n) - 1n;
@@ -116,10 +115,9 @@ function defaultNetworkName(): string {
  * client. QA/custom stacks override the canonical SDK registry via env.
  */
 export function commerceVerifyingContract(
-  chainId: number,
+  networkName: string,
 ): `0x${string}` {
-  const override = process.env.ERC8183_COMMERCE_ADDRESS?.trim();
-  return (override || deployedAddresses(chainId).commerceProxy) as `0x${string}`;
+  return erc8183Network(networkName).commerceContract as `0x${string}`;
 }
 
 /**
@@ -184,7 +182,8 @@ function getHandler(): NegotiationHandlerLike {
     const currency = String(cfg.currency ?? ""); // the Agent owns the currency now
     const ttl = Number(cfg.quote_ttl_seconds ?? 900);
     const est = Number(cfg.default_estimated_completion_seconds ?? 600);
-    const network = getNetwork(defaultNetworkName());
+    const networkName = defaultNetworkName();
+    const network = erc8183Network(networkName);
     const wallet = getWallet();
     handler = new NegotiationHandler({
       servicePrice: "0", // placeholder — overridden per call via price=
@@ -193,7 +192,7 @@ function getHandler(): NegotiationHandlerLike {
       ...negotiationSignerOptions(wallet),
       quoteTtlSeconds: ttl,
       chainId: network.chainId,
-      verifyingContract: commerceVerifyingContract(network.chainId),
+      verifyingContract: network.commerceContract as `0x${string}`,
     });
   }
   return handler;
@@ -219,6 +218,9 @@ export async function signQuote(
   request: Record<string, unknown>,
   clampedPriceWei: bigint,
 ): Promise<Record<string, unknown>> {
+  // Validate the entire custom contract trio before signing, including when
+  // tests inject a handler or a previously cached handler is reused.
+  commerceVerifyingContract(defaultNetworkName());
   const cfg = erc8183Cfg();
   const est = Number(cfg.default_estimated_completion_seconds ?? 600);
 

package/recipes/agent/recipe.toml

@@ -11,7 +11,7 @@ node = [
     # neutral. The agent project's serving deps (@a2a-js/sdk / MCP SDK / ai)
     # come from the runtimes/<R>/ recipe selected at `bag init` time.
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.0-alpha.3",
+    "@bnbagent/sdk@0.5.0",
 ]
 
 [env]

package/recipes/runtimes/agentcore/recipe.toml

@@ -32,7 +32,7 @@ node = [
     # BNBAGENT_RUNTIME_SECRET_ID is set (default secretsmanager mode + platform).
     "@aws-sdk/client-secrets-manager@^3.600.0",
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.0-alpha.3",
+    "@bnbagent/sdk@0.5.0",
     # The LLM work hook (generateText + tools) and the model factory.
     "ai@^7.0.29",
     # Tool input schemas (AI SDK tools + MCP registerTool).

package/recipes/runtimes/azure-foundry/recipe.toml

@@ -19,7 +19,7 @@ status = "v1"
 [dependencies]
 node = [
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.0-alpha.3",
+    "@bnbagent/sdk@0.5.0",
     # The LLM work hook (generateText + tools) and the model factory; the
     # Foundry host's OpenAI-compatible client comes from @ai-sdk/openai
     # (built from the BNBAGENT_LLM_* env the deploy injects).

package/recipes/x402-buyer/recipe.toml

@@ -6,7 +6,7 @@ status = "v0.0.x"
 [dependencies]
 node = [
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.0-alpha.3",
+    "@bnbagent/sdk@0.5.0",
     "ai@^7.0.29",   # AI SDK `tool` wrappers around the buyer functions
     "zod@^3.25.0",  # tool input schemas
 ]

package/skills/bnbagent-studio.md

@@ -30,7 +30,7 @@ One deployed runtime, one signer: a single valuable Agent serves the selected fa
 | 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` |
 | Extend the EIP-712 signing allowlist (custom contract / new x402 service / diagnose `PolicyViolation` / `X402PolicyError`) | `references/bnbagent-studio-extending-signing.md` |
 | Project uses `[wallet].kind = "twak"` (create / fund / SIWE-bind / container deploy / known limitations) | `references/bnbagent-studio-using-twak-wallet.md` |
-| Project uses `[wallet].kind = "altana"` (admin keystore / bounded session / quote checker / x402 allowance / local dev) | `references/bnbagent-studio-using-altana-wallet.md` |
+| Project uses `[wallet].kind = "altana"` (admin keystore / bounded session / quote checker / x402 allowance / local dev / session-only deploy + renewal) | `references/bnbagent-studio-using-altana-wallet.md` |
 | (Pieverse projects only) Fund the LLM, switch to a paid model, hit insufficient credits (`PieverseBudgetExhaustedError` / `PieverseAccountBalanceExhaustedError`) | skill `funding-pieverse-llm` (project-scope; emitted at `bag init --llm-provider pieverse-llm`) |
 
 If two or more match, read both - they're designed to be orthogonal.
@@ -49,7 +49,7 @@ Next to this file: this skill installs as a directory with a `references/` subdi
 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.
+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; the canonical stack supports it. If a custom stack is selected, require all three contract-address overrides from one verified deployment. 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
 

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

@@ -72,7 +72,7 @@ The Agent sub-project (`app/agent/`) is where your existing valuable agent lives
 
 Tune the price in `app/agent/studio.toml` (`[payments.erc8183]` `min_price`/ `max_price`): the `negotiate` path is **rule-based, no LLM** - fixed code takes the configured list price, clamps it to `[min_price, max_price]`, then `signing.ts` EIP-191-signs the offer. For per-task pricing, compute the price 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.
+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`; the canonical stack supports zero funding. If a custom deployment is selected, set all three `ERC8183_*_ADDRESS` overrides from that same stack. The buyer still runs `setBudget(0)` and `fund(0)`, but no ERC-20 approval or token escrow occurs. Require `bag doctor` and `bag deploy prepare` to pass.
 
 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`.
 

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

@@ -40,7 +40,7 @@ Common error: `Submission deadline has passed` → buyer set `expiredAt` too sho
 ## Preconditions
 
 - `bag doctor` is clean (or only warns on LLM key)
-- 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 **when they target the canonical contracts**, 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.) Sponsorship is granted per target contract by the paymaster policy: a custom/QA stack selected via the `ERC8183_*_ADDRESS` overrides is normally **not** covered, so every write self-pays gas (the SDK logs `… is not sponsorable on this network; self-paying gas` and falls back automatically) - keep tBNB for the whole flow, or set `BNBAGENT_USE_PAYMASTER=0` to skip the per-transaction sponsorship probe and self-pay directly. 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 - today that means a custom stack, so expect the writes to self-pay gas as above.
+- 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 **when they target the canonical contracts**, 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.) Sponsorship is granted per target contract by the paymaster policy: a custom/QA stack selected via the `ERC8183_*_ADDRESS` overrides is normally **not** covered, so every write self-pays gas (the SDK logs `… is not sponsorable on this network; self-paying gas` and falls back automatically) - keep tBNB for the whole flow, or set `BNBAGENT_USE_PAYMASTER=0` to skip the per-transaction sponsorship probe and self-pay directly. For a FREE job, use `--budget-u 0`: no U balance, ERC-20 approval, or token escrow is needed. The canonical zero-price-compatible stack keeps the normal testnet paymaster path; custom stacks still need their own gas path.
 - 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
 
@@ -56,7 +56,7 @@ bag erc8004 resolve <provider_agent_id>
 # → returns the agent_uri; decode it (base64 data: URI) to verify the endpoint URL
 ```
 
-If the provider's endpoint URL points somewhere reachable (e.g. an `https://` AgentCore runtime URL), proceed. If it's `http://localhost:...`, that means you must be on the same host.
+Automatic negotiation by `--agent-id` requires a public HTTPS provider endpoint and refuses redirects, credentials in the URL, loopback, and private addresses. For local protocol testing, negotiate manually and buy with `--provider <addr> --no-negotiate` instead.
 
 ## Stage 2 - (Optional) Negotiate price
 

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

@@ -134,7 +134,7 @@ bag wallet balance --all                 # both [network].default AND [llm.pieve
 
 The `--all` form is the right move when `app/agent/studio.toml`'s `[network].default = bsc-testnet` and `[llm].provider = pieverse-llm`: 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.
+`bag doctor` prints ERC-8183 pricing as `PAID` or `FREE`. FREE works on the canonical contract stack. If a custom deployment is selected, set `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`.
 
@@ -163,7 +163,6 @@ JobStatus enum: `OPEN` (0) → `FUNDED` (1) → `SUBMITTED` (2) → `COMPLETED`
 | `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 |

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

@@ -69,7 +69,7 @@ The fields (give the user all of them at once):
 | 1 | **Project name** | Must start with a letter, contain ASCII letters and digits only, and be at most 23 characters. `bag init` rejects `-`, `_`, `.`, and overlong names instead of renaming them. For example: `newsagent`, `twcopywriter`. | (required) |
 | 2 | **Network** | `bsc-testnet` / `bsc-mainnet` | `bsc-testnet` |
 | 3 | **LLM provider** | `pieverse-llm` / `openrouter` / `openai` / `anthropic` / `bedrock` | `pieverse-llm` |
-| 4 | **Wallet kind** (`--wallet-kind`) | `evm-local` (encrypted local keystore at the workspace root; `bag wallet new` creates it, `--private-key` imports an existing key; CodeZip deploy) / `twak` (**fully supported, opt in with `--wallet-kind twak`** - Trust Wallet Agent Kit CLI ≥0.20.0, self-custody encrypted mnemonic in a **project-dedicated** home `.studio/twak`, isolated from your main `~/.twak`; created manually with `HOME=<ws>/.studio/twak twak wallet create`, then `bag wallet new` adopts; container deploy. Reuse an existing wallet across agents with `--twak-home <path>`) | `evm-local` |
+| 4 | **Wallet kind** (`--wallet-kind`) | `evm-local` (encrypted local keystore at the workspace root; `bag wallet new` creates it, `--private-key` imports an existing key; CodeZip deploy) / `twak` (**fully supported, opt in with `--wallet-kind twak`** - Trust Wallet Agent Kit CLI ≥0.20.0, self-custody encrypted mnemonic in a **project-dedicated** home `.studio/twak`, isolated from your main `~/.twak`; created manually with `HOME=<ws>/.studio/twak twak wallet create`, then `bag wallet new` adopts; container deploy. Reuse an existing wallet across agents with `--twak-home <path>`) / `altana` (bounded-session custody - admin keystore stays local, deploys ship ONLY the `ALTANA_SESSION` secret; zip deploy; not compatible with `pieverse-llm` or a paid b402 rail; flow: `references/bnbagent-studio-using-altana-wallet.md`) | `evm-local` |
 | 5 | **Storage** | `local` (file:// on disk, offline dev only, does **NOT** survive deploy) / `ipfs` (durable, public, deploy-ready; needs your pinning service's upload endpoint + write key as `STORAGE_API_URL` / `STORAGE_API_KEY` in `.studio/.env.local` **before the first real delivery** - see Step 6b) | `local` |
 | 6 | **Protocol faces** (`--protocols`) | any non-empty subset of `A2A`, `MCP`, `X402` | `A2A` |
 | 7 | **LLM model** | provider catalogue; for `pieverse-llm` the default `auto/free` runs at $0/token | `auto/free` |
@@ -138,7 +138,9 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
 
 > **Onboarding note.** On a human TTY, `bag init` runs steps 3, 4 and 6 automatically (it prompts once for the wallet password, runs `bag wallet new`, zero-deposit-activates Pieverse, and prints faucet URLs). **You (Claude Code) drive `bag init` non-interactively**, so that auto-flow does NOT fire - 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> --rails <8183|b402|both> [--erc8183-price <base-units>] [--b402-price <usd>] --no-onboard` - scaffold the current workspace. **`<name>` must start with a letter, use ASCII letters and digits only, and be at most 23 characters.** `bag init` rejects `-`, `_`, `.`, and overlong names instead of renaming them. Pass `--wallet-kind evm-local` (default) or `--wallet-kind twak` (twak is fully supported - pass the flag to opt in), and `--storage-provider local` (default) or `ipfs`, per the Stage-1 choices; for twak, add `--twak-home <path>` ONLY if the user wants to reuse an existing wallet (otherwise omit - a project-dedicated `.studio/twak` is the safe default). add `--protocols <comma-list>` when the user chose non-default or multiple 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). 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 confirmation block you echoed no longer matches what was written. Omit `--destination` only when the user actually wants the `platform` 48h testnet trial (the campaign default) - do NOT treat that default as a mistake or re-confirm it; it is the intended behavior while the campaign is open. (Bare init also resolves to `self` once the campaign ends, or when `--network bsc-mainnet` / a non-agentcore `--runtime` is passed.) On the `platform` path `bag init` hard-forces `bsc-testnet`, pins `--runtime agentcore` + packages an artifact (a zip for the default evm-local wallet, a container for twak), and a wallet key will later leave your machine, so pair it with a throwaway `bag wallet new` (full flow: `docs/guides/platform-deploy.md`). Defaults `--runtime agentcore` (the only advertised runtime; the Preview `azure-foundry` runtime remains explicitly selectable but is outside this playbook; there is no `--framework` flag because the AI SDK model/tools story is part of the runtime templates). Creates `<name>/` workspace root + `<name>/app/agent/` (the single sub-project: A2A emits `src/main.ts` (the express + A2A entrypoint) + `src/sellerCore.ts` (the protocol-neutral core; executor inherits it) + `src/executor.ts` + `src/agentCard.ts`; MCP emits `src/mcpMain.ts`; both include `src/signing.ts` + `src/tools.ts` + `src/model.ts` + their own `studio.toml` + `package.json` + `tsconfig.json`) + `<name>/agentcore/` (`agentcore.json` + `aws-targets.json`, self-rendered - no agentcore CLI needed at init). The workspace root holds the `agentcore/` deploy descriptor, the `.studio/wallets/` keystore, a thin `package.json` + `pnpm-workspace.yaml`, README, and `.gitignore`. (v1 is seller-only - no `--role`.)
+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 current workspace. **`<name>` must start with a letter, use ASCII letters and digits only, and be at most 23 characters.** `bag init` rejects `-`, `_`, `.`, and overlong names instead of renaming them. Pass `--wallet-kind evm-local` (default) or `--wallet-kind twak` (twak is fully supported - pass the flag to opt in), and `--storage-provider local` (default) or `ipfs`, per the Stage-1 choices; for twak, add `--twak-home <path>` ONLY if the user wants to reuse an existing wallet (otherwise omit - a project-dedicated `.studio/twak` is the safe default). add `--protocols <comma-list>` when the user chose non-default or multiple 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). Pass `--erc8183-price 0` only when the user explicitly chose FREE; omitting the flag preserves the paid 0.1 U default. The canonical stack supports FREE; if a custom deployment is selected, set all three `ERC8183_COMMERCE_ADDRESS`, `ERC8183_ROUTER_ADDRESS`, and `ERC8183_POLICY_ADDRESS` values from that same stack. 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 confirmation block you echoed no longer matches what was written. Omit `--destination` only when the user actually wants the `platform` 48h testnet trial (the campaign default) - do NOT treat that default as a mistake or re-confirm it; it is the intended behavior while the campaign is open. (Bare init also resolves to `self` once the campaign ends, or when `--network bsc-mainnet` / a non-agentcore `--runtime` is passed.) On the `platform` path `bag init` hard-forces `bsc-testnet`, pins `--runtime agentcore` + packages an artifact (a zip for the default evm-local and altana wallets, a container for twak). For evm-local a wallet key will later leave your machine, so pair it with a throwaway `bag wallet new`; for altana only the bounded session ships - do NOT create a new wallet (full flow: `docs/guides/platform-deploy.md`). Defaults `--runtime agentcore` (the only advertised runtime; the Preview `azure-foundry` runtime remains explicitly selectable but is outside this playbook; there is no `--framework` flag because the AI SDK model/tools story is part of the runtime templates). Creates `<name>/` workspace root + `<name>/app/agent/` (the single sub-project: A2A emits `src/main.ts` (the express + A2A entrypoint) + `src/sellerCore.ts` (the protocol-neutral core; executor inherits it) + `src/executor.ts` + `src/agentCard.ts`; MCP emits `src/mcpMain.ts`; both include `src/signing.ts` + `src/tools.ts` + `src/model.ts` + their own `studio.toml` + `package.json` + `tsconfig.json`) + `<name>/agentcore/` (`agentcore.json` + `aws-targets.json`, self-rendered - no agentcore CLI needed at init). The workspace root holds the `agentcore/` deploy descriptor, the `.studio/wallets/` keystore, a thin `package.json` + `pnpm-workspace.yaml`, README, and `.gitignore`. (v1 is seller-only - no `--role`.)
+> **Altana + custom contracts:** Altana sessions remain bound to the canonical ERC-8183 targets. Use `evm-local` for a custom Commerce/Router/Policy stack; doctor and deploy readiness reject this unsupported combination when the ERC-8183 rail is active.
+
 2. `cd <name>`, then make sure the dependencies are installed. `bag init` already runs the install by default (skip only if it was scaffolded with `--no-install`); the manual equivalent from the workspace root is:
    ```bash
    pnpm install        # npm install works too - tooling is the user's choice

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

@@ -80,20 +80,17 @@ quote_ttl_seconds = 300
 default_estimated_completion_seconds = 600
 ```
 
-An explicit `price = "0"` opts into free jobs when the selected ERC-8183 contract supports zero-price funding. Keep `currency` configured because it remains part of the signed quote.
+An explicit `price = "0"` opts into free jobs on the canonical zero-price-compatible ERC-8183 stack. Keep `currency` configured because it remains part of the signed quote.
 
 Prefer the CLI so the zero-price choice is visible and remains a decimal string:
 
 ```bash
 bag config set payments.erc8183.price 0
-bag env set ERC8183_COMMERCE_ADDRESS '0x...'
-bag env set ERC8183_ROUTER_ADDRESS '0x...'
-bag env set ERC8183_POLICY_ADDRESS '0x...'
 bag doctor
 bag deploy prepare
 ```
 
-Take all three addresses from the same compatible custom deployment. Doctor/prepare reject canonical or partial contract selection for FREE and announce `zero token escrow` only when the complete custom stack is selected.
+Doctor/prepare announce `zero token escrow` for the canonical stack. If the operator intentionally selects a custom deployment, take all three `ERC8183_*_ADDRESS` values from that same compatible stack; partial or invalid overrides are rejected.
 
 ## Stage 3 - LLM credit continuity (Pieverse projects only)
 

package/skills/references/bnbagent-studio-use-aws-agentcore.md

@@ -31,7 +31,7 @@ The deployed product is **one** valuable Agent that serves its selected public f
 
 ## The runtime-secret channel (read this first)
 
-The deployed runtime does NOT read `.env.local` - nothing ships it. Instead, `bag deploy --provider aws` collects the runtime secrets (provider/storage keys, `WALLET_PASSWORD`, the encrypted keystore as `WALLET_KEYSTORE_JSON` - or the twak bundle) and hands them to bnbagent-deploy as a private (mode 0600) tempdir envFile. The deploy CLI provisions them as ONE Secrets Manager secret (`bnbagent/<project>/runtime`), injects the `BNBAGENT_RUNTIME_SECRET_ID` pointer into the runtime env, and grants the runtime execution role read access. The entrypoint loads the bundle at cold start.
+The deployed runtime does NOT read `.env.local` - nothing ships it. Instead, `bag deploy --provider aws` collects the runtime secrets (provider/storage keys, `WALLET_PASSWORD`, the encrypted keystore as `WALLET_KEYSTORE_JSON` - or the twak bundle; for `wallet.kind='altana'` ONLY the bounded session as `ALTANA_SESSION` - no keystore, no `WALLET_PASSWORD`) and hands them to bnbagent-deploy as a private (mode 0600) tempdir envFile. The deploy CLI provisions them as ONE Secrets Manager secret (`bnbagent/<project>/runtime`), injects the `BNBAGENT_RUNTIME_SECRET_ID` pointer into the runtime env, and grants the runtime execution role read access. The entrypoint loads the bundle at cold start.
 
 > **The KEYSTORE is never bundled.** The encrypted wallet keystore lives at the WORKSPACE root (`.studio/wallets/`, outside `app/agent/`, so no packaging path can include it) and reaches the runtime ONLY via that Secrets Manager channel. Only put non-secret runtime config in `agentcore.json` `envVars[]`.
 
@@ -87,6 +87,7 @@ bag deploy --provider aws
 - **Permission denials (AccessDenied)** - the deploy identity is missing one of the least-privilege statements; apply the policy JSON from `docs/guides/agentcore-deploy-iam.md`. The deploy CLI preflight-simulates its permissions when it can and names the denied actions.
 - **Wrong account** - the credentials in the environment resolve to an account that does not match `agentcore/aws-targets.json`; fix the env vars / `~/.aws/credentials` profile, not the descriptor.
 - **Container build fails / hangs** (twak) - the image is built LOCALLY for linux/arm64 and pushed to ECR; Docker must be running (x86 machines need buildx/containerd cross-build support).
+- **`agentcore_quota_headroom` CRITICAL (quota 0 or full)** - the `L-F4575653` ("Total Agents per Account") quota has no free slot; new accounts can start at an applied quota of ZERO even though the console shows a higher default. Raising it is a manual AWS step (`bag` and the AWS CLI cannot request it): open the Service Quotas console for "Amazon Bedrock AgentCore" in the target region and request an increase — low first requests are sometimes rejected and need an AWS support case. Check where an earlier request stands with `aws service-quotas list-requested-service-quota-change-history --service-code bedrock-agentcore --region <region>` (a `CASE_CLOSED` entry without a quota change means it was rejected — escalate via support). While the increase is pending, deploy to the managed platform instead: `bag deploy --provider bnb`. If the quota is full but nonzero, `bag deploy destroy` in an old workspace frees a slot.
 
 ### C. Inspect / operate
 

package/skills/references/bnbagent-studio-use-bnb-trial.md

@@ -7,7 +7,7 @@ description: Use when deploying or operating a bnbagent-studio seller on the BNB
 
 # Use the BNB Chain 48h trial
 
-Treat this provider as a temporary testnet sandbox. Require a throwaway wallet, keep `bsc-testnet`, and explain that the runtime signing material is transmitted to the operator's managed secret store for the trial. Never use a mainnet key.
+Treat this provider as a temporary testnet sandbox. Require a throwaway wallet, keep `bsc-testnet`, and explain that the runtime signing material is transmitted to the operator's managed secret store for the trial. Never use a mainnet key. Exception: `wallet.kind='altana'` ships only the bounded, budget-limited, revocable session - the throwaway-wallet advice does not apply; tighten the session instead (`bag wallet session grant --force --budget-u <small> --expiry-days <short>`) and never run `bag wallet new` on an altana project (it breaks the session's `[wallet].address` anchor).
 
 All auth and cloud lifecycle work must cross the pinned `@bnbagent/deploy-cli@0.4.14` boundary. Do not call the AWS CLI or platform REST routes directly.
 

package/skills/references/bnbagent-studio-using-altana-wallet.md

@@ -11,20 +11,21 @@ Altana separates trusted administration from runtime authority:
 - `.studio/wallets/altana-session.json` is the one bounded, expiring runtime session and must stay mode `0600`.
 - `WALLET_PASSWORD` is admin-only. The Agent gets `ALTANA_SESSION`, never the password or admin keystore.
 - Generic signing is refused. ERC-8183 uses `sessionQuoteSigner()` and the approved quote checker.
-- Deployment ships ONLY the serialized session as the `ALTANA_SESSION` runtime secret; the admin keystore and `WALLET_PASSWORD` never leave the operator machine. Renewal after expiry: `bag wallet session grant --force`, then re-run `bag deploy` (readiness warns under 7 days remaining). `bag deploy verify` needs `--skip-register` (no generic signing for the ERC-8004 register).
-- Altana refuses generic message signing, so Pieverse SIWE cannot authenticate either `bag llm activate` or runtime credit renewal. An existing Pieverse key is usable only with `auto/free`; use OpenRouter, OpenAI, or Anthropic for paid models.
+- Deployment ships ONLY the serialized session as the `ALTANA_SESSION` runtime secret; the admin keystore and `WALLET_PASSWORD` never leave the operator machine. Renewal after expiry: `bag wallet session grant --force`, then re-run `bag deploy`. Readiness fails on a missing/expired/address-mismatched session, a group/world-readable session file, a session inside the artifact root, or an unresolvable project-local `@altananetwork/sdk`; it warns under 7 days remaining. `bag deploy verify` needs `--skip-register` (no generic signing for the ERC-8004 register).
+- Altana refuses generic message signing, so Pieverse SIWE cannot authenticate `bag llm activate` or runtime credit renewal. `bag init --wallet-kind altana --llm-provider pieverse-llm` is rejected outright; use OpenRouter, OpenAI, or Anthropic (API-key providers). `bag llm activate` and `bag doctor` also flag the combination on projects edited by hand.
 
 ## Procedure
 
 ```bash
 bag init <name> --wallet-kind altana --destination self --no-onboard
+# --destination platform is also accepted (48h trial; same session-only transport).
 # Non-TTY defaults to OpenRouter. In a TTY, choose OpenRouter, OpenAI, or
 # Anthropic from the provider menu; a flag remains available when desired:
 # bag init <name> --wallet-kind altana --llm-provider anthropic --destination self
 # Edit <name>/.studio/.env.local and set WALLET_PASSWORD first.
 cd <name>/app/agent
 bag wallet new
-# fund the printed admin address with gas + U
+# fund the printed admin address with ~0.05 tBNB + U
 bag wallet session grant
 bag wallet session status
 bag doctor

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of tracking or otherwise improving the Work,
-      but excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Support. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or support.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of "Purpose" be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 BNB Chain Studio
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-   implied. See the License for the specific language governing
-   permissions and limitations under the License.