bnb-chain · 0xlucasliao · Aug 25, 2026 · Aug 23, 2026 · Aug 23, 2026
diff --git a/docs/developer-kit/bnbchain-studio/index.md b/docs/developer-kit/bnbchain-studio/index.md
@@ -4,95 +4,125 @@ title: BNB Agent Studio
 
 # BNB Agent Studio
 
-Scaffold, run, and deploy a **two-layer blockchain seller** on BNB Chain. BNB Agent Studio (`bnbagent-studio`) lets you describe what you want in Claude Code or Cursor; the studio emits a working agent project that **you own**, then helps you develop, debug, and deploy it.
+Describe the agent you want in Claude Code or Cursor; Studio scaffolds a working
+**TypeScript** project that you own, then helps you run, diagnose, and deploy it.
 
-A seller agent earns on-chain by offering services over **ERC-8004** (identity) + **ERC-8183** (commerce) + **x402** (payments), built on the [BNB Agent SDK](https://docs.bnbchain.org/developer-kit/bnbagent-sdk/).
+A seller agent earns on-chain by offering services over **ERC-8004** (identity),
+**ERC-8183** (escrowed commerce), and **x402/B402** (per-request payments), built on
+the [BNB Agent SDK](../bnbagent-sdk/index.md).
 
-> **v0.0.1 is seller-only.** The CLI (`bag`), runtime library (`bnbagent_studio_core`), read-only MCP server, and IDE skills ship today. Buyer product flows and a hosted console are deferred to v2.
+!!! warning "Under active development"
+    Studio manages wallet keys and on-chain funds, and may introduce breaking
+    changes. Start on **BSC testnet** with a wallet funded only for the task.
 
-> ⚠️ This project is under active development and may introduce breaking changes. It manages wallet keys and on-chain funds — start on **testnet** and use at your own risk.
+## Studio vs the SDK
 
-## What you get
+Two layers, and it is worth being clear which one you want:
 
-| Artifact | Package | Purpose |
-|----------|---------|---------|
-| **`bag` CLI** | `@bnbagent/studio-cli` | Scaffold projects, manage wallets, run locally, deploy |
-| **Runtime library** | `bnbagent-studio-core` | Wallet, ERC-8004/8183, x402, signing policy — imported by emitted agent code |
-| **MCP server** | `bnbagent-studio` | 15 read-only chain tools for your IDE |
-| **Skills** | bundled in CLI | 10 procedure playbooks for Claude Code / Cursor |
+| | What it is | Reach for it when |
+| --- | --- | --- |
+| **[BNB Agent SDK](../bnbagent-sdk/index.md)** | A **library you import** — ERC-8004, ERC-8183, x402, wallets. Python and TypeScript. | You want full control and will wire the agent yourself. |
+| **BNB Agent Studio** | A **tool that builds and deploys an app for you**, which then imports the SDK. | You want scaffolding, IDE-driven workflow, and a guided path to production. |
 
-Install one command:
+## What you install
 
 ```bash
-npm install -g @bnbagent/studio-cli
+npm install --global @bnbagent/studio-cli
+bag skills install
 ```
 
-## Two-layer deploy model
-
-AWS Bedrock AgentCore is invoke-only (no public HTTP routes, no background poll loop), so v1 splits the seller into two deployable artifacts:
-
-```
-            buyer                                   BNB Chain
-              │ POST /apex/negotiate                   ▲
-              ▼                                        │ funds / settles jobs
-┌──────────────────────────────┐   InvokeAgentRuntime  │
-│  Layer B — ERC-8183 Service  │ ──────────────────►  ┌┴─────────────────────────────┐
-│  app/service/ → EC2/Fargate  │                      │  Layer A — the Agent         │
-│  public · long-running       │ ◄────────────────── │  app/agent/ → AgentCore      │
-│  KEYLESS · no LLM · no sign  │   signed offer /     │  non-public · invoke-only    │
-│  /negotiate + funded-job     │   deliverable        │  the LLM + the SOLE signer   │
-│  poller                      │                      │  quote / fulfill / settle    │
-└──────────────────────────────┘                      └──────────────────────────────┘
+| Artifact | Package | Purpose |
+|----------|---------|---------|
+| **`bag` CLI** | [`@bnbagent/studio-cli`](https://www.npmjs.com/package/@bnbagent/studio-cli) | Scaffold projects, manage wallets, run locally, deploy |
+| **Agent runtime** | [`@bnbagent/studio-runtime`](https://www.npmjs.com/package/@bnbagent/studio-runtime) | Imported by the generated agent code. The generated project depends on this, **not** on the CLI — removing the global CLI does not disable an already-generated agent. |
+| **Deploy engine** | [`@bnbagent/deploy-cli`](https://www.npmjs.com/package/@bnbagent/deploy-cli) | Pinned; all cloud lifecycle mutations are delegated to it |
+| **IDE skill** | bundled in the CLI | The `/bnbagent-studio` router plus its on-demand playbooks, installed by `bag skills install` |
+| **MCP server** | `bag mcp serve` | 15 read-only chain tools for your IDE — it never signs |
+
+The bundled skill is the primary interface: it turns your intent into a reviewable
+workflow and drives `bag` for you. `bag` remains available for automation and for
+anyone who prefers direct control.
+
+## One runtime, one signer
+
+A single deployed process serves every selected public face and holds the only key.
+There is no separate keyless service tier.
+
+- **Faces are composable** (`--protocols`): **A2A** (agent card + JSON-RPC on `:9000`),
+  **MCP** (Streamable HTTP at `:8000/mcp`), and **X402** (`/x402`). One seller core and
+  one wallet serve all of them.
+- **Signing is fixed code**, never an LLM-callable tool. It lives in
+  `app/agent/src/signing.ts`. The LLM's chain tools are read-only, and no LLM
+  participates in pricing.
+- **The keystore lives at the workspace root** in `.studio/wallets/` — outside
+  `app/agent/`, so no packaging path can bundle it into a deploy artifact.
+
+The ERC-8183 rail exposes exactly two bounded operations: `negotiate` (a rule-based
+price clamp plus a signed quote) and `notify_funded` (verify the funded job on-chain,
+produce the deliverable, submit it).
+
+## The choices you make
+
+| Dimension | Choices | Notes |
+| --- | --- | --- |
+| Network | `bsc-testnet`, `bsc-mainnet` | Start on testnet. The managed BNB trial is always testnet. |
+| Wallet | `evm-local` (default), `twak`, `altana` | Local encrypted keystore; Trust Wallet Agent Kit custody; or a budget- and time-bounded Altana session. |
+| LLM | Pieverse (default), OpenRouter, OpenAI, Anthropic, Bedrock | Pieverse `auto/free` starts at $0/token. Others use your own credentials. |
+| Commerce rails | ERC-8183, B402, or both | ERC-8183 is job escrow; B402 settles x402 requests. Rails and faces are separate choices. |
+| Public faces | A2A, MCP, X402, or a combination | One runtime serves every selected face. |
+| Deployment | BNB managed trial, AWS AgentCore, Azure Foundry | Every deploy explicitly selects a target; a previous deployment is never a silent default. |
+| Deliverable storage | local or IPFS | Local is for offline development and **fails deployment readiness**. IPFS is durable and deploy-ready. |
+
+Some combinations are rejected before the project changes — Altana does not support
+paid B402 selling, and Azure Foundry currently deploys **A2A scaffolds only**
+(the MCP entrypoint is rejected before a Foundry deploy).
+
+## What gets generated
+
+```text
+weatheragent/
+├── package.json                 workspace marker
+├── pnpm-workspace.yaml
+├── AGENTS.md                    generated safety rules for coding agents
+├── agentcore/
+│   ├── agentcore.json           deployment descriptor
+│   └── aws-targets.json         AWS account and region for self-deploy
+├── .studio/
+│   ├── .env.local               gitignored secrets, mode 0600
+│   └── wallets/                 encrypted keystore, outside deployable code
+└── app/agent/
+    ├── studio.toml              network, wallet, LLM, policy, rails, faces
+    └── src/
+        ├── sellerCore.ts        the work your agent sells  ← you edit this
+        ├── signing.ts           fixed quote / verify / submit path
+        ├── tools.ts             read-only chain tools for the LLM
+        ├── unifiedMain.ts       A2A + X402 entrypoint (:9000)
+        ├── mcpMain.ts           MCP-only entrypoint (:8000/mcp)
+        └── dualMain.ts          A2A-native + tunneled /mcp (AgentCore only)
 ```
 
-- **Layer A — the Agent** (`app/agent/` → AWS Bedrock AgentCore): the LLM, memory, tools, and **sole key-holder/signer**. Invoked on action envelopes (`quote` / `fulfill` / `settle`). All signing is fixed entrypoint code — never an LLM-callable tool.
-- **Layer B — the ERC-8183 Service** (`app/service/` → EC2/Fargate): a public, long-running, **keyless** container — `/negotiate` ingress, funded-job poller, and `InvokeAgentRuntime` client. Holds no key, runs no LLM, never signs.
-
-## Relationship to BNB Agent SDK
-
-| Layer | Package | Role |
-|-------|---------|------|
-| Protocol | [bnbagent](https://pypi.org/project/bnbagent/) (BNB Agent SDK) | ERC-8004, ERC-8183, wallet ABC — pure protocol clients |
-| Studio core | `bnbagent_studio_core` | Config, workflows, signing policy, audit log |
-| Studio surface | `bag` CLI + MCP + skills + recipes | Scaffolding, ops, IDE integration |
-| Your code | `app/agent/*`, `app/service/*` | Emitted by recipes; you own and edit freely |
+Ordinary TypeScript that you own — edit, fork, or move it whenever you want.
 
-Use BNB Agent SDK directly when you want full control over protocol integration. Use BNB Agent Studio when you want scaffolding, IDE skills, a two-layer deploy path, and safety defaults out of the box.
+## How a seller gets paid
 
-## Prerequisites
+**ERC-8183 — negotiated work with escrow.** A buyer calls `negotiate`; fixed code
+clamps the configured list price and signs a quote. The buyer creates the job, sets a
+budget, and funds escrow, then sends `notify_funded`. The seller verifies the signed
+terms, assigned provider, status, budget, and funded state **on-chain before doing paid
+work**, stores the deliverable, and submits its reference. The buyer then manually
+chooses approve, reject, or dispute — Studio never silently auto-settles a buyer's job.
 
-| Requirement | Why |
-|-------------|-----|
-| Python ≥ 3.10 | CLI and runtime library |
-| Claude Code or Cursor | Studio is driven from your AI tool via skills |
-| Node ≥ 20 + `npm i -g @aws/agentcore` | `bag init` / `bag dev` / `bag deploy agent` shell out to the native AgentCore CLI |
-| A wallet password | `bag init` creates a local encrypted keystore; password lives in `WALLET_PASSWORD` env only |
+`price = "0"` is an explicit **FREE** ERC-8183 job: it skips token escrow, though
+state-changing calls still need gas or a sponsored path.
 
-Optional: testnet funds (only for paid LLM models or on-chain settle — default `auto/free` Pieverse model needs no funds).
-
-## Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [Quickstart](quickstart.md) | Install, scaffold, run locally, first negotiate |
-| [Demo](demo.md) | End-to-end weather-forecast seller walkthrough |
-| [Architecture](architecture.md) | Six-layer stack, recipes, workspace layout |
-| [Configuration](configuration.md) | `studio.toml`, `.env.local`, cross-layer sync |
-| [CLI reference](cli-reference.md) | `bag` command groups and key flags |
-| [Deployment](deployment.md) | Layer A (AgentCore) + Layer B (EC2) deploy path |
-| [Security](security.md) | Keystore posture, signing policy, MCP read-only guarantee |
-| [Troubleshooting](troubleshooting.md) | `bag doctor`, common errors |
-
-## Repository
-
-[https://github.com/bnb-chain/bnbagent-studio](https://github.com/bnb-chain/bnbagent-studio)
-
-## Package
-
-```bash
-npm install -g @bnbagent/studio-cli
-```
+**x402 — pay per HTTP request.** The X402 face exposes `/x402`. A positive
+`price_usd` returns a payment challenge and settles through B402 *before* work starts;
+`price_usd = "0"` is anonymous FREE passthrough that bypasses B402 entirely. Paid mode
+needs a complete per-agent B402 merchant setup and an `evm-local` or `twak` payout
+wallet. Payment settles before work, so a later work failure has no automatic refund.
 
-[npm — @bnbagent/studio-cli](https://www.npmjs.com/package/@bnbagent/studio-cli) · [PyPI — bnbagent-studio-core](https://pypi.org/project/bnbagent-studio-core/)
+## Next
 
-[← Developer Kit overview](../index.md)
+- **[Quickstart](quickstart.md)** — install, scaffold, run, and deploy your first agent
+- [Configuration](configuration.md) · [CLI reference](cli-reference.md) · [Deployment](deployment.md)
+- [Security](security.md) · [Troubleshooting](troubleshooting.md)