@bnbagent/studio-cli 0.0.6-alpha.1

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

@@ -0,0 +1,208 @@
+---
+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.
+---
+
+> **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.
+
+```
+<workspace>/
+├── agentcore/
+│   ├── agentcore.json     # deploy descriptor: name (resource naming), protocol, authorizer, envVars
+│   └── aws-targets.json   # AWS account + region the deploy targets
+└── 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.
+
+## 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.
+
+## 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).
+
+## Command reference
+
+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 --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. |
+
+## 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.
+
+### 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:
+>
+> 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.
+>
+> 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.
+
+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:
+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.
+
+### 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).
+
+### C. Inspect / operate
+
+```bash
+bag deploy status                         # every recorded provider + delegated live state
+bag deploy logs --provider aws --since 1h # delegated CloudWatch tail
+bag deploy verify --provider aws          # delegated status + ERC-8004 reconcile
+bag deploy destroy --provider aws         # dry-run teardown plan
+bag deploy destroy --provider aws --execute # delegated teardown (add --purge)
+```
+
+## Reference
+
+- b402/x402 selling on self-hosted AgentCore: the rail activates in-process
+  when the B402 credentials are set, but there is no anonymous URL — operate
+  your own HTTP front that relays envelope-v1 over `InvokeAgentRuntime`. See
+  `bnbagent-studio-selling-via-b402` and `docs/guides/x402-selling.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)

package/skills/references/bnbagent-studio-use-azure-foundry.md

