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

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

@@ -3,30 +3,20 @@ name: bnbagent-studio-selling-via-b402
 description: When the user wants a bnbagent-studio agent to sell paid or FREE HTTP requests through the B402-backed x402 rail. Owns the explicit pricing choice and, for PAID mode, per-agent merchant onboarding, RSA key preparation, egress-IP allowlisting, sandbox/production separation, B402 environment setup, seller status checks, and activation by redeploy (managed platform or self-hosted AgentCore).
 ---
 
-> **Reference file** of the `bnbagent-studio` router skill, installed at
-> `bnbagent-studio/references/` and loaded on demand (not a standalone skill).
-> Route here via the router's decision tree.
+> **Reference file** of the `bnbagent-studio` router skill, installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
 
 # Sell via B402
 
-Use this playbook to activate the x402 seller rail for one agent. First choose
-PAID or FREE explicitly. B402 merchant credentials are per agent and per
-environment and are needed only for PAID. Never reuse a merchant record across
-agent wallets, or mix sandbox and production values.
+Use this playbook to activate the x402 seller rail for one agent. First choose PAID or FREE explicitly. B402 merchant credentials are per agent and per environment and are needed only for PAID. Never reuse a merchant record across agent wallets, or mix sandbox and production values.
 
 ## Preconditions
 
 - The agent wallet already exists. In PAID mode its address receives U.
-- The project targets the managed platform or self-hosted AgentCore
-  (azure-foundry cannot activate the rail).
-- PAID managed platform only: an interactive GitHub-login session from
-  `bag platform login` is available for reading the platform Relay egress
-  IPs. A `bnbk_…` CI token does not satisfy this endpoint's GitHub-user check.
-- `[payments.x402_seller]` exists. If not, run
-  `bag x402 sell init`.
+- The project targets the managed platform or self-hosted AgentCore (azure-foundry cannot activate the rail).
+- PAID managed platform only: an interactive GitHub-login session from `bag platform login` is available for reading the platform Relay egress IPs. A `bnbk_…` CI token does not satisfy this endpoint's GitHub-user check.
+- `[payments.x402_seller]` exists. If not, run `bag x402 sell init`.
 
-The PAID application uses the **agent wallet address**, not a developer
-treasury, buyer wallet, or platform wallet.
+The PAID application uses the **agent wallet address**, not a developer treasury, buyer wallet, or platform wallet.
 
 ## Choose PAID or FREE
 
@@ -38,28 +28,15 @@ bag x402 sell init --price-usd 0
 bag config set payments.x402_seller.price_usd 0
 ```
 
-`"0"` means anonymous FREE passthrough. The runtime returns work directly and
-does not issue a 402 challenge, call B402 `/supported`/verify/settle, transfer
-U, or write an `x402_sell` settlement audit. B402 credentials are ignored and
-not synchronized. Run `bag x402 sell status`, `bag doctor`, and
-`bag deploy prepare`; all must label the route FREE.
+`"0"` means anonymous FREE passthrough. The runtime returns work directly and does not issue a 402 challenge, call B402 `/supported`/verify/settle, transfer U, or write an `x402_sell` settlement audit. B402 credentials are ignored and not synchronized. Run `bag x402 sell status`, `bag doctor`, and `bag deploy prepare`; all must label the route FREE.
 
-This is unrestricted public access. Confirm that intent before continuing.
-Managed platform still publishes the route through its gateway; self-hosted
-AgentCore still needs an envelope-v1 front; Azure Foundry remains unsupported.
-If FREE is the selected product, skip the merchant/RSA/IP sections below.
+This is unrestricted public access. Confirm that intent before continuing. Managed platform still publishes the route through its gateway; self-hosted AgentCore still needs an envelope-v1 front; Azure Foundry remains unsupported. If FREE is the selected product, skip the merchant/RSA/IP sections below.
 
 ## Generate the agent's RSA material
 
-This playbook is the canonical key-generation procedure; neither the CLI nor
-the B402 SDK generates keys. The pair authenticates every facilitator API
-call under the
-[B402 request-signing scheme](https://developers.binance.com/en/docs/products/onchainpay-x402/basics/3.request-signing);
-the runtime signs each request automatically once the credentials are stored.
+This playbook is the canonical key-generation procedure; neither the CLI nor the B402 SDK generates keys. The pair authenticates every facilitator API call under the [B402 request-signing scheme](https://developers.binance.com/en/docs/products/onchainpay-x402/basics/3.request-signing); the runtime signs each request automatically once the credentials are stored.
 
-Work from the workspace root. Keep private material under `.studio/`, which is
-excluded from source and deploy artifacts. Generate a separate key pair for
-each environment:
+Work from the workspace root. Keep private material under `.studio/`, which is excluded from source and deploy artifacts. Generate a separate key pair for each environment:
 
 ```bash
 umask 077
