@bnbagent/studio-cli 0.0.13 → 0.0.14-alpha.2

package/recipes/runtimes/azure-foundry/code/{{PKG}}/sellerCore.ts.tmpl

@@ -38,24 +38,38 @@
  */
 
 import { ERC8183JobOps } from "@bnbagent/sdk/erc8183";
+import { maskUrlSecrets } from "@bnbagent/studio-runtime/audit";
 import { SubmitPermanentlyUnsupportedError } from "@bnbagent/studio-runtime/erc8183";
 import { getWallet } from "@bnbagent/studio-runtime/wallet";
+import {
+  DeliveryTimeoutError,
+  deliveryTimeoutSeconds,
+  envSeconds,
+  minimumDeliveryWindowSeconds,
+  withTimeout,
+} from "./deliveryPolicy.js";
 import { limitCommerceOperation } from "./requestLimits.js";
 import * as defaultSigning from "./signing.js";
 
+function safeLogText(value: unknown): string {
+  const text =
+    value instanceof Error
+      ? (value.stack ?? `${value.name}: ${value.message}`)
+      : String(value ?? "");
+  return maskUrlSecrets(text);
+}
+
 const log = {
-  info: (msg: string) => console.log(`[seller-agent.core] ${msg}`),
-  warn: (msg: string) => console.warn(`[seller-agent.core] WARNING ${msg}`),
+  info: (msg: string) => console.log(`[seller-agent.core] ${safeLogText(msg)}`),
+  warn: (msg: string) =>
+    console.warn(`[seller-agent.core] WARNING ${safeLogText(msg)}`),
   error: (msg: string, e?: unknown) =>
-    console.error(`[seller-agent.core] ERROR ${msg}`, e ?? ""),
+    console.error(
+      `[seller-agent.core] ERROR ${safeLogText(msg)}`,
+      safeLogText(e),
+    ),
 };
 
-/** Read a positive timeout (seconds) from the env, falling back to `dflt`. */
-function envSeconds(name: string, dflt: number): number {
-  const v = Number(process.env[name] || dflt);
-  return Number.isFinite(v) && v > 0 ? v : dflt;
-}
-
 // Background-task ceilings. notifyFunded ACKs immediately and delivers in a
 // BACKGROUND task; AgentCore keeps the scale-to-zero microVM warm
 // (HEALTHY_BUSY) while isBusy() is true. A delivery (LLM text + on-chain
