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

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

@@ -1,128 +1,76 @@
 ---
 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.
+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 --protocols A2A`, deploy with `bag deploy --provider azure` (container-only Invocations contract; all cloud lifecycle 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.
+> **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 — not advertised in this release.** Azure Foundry support is fully wired but hidden from the `--runtime` menu and the deploy provider menu; these steps still work if you select `azure-foundry` / `--provider azure` explicitly. The most recent end-to-end live verification predates the TypeScript rewrite — treat your first deploy as a verification run.
+> **Preview - not advertised in this release.** Azure Foundry support is fully wired but hidden from the `--runtime` menu and the deploy provider menu; these steps still work if you select `azure-foundry` / `--provider azure` explicitly. 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.
+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)
+└── .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.
+> **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.
+> **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.
+> **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.
+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.
+- **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 myagent --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.
+> **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.
+> ⚠️ **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.
+`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
 
@@ -131,10 +79,7 @@ bag deploy status                            # all recorded providers + live sta
 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>"}`.
+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
 
@@ -144,21 +89,15 @@ 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`.
+`--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`.
+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)
+- `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

@@ -3,18 +3,13 @@ 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.
+> **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.
+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 the AWS CLI or platform
-REST routes directly.
+All auth and cloud lifecycle work must cross the pinned `@bnbagent/deploy-cli@0.4.14` boundary. Do not call the AWS CLI or platform REST routes directly.
 
 ## Select and authenticate
 
@@ -26,27 +21,18 @@ 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.
+`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 remains 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.
+- `expired`: show the row and expiry, but mark it unavailable and do not select it. AWS remains 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.
+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`.
+Automation requires `--provider bnb --yes`. When another provider remains active, also require `--allow-multiple`.
 
 ## Operate
 
@@ -58,13 +44,9 @@ 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`.
+`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.
+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
 
@@ -81,12 +63,6 @@ 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`.
+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`.
+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

@@ -1,6 +1,6 @@
 ---
 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.
+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 session-only deployment and renewal.
 ---
 
 # Using the Altana wallet
@@ -8,17 +8,11 @@ description: Use when a bnbagent-studio project selects wallet.kind = "altana" a
 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.
+- `.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 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 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 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
 
@@ -37,20 +31,15 @@ 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.
+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:
+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.
+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:
 
@@ -58,12 +47,6 @@ x402 buying remains separate and exact-bounded:
 bag wallet session x402-setup --allowance-u <U> --yes
 ```
 
-Altana cannot be the b402 **seller** payout wallet for a positive price (paid
-mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and
-deploy readiness reject that paid combination. Explicit
-`price_usd = "0"` is allowed because FREE passthrough performs no payout and
-bypasses B402. The outbound buying authority above remains a separate feature.
+Altana cannot be the b402 **seller** payout wallet for a positive price (paid mode allows `evm-local` and `twak` only); init, `bag x402 sell init`, and deploy readiness reject that paid combination. Explicit `price_usd = "0"` is allowed because FREE passthrough performs no payout and bypasses B402. The outbound buying authority above remains a separate feature.
 
-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/`.
+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/`.