@@ -79,25 +56,15 @@ chmod 600 ".studio/b402/$b402_env/private.pem" \
   ".studio/b402/$b402_env/private.der.b64"
 ```
 
-Do not print the private key or its base64 form. Submit only the public key
-material to B402.
+Do not print the private key or its base64 form. Submit only the public key material to B402.
 
-The current B402 request-signing contract explicitly requires a 1024-bit RSA
-key and RSA-SHA256. Follow that protocol requirement even if a larger RSA key
-would normally be preferred elsewhere. Repeat with `b402_env=production`
-instead of reusing the sandbox pair.
+The current B402 request-signing contract explicitly requires a 1024-bit RSA key and RSA-SHA256. Follow that protocol requirement even if a larger RSA key would normally be preferred elsewhere. Repeat with `b402_env=production` instead of reusing the sandbox pair.
 
 ## Collect the IP allowlist
 
-B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the
-agent's facilitator calls come FROM. Submit every part that applies to your
-deployment target:
+B402 allowlists the merchant's **outbound** (egress) IPs, the addresses the agent's facilitator calls come FROM. Submit every part that applies to your deployment target:
 
-1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses
-   that the platform B402 Relay uses to reach the facilitator. The managed
-   deployment worker points only the AgentCore runtime copy of
-   `B402_BASE_URL` at this Relay. Refresh and read the interactive session
-   without printing its bearer:
+1. **Platform Relay egress IPs (managed-platform deploys)**: the addresses that the platform B402 Relay uses to reach the facilitator. The managed deployment worker points only the AgentCore runtime copy of `B402_BASE_URL` at this Relay. Refresh and read the interactive session without printing its bearer:
 
    ```bash
    bag platform whoami >/dev/null
@@ -110,48 +77,26 @@ deployment target:
    # → {"whitelist_ips": ["13.115.15.190", …], "cache_ttl_seconds": 300}
    ```
 
-   Submit every address in `whitelist_ips`. The list is served with a short
-   cache TTL and can rotate, so re-read it right before submitting the form.
-   The login session is stored mode `0600`. Do not echo, log, or paste its
-   access or refresh token. `bnbk_` tokens from `bag platform token` are
-   deliberately rejected by this GitHub-login-only endpoint.
+   Submit every address in `whitelist_ips`. The list is served with a short cache TTL and can rotate, so re-read it right before submitting the form. The login session is stored mode `0600`. Do not echo, log, or paste its access or refresh token. `bnbk_` tokens from `bag platform token` are deliberately rejected by this GitHub-login-only endpoint.
 
-2. **Your local public IP**: required so a local `bag dev` run can reach
-   B402:
+2. **Your local public IP**: required so a local `bag dev` run can reach B402:
 
    ```bash
    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.
-
-   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.
-
-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.
+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.
+
+   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.
+
+Do not add the public inbound gateway IP, a transient build-runner IP, or guessed addresses. If the whitelist endpoint is unreachable, stop onboarding and confirm the platform environment with the operator.
 
 ## Submit the B402 merchant application
 