@@ -0,0 +1,164 @@
+---
+name: bnbagent-studio-use-azure-foundry
+description: When the user wants to deploy or operate an A2A bnbagent-studio project on Azure AI Foundry Hosted Agents — scaffold with `bag init --runtime azure-foundry --protocol A2A`, deploy with `bag deploy --provider azure` (container-only Invocations contract; ALL cloud execution is delegated to pinned `@bnbagent/deploy-cli@0.4.14`, SDK/REST with browser login — no `az`/`azd` CLIs), and run lifecycle commands with `--provider azure` when multiple deployments exist. Native MCP deploy is not supported on Azure yet; use AgentCore for MCP.
+---
+
+> **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-azure-foundry
+
+> **Preview.** Azure Foundry support is fully wired and listed in the `--runtime` menu. The most recent end-to-end live verification predates the TypeScript rewrite — treat your first deploy as a verification run.
+
+Procedure for deploying and operating the seller Agent on **Azure AI
+Foundry Hosted Agents** (`[stack].runtime = "azure-foundry"`). ALL cloud
+execution — browser login, Foundry onboarding, the container registry image
+build/push, secret provisioning, and the RBAC self-grant — is **delegated to
+the pinned `@bnbagent/deploy-cli`** (run via `bunx --bun`; override with
+`BNBAGENT_DEPLOY_COMMAND`), whose Azure provider is **SDK/REST-only**. Studio
+never shells out to (or requires) the `az` / `azd` CLIs.
+
+```
+<workspace>/
+├── app/agent/             # the deployed code (src/foundryMain.ts host + Dockerfile here)
+│   ├── studio.toml        # [azure] block: location / account_name / subdomain / project_name / agent_endpoint
+│   └── Dockerfile         # the container image bnbagent-deploy builds + pushes
+└── .studio/               # secrets + wallets (workspace root — never in the image)
+```
+
+> **Deploy model: CONTAINER-ONLY.** The deploy-cli Azure provider rejects Node
+> zip artifacts, so every azure-foundry deploy builds the scaffolded
+> `app/agent/Dockerfile` **locally with Docker** (linux/amd64) and pushes it
+> to the auto-provisioned Azure Container Registry; Foundry Agent Service
+> pulls and runs the image. A running Docker daemon is required.
+
+> **Protocol: A2A projects only for now.** The deployed Node host speaks
+> Foundry's pass-through Invocations container contract on `:8088`
+> (`GET /readiness`, `POST /invocations`). That endpoint is not native MCP
+> streamable HTTP; `bag init` and provider selection reject azure-foundry +
+> MCP instead of deploying a container that can never become ready.
+
+> **Auth is a browser login.** The first delegated run opens a browser to sign
+> in to the right tenant/subscription — there is no `az login` / `azd auth
+> login` step and no CLI to install.
+
+## Prerequisites
+
+1. **Bun 1.3+ (`bunx`) on PATH** — the pinned `@bnbagent/deploy-cli` runs
+   through it.
+2. **Docker running** — the image is built locally (linux/amd64) before push.
+3. **An Azure subscription** the operator may provision in (Foundry
+   account/project, container registry, hosted agent); sign-in happens via
+   the browser at deploy time.
+
+## ⚠️ Foundry gotchas (read before deploying)
+
+`bag deploy prepare --runtime azure-foundry` encodes these as checks, but know them:
+
+- **Region must support Hosted Agents.** Default `eastus2`. `eastus` does NOT.
+  Prepare refuses an unsupported `[azure].location` (else deploy fails with
+  `Unsupported region for Foundry Hosted Agents`).
+- **Account name MUST equal the custom subdomain.** The runtime derives
+  `https://{account_name}.services.ai.azure.com`; a mismatch resolves to
+  NXDOMAIN and the agent returns HTTP 500. `bag init` sets them equal — keep them
+  equal in `[azure]`.
+- **Empty `APPLICATIONINSIGHTS_CONNECTION_STRING` crashes the exporter.** The
+  emitted entrypoint drops it when blank — don't remove that guard.
+- **The hosted container contract is fixed.** Keep `AGENT_PORT=8088`,
+  `GET /readiness` returning HTTP 200, and `POST /invocations`. Local A2A still
+  runs on `:9000`; do not copy that local port into the Foundry Dockerfile.
+- **Prepare checks are local-only.** They validate the scaffold (region,
+  subdomain, entrypoint + Dockerfile, an OpenAI-compatible `[llm]` provider,
+  twak readiness) without any cloud call; Azure auth happens at deploy time.
+
+## Runtime secrets — the delegated hand-off
+
+`bag deploy --provider azure` bundles the runtime secrets (provider/storage keys,
+`WALLET_PASSWORD`, the encrypted keystore as `WALLET_KEYSTORE_JSON` — plus the
+`BNBAGENT_LLM_*` wiring the Foundry host reads) and hands them to
+bnbagent-deploy as a private (mode 0600) tempdir envFile; the deploy CLI
+provisions them for the hosted agent as **Foundry CustomKeys**. No vault setup,
+no role assignments, and no cloud CLI on your side.
+
+> The encrypted keystore (`.studio/wallets/`) stays at the workspace root and
+> rides only that secret channel — never baked into the image.
+
+Provider-native overrides go in the optional `studio.toml [deploy.foundry]`
+table (verbatim deploy-spec keys; deploy-cli 0.4.14 consumes `account`, `cpu`,
+`location`, `memory`, `project`, `projectEndpoint`, `protocol`, `registry` and
+warns about anything else). The `[azure]` block's `account_name` /
+`project_name` / `project_endpoint` / `location` win over conflicting
+`[deploy.foundry]` keys.
+
+## Typical workflow
+
+### A. Scaffold
+
+```bash
+bag init my-agent --runtime azure-foundry
+```
+
+`bag init` makes no Azure calls; all cloud onboarding happens at deploy time.
+
+### B. Deploy
+
+> **Preview, live E2E verified 2026-07-20.** The A2A azure-foundry path was
+> verified through container build/push, CustomKeys wallet injection, hosted
+> agent create/update, cold-start smoke, status, invoke, logs, a signed
+> `negotiate`, and destroy. Foundry itself remains a preview service.
+
+> ⚠️ **First deploy: relay the Azure-resource notice to the user.** `bag deploy
+> --provider azure` prints a notice that the delegated deploy CREATES billable Azure
+> resources (Foundry account/project, container registry, hosted agent
+> container) under the signed-in subscription. Show it, get consent, then
+> deploy.
+
+```bash
+bag deploy prepare --runtime azure-foundry   # local readiness gate (region/subdomain/Dockerfile)
+bag deploy --provider azure                  # delegated: login → onboard → build+push → CustomKeys → deploy [--smoke]
+```
+
+`bag deploy --provider azure` runs an HTTP contract smoke by default (pass
+`--skip-smoke` to omit it) and captures the Foundry endpoint into
+`app/agent/studio.toml [azure].agent_endpoint`. If Foundry creates the resource
+but that post-create check fails, Studio still records the discovered endpoint
+so `status`, `logs`, and `destroy` can manage the resource; the deploy command
+continues to return non-zero.
+
+### C. Validate / operate
+
+```bash
+bag deploy status                            # all recorded providers + live state
+bag deploy logs --provider azure --limit 50 # delegated Hosted Agent logs
+```
+
+The built-in smoke proves the container contract, not the seller signature.
+For a release E2E, invoke with a complete `negotiate` envelope and require
+`response.accepted=true`, a non-empty `negotiation_hash`, and `provider_sig`.
+The Invocations body is `{"input":"<serialized skill JSON>"}`.
+
+### D. Tear down
+
+```bash
+bag deploy destroy --provider azure                 # dry-run plan
+bag deploy destroy --provider azure --execute       # delegates `destroy --yes`
+bag deploy destroy --provider azure --execute --purge # retained resources too
+```
+
+`--purge` also removes the retained resources the deploy record tracks —
+including the soft-deleted Cognitive Services account, freeing the custom
+subdomain immediately (otherwise held ~48h). A successful teardown clears the
+recorded `[azure].agent_endpoint`.
+
+## Scope note
+
+Azure Foundry is an alternate runtime for the whole seller agent. There is no
+separate keyless Layer B service to keep in sync; ERC-8183 seller delivery still
+runs through the single signer runtime selected in `studio.toml [stack].runtime`.
+
+## Reference
+
+- `bag deploy --help` / `bag deploy <command> --help` (authoritative for commands + flags)
+- `app/agent/studio.toml [azure]` — location / account_name / subdomain /
+  project_name / agent_endpoint
+- `app/agent/studio.toml [deploy.foundry]` — provider-native deploy-spec passthrough
+- `BNBAGENT_DEPLOY_COMMAND` — override the pinned `bunx --bun @bnbagent/deploy-cli@<pin>` invocation (E2E/dev)

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

