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

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

@@ -13,7 +13,7 @@ import * as os from "os";
 import * as path5 from "path";
 import {
   findSubProjectRoot as findSubProjectRoot2,
-  loadStudioToml as loadStudioToml2
+  loadStudioToml as loadStudioToml3
 } from "@bnbagent/studio-runtime/config";
 import { stringify as tomlStringify } from "smol-toml";
 
@@ -21,6 +21,8 @@ import { stringify as tomlStringify } from "smol-toml";
 import { createHash } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
+import { loadStudioToml } from "@bnbagent/studio-runtime/config";
+import { resolveProjectAltanaSdkEntry } from "@bnbagent/studio-runtime/wallet";
 import { build as esbuildBuild } from "esbuild";
 
 // src/cli/utils/protocol.ts
@@ -133,6 +135,7 @@ async function buildZip(agentDir, outZip, opts = {}) {
     await (opts.bundle ?? bundleEntry)(entry, outfile);
     stageManifest(agentDir, buildRoot, entrypoint);
     stageStudioToml(agentDir, buildRoot);
+    await stageAltanaSdk(agentDir, buildRoot, opts.bundle ?? bundleEntry);
     assertWithinUncompressedCap(
       buildRoot,
       opts.maxUncompressedBytes ?? MAX_UNCOMPRESSED_BYTES
@@ -222,6 +225,72 @@ function stageStudioToml(agentDir, buildRoot) {
     fs.copyFileSync(src, path.join(buildRoot, "studio.toml"));
   }
 }
+async function stageAltanaSdk(agentDir, buildRoot, bundle) {
+  let kind = "evm-local";
+  try {
+    const cfg = loadStudioToml(path.join(agentDir, "studio.toml"));
+    const wallet = cfg.wallet;
+    if (wallet !== null && typeof wallet === "object" && !Array.isArray(wallet)) {
+      kind = String(wallet.kind ?? "evm-local");
+    }
+  } catch {
+  }
+  if (kind !== "altana") {
+    return;
+  }
+  let entry = null;
+  try {
+    entry = resolveProjectAltanaSdkEntry(agentDir);
+  } catch (exc) {
+    throw new Error(
+      `wallet.kind='altana' zip build: ${exc instanceof Error ? exc.message : exc}`
+    );
+  }
+  if (entry === null) {
+    throw new Error(
+      "wallet.kind='altana' but @altananetwork/sdk is not resolvable from the agent project \u2014 the zip runtime could never load the Altana session wallet. Run `pnpm add @altananetwork/sdk@0.5.1` in app/agent, or deploy as a container."
+    );
+  }
+  const pkgDir = path.join(buildRoot, "node_modules", "@altananetwork", "sdk");
+  fs.mkdirSync(pkgDir, { recursive: true });
+  await bundle(entry, path.join(pkgDir, "index.js"));
+  fs.writeFileSync(
+    path.join(pkgDir, "package.json"),
+    `${JSON.stringify(
+      {
+        name: "@altananetwork/sdk",
+        version: altanaSdkVersionOf(entry),
+        private: true,
+        type: "module",
+        main: "index.js"
+      },
+      null,
+      2
+    )}
+`
+  );
+}
+function altanaSdkVersionOf(entry) {
+  let cursor = path.dirname(entry);
+  for (let i = 0; i < 4; i += 1) {
+    const manifest = path.join(cursor, "package.json");
+    if (isFile(manifest)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+        if (pkg.name === "@altananetwork/sdk") {
+          return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+        }
+      } catch {
+      }
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return "0.0.0";
+}
 async function pack(buildRoot, outZip) {
   fs.rmSync(outZip, { force: true });
   const ZipArchive = await loadZipArchive();
@@ -568,7 +637,7 @@ import * as path4 from "path";
 import {
   envLocalPath,
   findSubProjectRoot,
-  loadStudioToml
+  loadStudioToml as loadStudioToml2
 } from "@bnbagent/studio-runtime/config";
 
 // src/cli/utils/envFile.ts
@@ -677,7 +746,7 @@ function loadDeployConfig(root) {
   try {
     return {
       agentRoot,
-      cfg: loadStudioToml(path4.join(agentRoot, "studio.toml"))
+      cfg: loadStudioToml2(path4.join(agentRoot, "studio.toml"))
     };
   } catch {
     return { agentRoot, cfg: {} };
@@ -829,7 +898,7 @@ function providerPassthrough(studio, table4) {
 }
 function buildDeploySpec(root, opts) {
   const agentRoot = findSubProjectRoot2("agent", root) ?? root;
-  const studio = loadStudioToml2(path5.join(agentRoot, "studio.toml"));
+  const studio = loadStudioToml3(path5.join(agentRoot, "studio.toml"));
   const name = String(
     opts.nameOverride || descriptorName(root) || tableOf(studio, "project").name || path5.basename(root)
   );
@@ -963,7 +1032,7 @@ async function withDeployFiles(root, opts, fn) {
     let zip;
     if (opts.packaging === "zip") {
       const agentRoot = findSubProjectRoot2("agent", root) ?? root;
-      const studio = loadStudioToml2(
+      const studio = loadStudioToml3(
         path5.join(agentRoot, "studio.toml")
       );
       const stack = tableOf(studio, "stack");

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

@@ -18,7 +18,7 @@ import {
   runPlatformAccountCommand,
   trialFromDeployCliJson,
   withDeployFiles
-} from "./chunk-VEOOFDSF.js";
+} from "./chunk-JZAW6HMV.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.6",
+  "version": "0.0.6-alpha.8",
   "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": {
@@ -38,7 +38,7 @@
     "tar": "^7.4.0",
     "viem": "^2.54.0",
     "yaml": "^2.9.0",
-    "@bnbagent/studio-runtime": "0.0.6-alpha.6"
+    "@bnbagent/studio-runtime": "0.0.6-alpha.8"
   },
   "devDependencies": {
     "@a2a-js/sdk": "^0.3.14",

package/recipes/providers/pieverse-llm/skills/funding-pieverse-llm.md

@@ -1,34 +1,29 @@
 ---
 name: funding-pieverse-llm
-description: When the user is dealing with Pieverse LLM funding — switching to a paid model, hitting InsufficientCreditsError / PieverseAccountBalanceExhaustedError, topping up the wallet for paid LLM usage, or asking "how do I pay for the LLM" / "why is my agent stuck on LLM". Covers the zero-deposit default + the paid-upgrade path.
+description: When the user is dealing with Pieverse LLM funding - switching to a paid model, hitting InsufficientCreditsError / PieverseAccountBalanceExhaustedError, topping up the wallet for paid LLM usage, or asking "how do I pay for the LLM" / "why is my agent stuck on LLM". Covers the zero-deposit default + the paid-upgrade path.
 ---
 
 # funding-pieverse-llm
 
-Procedure for **Pieverse LLM funding decisions** in a bnbagent-studio project.
-Audience: Claude Code helping a user who has already run `bag init` + `bag llm activate`.
+Procedure for **Pieverse LLM funding decisions** in a bnbagent-studio project. Audience: Claude Code helping a user who has already run `bag init` + `bag llm activate`.
 
-**Different from**: `-operating` (general ops) — this skill is specifically for the
-Pieverse credit lifecycle, paid-model upgrade, and topup troubleshooting.
+**Different from**: `-operating` (general ops) - this skill is specifically for the Pieverse credit lifecycle, paid-model upgrade, and topup troubleshooting.
 
 ## Mental model (zero-deposit default)
 
-bnbagent-studio v0.0.x defaults to **zero-deposit Pieverse activation**:
+The current bnbagent-studio release defaults to **zero-deposit Pieverse activation**:
 
-- `bag init` + `bag llm activate` together create a Pieverse account + API key
-  with **$0 initial allocation**. No wallet funding required.
-- Default model is **`auto/free`** (Pieverse's $0/token tier). The agent runs
-  unmetered against it.
+- `bag init` + `bag llm activate` together create a Pieverse account + API key with **$0 initial allocation**. No wallet funding required.
+- Default model is **`auto/free`** (Pieverse's $0/token tier). The agent runs unmetered against it.
 - The user **only needs to fund their wallet** when they want to:
-  1. Switch to a **paid model** (e.g. `auto/paid`, `claude-haiku-4.5`,
-     `anthropic/claude-sonnet-4.6`, etc.)
+  1. Switch to a **paid model** (e.g. `auto/paid`, `claude-haiku-4.5`, `anthropic/claude-sonnet-4.6`, etc.)
   2. Run `bag erc8004 register` (needs **testnet tBNB** for gas)
   3. `bag deploy` to AgentCore
 
 **Three independent balances**, on the same EOA address but different chains/assets:
 
 | Balance | Chain | Purpose | When needed |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | testnet tBNB | BSC testnet (97) | gas for ERC-8004 / ERC-8183 / deploy txs | register / deploy |
 | testnet U | BSC testnet (97) | ERC-8183 job settlement | when this agent buys/sells via 8183 |
 | mainnet U | BSC mainnet (56) | Pieverse paid LLM credits | switching to paid LLM model |
@@ -38,7 +33,7 @@ Use `bag wallet balance --all` to see all three.
 ## Quick triage decision tree
 
 | User said... | Run first |
-|---|---|
+| --- | --- |
 | "how do I switch to claude/opus/sonnet/paid model" | Section A below |
 | `InsufficientCreditsError` during a negotiate or job delivery | Section B below |
 | `PieverseAccountBalanceExhaustedError` | Section B below |
@@ -71,8 +66,7 @@ bag llm status               # should show non-zero key_credit
 bag llm test                 # one-shot smoke check
 ```
 
-**Do NOT** silently fallback to `auto/free` when a paid call fails — see the
-zero-deposit hard-fail rule. The user explicitly chose a paid model; surface the failure.
+**Do NOT** silently fallback to `auto/free` when a paid call fails - see the zero-deposit hard-fail rule. The user explicitly chose a paid model; surface the failure.
 
 ## B. InsufficientCreditsError / PieverseAccountBalanceExhaustedError
 
@@ -92,55 +86,41 @@ bag llm topup --amount 1     # spends mainnet U via x402
 bag llm allocate --amount 1  # then allocate
 ```
 
-Never edit `studio.toml [llm].model = auto/free` to "fix" a paid model's
-funding error — that's silently changing agent behavior. Either fund or
-explicitly downgrade, and tell the user which you did.
+Never edit `studio.toml [llm].model = auto/free` to "fix" a paid model's funding error - that's silently changing agent behavior. Either fund or explicitly downgrade, and tell the user which you did.
 
 ## C. PieverseColdStartTopupBlockedError
 
-The auto-topup hook refuses to fund during the first 60 seconds after process
-start. This is a **safety feature** (闸门 5) — it prevents boot-loop
-scenarios from burning the user's monthly budget.
+The auto-topup hook refuses to fund during the first 60 seconds after process start. This is a **safety feature** (闸门 5) - it prevents boot-loop scenarios from burning the user's monthly budget.
 
 Recovery:
+
 - Wait 60s, then retry the LLM call (auto-topup will engage).
-- Or topup manually: `bag llm topup --amount N` (CLI is not subject to the
-  cold-start gate; only the in-process auto-topup hook is).
-- **Never** advise the user to set `PIEVERSE_BUDGET_COLD_START_SECONDS=0` to
-  work around this — that env var is for CI/e2e only. If the user is hitting
-  this repeatedly, it indicates the agent is restarting too often; investigate
-  why.
+- Or topup manually: `bag llm topup --amount N` (CLI is not subject to the cold-start gate; only the in-process auto-topup hook is).
+- **Never** advise the user to set `PIEVERSE_BUDGET_COLD_START_SECONDS=0` to work around this - that env var is for CI/e2e only. If the user is hitting this repeatedly, it indicates the agent is restarting too often; investigate why.
 
 ## D. Auto-renew: two independent tiers + their switches
 
-Auto-renew is a **two-tier ladder**, each with its own on/off switch. Inspect
-both at once:
+Auto-renew is a **two-tier ladder**, each with its own on/off switch. Inspect both at once:
 
 ```bash
 bag llm auto-renew status        # prints the llm tier AND the wallet tier
 ```
 
-**Tier 1 — `llm` (allocate from Pieverse Account Balance; no wallet spend).**
-Default **on**. Before each LLM call the agent tops the API key up from credit
-already parked in the Account Balance when it dips below `min_balance_usd`.
+**Tier 1 - `llm` (allocate from Pieverse Account Balance; no wallet spend).** Default **on**. Before each LLM call the agent tops the API key up from credit already parked in the Account Balance when it dips below `min_balance_usd`.
 
 ```bash
 bag llm auto-renew llm off       # disable: agent runs as a plain model, no credit hook
 bag llm auto-renew llm on        # re-enable (writes [llm.auto_renew].enabled)
 ```
 
-**Tier 2 — `wallet` (spend wallet U via x402 to refill the Account Balance).**
-Default **off** (opt-in; the agent will not autonomously spend the wallet until
-this is on). Turning it on records a consent stamp — required before any
-autonomous spend.
+**Tier 2 - `wallet` (spend wallet U via x402 to refill the Account Balance).** Default **off** (opt-in; the agent will not autonomously spend the wallet until this is on). Turning it on records a consent stamp - required before any autonomous spend.
 
 ```bash
 bag llm auto-renew wallet on     # opt in (= bag budget enable; records acknowledged_at)
 bag llm auto-renew wallet off    # opt out (= bag budget disable)
 ```
 
-`bag llm auto-renew wallet on` is exactly `bag budget enable` and accepts the
-same cap overrides via that command:
+`bag llm auto-renew wallet on` is exactly `bag budget enable` and accepts the same cap overrides via that command:
 
 ```bash
 bag budget show                                  # current state (default: disabled)
@@ -153,51 +133,39 @@ bag budget enable \
 ```
 
 Once enabled, the agent will:
+
 - Wait at least 60s after process start before any topup (cold-start gate)
-- Try to topup_x402 from mainnet U when the API key drops below
-  `min_balance_usd` (default $0.2)
-- Stop and raise on cap-exceeded; not retry on failure (exponential backoff
-  applies — next LLM call may retry)
-- Log every topup attempt to `~/.bnbagent-studio/<project>/logs/topup.jsonl`
-  and print a red-text notice to stdout
+- Try to topup_x402 from mainnet U when the API key drops below `min_balance_usd` (default $0.2)
+- Stop and raise on cap-exceeded; not retry on failure (exponential backoff applies - next LLM call may retry)
+- Log every topup attempt to `~/.bnbagent-studio/<project>/logs/topup.jsonl` and print a red-text notice to stdout
 
-`WALLET_PASSWORD` env must be present in the runtime — without it the gate
-falls back to allocate-only mode (no wallet spend, no error).
+`WALLET_PASSWORD` env must be present in the runtime - without it the gate falls back to allocate-only mode (no wallet spend, no error).
 
 ## E. Protocol-level details (for advanced cases)
 
-When the user needs to understand the Pieverse protocol itself (raw SIWE,
-x402 v2 envelope, deposit methods schema, signing typed data), point them
-to Pieverse's official skill markdown — it is the authoritative reference:
+When the user needs to understand the Pieverse protocol itself (raw SIWE, x402 v2 envelope, deposit methods schema, signing typed data), point them to Pieverse's official skill markdown - it is the authoritative reference:
 
 - https://llm.pieverse.io/ai-gateway/skill.md (overview)
 - https://llm.pieverse.io/ai-gateway/references/siwe-format.md (SIWE login)
 - https://llm.pieverse.io/ai-gateway/references/x402-payment.md (topup mechanics)
 - https://llm.pieverse.io/ai-gateway/references/api-reference.md (key/usage)
 
-Do **not** re-implement what these documents specify. studio's `bag llm` /
-`bag wallet` commands already wrap these flows.
+Do **not** re-implement what these documents specify. studio's `bag llm` / `bag wallet` commands already wrap these flows.
 
 ## Read-only inspection (no password needed)
 
-The CLI commands that only need the `sk-pv-...` API key (no wallet signature)
-work without prompting for `WALLET_PASSWORD`:
+The CLI commands that only need the `sk-pv-...` API key (no wallet signature) work without prompting for `WALLET_PASSWORD`:
 
 ```bash
 bag llm usage [--days 7]         # per-key usage, no session
 bag llm test --message "hi"      # one-shot LLM smoke (uses key only)
 ```
 
-Anything that needs the session_token (balance / deposits / key management)
-will require `WALLET_PASSWORD` to be set in the environment or interactively.
+Anything that needs the session_token (balance / deposits / key management) will require `WALLET_PASSWORD` to be set in the environment or interactively.
 
 ## Hard rules
 
-- Wallet private keys are never sent to Pieverse, never logged, and never put in
-  error messages. (Deploying to the managed platform is the one case a key leaves
-  your machine — it is sent to the operator to sign; self-deploy keeps it local.)
-- `session_token` is memory-only per Pieverse spec — never persist to disk.
-- When in doubt about a topup amount, suggest **smaller** values. Starting at
-  $0.5 – $1 is far better than $5+ for a user's first paid run.
-- If the user has not opted into `bag budget enable`, never trigger an
-  auto-topup on their behalf — surface the error and let them decide.
+- Wallet private keys are never sent to Pieverse, never logged, and never put in error messages. (Deploying to the managed platform is the one case a key leaves your machine - it is sent to the operator to sign; self-deploy keeps it local.)
+- `session_token` is memory-only per Pieverse spec - never persist to disk.
+- When in doubt about a topup amount, suggest **smaller** values. Starting at $0.5 - $1 is far better than $5+ for a user's first paid run.
+- If the user has not opted into `bag budget enable`, never trigger an auto-topup on their behalf - surface the error and let them decide.

package/skills/bnbagent-studio.md

@@ -1,55 +1,24 @@
 ---
 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 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.
+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)
 
-`bnbagent-studio` (CLI: `bag`) wires the `@bnbagent/sdk` protocol layer (wallet /
-ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploys it
-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 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 deploys into the
-user's own account. All cloud lifecycle calls go through the pinned
-`@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.
+`bnbagent-studio` (CLI: `bag`) wires the `@bnbagent/sdk` protocol layer (wallet / ERC-8004 / ERC-8183 / Pieverse LLM) into a TypeScript agent project, then deploys it 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 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 deploys into the user's own account. All cloud lifecycle mutations go through the pinned `@bnbagent/deploy-cli`; the optional AWS CLI is used only by the fail-open, read-only AgentCore quota check in `bag deploy prepare`. 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.
 
 ## The single seller runtime model (the invariants)
 
-One deployed runtime, one signer: a single valuable Agent serves the selected
-faces (A2A `src/main.ts` on `:9000`, MCP `src/mcpMain.ts` on `:8000/mcp`, or
-A2A-native `src/dualMain.ts` on `:9000` with tunneled `/mcp`),
-holds the key, and signs in-process. The ERC-8183 rail exposes exactly two
-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 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
-`.studio/wallets/`, outside the deploy codeLocation, and is injected only via
-the selected provider's delegated secret channel. `settle` is manual
-(`bag erc8183 settle`). Full layout and lifecycle details live in the
-references below — read them before acting.
-
-## Decision tree — which reference to read next
-
-**References are plain markdown files installed in THIS skill's directory** at
-`references/<name>.md`. When a row matches, READ THAT FILE before acting — do
-not answer from memory.
+One deployed runtime, one signer: a single valuable Agent serves the selected faces (A2A `src/main.ts` on `:9000`, MCP `src/mcpMain.ts` on `:8000/mcp`, or A2A-native `src/dualMain.ts` on `:9000` with tunneled `/mcp`), holds the key, and signs in-process. The ERC-8183 rail exposes exactly two 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 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 `.studio/wallets/`, outside the deploy codeLocation, and is injected only via the selected provider's delegated secret channel. `settle` is manual (`bag erc8183 settle`). Full layout and lifecycle details live in the references below - read them before acting.
+
+## Decision tree - which reference to read next
+
+**References are plain markdown files installed in THIS skill's directory** at `references/<name>.md`. When a row matches, READ THAT FILE before acting - do not answer from memory.
 
 | User intent | Read / do |
-|---|---|
+| --- | --- |
 | Create a brand new single seller project from zero | `references/bnbagent-studio-scaffolding-agent.md` |
 | 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` |
@@ -57,58 +26,44 @@ not answer from memory.
 | 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` |
+| 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` |
 | 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` |
 | (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.
+If two or more match, read both - they're designed to be orthogonal.
 
 ### Where the references live
 
-Next to this file: this skill installs as a directory with a `references/`
-subdirectory (Claude Code: `~/.claude/skills/bnbagent-studio/references/` or the
-project-scope `<project>/.claude/skills/bnbagent-studio/references/`; Cursor:
-`bnbagent-studio/references/` under the rules directory, beside the `.mdc`
-rules). If a reference file is missing, `bag skills install` (re)installs it.
+Next to this file: this skill installs as a directory with a `references/` subdirectory (Claude Code: `~/.claude/skills/bnbagent-studio/references/` or the project-scope `<project>/.claude/skills/bnbagent-studio/references/`; Cursor: `bnbagent-studio/references/` under the rules directory, beside the `.mdc` rules). If a reference file is missing, `bag skills install` (re)installs it.
 
-<!-- Maintainers: this skill's DESCRIPTION only carries ENTRY intents (identity
-+ create/deploy/run/debug/operate/monetize). Mid-journey topics (twak, EIP-712,
-disputes, buyer flow, tool wiring, ...) are routed by the decision tree above and
-must NOT be added to the description — see docs/design/decisions.md §14. -->
+<!-- Maintainers: this skill's DESCRIPTION only carries ENTRY intents (identity + create/deploy/run/debug/operate/monetize). Mid-journey topics such as twak, EIP-712, disputes, buyer flow, and tool wiring are routed by the decision tree above and must NOT be added to the description - see docs/design/decisions.md §14. -->
 
 ## 5 core commitments (always honor)
 
-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 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.
+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 the runtime only a bounded session — local `bag dev` and deploy both receive the session (`ALTANA_SESSION`), never the admin keystore. 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 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.
+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]` 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`, and `fix-gitignore` 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
 
-- **CLI** — write-side (wallet ops, on-chain register, x402 buy, deploy)
-- **MCP** — an external seller face (`bag init --protocols MCP`), composable
-  with A2A; dual mode is A2A-native so `HEALTHY_BUSY` preserves background work
-- **`@bnbagent/studio-runtime/tools`** — 15 pure read-only functions, wrapped into LLM tools by the chain-tools recipe (read `references/bnbagent-studio-wiring-llm-tools.md`)
+- **CLI** - write-side (wallet ops, on-chain register, x402 buy, deploy)
+- **MCP** - an external seller face (`bag init --protocols MCP`), composable with A2A; dual mode is A2A-native so `HEALTHY_BUSY` preserves background work
+- **`@bnbagent/studio-runtime/tools`** - 15 pure read-only functions, wrapped into LLM tools by the chain-tools recipe (read `references/bnbagent-studio-wiring-llm-tools.md`)
 
 ## Where docs live
 
-- `docs/design/architecture.md` — layered architecture
-- `docs/design/decisions.md` — decision records (Pieverse default, signing policy, chain tools, zero-deposit, skill reorg, **single seller runtime + protocol faces**)
-- `docs/guides/pieverse-integration.md` — Pieverse LLM full lifecycle
-- `docs/guides/user-guide.md` — end-user procedures
+- `docs/design/architecture.md` - layered architecture
+- `docs/design/decisions.md` - decision records (Pieverse default, signing policy, chain tools, zero-deposit, skill reorg, **single seller runtime + protocol faces**)
+- `docs/guides/pieverse-integration.md` - Pieverse LLM full lifecycle
+- `docs/guides/user-guide.md` - end-user procedures