-Apply through the
-[B402 developer account application](https://developers.binance.com/en/docs/products/onchainpay-x402/basics/6.apply-developer-account).
-Complete one application for sandbox and a separate application for
-production. Fill the form as follows:
+Apply through the [B402 developer account application](https://developers.binance.com/en/docs/products/onchainpay-x402/basics/6.apply-developer-account). Complete one application for sandbox and a separate application for production. Fill the form as follows:
 
 | Field | Value |
-|---|---|
+| --- | --- |
 | Business Name | Your agent or business display name |
 | Email | Primary contact email address |
 | Wallet address | The agent wallet for that environment |
@@ -161,15 +106,14 @@ production. Fill the form as follows:
 
 Keep the two environments isolated:
 
-| Environment | Chain | Credentials | Wallet/IP registration |
-|---|---|---|---|
-| Sandbox | BSC testnet | sandbox-only | apply separately |
-| Production | BSC mainnet | production-only | apply separately |
+| Environment | Chain       | Credentials     | Wallet/IP registration |
+| ----------- | ----------- | --------------- | ---------------------- |
+| Sandbox     | BSC testnet | sandbox-only    | apply separately       |
+| Production  | BSC mainnet | production-only | apply separately       |
 
 ## Store the issued credentials
 
-Open the workspace `.studio/.env.local` in an editor and fill exactly four
-values:
+Open the workspace `.studio/.env.local` in an editor and fill exactly four values:
 
 ```dotenv
 B402_BASE_URL=
@@ -178,21 +122,11 @@ B402_ACCESS_TOKEN=
 B402_PRIVATE_KEY_B64=
 ```
 
-Copy the single-line DER value from
-`.studio/b402/<environment>/private.der.b64` into `B402_PRIVATE_KEY_B64`.
-`B402_BASE_URL`, `B402_CLIENT_ID`, and `B402_ACCESS_TOKEN` are the values
-issued together for that environment. Do not include any value in shell
-history, terminal output, source files, TOML, screenshots, or support tickets.
+Copy the single-line DER value from `.studio/b402/<environment>/private.der.b64` into `B402_PRIVATE_KEY_B64`. `B402_BASE_URL`, `B402_CLIENT_ID`, and `B402_ACCESS_TOKEN` are the values issued together for that environment. Do not include any value in shell history, terminal output, source files, TOML, screenshots, or support tickets.
 
-`B402_PRIVATE_KEY` accepts the PEM representation as an alternative. Keep
-exactly one private-key form; do not set both.
+`B402_PRIVATE_KEY` accepts the PEM representation as an alternative. Keep exactly one private-key form; do not set both.
 
-For the current managed BSC Testnet path, the platform-supported upstream is
-`https://qacb.sdtaop.com`; the worker projects only the AgentCore runtime copy
-to its Relay. For a generic self-hosted environment, use the authenticated
-base URL issued during onboarding. With your own Relay, set the runtime
-`B402_BASE_URL` to that Relay base URL and configure the Relay's fixed upstream
-to the issued URL.
+For the current managed BSC Testnet path, the platform-supported upstream is `https://qacb.sdtaop.com`; the worker projects only the AgentCore runtime copy to its Relay. For a generic self-hosted environment, use the authenticated base URL issued during onboarding. With your own Relay, set the runtime `B402_BASE_URL` to that Relay base URL and configure the Relay's fixed upstream to the issued URL.
 
 ## Verify and activate
 
@@ -202,16 +136,13 @@ For PAID mode, check names and presence without exposing values:
 bag x402 sell status --no-probe
 ```
 
-When the credentials, IP allowlist, and facilitator environment are ready, run
-the authenticated read-only capability check:
+When the credentials, IP allowlist, and facilitator environment are ready, run the authenticated read-only capability check:
 
 ```bash
 bag x402 sell status
 ```
 
-For a sandbox/trial agent, it must find exact/eip3009 U on `eip155:97`. For
-production it must find the mainnet environment expected by the project. A
-network mismatch is not safe to ignore.
+For a sandbox/trial agent, it must find exact/eip3009 U on `eip155:97`. For production it must find the mainnet environment expected by the project. A network mismatch is not safe to ignore.
 
 Run the deployment gate, then redeploy to activate the selected mode:
 
@@ -221,38 +152,15 @@ 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)`: 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)`: 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.
 
 ## Hard rules
 
 - Never log or print any B402 value or private key.
 - Never put a B402 value in `studio.toml` or a deploy descriptor.
-- Never replay a paid HTTP request whose outcome is unknown. Follow
-  `docs/guides/x402-selling.md` and reconcile `(nonce, network, payer)` first.
-- Binance `/settle` is asynchronous. A parseable `success: false` response
-  with a transaction is pending and requires an idempotent poll with the same
-  settlement payload. Studio v0.0.6 and the latest
-  `@bnb-chain/b402@0.1.0` do not yet perform that poll; they classify pending
-  as unknown. Do not claim current mainnet readiness until this is updated.
-- Settlement happens before work. A later work failure retains the payment and
-  does not trigger an automatic refund.
-- The rail activates on AgentCore targets only (managed platform or
-  self-hosted); azure-foundry stays forced dormant.
-- PAID B402 payout wallets must use `wallet.kind` `evm-local` (private-key
-  wallet stored as an encrypted keystore) or `twak`. Altana is unsupported.
-  FREE x402 bypasses B402, has no payout, and must not be described as Altana
-  B402 support.
+- Never replay a paid HTTP request whose outcome is unknown. Follow `docs/guides/x402-selling.md` and reconcile `(nonce, network, payer)` first.
+- Binance `/settle` is asynchronous. A parseable `success: false` response with a transaction is pending and requires an idempotent poll with the same settlement payload. Studio v0.0.6 and the latest `@bnb-chain/b402@0.1.0` do not yet perform that poll; they classify pending as unknown. Do not claim current mainnet readiness until this is updated.
+- Settlement happens before work. A later work failure retains the payment and does not trigger an automatic refund.
+- The rail activates on AgentCore targets only (managed platform or self-hosted); azure-foundry stays forced dormant.
+- PAID B402 payout wallets must use `wallet.kind` `evm-local` (private-key wallet stored as an encrypted keystore) or `twak`. Altana is unsupported. FREE x402 bypasses B402, has no payout, and must not be described as Altana B402 support.
 - Never describe FREE as a zero-value B402 settlement. It bypasses B402.

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

@@ -1,28 +1,15 @@
 ---
 name: bnbagent-studio-use-aws-agentcore
-description: When the user wants to deploy or operate a bnbagent-studio project on AWS Bedrock AgentCore — deploy with `bag deploy --provider aws` (ALL cloud execution is delegated to pinned `@bnbagent/deploy-cli@0.4.14`), inspect with `bag deploy status` / `logs --provider aws` / `verify --provider aws`, and tear down with `bag deploy destroy --provider aws --execute [--purge]`. Also covers AWS credential prerequisites and the runtime-secret channel.
+description: When the user wants to deploy or operate a bnbagent-studio project on AWS Bedrock AgentCore - deploy with `bag deploy --provider aws` (all cloud lifecycle mutations are delegated to pinned `@bnbagent/deploy-cli@0.4.14`), inspect with `bag deploy status` / `logs --provider aws` / `verify --provider aws`, and tear down with `bag deploy destroy --provider aws --execute [--purge]`. Also covers AWS credential prerequisites, the optional read-only quota probe, and the runtime-secret channel.
 ---
 
-> **Reference file** of the `bnbagent-studio` router skill — installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
+> **Reference file** of the `bnbagent-studio` router skill - installed at `bnbagent-studio/references/` and loaded on demand (not a standalone skill). Route here via the router's decision tree.
 
 # bnbagent-studio-use-aws-agentcore
 
-Procedure for deploying and operating the seller Agent on **AWS Bedrock
-AgentCore** via the **delegated deploy**: `bag deploy --provider aws` hands a generated
-deploy spec to the pinned **`@bnbagent/deploy-cli`** (run via `bunx --bun`;
-override the command with `BNBAGENT_DEPLOY_COMMAND`), which executes every
-cloud step through the AWS SDK under the user's credentials. There is **no
-`aws` CLI, no CDK deploy, and no `agentcore deploy`** in this path — the npm
-`@aws/agentcore` CLI is used ONLY by `bag dev --container` (image-parity local
-runs).
-
-The deployed product is **one** valuable Agent that serves its selected public
-faces (A2A → `0.0.0.0:9000`, MCP-only → `0.0.0.0:8000/mcp`, or A2A+MCP →
-A2A-native `dualMain.ts` on `:9000` with `/mcp` tunneled by the platform, per
-`app/agent/studio.toml [stack].protocols`): it holds the key, signs in-process,
-and is its own public endpoint behind an OAuth2 authorizer. There is no
-separate service to deploy — the agent IS the public surface, so this one
-procedure is the whole runtime deploy.
+Procedure for deploying and operating the seller Agent on **AWS Bedrock AgentCore** via the **delegated deploy**: `bag deploy --provider aws` hands a generated deploy spec to the pinned **`@bnbagent/deploy-cli`** (run via `bunx --bun`; override the command with `BNBAGENT_DEPLOY_COMMAND`), which executes every cloud lifecycle mutation through the AWS SDK under the user's credentials. There is **no `aws` CLI, no CDK deploy, and no `agentcore deploy`** in the mutation path - the npm `@aws/agentcore` CLI is used ONLY by `bag dev --container` (image-parity local runs). If the AWS CLI is installed, `bag deploy prepare` may use it only for a fail-open, read-only AgentCore quota-headroom probe.
+
+The deployed product is **one** valuable Agent that serves its selected public faces (A2A → `0.0.0.0:9000`, MCP-only → `0.0.0.0:8000/mcp`, or A2A+MCP → A2A-native `dualMain.ts` on `:9000` with `/mcp` tunneled by the platform, per `app/agent/studio.toml [stack].protocols`): it holds the key, signs in-process, and is its own public endpoint behind an OAuth2 authorizer. There is no separate service to deploy - the agent IS the public surface, so this one procedure is the whole runtime deploy.
 
 ```
 <workspace>/
@@ -32,157 +19,74 @@ procedure is the whole runtime deploy.
 └── app/agent/             # the deployed code (entrypoint lives here)
 ```
 
-> **`bag deploy --provider aws` runs the whole deploy.** It gates on readiness, builds
-> the agent (`pnpm build`), collects the runtime secrets, and delegates to
-> bnbagent-deploy. The old `bag deploy agent` spelling is a deprecated
-> compatibility alias.
+> **`bag deploy --provider aws` runs the whole deploy.** It gates on readiness, builds the agent (`pnpm build`), collects the runtime secrets, and delegates to bnbagent-deploy. The old `bag deploy agent` spelling is a deprecated compatibility alias.
 
 ## Prerequisites
 
-1. **Bun 1.3+ (`bunx`) on PATH** — the pinned `@bnbagent/deploy-cli` runs
-   through it (`bag deploy prepare` fails a CRITICAL check when `bunx` is
-   missing). Install from https://bun.sh, or point `BNBAGENT_DEPLOY_COMMAND`
-   at another launcher.
-2. **AWS credentials** for the deploy identity — use `bnbagent-deploy login
-   --provider aws` or the standard env/profile files. Studio does not inspect
-   credentials itself; the delegated deploy-cli validates identity and
-   permissions before mutation. Credentials may come from
-   `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` or the
-   standard `~/.aws/credentials` file. Verify you're in the RIGHT account: it must
-   match `agentcore/aws-targets.json` (the AWS Console's account menu shows
-   the active account id). Least-privilege policy JSON:
-   `docs/guides/agentcore-deploy-iam.md`.
-3. **Docker running — container packaging only** (`wallet.kind = "twak"` or a
-   scaffold with `[deploy].platform_artifact = "container"`): bnbagent-deploy
-   builds the scaffolded Dockerfile locally for linux/arm64 and pushes it to
-   ECR. A default evm-local AWS scaffold deploys as a Node zip and needs no
-   Docker; an evm-local platform-container scaffold remains a container when
-   AWS is selected later.
-4. **`@aws/agentcore` CLI — ONLY for `bag dev --container`** (needs Node ≥ 20:
-   `npm install -g @aws/agentcore`). Not needed to deploy.
-   ⚠️ Some environments carry `bedrock-agentcore-starter-toolkit`, a
-   **same-named but incompatible** `agentcore` shim that can shadow the npm
-   CLI on PATH. Check with `which -a agentcore` and remove the shim (or put
-   the npm `@aws/agentcore` first on PATH) if `bag dev --container`
-   misbehaves.
+1. **Bun 1.3+ (`bunx`) on PATH** - the pinned `@bnbagent/deploy-cli` runs through it (`bag deploy prepare` fails a CRITICAL check when `bunx` is missing). Install from https://bun.sh, or point `BNBAGENT_DEPLOY_COMMAND` at another launcher.
+2. **AWS credentials** for the deploy identity - use `bnbagent-deploy login --provider aws` or the standard env/profile files. Studio does not inspect credentials itself; the delegated deploy-cli validates identity and permissions before mutation. Credentials may come from `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` or the standard `~/.aws/credentials` file. Verify you're in the RIGHT account: it must match `agentcore/aws-targets.json` (the AWS Console's account menu shows the active account id). Least-privilege policy JSON: `docs/guides/agentcore-deploy-iam.md`.
+3. **Docker running - container packaging only** (`wallet.kind = "twak"` or a scaffold with `[deploy].platform_artifact = "container"`): bnbagent-deploy builds the scaffolded Dockerfile locally for linux/arm64 and pushes it to ECR. A default evm-local AWS scaffold deploys as a Node zip and needs no Docker; an evm-local platform-container scaffold remains a container when AWS is selected later.
+4. **`@aws/agentcore` CLI - ONLY for `bag dev --container`** (use the repository baseline, Node >=22: `npm install -g @aws/agentcore`). Not needed to deploy. ⚠️ Some environments carry `bedrock-agentcore-starter-toolkit`, a **same-named but incompatible** `agentcore` shim that can shadow the npm CLI on PATH. Check with `which -a agentcore` and remove the shim (or put the npm `@aws/agentcore` first on PATH) if `bag dev --container` misbehaves.
+5. **AWS CLI - optional for readiness only.** When available, `bag deploy prepare` reads quota `L-F4575653` and lists existing AgentCore runtimes so it can stop before a full-quota deploy creates orphaned intermediate resources. The probe stays silent if the CLI, credentials, `servicequotas:GetServiceQuota`, `bedrock-agentcore:ListAgentRuntimes`, or usable JSON output is unavailable. The delegated deployment itself does not require the AWS CLI.
 
 ## The runtime-secret channel (read this first)
 
-The deployed runtime does NOT read `.env.local` — nothing ships it. Instead,
-`bag deploy --provider aws` collects the runtime secrets (provider/storage keys,
-`WALLET_PASSWORD`, the encrypted keystore as `WALLET_KEYSTORE_JSON` — or the
-twak bundle) and hands them to bnbagent-deploy as a private (mode 0600)
-tempdir envFile. The deploy CLI provisions them as ONE Secrets Manager secret
-(`bnbagent/<project>/runtime`), injects the `BNBAGENT_RUNTIME_SECRET_ID`
-pointer into the runtime env, and grants the runtime execution role read
-access. The entrypoint loads the bundle at cold start.
-
-> **The KEYSTORE is never bundled.** The encrypted wallet keystore lives at
-> the WORKSPACE root (`.studio/wallets/`, outside `app/agent/`, so no
-> packaging path can include it) and reaches the runtime ONLY via that
-> Secrets Manager channel. Only put non-secret runtime config in
-> `agentcore.json` `envVars[]`.
-
-> **`--secrets-mode envvars` is testnet-only.** It inlines the secrets as
-> PLAINTEXT runtime env vars in the deploy spec — use it only when you cannot
-> grant `secretsmanager:CreateSecret`; it is refused on mainnet.
-
-Provider-native overrides: the optional `studio.toml [deploy.agentcore]` table
-passes verbatim deploy-spec keys through to CreateAgentRuntime /
-UpdateAgentRuntime. Two keys are reserved and refused: `secretName`
-(studio-managed) and `environmentVariables` (would replace the merged runtime
-env, secret pointer included).
+The deployed runtime does NOT read `.env.local` - nothing ships it. Instead, `bag deploy --provider aws` collects the runtime secrets (provider/storage keys, `WALLET_PASSWORD`, the encrypted keystore as `WALLET_KEYSTORE_JSON` - or the twak bundle) and hands them to bnbagent-deploy as a private (mode 0600) tempdir envFile. The deploy CLI provisions them as ONE Secrets Manager secret (`bnbagent/<project>/runtime`), injects the `BNBAGENT_RUNTIME_SECRET_ID` pointer into the runtime env, and grants the runtime execution role read access. The entrypoint loads the bundle at cold start.
+
+> **The KEYSTORE is never bundled.** The encrypted wallet keystore lives at the WORKSPACE root (`.studio/wallets/`, outside `app/agent/`, so no packaging path can include it) and reaches the runtime ONLY via that Secrets Manager channel. Only put non-secret runtime config in `agentcore.json` `envVars[]`.
+
+> **`--secrets-mode envvars` is testnet-only.** It inlines the secrets as PLAINTEXT runtime env vars in the deploy spec - use it only when you cannot grant `secretsmanager:CreateSecret`; it is refused on mainnet.
+
+Provider-native overrides: the optional `studio.toml [deploy.agentcore]` table passes verbatim deploy-spec keys through to CreateAgentRuntime / UpdateAgentRuntime. Two keys are reserved and refused: `secretName` (studio-managed) and `environmentVariables` (would replace the merged runtime env, secret pointer included).
 
 ## Command reference
 
-Everything runs through `bag deploy` (run `bag deploy <cmd> --help` for
-flags); cloud execution is the pinned bnbagent-deploy's job.
+Everything runs through `bag deploy` (run `bag deploy <cmd> --help` for flags); cloud execution is the pinned bnbagent-deploy's job.
 
 | Command | What it does |
-|---|---|
-| `bag deploy prepare` | The deploy-readiness sweep (incl. the `bunx` check). Run before deploying. |
+| --- | --- |
+| `bag deploy prepare` | The deploy-readiness sweep, including `bunx` and the optional fail-open AgentCore quota probe. Run before deploying. |
 | `bag deploy --provider aws [--yes]` | The whole deploy: prepare gate → AWS-permissions notice → secret hand-off → `pnpm build` → delegated deploy (artifact, runtime create/update, secret provision + role grant, Cognito inbound OAuth) → ARN capture + state stamp. Automation requires `--yes`; add `--allow-multiple` when another provider stays active. |
 | `bag deploy verify [--provider aws]` | Ask bnbagent-deploy for live provider status, then reconcile ERC-8004. Provider is required only when multiple deployments are recorded. |
 | `bag deploy status [--provider aws]` | List every recorded deployment and delegated live state (read-only); `--no-probe` is local-only. |
 | `bag deploy logs [--provider aws] [--follow] [--since 10m]` | Delegate runtime logs to bnbagent-deploy. |
 | `bag deploy destroy [--provider aws]` | Dry-run teardown plan; `--execute` delegates `destroy --yes`; `--purge` also deletes retained ECR/log resources. |
-| `bag deploy provision-cognito [--wire]` | Emit (then wire) the optional Cognito CDK app for operator-managed buyer credentials. |
+| `bag deploy provision-cognito [--wire]` | **Deprecated** (hidden from `--help`). Emits a Cognito CDK app whose pool a deploy never uses. |
 
 ## Typical workflows
 
 ### A. Run locally
 
-Prefer `bag dev` (auto-loads `.env.local`, runs the agent in-process, no
-Docker). `bag dev --container` opts into the native `agentcore dev` container
-for full image parity — the ONE flow that needs the npm `@aws/agentcore` CLI
-plus a container engine.
+Prefer `bag dev` (auto-loads `.env.local`, runs the agent in-process, no Docker). `bag dev --container` opts into the native `agentcore dev` container for full image parity - the ONE flow that needs the npm `@aws/agentcore` CLI plus a container engine.
 
 ### B. Deploy to AWS (delegated)
 
-> ⚠️ **First deploy: relay the AWS-permissions notice to the user.** Deploying
-> provisions resources in the user's AWS account. `bag deploy --provider aws` prints a
-> pre-deploy notice (required-permission guides, AWS best-practice links, and a
-> disclaimer) and gates the project's FIRST deploy on an explicit acceptance —
-> in a non-interactive run it exits with an error instead of prompting. When
-> that happens: show the printed notice to the user **verbatim**, get their
-> explicit consent, then re-run with `--accept-risk`. NEVER add `--accept-risk`
-> without asking the user first.
-
-> 🔒 **Inbound auth is auto-provisioned.** An AgentCore seller endpoint is
-> **never anonymous**. When `agentcore.json` carries no authorizer of its own,
-> the delegated deploy auto-provisions a Cognito inbound OAuth (account pool +
-> per-agent M2M client) so the runtime is token-gated. To mint buyer
-> credentials the operator manages directly, use the optional CDK path:
+> ⚠️ **First deploy: relay the AWS-permissions notice to the user.** Deploying provisions resources in the user's AWS account. `bag deploy --provider aws` prints a pre-deploy notice (required-permission guides, AWS best-practice links, and a disclaimer) and gates the project's FIRST deploy on an explicit acceptance - in a non-interactive run it exits with an error instead of prompting. When that happens: show the printed notice to the user **verbatim**, get their explicit consent, then re-run with `--accept-risk`. NEVER add `--accept-risk` without asking the user first.
+
+> 🔒 **Inbound auth is auto-provisioned.** An AgentCore seller endpoint is **never anonymous**. The delegated deploy provisions a Cognito inbound OAuth (account pool + per-agent M2M client) so the runtime is token-gated, then writes the live token URL, scope, client id, and discovery URL back into `studio.toml`, `agentcore.json`, and the printed buyer block. Hand those to each buyer; the client secret is retrieved read-only in the AWS Console (Cognito → User pools → App clients → "Show client secret") - never persisted by studio.
 >
-> 1. `bag deploy provision-cognito` emits a self-contained Cognito CDK app
->    (UserPool + M2M app client) — the user runs `cdk deploy --outputs-file
->    cdk-outputs.json` themselves.
-> 2. `bag deploy provision-cognito --wire` reads that local outputs file and
->    patches `agentcore.json`'s `authorizerConfiguration.customJwtAuthorizer` +
->    the card's `OAUTH_TOKEN_URL` / `OAUTH_SCOPE` (no AWS call). The client
->    secret is retrieved read-only in the AWS Console (Cognito → User pools →
->    App clients → "Show client secret") — never persisted by studio.
+> `bag deploy provision-cognito` (the CDK path) is **deprecated**: a deploy provisions and uses its own pool regardless, so the CDK stack is a billable orphan and anything wired from it gets overwritten.
 >
-> Buyers then reach the agent over plain HTTPS + an OAuth2 Bearer (the
-> client-credentials grant) — **no AWS SigV4 / IAM credentials**. Locally,
-> `bag dev` runs without Cognito env, so the card omits the scheme.
+> Buyers reach the agent over plain HTTPS + an OAuth2 Bearer (the client-credentials grant) - **no AWS SigV4 / IAM credentials**. Locally, `bag dev` runs without Cognito env, so the card omits the scheme.
 
-The 2026-07-20 live baseline passed both ZIP and linux/arm64 container through
-deploy, status, OAuth-authenticated signed A2A negotiation, logs, destroy, and
-purge. A SigV4 invoke against this custom-JWT endpoint is expected to fail; use
-the buyer OAuth bearer when verifying the data plane. That baseline bypassed
-local storage readiness and therefore does not prove funded delivery or durable
-storage.
+The 2026-07-20 live baseline passed both ZIP and linux/arm64 container through deploy, status, OAuth-authenticated signed A2A negotiation, logs, destroy, and purge. A SigV4 invoke against this custom-JWT endpoint is expected to fail; use the buyer OAuth bearer when verifying the data plane. That baseline bypassed local storage readiness and therefore does not prove funded delivery or durable storage.
 
 ```bash
 # 1. Set the real AWS account + region in agentcore/aws-targets.json and
 #    export the deploy credentials (env vars or ~/.aws/credentials).
-# 2. Check readiness, then deploy — the pinned bnbagent-deploy does the cloud work:
+# 2. Check readiness, then deploy - the pinned bnbagent-deploy does the cloud work:
 bag deploy prepare
 bag deploy --provider aws
 ```
 
-> After deploy, ERC-8004 registration records the **AgentCore endpoint**:
-> A2A uses the normalized agent-card URL (`AgentEndpoint.a2a`), while MCP records
-> the `/mcp` endpoint plus access metadata. `bag deploy verify` handles this. The
-> on-chain identity points buyers straight at the agent; there is no proxy or
-> relay in front of it.
+> After deploy, ERC-8004 registration records the **AgentCore endpoint**: A2A uses the normalized agent-card URL (`AgentEndpoint.a2a`), while MCP records the `/mcp` endpoint plus access metadata. `bag deploy verify` handles this. The on-chain identity points buyers straight at the agent; there is no proxy or relay in front of it.
 
 ### B1. Troubleshooting the delegated deploy
 
-- **`could not start bnbagent-deploy (bunx not found)`** — install Bun 1.3+
-  (https://bun.sh) or set `BNBAGENT_DEPLOY_COMMAND` to a command that can run
-  the pinned `@bnbagent/deploy-cli`.
-- **Permission denials (AccessDenied)** — the deploy identity is missing one
-  of the least-privilege statements; apply the policy JSON from
-  `docs/guides/agentcore-deploy-iam.md`. The deploy CLI preflight-simulates
-  its permissions when it can and names the denied actions.
-- **Wrong account** — the credentials in the environment resolve to an account
-  that does not match `agentcore/aws-targets.json`; fix the env vars /
-  `~/.aws/credentials` profile, not the descriptor.
-- **Container build fails / hangs** (twak) — the image is built LOCALLY for
-  linux/arm64 and pushed to ECR; Docker must be running (x86 machines need
-  buildx/containerd cross-build support).
+- **`could not start bnbagent-deploy (bunx not found)`** - install Bun 1.3+ (https://bun.sh) or set `BNBAGENT_DEPLOY_COMMAND` to a command that can run the pinned `@bnbagent/deploy-cli`.
+- **Permission denials (AccessDenied)** - the deploy identity is missing one of the least-privilege statements; apply the policy JSON from `docs/guides/agentcore-deploy-iam.md`. The deploy CLI preflight-simulates its permissions when it can and names the denied actions.
+- **Wrong account** - the credentials in the environment resolve to an account that does not match `agentcore/aws-targets.json`; fix the env vars / `~/.aws/credentials` profile, not the descriptor.
+- **Container build fails / hangs** (twak) - the image is built LOCALLY for linux/arm64 and pushed to ECR; Docker must be running (x86 machines need buildx/containerd cross-build support).
 
 ### C. Inspect / operate
 
@@ -194,19 +98,14 @@ bag deploy destroy --provider aws         # dry-run teardown plan
 bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
 ```
 
+If verification reports a partial ERC-8004 registration because `setAgentURI` did not complete, the deployment check remains a warning and records pending identity state. Retry with `bag erc8004 update-endpoint --endpoint <url>`, or run `bag erc8004 clear-pending` first when the relay transaction was never observed on-chain.
+
 ## Reference
 
-- b402/x402 selling on self-hosted AgentCore: the rail activates in-process
-  with complete B402 credentials for PAID, or without them when explicit zero
-  selects FREE. There is no anonymous URL — operate your own HTTP front that
-  relays envelope-v1 through the runtime's configured authorizer. The default
-  Bag deploy uses Cognito OAuth over HTTPS, not SDK/SigV4. PAID also needs a
-  fixed-egress B402 Relay or VPC/NAT/Elastic-IP path. See
-  `bnbagent-studio-selling-via-b402` and
-  `docs/guides/self-hosted-x402-gateway.md`.
+- b402/x402 selling on self-hosted AgentCore: the rail activates in-process with complete B402 credentials for PAID, or without them when explicit zero selects FREE. There is no anonymous URL - operate your own HTTP front that relays envelope-v1 through the runtime's configured authorizer. The default Bag deploy uses Cognito OAuth over HTTPS, not SDK/SigV4. PAID also needs a fixed-egress B402 Relay or VPC/NAT/Elastic-IP path. See `bnbagent-studio-selling-via-b402` and `docs/guides/self-hosted-x402-gateway.md`.
 - `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
-- `agentcore/agentcore.json` — name (resource naming continuity), protocol, authorizer, envVars
-- `agentcore/aws-targets.json` — AWS account + region
-- `app/agent/studio.toml [deploy.agentcore]` — provider-native deploy-spec passthrough
-- `docs/guides/agentcore-deploy-iam.md` — least-privilege IAM for the delegated deploy
-- `BNBAGENT_DEPLOY_COMMAND` — override the pinned `bunx --bun @bnbagent/deploy-cli@<pin>` invocation (E2E/dev)
+- `agentcore/agentcore.json` - name (resource naming continuity), protocol, authorizer, envVars
+- `agentcore/aws-targets.json` - AWS account + region
+- `app/agent/studio.toml [deploy.agentcore]` - provider-native deploy-spec passthrough
+- `docs/guides/agentcore-deploy-iam.md` - least-privilege IAM for the delegated deploy
+- `BNBAGENT_DEPLOY_COMMAND` - override the pinned `bunx --bun @bnbagent/deploy-cli@<pin>` invocation (E2E/dev)