@@ -0,0 +1,92 @@
+---
+name: bnbagent-studio-use-bnb-trial
+description: Use when deploying or operating a bnbagent-studio seller on the BNB Chain managed 48h testnet trial, including GitHub device login, trial eligibility/expiry, staging verification, status, logs, verify, and destroy.
+---
+
+> **Reference file** of the `bnbagent-studio` router skill. Load it only for
+> provider `bnb` deployment work.
+
+# Use the BNB Chain 48h trial
+
+Treat this provider as a temporary testnet sandbox. Require a throwaway wallet,
+keep `bsc-testnet`, and explain that the runtime signing material is transmitted
+to the operator's managed secret store for the trial. Never use a mainnet key.
+
+All auth and cloud lifecycle work must cross the pinned
+`@bnbagent/deploy-cli@0.4.14` boundary. Do not call AWS/Azure CLIs or platform
+REST routes directly.
+
+## Select and authenticate
+
+Run:
+
+```bash
+bag platform login
+bag platform credit
+bag deploy --provider bnb
+```
+
+`bag platform login` must print the GitHub verification URL and device code. It
+must not open a browser. Give both values to the user and wait for them to
+complete verification.
+
+Before offering BNB, inspect the trial result:
+
+- `available`: selectable; explain that the 48h clock starts on first success.
+- `active`: selectable; show remaining time and expiry immediately.
+- `expired`: show the row and expiry, but mark it unavailable and do not select
+  it. AWS/Azure remain independently available when compatible with the
+  project scaffold.
+- unknown/auth required: explain that eligibility cannot be confirmed until
+  login; the delegated deploy rechecks before building.
+
+Every deploy/redeploy uses scheme C. Never silently reuse `[deploy].destination`
+or the last provider. A sole active BNB record may produce an explicit “update
+BNB” action. Switching to another compatible provider creates a coexisting
+deployment; it does not destroy BNB automatically.
+
+Automation requires `--provider bnb --yes`. When another provider remains
+active, also require `--allow-multiple`.
+
+## Operate
+
+```bash
+bag deploy status
+bag deploy logs --provider bnb
+bag deploy verify --provider bnb
+bag deploy destroy --provider bnb           # dry-run
+bag deploy destroy --provider bnb --execute # destructive confirmation
+```
+
+`status` lists every recorded provider and includes the live trial countdown.
+Use `--no-probe` only when local records are desired. With multiple deployments,
+logs/verify/destroy must select a provider interactively or pass `--provider`.
+
+Destroy clears only the BNB lifecycle record after the delegated delete
+succeeds. It does not delete the local keystore or the on-chain ERC-8004
+identity. Destroyed BNB slugs are retired; choose a fresh slug before redeploy.
+
+## Manual staging verification
+
+Use the staging endpoint only for the current shell:
+
+```bash
+export BNBAGENT_API_URL=https://bnbagent-api.fe.kfkshore.org
+bag platform login
+bag platform credit
+bag deploy --provider bnb
+bag deploy status --provider bnb
+bag deploy logs --provider bnb
+bag deploy verify --provider bnb --skip-register
+bag deploy destroy --provider bnb
+```
+
+Do not execute the final destructive step until the user explicitly approves
+`bag deploy destroy --provider bnb --execute`. For headless verification, use
+`BNBAGENT_API_TOKEN`, `BNBAGENT_API_URL`, `--provider bnb`, and `--yes`.
+
+Treat both artifact channels as required release coverage. The 2026-07-20
+staging baseline passed ZIP and linux/arm64 container through deploy, status,
+OAuth-authenticated signed A2A negotiation, logs, and destroy. Do not infer
+funded delivery or durable-storage coverage from that smoke; those require the
+separate commerce flow in `docs/guides/verification.md`.

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

@@ -0,0 +1,68 @@
+---
+name: bnbagent-studio-using-altana-wallet
+description: Use when a bnbagent-studio project selects wallet.kind = "altana" and needs the encrypted admin keystore, bounded runtime session lifecycle, ERC-8183 quote checker, x402 allowance, local dev, or deployment limitation.
+---
+
+# Using the Altana wallet
+
+Altana separates trusted administration from runtime authority:
+
+- `.studio/wallets/<address>.json` is the encrypted admin keystore.
+- `.studio/wallets/altana-session.json` is the one bounded, expiring runtime
+  session and must stay mode `0600`.
+- `WALLET_PASSWORD` is admin-only. The Agent gets `ALTANA_SESSION`, never the
+  password or admin keystore.
+- Generic signing is refused. ERC-8183 uses `sessionQuoteSigner()` and the
+  approved quote checker.
+- Deployment is deferred; `bag deploy --provider <provider>` hard-blocks before side effects.
+- Altana refuses generic message signing, so Pieverse SIWE cannot authenticate
+  either `bag llm activate` or runtime credit renewal. An existing Pieverse key
+  is usable only with `auto/free`; use OpenRouter, OpenAI, or Anthropic for paid
+  models.
+
+## Procedure
+
+```bash
+bag init <name> --wallet-kind altana --destination self --no-onboard
+# Non-TTY defaults to OpenRouter. In a TTY, choose OpenRouter, OpenAI, or
+# Anthropic from the provider menu; a flag remains available when desired:
+# bag init <name> --wallet-kind altana --llm-provider anthropic --destination self
+cd <name>/app/agent
+export WALLET_PASSWORD='<strong password>'
+bag wallet new
+# fund the printed admin address with gas + U
+bag wallet session grant
+bag wallet session status
+bag doctor
+bag dev
+```
+
+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.
+
+If quote-checker approval fails after the paid grant, the owner-only session
+file is preserved. Repair it with:
+
+```bash
+bag wallet session grant --approve-only
+```
+
+Replace with `grant --force`; the old on-chain revoke must succeed before the
+new grant begins. Revoke with `bag wallet session revoke --yes`; the file is
+deleted only after chain success.
+
+x402 buying remains separate and exact-bounded:
+
+```bash
+bag wallet session x402-setup --allowance-u <U> --yes
+```
+
+Altana cannot be the b402 **seller** payout wallet (the rail allows
+`evm-local` and `twak` only); init, `bag x402 sell init`, and deploy
+readiness reject the combination. Only the outbound buying authority above
+is available.
+
+For troubleshooting, run `bag doctor` and `bag wallet session status`. Do not
+print, parse, or copy the `signer` portion of the serialized session, and never
+move `.studio/wallets/` under `app/agent/`.