@@ -65,43 +79,10 @@ function envSeconds(name: string, dflt: number): number {
 // billing memory the whole time. A timed-out job is treated as TRANSIENT
 // (not dropped): the funded job stays on-chain and a later sweep re-delivers
 // it idempotently. (Read lazily so tests can tune them via the env.)
-const jobDeliveryTimeoutSeconds = () =>
-  envSeconds("NOTIFY_DELIVERY_TIMEOUT_SECONDS", 600);
 const sweepTimeoutSeconds = () => envSeconds("NOTIFY_SWEEP_TIMEOUT_SECONDS", 60);
 const preverifyTimeoutSeconds = () =>
   envSeconds("NOTIFY_PREVERIFY_TIMEOUT_SECONDS", 30);
 
-/** Rejection raised by {@link withTimeout} when the deadline fires. */
-export class DeliveryTimeoutError extends Error {}
-
-/**
- * Race `work` against a deadline, aborting `controller` when it fires.
- *
- * JS cannot hard-cancel an arbitrary promise the way asyncio.wait_for
- * cancels a coroutine: the abort signal stops the LLM call (the AI SDK
- * honours it), and the on-chain layers are idempotent — `verifySignedJob`
- * returns non-OK for an already-SUBMITTED job and `submitResult` re-verifies
- * FUNDED — so an orphaned straggler can never double-deliver.
- */
-async function withTimeout<T>(
-  work: Promise<T>,
-  seconds: number,
-  controller?: AbortController,
-): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      controller?.abort();
-      reject(new DeliveryTimeoutError(`timed out after ${seconds}s`));
-    }, seconds * 1000);
-  });
-  try {
-    return await Promise.race([work, deadline]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 /**
  * The LLM work hook: produce the deliverable text for a prompt.
  *
@@ -125,6 +106,7 @@ export interface SigningApi {
   ): Promise<Record<string, unknown>>;
   verifySignedJob(
     jobId: number,
+    minimumRemainingSeconds?: number,
   ): Promise<{ ok: boolean; reason: string; permanent: boolean }>;
   jobSpec(
     jobId: number,
@@ -284,7 +266,7 @@ export class SellerCore {
       // Time-bounded: a hung RPC must not stall the ack path. On timeout we
       // fall through to accept-and-re-verify below.
       const v = await withTimeout(
-        this.signing.verifySignedJob(jobId),
+        this.signing.verifySignedJob(jobId, minimumDeliveryWindowSeconds()),
         preverifyTimeoutSeconds(),
       );
       if (!v.ok && v.permanent) {
@@ -351,7 +333,7 @@ export class SellerCore {
         verified
           ? this.doWorkAndSubmit(jobId, controller.signal)
           : this.fulfillJob(jobId, controller.signal),
-        jobDeliveryTimeoutSeconds(),
+        deliveryTimeoutSeconds(),
         controller,
       );
       log.info(`notify_funded job ${jobId} → ${JSON.stringify(result)}`);
@@ -367,7 +349,7 @@ export class SellerCore {
       if (e instanceof DeliveryTimeoutError) {
         // Transient by design — leave terminal false so a later sweep retries.
         log.warn(
-          `background delivery of job ${jobId} timed out after ${jobDeliveryTimeoutSeconds()}s; will retry`,
+          `background delivery of job ${jobId} timed out after ${deliveryTimeoutSeconds()}s; will retry`,
         );
       } else {
         log.error(`background delivery of job ${jobId} failed`, e);
@@ -399,7 +381,10 @@ export class SellerCore {
     jobId: number,
     abortSignal: AbortSignal,
   ): Promise<Record<string, unknown>> {
-    const v = await this.signing.verifySignedJob(jobId);
+    const v = await this.signing.verifySignedJob(
+      jobId,
+      minimumDeliveryWindowSeconds(),
+    );
     if (!v.ok) {
       return { ok: false, job_id: jobId, skip: v.permanent, reason: v.reason };
     }

package/recipes/runtimes/azure-foundry/code/{{PKG}}/tools.ts.tmpl

@@ -30,6 +30,7 @@ import * as cr from "@bnbagent/studio-runtime/tools";
 import { loadStudioToml } from "@bnbagent/studio-runtime/config";
 import { tool, type ToolSet } from "ai";
 import { z } from "zod";
+import { READ_TOOL_CATALOG } from "./readToolCatalog.js";
 
 /**
  * The project-wide default network (`[network].default`) — tool calls that
@@ -46,51 +47,34 @@ function defaultNetwork(): string {
   }
 }
 
-const networkArg = z
-  .string()
-  .optional()
-  .describe("studio network name (defaults to the project's [network].default)");
-
 export const LLM_READ_TOOLS: ToolSet = {
   // --- Wallet & chain basics ---
   wallet_info: tool({
-    description:
-      "Describe the agent's active wallet (address, kind, key location).",
-    inputSchema: z.object({}),
+    description: READ_TOOL_CATALOG.wallet_info.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.wallet_info.inputSchema),
     execute: async () => cr.walletInfo(),
   }),
   balance_native: tool({
-    description:
-      "Native BNB balance of an address (defaults to the agent's own wallet).",
-    inputSchema: z.object({
-      address: z.string().optional().describe("0x address; omit for own wallet"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.balance_native.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.balance_native.inputSchema),
     execute: async ({ address, network }) =>
       cr.balanceNative(address ?? null, network ?? defaultNetwork()),
   }),
   balance_u: tool({
     // requires [u_token] in studio.toml
-    description:
-      "$U (payment token) balance of an address (defaults to the agent's own wallet).",
-    inputSchema: z.object({
-      address: z.string().optional().describe("0x address; omit for own wallet"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.balance_u.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.balance_u.inputSchema),
     execute: async ({ address, network }) =>
       cr.balanceU(address ?? null, network ?? defaultNetwork()),
   }),
   network_info: tool({
-    description: "Chain id / RPC / token info for a studio network.",
-    inputSchema: z.object({ network: networkArg }),
+    description: READ_TOOL_CATALOG.network_info.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.network_info.inputSchema),
     execute: async ({ network }) => cr.networkInfo(network ?? defaultNetwork()),
   }),
   tx_status: tool({
-    description: "Status + receipt summary of a transaction hash.",
-    inputSchema: z.object({
-      tx_hash: z.string().describe("0x transaction hash"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.tx_status.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.tx_status.inputSchema),
     execute: async ({ tx_hash, network }) =>
       cr.txStatus(tx_hash, network ?? defaultNetwork()),
   }),
@@ -106,21 +90,15 @@ export const LLM_READ_TOOLS: ToolSet = {
   // --- ERC-8004 identity (read-only lookups the LLM may want for context) ---
   agent_info: tool({
     // requires [erc8004] in studio.toml
-    description: "ERC-8004 identity record for an agent id.",
-    inputSchema: z.object({
-      agent_id: z.number().int().describe("ERC-8004 agent id"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.agent_info.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.agent_info.inputSchema),
     execute: async ({ agent_id, network }) =>
       cr.agentInfo(agent_id, network ?? defaultNetwork()),
   }),
   agent_by_address: tool({
     // requires [erc8004] in studio.toml
-    description: "Look up an ERC-8004 agent registration by wallet address.",
-    inputSchema: z.object({
-      address: z.string().describe("0x wallet address"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.agent_by_address.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.agent_by_address.inputSchema),
     execute: async ({ address, network }) =>
       cr.agentByAddress(address, network ?? defaultNetwork()),
   }),
@@ -128,22 +106,15 @@ export const LLM_READ_TOOLS: ToolSet = {
   // --- ERC-8183 jobs (READ-ONLY status/list — writes live in signing.ts) ---
   job_status: tool({
     // requires [erc8183] in studio.toml
-    description: "Read-only ERC-8183 job summary (status, budget, deliverable URL).",
-    inputSchema: z.object({
-      job_id: z.number().int().describe("on-chain job id"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.job_status.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.job_status.inputSchema),
     execute: async ({ job_id, network }) =>
       cr.jobStatus(job_id, network ?? defaultNetwork()),
   }),
   job_list: tool({
     // requires [erc8183] in studio.toml
-    description: "List recent ERC-8183 jobs (optionally only this agent's).",
-    inputSchema: z.object({
-      limit: z.number().int().optional(),
-      mine: z.boolean().optional().describe("only jobs assigned to this agent"),
-      network: networkArg,
-    }),
+    description: READ_TOOL_CATALOG.job_list.description,
+    inputSchema: z.object(READ_TOOL_CATALOG.job_list.inputSchema),
     execute: async ({ limit, mine, network }) =>
       cr.jobList({ limit, mine, network: network ?? defaultNetwork() }),
   }),

package/recipes/runtimes/azure-foundry/code/{{PKG}}/unifiedMain.ts.tmpl

@@ -225,7 +225,8 @@ export function buildRunWork(): RunWork {
 
 function hasErc8183Rail(cfg: TomlTable): boolean {
   const payments = asTable(cfg.payments);
-  return asTable(payments?.erc8183) !== null;
+  const rail = asTable(payments?.erc8183);
+  return rail !== null && rail.enabled !== false;
 }
 
 function asTable(value: unknown): TomlTable | null {

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

@@ -29,7 +29,7 @@ node = [
     # on either cloud.
     "@aws-sdk/client-secrets-manager@^3.600.0",
     "@bnbagent/studio-runtime",
-    "@bnbagent/sdk@0.5.5",
+    "@bnbagent/sdk@0.5.6",
     # The LLM work hook (generateText + tools) and the model factory
     # (model.ts buildModel — studio.toml [llm] + the provider key env).
     "ai@^7.0.29",

package/recipes/wallet/recipe.toml

@@ -11,8 +11,9 @@ node = ["@altananetwork/sdk@0.7.1"]
 node = ["@turnkey/sdk-server@8.1.0", "@turnkey/viem@0.14.34"]
 
 [env]
-# kind='twak': the twak CLI reads the unlock password from the environment —
-# it never goes on a command line.
+# kind='twak': Studio generates this unlock password. Runtime operations read
+# it from the environment; upstream twak requires it briefly on the one-time
+# wallet-create child argv, which Studio never prints.
 TWAK_WALLET_PASSWORD = "unlocks ~/.twak/wallet.json (twak kind); set in .studio/.env.local"
 # kind='turnkey': P-256 API credential; the signing key never leaves Turnkey's enclave.
 TURNKEY_API_PRIVATE_KEY = "Turnkey P-256 API private key (turnkey kind); set in .studio/.env.local"

package/recipes/x402-buyer/recipe.toml

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

package/skills/bnbagent-studio.md

@@ -9,6 +9,16 @@ description: The single entry point for bnbagent-studio - a TypeScript CLI (`bag
 
 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.
 
+## Runtime preflight
+
+This skill requires `bag` **0.0.13 or newer**. Before following any workflow,
+run the read-only command `bag --version`. If `bag` is missing or older, stop
+and ask the user to run `npm install -g @bnbagent/studio-cli@latest`, then
+repeat the version check. Never install or upgrade a global executable without
+the user's approval.
+
+<!-- bag-compatibility: >=0.0.13 -->
+
 ## The single seller runtime model (the invariants)
 
 One deployed runtime, one signer: a single valuable Agent serves the selected faces (A2A `src/unifiedMain.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.
@@ -22,6 +32,7 @@ One deployed runtime, one signer: a single valuable Agent serves the selected fa
 | 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` |
+| Report a CLI problem or share product feedback | Run `bag feedback`, review the local JSON bundle before attaching it, and read `references/bnbagent-studio-operating.md`; Studio never uploads or submits it automatically |
 | Implement what the Agent sells, tune pricing, publish over A2A and/or MCP, defend disputes (seller flow) | `references/bnbagent-studio-selling-via-8183.md` |
 | Sell one paid or FREE HTTP request through the selected B402-backed x402 or MPP 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\|azure --yes` (and `--allow-multiple` when keeping another provider active). Read `references/bnbagent-studio-use-bnb-trial.md`, `references/bnbagent-studio-use-aws-agentcore.md`, or `references/bnbagent-studio-use-azure-foundry.md` for the selected provider. `bag deploy status` lists every recorded provider; multi-deployment logs/verify/destroy require `--provider`. |
@@ -54,7 +65,7 @@ Treat ERC-8183 amounts as decimal strings at CLI/config boundaries and `bigint`
 
 ## CLI groups at a glance
 
-`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `mpp`, `agents`, `config`, `env`, `dev`, `doctor`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` - see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure] [--backend aws\|azure]` is the primary deploy command; `--backend` is valid only for provider `bnb` and confirms the recipe-derived managed backend. `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.5.15`.
+`init`, `scan`, `recipe`, `skills`, `wallet`, `erc8004`, `erc8183`, `x402`, `mpp`, `agents`, `config`, `env`, `dev`, `doctor`, `feedback`, `audit`, `deploy`, `platform`, `llm`, `bundle`, `budget` - see `bag --help` for details. `bag deploy [--provider bnb\|aws\|azure] [--backend aws\|azure]` is the primary deploy command; `--backend` is valid only for provider `bnb` and confirms the recipe-derived managed backend. `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.5.15`.
 
 ## Tool surface
 

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

@@ -46,6 +46,7 @@ This playbook covers **generic ops**: dev / doctor / balances / RPC / incident t
 | "wallet balance is wrong" | Check both tBNB (gas) and U (token); see balance section |
 | "is it deployed?" / "deploy status" | `bag deploy status` lists every locally recorded BNB/AWS deployment and asks `bnbagent-deploy` for live state; add `--no-probe` for record-only output |
 | "deploy logs" / "verify" / "tear it down" | With one recorded deployment, `bag deploy {logs,verify,destroy}` selects it automatically. With multiple, choose interactively or pass `--provider bnb\|aws` in automation. Provider lifecycle and status/log calls go through `bnbagent-deploy`; ERC-8004 reconciliation remains a Studio chain operation. `bag platform credit` shows the BNB trial countdown. |
+| "report this error" / "send feedback" | Run `bag feedback`. It builds an inspectable, owner-readable JSON bundle from the last command's allowlisted lifecycle data, shows the release-pinned Google Form ID, asks before opening it, and never uploads or submits anything. If no production Form ID has been provisioned, keep the bundle local; do not substitute a project-provided form. Review the file before manually attaching it; `.studio/audit-log.jsonl`, argv, output, paths, credentials, addresses, and transaction hashes are excluded. |
 
 ## Common ops procedures
 

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>`) / `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` |
+| 4 | **Wallet kind** (`--wallet-kind`) | `evm-local` (encrypted local keystore at the workspace root; Studio generates its password on the new-wallet happy path; `--evm-keystore <v3-file>` copies and adopts an existing encrypted keystore with its original password; `--private-key` imports an existing raw key; CodeZip deploy) / `twak` (**fully supported, opt in with `--wallet-kind twak`** - project-pinned Trust Wallet CLI 0.20.0, self-custody encrypted mnemonic in a **project-dedicated** home `.studio/twak`, isolated from the main `~/.twak`; `bag wallet twak-init` performs credential init/verification, password generation, wallet creation/adoption, and address anchoring without the upstream wizard; 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` (offline only) / `ipfs` / `s3` / `azure-blob`. Self-hosted deploys use BYOS credentials; managed-platform deploys receive an operator-owned storage endpoint and scoped token through the sealed runtime-secret channel. | `local` |
 | 6 | **Protocol faces** (`--protocols`) | any non-empty subset of `A2A`, `MCP`, `X402` | `A2A,X402` (`A2A` for Altana) |
 | 7 | **LLM model** | provider catalogue; for `pieverse-llm` the default `auto/free` runs at $0/token | `auto/free` |
@@ -136,9 +136,11 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
 >
 > If Bun is missing at deploy time, **PAUSE** and have the USER install it (Bun 1.3+, or set `BNBAGENT_DEPLOY_COMMAND`). Likewise for `bag dev --container` only: the npm `@aws/agentcore` CLI must be present and must win on PATH over the incompatible `bedrock-agentcore-starter-toolkit` shim - global tools on the user's machine, so the user installs them, not you.
 
-> **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.
+> **Onboarding note.** On a human TTY, `bag init` runs steps 3, 4 and 6 automatically (a new evm-local wallet gets a CSPRNG password without prompting; `--evm-keystore` instead asks for the existing file's original password; then Studio 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> [--protocols <comma-list>] [--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). Omit `--protocols` and `--rails` for the default A2A + X402 faces with both ERC-8183 and B402 rails (all wallet kinds, altana included — its paid B402 payout lands at the admin address). Pass either flag when the user chose another face/rail combination (`--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/unifiedMain.ts` (the express + A2A entrypoint, one code set for both deploy clouds) + `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`.)
+
+   To reuse an encrypted evm-local wallet at scaffold time, add `--wallet-kind evm-local --evm-keystore /secure/path/wallet.json`. The input must be Web3 Secret Storage v3. Studio copies it to the private workspace wallet directory and, on a TTY, verifies it using its original password; it never generates a replacement password. For an already-created project that points at a shared wallet directory, set the original password locally and run `bag wallet new --keystore-dir /secure/path/wallets`; the directory and anchor are persisted for later commands.
 > **Current storage choices:** `--storage-provider` accepts `local`, `ipfs`, `s3`, and `azure-blob`. The latter three are BYOS only for self-hosted deployment; a managed-platform deployment replaces the writer with its injected API endpoint/token.
 >
 > **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.
@@ -148,44 +150,19 @@ Build a TodoWrite list. The shape depends on the `wallet kind`. The canonical 8-
    pnpm install        # npm install works too - tooling is the user's choice
    ```
    The sub-project's `package.json` carries its deps: `@bnbagent/studio-runtime` (the runtime lib, pinned to the scaffolding CLI's exact version - NOT the CLI itself) + `@bnbagent/sdk` + `ai` (the AI SDK) plus the **protocol-specific** group - A2A adds `@a2a-js/sdk` + `express`, MCP adds `@modelcontextprotocol/sdk` instead (an A2A-only deploy never ships the MCP SDK, and an MCP-only deploy never ships the A2A one). For local dev against unreleased libs, `bag init` vendors local `.tgz` tarballs and points the manifest at them automatically.
-3. **Set the wallet password** - the USER does this, NOT you.
-
-   🔒 **SECURITY - never route the wallet password through the chat.** It encrypts the key material that is the Agent's sole signing key. Do **NOT** ask the user to type it into the chat, and do **NOT** run any command with the password on the command line (`bag env set <PW_VAR> <literal>`, `twak wallet create --password <literal>`, …) - it would land in the session transcript, be sent to the model API, and hit shell history / `ps`.
-
-   Tell the user to set it **themselves, in their own terminal**, so it never reaches you. The env var depends on the wallet kind:
-   - **twak** → `TWAK_WALLET_PASSWORD` (the twak CLI reads it itself)
-   - **evm-local** → `WALLET_PASSWORD`
-
-   ```bash
-   # In YOUR OWN terminal (not via the agent): open .studio/.env.local and
-   # set the line for your wallet kind:
-   #     TWAK_WALLET_PASSWORD=<a strong password you choose>   # twak
-   #     WALLET_PASSWORD=<a strong password you choose>        # evm-local
-   # Save it. Do not paste the password into this chat.
-   ```
-
-   `bag` auto-loads `.studio/.env.local` (resolved via the project root), so once the line is set you do NOT need to `source` it or `cd` anywhere special - `bag wallet new` / `bag llm activate` will read it. Wait for the user to confirm they've set it before continuing.
+3. **Keep all wallet secrets out of chat.** Never ask for, read, echo, or log a wallet password, NaaS Access ID/HMAC secret, mnemonic, or private key. Studio generates new-wallet passwords with the OS cryptographic random source and stores them in `.studio/.env.local` (0600). There is no weak-random fallback.
 
 4. **Create / adopt the wallet** - depends on the wallet kind:
-   - **twak** (fully supported - opt in with `--wallet-kind twak`): `bag init` writes `[wallet].twak_home = "../../.studio/twak"` - a **project-dedicated** wallet isolated from your main `~/.twak`, so a deploy never pushes the main wallet's key material to Secrets Manager. Setting it up is a ONE-TIME job: the user runs the interactive 3-step `twak setup` wizard themselves in their own terminal, then `bag wallet twak-init` creates the wallet (so the password never goes into a command line). Start with the wizard:
-
-     ```bash
-     HOME=<workspace>/.studio/twak twak setup
-     ```
 
-     **Tell the user exactly what to pick at each wizard step** - it is not obvious and a wrong pick is dangerous:
-     - **Step 1 (API credentials):** paste Access ID + HMAC secret from https://portal.trustwallet.com/dashboard/apps; WalletConnect Project ID → leave blank, ENTER.
-     - **Step 2 (wire up harnesses): SELECT NONE, press ENTER** (don't press SPACE/`a`) - never wire twak's signing MCP into Claude Code / Cursor / etc.; studio keeps signing in fixed code, not MCP.
-     - **Step 3 (wallet): pick `3) Skip for now`**, then create the wallet with the standalone command below. (`1) Create a new agent wallet` persists the password via the OS keychain, which fails on keychain-less environments - "OS keychain cannot persist passwords here … headless / Docker" - and studio unlocks via `TWAK_WALLET_PASSWORD` env anyway. NEVER pick `2) Use WalletConnect` = your main wallet.)
+   - **twak**: the generated project pins `@trustwallet/cli@0.20.0`; no global CLI install is needed. `bag init` on a human TTY delegates the full happy path to Studio. For a `--no-onboard` or agent-driven scaffold, ask the user to create a NaaS app at https://portal.trustwallet.com/dashboard/apps and run this command in their terminal, where Studio can collect both values through hidden prompts:
 
      ```bash
-     cd app/agent && bag wallet twak-init                       # hidden prompt
-     printf %s "$PW" | bag wallet twak-init --password-stdin     # CI / scripts
+     cd app/agent && bag wallet twak-init
      ```
 
-     Use UPPER + lower + digit; put that same password in `.studio/.env.local` as `TWAK_WALLET_PASSWORD`. `twak-init` passes `--no-keychain`, which keeps the password out of the OS keychain (no macOS prompt); studio unlocks via the env. (If a macOS prompt _loops_ on a manual `twak` run, do NOT "Reset Default Keychain" - `pkill -9 -f twak`, then re-run with `--no-keychain`.) It also adopts the address into `studio.toml` and echoes it - confirm it's the intended wallet before funding/deploy, and there is no separate `bag wallet new` step. The manual equivalent is `HOME=<workspace>/.studio/twak twak wallet create --password <StrongPw> --no-keychain` followed by `bag wallet new`. Full detail: the `bnbagent-studio-using-twak-wallet.md` reference (in the router skill's `references/` directory). To reuse an EXISTING wallet across agents, scaffold with `bag init --twak-home <path-to-its-home>` instead. Reusing your main `~/.twak` is opt-in only (`--twak-home ~`) and discouraged. Full detail: the `bnbagent-studio-using-twak-wallet.md` reference (in the router skill's `references/` directory).
+     Do not run or explain the upstream `twak setup` wizard. `twak-init` uses the project-pinned binary, runs `twak init --json`, verifies an authenticated read, generates and persists `TWAK_WALLET_PASSWORD`, creates/adopts the project-dedicated no-keychain wallet, and anchors the address. No separate `bag wallet new` step exists. For CI, the user may place `TWAK_ACCESS_ID` + `TWAK_HMAC_SECRET` in `.studio/.env.local` themselves; never route them through chat. Reuse an existing wallet only with explicit `--twak-home <home-style-path>`; `--twak-home ~` is a discouraged opt-in to the main wallet. Load `bnbagent-studio-using-twak-wallet.md` for the exact security and deploy contract.
 
-   - **evm-local** (default): `bag wallet new` creates the encrypted keystore. To import an existing key, the user pastes it and you immediately run `bag wallet new --private-key <pk>` (the key is written only into the keystore, nowhere else on disk).
+   - **evm-local** (default): the new-wallet TTY happy path generates `WALLET_PASSWORD` with the OS CSPRNG, persists it privately, then creates the encrypted keystore in-process. After `--no-onboard`, run `(cd app/agent && bag wallet new --generate-password)` for the same non-interactive safe path. It refuses to replace an existing or anchored wallet. For an existing encrypted v3 file, prefer `bag init ... --wallet-kind evm-local --evm-keystore <path>` and use the file's original password; Studio copies and verifies the file without re-encrypting it. To import a raw key, use the hidden `bag wallet new --private-key` prompt or stdin; never pass the key inline.
 
 5. **Fund the wallet - OPTIONAL; do NOT block on it.** The default `auto/free` LLM model runs at $0 and AgentCore deploy consumes no wallet balance, so a brand-new seller can scaffold, run `bag dev`, and deploy with an empty wallet. `bag doctor` and `bag deploy` only **WARN** (never block) on zero balance. Funding is needed later only for: a paid LLM model, on-chain settle, paying positive-price ERC-8183 job buys, or buying/smoking a PAID B402 request. A FREE ERC-8183 buy needs no U escrow or ERC-20 approval, but still needs the ERC-8183 state-changing calls and their gas/paymaster path. A FREE B402/x402 request needs neither token funding nor a facilitator call. When funding is needed, the wallet uses **TWO distinct U balances on TWO chains** (same wallet address, same private key, different chains):
    - **tBNB (gas)** on BSC testnet: message the official Telegram bot https://t.me/bnbchain_official_bot with `I would like to get tBNB to my wallet <address>` (up to 0.3 tBNB/day; replies with the tx hash). More options: https://docs.bnbchain.org/bnb-smart-chain/developers/faucet/
@@ -231,7 +208,7 @@ For each todo item:
 
 **Stop and ask the user** at:
 
-- Step 3 (password): the USER sets it **themselves, in their own terminal** - never through the chat or on a command line (see Step 3's security note). They edit `.studio/.env.local` and set `TWAK_WALLET_PASSWORD` (twak) or `WALLET_PASSWORD` (evm-local). `bag` auto-loads that file, so once it's set `bag wallet new` / `bag llm activate` pick it up - no `source`/`cd` needed. Wait for the user to confirm before continuing.
+- Step 3 (wallet secrets): do not stop for a brand-new evm-local wallet; `bag wallet new --generate-password` uses the OS CSPRNG and writes the private local env file itself. Stop only when the selected flow requires an existing secret: an imported v3 keystore needs its original `WALLET_PASSWORD`, an existing TWAK wallet needs its original `TWAK_WALLET_PASSWORD`, and TWAK credential initialization needs the NaaS values. The USER enters those **themselves, in their own terminal**; never request or route them through chat, argv, or logs. Wait only for completion, not for the value.
 - Step 5 (funding): OPTIONAL - only stop here if the user explicitly wants a paid LLM model, on-chain settle, or to pay ERC-8183 buys now. Otherwise skip; the `auto/free` default needs no funds.
 - Step 6 (Pieverse activation): zero-deposit, so it just works - no funding precheck needed. If `bag llm activate` fails on connectivity, retry once.
 - Step 6b (deliverable storage): skip for `local` and for every managed-platform deploy. Self-hosted IPFS needs its write endpoint, S3 needs namespaced keys unless ambient identity is deliberately configured, and Azure Blob needs a write SAS/service principal unless ambient identity is deliberately configured. Do not ask for secret values in chat; have the user set them with `bag env set`. Self-hosted deploy readiness blocks incomplete storage configuration.
@@ -278,7 +255,7 @@ Edit (from workspace root):
 
 - **U is 18 decimals** (not 6 like USDC). The `@bnbagent/studio-runtime/networks` `toRaw`/`fromRaw` helpers handle this.
 - **`buy_workflow`'s `deadline_minutes`** is the seller's _submission_ window. The on-chain job lifetime is automatically `deadline_minutes + 24h dispute_window`.
-- **`bag init` runs wallet onboarding only on a human TTY** (evm-local: prompts for the password and runs `bag wallet new`; twak: adopts the existing twak wallet - never creates one, since `twak wallet create` puts the password on argv). When **Claude Code** runs `bag init` (non-interactively, via the shell tool) that auto-flow does NOT fire, so this skill drives Step 3/4 explicitly - use `--no-onboard` to make the behavior deterministic. This skill bridges the gap by collecting the wallet kind upfront and calling the right form.
+- **`bag init` runs wallet onboarding only on a human TTY** (evm-local: generates and privately persists the password, then creates the keystore; twak: delegates credential init/verification, password generation, create/adopt, and address anchoring to `bag wallet twak-init`). When an agent runs `bag init` non-interactively, use `--no-onboard` for deterministic scaffolding, then follow Step 4 without collecting secrets in chat.
 - **The agent is the sole key-holder; the key material never enters the deploy package.** For **evm-local** the encrypted keystore lives at the **workspace root** `.studio/wallets/` (outside the `app/agent/` codeLocation, so no packaging path can bundle it); for **twak** the mnemonic lives at `~/.twak` (or `.studio/twak/`), never in the repo. Either way it is injected at deploy via AWS Secrets Manager (default `--secrets-mode secretsmanager`) - `WALLET_KEYSTORE_JSON` / `WALLET_PASSWORD` for evm-local, `TWAK_WALLET_JSON` / `TWAK_CREDENTIALS_JSON` / `TWAK_WALLET_PASSWORD` for twak - reconstructed at cold start, never in the package; the testnet-only `--secrets-mode envvars` fallback is refused on mainnet.
 - **AgentCore seller endpoints are never anonymous.** `bag deploy --provider aws` provisions the Cognito OAuth2 pool + buyer M2M client itself and prints the token URL / client id / scope to hand to buyers (`bag deploy provision-cognito` is deprecated - a deploy uses its own pool regardless). Locally, `bag dev` runs without Cognito env, so the card omits the scheme and is reachable without a token.
 - **ERC-8183 does NOT require ERC-8004** at the protocol level (commerce contract doesn't check the identity registry). Local two-agent dev can run end-to-end without ever touching 8004. Use 8004 only when you actually want discoverable identity.

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

@@ -85,11 +85,11 @@ B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the agen
    curl ipinfo.io/ip
    ```
 
-3. **Self-hosted AgentCore egress (self-deploys)**: operate a restricted B402 Relay on a host with a fixed public egress IP, such as a user-managed VPS, and submit that IP. Set the runtime `B402_BASE_URL` to the Relay base URL. The Relay exposes only `supported`, `verify`, and `settle`, fixes the upstream facilitator, and forwards the signed body and Tesla header allowlist without holding the merchant private key or automatically retrying a settlement transport failure. See the [self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md) for a TypeScript example.
+3. **Self-hosted AgentCore egress (self-deploys)**: operate a restricted B402 Relay on a host with a fixed public egress IP, such as a user-managed VPS, and submit that IP. Set the runtime `B402_BASE_URL` to the Relay base URL. The Relay exposes only `supported`, `verify`, and `settle`, fixes the upstream facilitator, and forwards the signed body and Tesla header allowlist without holding the merchant private key or automatically retrying a settlement transport failure. Review the public [BNB Agent Studio deployment guide](https://docs.bnbchain.org/developer-kit/bnbchain-studio/deployment/) for provider constraints; the Studio source checkout keeps the TypeScript gateway example at `docs/guides/self-hosted-x402-gateway.md`.
 
    As an alternative, use AWS-supported AgentCore VPC mode with a private subnet, NAT Gateway, and Elastic IP. Submit the Elastic IP and keep `B402_BASE_URL` pointed at the facilitator. Studio does not deploy or manage that AWS network.
 
-4. **Self-hosted Azure Foundry egress (self-deploys)**: Foundry hosted-agent containers have floating egress just like AgentCore, so the agent must NOT call the facilitator directly. Run the envelope gateway on a Container Apps workload-profiles environment whose subnet has a NAT Gateway with a Standard static public IP, co-host a restricted B402 forwarder there (the AWS guide's Relay example works verbatim — the NAT Gateway replaces its fixed-IP host requirement), point the runtime `B402_BASE_URL` at that forwarder, and submit the NAT Gateway IP. The environment type and VNet cannot be changed after creation; the full recipe (subnet sizing, ingress caveats, minReplicas) is in the [Azure self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway-azure.md). Studio does not deploy or manage that Azure network.
+4. **Self-hosted Azure Foundry egress (self-deploys)**: Foundry hosted-agent containers have floating egress just like AgentCore, so the agent must NOT call the facilitator directly. Run the envelope gateway on a Container Apps workload-profiles environment whose subnet has a NAT Gateway with a Standard static public IP, co-host a restricted B402 forwarder there (the AWS guide's Relay example works verbatim — the NAT Gateway replaces its fixed-IP host requirement), point the runtime `B402_BASE_URL` at that forwarder, and submit the NAT Gateway IP. The environment type and VNet cannot be changed after creation. Review the public [BNB Agent Studio deployment guide](https://docs.bnbchain.org/developer-kit/bnbchain-studio/deployment/) for provider constraints; the Studio source checkout keeps the subnet, ingress, and `minReplicas` recipe at `docs/guides/self-hosted-x402-gateway-azure.md`. Studio does not deploy or manage that Azure network.
 
 Do not add the public inbound gateway IP, a transient build-runner IP, or guessed addresses. If the whitelist endpoint is unreachable, stop onboarding and confirm the platform environment with the operator.
 
@@ -154,7 +154,7 @@ bag deploy --provider bnb   # managed platform
 bag deploy --provider aws   # self-hosted AgentCore
 ```
 
-On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or `ACTIVE in FREE mode`) and print the anonymous `/x402` URL. On a self-hosted AgentCore deploy it says `x402 rail is ACTIVE (self-hosted AgentCore)` or `ACTIVE in FREE mode (self-hosted AgentCore)` (self-hosted Azure Foundry prints the same summary with its own label): the rail runs in-process, but there is no anonymous URL. Operate your own HTTP front that relays envelope-v1 JSON through an authenticated AgentCore invocation. The default Bag self-deploy uses Cognito OAuth over raw HTTPS; AWS SDK/SigV4 is only for a runtime deliberately configured with IAM authorization. PAID also needs your own fixed-egress B402 Relay or equivalent network path. The complete gateway wrapper, response parser, Relay example, and direct-invocation fallback are in the [self-hosted x402 gateway guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/self-hosted-x402-gateway.md). A dormant or forced-dormant summary means the rail was not activated; fix the named credential, runtime, network, or tunnel condition and redeploy.
+On the managed platform the deploy summary must say `x402 rail is ACTIVE` (or `ACTIVE in FREE mode`) and print the anonymous `/x402` URL. On a self-hosted AgentCore deploy it says `x402 rail is ACTIVE (self-hosted AgentCore)` or `ACTIVE in FREE mode (self-hosted AgentCore)` (self-hosted Azure Foundry prints the same summary with its own label): the rail runs in-process, but there is no anonymous URL. Operate your own HTTP front that relays envelope-v1 JSON through an authenticated AgentCore invocation. The default Bag self-deploy uses Cognito OAuth over raw HTTPS; AWS SDK/SigV4 is only for a runtime deliberately configured with IAM authorization. PAID also needs your own fixed-egress B402 Relay or equivalent network path. Review the public [BNB Agent Studio deployment guide](https://docs.bnbchain.org/developer-kit/bnbchain-studio/deployment/) for provider constraints; the Studio source checkout keeps the complete gateway wrapper, response parser, Relay example, and direct-invocation fallback at `docs/guides/self-hosted-x402-gateway.md`. A dormant or forced-dormant summary means the rail was not activated; fix the named credential, runtime, network, or tunnel condition and redeploy.
 
 ## Hard rules
 

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

@@ -11,7 +11,7 @@ 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.
-- The generated project pins `@bnbagent/sdk@0.5.5` and `@altananetwork/sdk@0.7.1`; doctor, readiness, and runtime loading reject version drift. SDK 0.5.4 introduced selector-bound calls, removed session-key token approvals, and requires an admin-provisioned bounded Commerce allowance. Projects upgrading from an older SDK must update it, re-grant with `bag wallet session grant --force`, and redeploy.
+- The generated project pins `@bnbagent/sdk@0.5.6` and `@altananetwork/sdk@0.7.1`; doctor, readiness, and runtime loading reject version drift. SDK 0.5.4 introduced selector-bound calls, removed session-key token approvals, and requires an admin-provisioned bounded Commerce allowance. Projects upgrading from SDK versions older than 0.5.4 must update it, re-grant with `bag wallet session grant --force`, and redeploy.
 - 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.
 
@@ -26,13 +26,18 @@ bag init <name> --wallet-kind altana --destination self --no-onboard
 # Edit <name>/.studio/.env.local and set WALLET_PASSWORD first.
 cd <name>/app/agent
 bag wallet new
-# fund the printed admin address with ~0.05 tBNB + U
+# after GitHub login, request the configured tBNB + U grant for the admin
+bag wallet fund
 bag wallet session grant
 bag wallet session status
 bag doctor
 bag dev
 ```
 
+`bag wallet fund` always uses the Altana admin's encrypted keystore for an
+EIP-191 ownership signature and sends funds to that same admin address. The
+bounded runtime session is not involved in faucet claims.
+
 Interactive grant recommendations are 10 U/day, 30 days, register=yes. In a non-TTY, pass `--budget-u`, `--expiry-days`, optional `--no-register`, and `--yes`. Stdout from a successful grant is only the session public key.
 
 The grant persists the owner-only session, provisions a Commerce allowance no higher than its U-token cap, and approves the quote checker. Every relay-backed management write must return `CONFIRMED`; `PENDING` fails closed and preserves the session file. If either setup step fails after the paid grant, repair both with: