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

package/skills/references/bnbagent-studio-buying-via-8183.md

@@ -1,85 +1,50 @@
 ---
 name: bnbagent-studio-buying-via-8183
-description: When the user is acting as ERC-8183 buyer — finding a provider, getting a quote, buying a service, fetching the deliverable, and deciding to approve / dispute / reject the work. Owns the buyer-side decision tree for the entire job lifecycle including settle-window timing (24h dispute window), dispute governance flow, and `Submission deadline has passed` recovery.
+description: When the user is acting as ERC-8183 buyer - finding a provider, getting a quote, buying a service, fetching the deliverable, and deciding to approve / dispute / reject the work. Owns the buyer-side decision tree for the entire job lifecycle including settle-window timing (24h dispute window), dispute governance flow, and `Submission deadline has passed` recovery.
 ---
 
-> **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-buying-via-8183
 
-> **v1 scope note:** v1 is **seller-only** — buyer flows are **NOT**
-> the main v1 payment path. The x402 buyer kernel survives only as the Agent's
-> *automatic* LLM top-up (`@bnbagent/studio-runtime/x402`, budget-gated, not an LLM tool),
-> and the erc8183 `buyWorkflow` survives as an **underlying capability** still
-> reachable via the `bag erc8183 buy/status/fetch/settle` CLI. Full buyer-side
-> *product* flows (a buyer agent, buyer-side negotiation wrapping) are deferred
-> to v2. The CLI procedure below still works for manual / testing use.
+> **v1 scope note:** v1 is **seller-only** - buyer flows are **NOT** the main v1 payment path. The x402 buyer kernel survives only as the Agent's _automatic_ LLM top-up (`@bnbagent/studio-runtime/x402`, budget-gated, not an LLM tool), and the erc8183 `buyWorkflow` survives as an **underlying capability** still reachable via the `bag erc8183 buy/status/fetch/settle` CLI. Full buyer-side _product_ flows (a buyer agent, buyer-side negotiation wrapping) are deferred to v2. The CLI procedure below still works for manual / testing use.
 
-Procedure for **buyer-side flow**: have your agent (or you directly via CLI)
-purchase a service from another ERC-8183 seller, verify the deliverable, and
-close out the job with the right `settle` action.
+Procedure for **buyer-side flow**: have your agent (or you directly via CLI) purchase a service from another ERC-8183 seller, verify the deliverable, and close out the job with the right `settle` action.
 
-Audience: Claude Code in a v0.0.x workspace with a funded wallet (tBNB + U).
-The buying CLI (`bag erc8183 buy/status/fetch/settle`) targets the **Agent
-sub-project's** wallet — these commands resolve to `<workspace>/app/agent/`
-automatically when run from the workspace root.
+Audience: Claude Code in a current TypeScript workspace with a funded wallet (tBNB + U). The buying CLI (`bag erc8183 buy/status/fetch/settle`) targets the **Agent sub-project's** wallet - these commands resolve to `<workspace>/app/agent/` automatically when run from the workspace root.
 
-> **Protocol facts** (independent of the local filesystem layout): 24h dispute
-> window, `0x17be5b7b` revert, `expired_at` arithmetic.
+> **Protocol facts** (independent of the local filesystem layout): 24h dispute window, `0x17be5b7b` revert, `expired_at` arithmetic.
 
 **Different from**:
-- `bnbagent-studio-operating.md` (same directory) — generic ops (dev / doctor / balance / RPC); jumps here for buyer-specific decisions
-- `bnbagent-studio-adding-to-project` — covers wiring a buyer tool set into an existing project (the static setup, not the runtime decisions)
-- `bnbagent-studio-selling-via-8183.md` (same directory) — the mirror playbook for the seller side (`on_job`, dispute defense)
 
-This skill owns: **buy → fetch → approve/dispute/reject loop**, whether
-driven via CLI or the agent's LLM calling `erc8183_buyer_set` tools.
+- `bnbagent-studio-operating.md` (same directory) - generic ops (dev / doctor / balance / RPC); jumps here for buyer-specific decisions
+- `bnbagent-studio-adding-to-project` - covers wiring a buyer tool set into an existing project (the static setup, not the runtime decisions)
+- `bnbagent-studio-selling-via-8183.md` (same directory) - the mirror playbook for the seller side (`on_job`, dispute defense)
+
+This skill owns: **buy → fetch → approve/dispute/reject loop**, whether driven via CLI or the agent's LLM calling `erc8183_buyer_set` tools.
 
 ## Buyer settle decision tree (load this skill when the user hits any of these)
 
 `SUBMITTED` job → buyer has three options, **time-gated by the on-chain dispute window**:
 
 | Action | Allowed | What happens |
-|---|---|---|
+| --- | --- | --- |
 | `bag erc8183 settle <id> --action approve` | **After 24h dispute_window has passed** (chain enforces; reverts with `0x17be5b7b` if early) | Job → `COMPLETED`; seller receives U |
 | `bag erc8183 settle <id> --action dispute` | **Within dispute_window** | Opens governance flow; quorum vote decides; refund possible |
 | `bag erc8183 settle <id> --action reject` | **Only if you're a quorum voter, not the buyer** | Job → `REJECTED` via governance |
 
-If the buyer agent (or LLM) is about to call `settle --action approve` and it's
-been <24h since SUBMITTED, **wait** or use `dispute`. Don't try to retry
-through the revert — read the error and pick the right action.
+If the buyer agent (or LLM) is about to call `settle --action approve` and it's been <24h since SUBMITTED, **wait** or use `dispute`. Don't try to retry through the revert - read the error and pick the right action.
 
-Common error: `Submission deadline has passed` → buyer set `expiredAt` too
-short (< dispute_window). Fix: re-buy with `--deadline-min ≥ 1` (the buy
-flow now auto-adds dispute_window).
+Common error: `Submission deadline has passed` → buyer set `expiredAt` too short (< dispute_window). Fix: re-buy with `--deadline-min ≥ 1` (the buy flow now auto-adds dispute_window).
 
 ## Preconditions
 
 - `bag doctor` is clean (or only warns on LLM key)
-- For a paid job, the wallet has ≥ 0.05 tBNB (gas) and enough U for the budget
-  plus slack. On BSC testnet the
-  ERC-8183 kernel writes (`createJob` / `fund` deposit / `settle` …) are
-  gas-sponsored via the SDK's MegaFuel paymaster **when they target the
-  canonical contracts**, so you spend far less tBNB than
-  that — but **not zero**: `fund` sends an ERC-20 `approve` (a token call, not
-  sponsored) when the token allowance is too low — typically just the first fund,
-  since studio approves a floored cap that later jobs reuse. Keep a little tBNB for
-  it. (Mainnet is never sponsored.) Sponsorship is granted per target contract
-  by the paymaster policy: a custom/QA stack selected via the
-  `ERC8183_*_ADDRESS` overrides is normally **not** covered, so every write
-  self-pays gas (the SDK logs `… is not sponsorable on this network;
-  self-paying gas` and falls back automatically) — keep tBNB for the whole
-  flow, or set `BNBAGENT_USE_PAYMASTER=0` to skip the per-transaction
-  sponsorship probe and self-pay directly. For a FREE job, use `--budget-u 0`:
-  no U balance, ERC-20 approval, or token escrow is needed, but the ERC-8183
-  writes still need the selected gas/paymaster path and a zero-price-compatible
-  commerce/router/policy stack — today that means a custom stack, so expect the
-  writes to self-pay gas as above.
+- For a paid job, the wallet has ≥ 0.05 tBNB (gas) and enough U for the budget plus slack. On BSC testnet the ERC-8183 kernel writes (`createJob` / `fund` deposit / `settle` …) are gas-sponsored via the SDK's MegaFuel paymaster **when they target the canonical contracts**, so you spend far less tBNB than that - but **not zero**: `fund` sends an ERC-20 `approve` (a token call, not sponsored) when the token allowance is too low - typically just the first fund, since studio approves a floored cap that later jobs reuse. Keep a little tBNB for it. (Mainnet is never sponsored.) Sponsorship is granted per target contract by the paymaster policy: a custom/QA stack selected via the `ERC8183_*_ADDRESS` overrides is normally **not** covered, so every write self-pays gas (the SDK logs `… is not sponsorable on this network; self-paying gas` and falls back automatically) - keep tBNB for the whole flow, or set `BNBAGENT_USE_PAYMASTER=0` to skip the per-transaction sponsorship probe and self-pay directly. For a FREE job, use `--budget-u 0`: no U balance, ERC-20 approval, or token escrow is needed, but the ERC-8183 writes still need the selected gas/paymaster path and a zero-price-compatible commerce/router/policy stack - today that means a custom stack, so expect the writes to self-pay gas as above.
 - You know the **provider's wallet address** (the seller agent's address)
-- The seller is **reachable** (its A2A agent is deployed somewhere); discoverable
-  via the provider's `bag erc8004 resolve <agent_id>` endpoint URI
+- The seller is **reachable** (its A2A agent is deployed somewhere); discoverable via the provider's `bag erc8004 resolve <agent_id>` endpoint URI
 
-## Stage 1 — Pre-flight checks
+## Stage 1 - Pre-flight checks
 
 ```bash
 # 1. Confirm wallet + balances
@@ -91,27 +56,15 @@ bag erc8004 resolve <provider_agent_id>
 # → returns the agent_uri; decode it (base64 data: URI) to verify the endpoint URL
 ```
 
-If the provider's endpoint URL points somewhere reachable (e.g. an `https://`
-AgentCore runtime URL), proceed. If it's `http://localhost:...`, that means you
-must be on the same host.
+If the provider's endpoint URL points somewhere reachable (e.g. an `https://` AgentCore runtime URL), proceed. If it's `http://localhost:...`, that means you must be on the same host.
 
-## Stage 2 — (Optional) Negotiate price
+## Stage 2 - (Optional) Negotiate price
 
-**v0.0.x**: `@bnbagent/studio-runtime` *does* wrap the buyer-side negotiation
-handshake (`@bnbagent/studio-runtime/erc8183` `negotiateWithSeller`, wired into
-the buy workflow). It fires automatically when you buy by `--agent-id` (resolves
-the seller's endpoint from its ERC-8004 record, then POSTs `/negotiate`); pass
-`--no-negotiate` to skip it. When you buy by `--provider <addr>` you supply the
-budget directly and assume the price was agreed off-chain.
+The current `@bnbagent/studio-runtime` wraps the buyer-side negotiation handshake (`@bnbagent/studio-runtime/erc8183` `negotiateWithSeller`, wired into the buy workflow). It fires automatically when you buy by `--agent-id` (resolves the seller's endpoint from its ERC-8004 record, then POSTs `/negotiate`); pass `--no-negotiate` to skip it. When you buy by `--provider <addr>` you supply the budget directly and assume the price was agreed off-chain.
 
-If you want to talk to the seller manually, the seller now exposes its
-`negotiate` skill over **A2A** (the seller's ERC-8004 endpoint URI is an A2A base
-URL): send an A2A `message/send` JSON-RPC call carrying a `DataPart`
-`{"skill": "negotiate", "task_description": "...", "terms": {...}}` (+ the seller's
-OAuth2 Bearer when deployed). The reply data part is the signed `NegotiationResult`
-quote. But you don't need this for v0.0.x — go straight to buy.
+If you want to talk to the seller manually, the seller now exposes its `negotiate` skill over **A2A** (the seller's ERC-8004 endpoint URI is an A2A base URL): send an A2A `message/send` JSON-RPC call carrying a `DataPart` `{"skill": "negotiate", "task_description": "...", "terms": {...}}` (+ the seller's OAuth2 Bearer when deployed). The reply data part is the signed `NegotiationResult` quote. For the normal CLI flow, go straight to buy.
 
-## Stage 3 — Buy
+## Stage 3 - Buy
 
 ```bash
 bag erc8183 buy --provider <provider_addr> "<task description>" \
@@ -129,34 +82,22 @@ bag erc8183 buy --provider <provider_addr> "<task description>" \
   --budget-u 0 --deadline-min 30 --network bsc-testnet
 ```
 
-> **Task can be passed two ways** (both accepted): as a positional argument
-> `bag erc8183 buy --provider <addr> "<task>"` OR via the flag
-> `bag erc8183 buy --provider <addr> --task "<task>"`. Pass it once — supplying
-> both at the same time is an error.
+> **Task can be passed two ways** (both accepted): as a positional argument `bag erc8183 buy --provider <addr> "<task>"` OR via the flag `bag erc8183 buy --provider <addr> --task "<task>"`. Pass it once - supplying both at the same time is an error.
 
 The 4 on-chain steps run sequentially:
 
 1. `createJob(provider, expiredAt, description)` → returns `job_id`
 2. `registerJob(jobId)`
 3. `setBudget(jobId, rawBudget)`
-4. `fund(jobId, rawBudget, approveFloor=rawBudget)` — auto-approves U only
-   when the positive budget needs allowance; budget 0 skips approval and escrow
+4. `fund(jobId, rawBudget, approveFloor=rawBudget)` - auto-approves U only when the positive budget needs allowance; budget 0 skips approval and escrow
 
 Output prints 4 tx hashes + `job_id`. Note the `job_id` for later.
 
-**Gotcha**: `expired_at = now + deadline_minutes*60 + dispute_window` (24h). This
-is intentional — the chain enforces that submission must happen before
-`expired_at - dispute_window`. If you set `deadline_minutes=30`, the seller has
-30 min to submit (then a 24h dispute window starts).
+**Gotcha**: `expired_at = now + deadline_minutes*60 + dispute_window` (24h). This is intentional - the chain enforces that submission must happen before `expired_at - dispute_window`. If you set `deadline_minutes=30`, the seller has 30 min to submit (then a 24h dispute window starts).
 
-## Stage 4 — Wait for SUBMITTED
+## Stage 4 - Wait for SUBMITTED
 
-The single seller runtime has **no standalone poller** — after funding, send a
-`notify_funded` A2A message to the seller ("I funded job X, please deliver"). The
-seller **acks `accepted` immediately and delivers in the background**, so you do
-**not** get the deliverable in the A2A reply — you poll the chain for it. The
-seller also sweeps other funded jobs on each `notify_funded` (in the background,
-deduped). Check status:
+The single seller runtime has **no standalone poller** - after funding, send a `notify_funded` A2A message to the seller ("I funded job X, please deliver"). The seller **acks `accepted` immediately and delivers in the background**, so you do **not** get the deliverable in the A2A reply - you poll the chain for it. The seller also sweeps other funded jobs on each `notify_funded` (in the background, deduped). Check status:
 
 ```bash
 bag erc8183 status <job_id>
@@ -167,31 +108,21 @@ Statuses:
 - `OPEN` → not yet funded (shouldn't see this after Step 3)
 - `FUNDED` → waiting for seller to pick up + submit
 - `SUBMITTED` → ready to fetch + settle
-- `EXPIRED` → seller missed the deadline; use `bag erc8183 settle --action ...` or
-  the SDK's `mark_expired` / `claim_refund`
+- `EXPIRED` → seller missed the deadline; use `bag erc8183 settle --action ...` or the SDK's `mark_expired` / `claim_refund`
 
-Delivery is no longer instant: because the seller works in the background, the
-wait is however long its work takes (seconds to minutes). Poll until `SUBMITTED`,
-then read `deliverable_url` (Stage 5). If it stays `FUNDED`, either no one sent
-`notify_funded` (and the sweep hasn't run — the seller may be scaled to zero), or
-the seller's background work failed or hasn't finished yet — re-send
-`notify_funded` to nudge it while the runtime is warm. (Also possible: a config
-mismatch, most often `expired_at` too soon — but the workflow auto-fixes this now.)
+Delivery is no longer instant: because the seller works in the background, the wait is however long its work takes (seconds to minutes). Poll until `SUBMITTED`, then read `deliverable_url` (Stage 5). If it stays `FUNDED`, either no one sent `notify_funded` (and the sweep hasn't run - the seller may be scaled to zero), or the seller's background work failed or hasn't finished yet - re-send `notify_funded` to nudge it while the runtime is warm. (Also possible: a config mismatch, most often `expired_at` too soon - but the workflow auto-fixes this now.)
 
-## Stage 5 — Fetch the deliverable
+## Stage 5 - Fetch the deliverable
 
-The single seller runtime serves **no** job-query endpoint — the deliverable is read
-back from the on-chain submission (the `submit` tx carries the `deliverable_url`,
-typically `ipfs://...`) and the IPFS object. Get the URL via CLI:
+The single seller runtime serves **no** job-query endpoint - the deliverable is read back from the on-chain submission (the `submit` tx carries the `deliverable_url`, typically `ipfs://...`) and the IPFS object. Get the URL via CLI:
 
 ```bash
 bag erc8183 fetch <job_id>
 ```
 
-Prints the `deliverable_url`. Fetch it yourself (e.g. via an IPFS gateway) to read
-the `DeliverableManifest`: `{"chain_id", "contracts", "job_id", "response": {"content": ..., "content_type": ...}, "metadata": {...}}`.
+Prints the `deliverable_url`. Fetch it yourself (e.g. via an IPFS gateway) to read the `DeliverableManifest`: `{"chain_id", "contracts", "job_id", "response": {"content": ..., "content_type": ...}, "metadata": {...}}`.
 
-## Stage 6 — Settle
+## Stage 6 - Settle
 
 ```bash
 # Happy path: accept the deliverable. NOTE: must wait 24h dispute_window first.
@@ -206,18 +137,16 @@ bag erc8183 settle <job_id> --action reject
 
 Returns a tx hash. Verify on BscScan.
 
-**On `--action approve` revert with `0x17be5b7b`**: chain refuses because
-`submitted_at + dispute_window > now`. Either wait the remaining time or
-use `--action dispute` for immediate effect.
+**On `--action approve` revert with `0x17be5b7b`**: chain refuses because `submitted_at + dispute_window > now`. Either wait the remaining time or use `--action dispute` for immediate effect.
 
-## Stage 7 — Verify on-chain settlement
+## Stage 7 - Verify on-chain settlement
 
 ```bash
 bag erc8183 status <job_id>
 # Expect: status COMPLETED (after approve) or unchanged SUBMITTED (after dispute, until voters resolve)
 ```
 
-Check seller's U balance increased (minus platform fee — see `CommerceClient.platform_fee_bp()`).
+Check seller's U balance increased (minus platform fee - see `CommerceClient.platform_fee_bp()`).
 
 ## End-to-end smoke (one-shot, for testing your setup)
 
@@ -232,12 +161,9 @@ bag erc8183 status $JOB
 bag erc8183 settle $JOB --action dispute
 ```
 
-For the FREE regression, change the budget to `0` and confirm the compatible
-contract job still reaches `FUNDED` and `SUBMITTED` without an ERC-20 approval
-or balance change.
+For the FREE regression, change the budget to `0` and confirm the compatible contract job still reaches `FUNDED` and `SUBMITTED` without an ERC-20 approval or balance change.
 
-This is the exact end-to-end flow used to validate real-chain buying. See the
-references below for the canonical picture.
+This is the exact end-to-end flow used to validate real-chain buying. See the references below for the canonical picture.
 
 ## Reference
 

package/skills/references/bnbagent-studio-extending-signing.md

@@ -1,26 +1,21 @@
 ---
 name: bnbagent-studio-extending-signing
-description: When the user wants the agent's wallet to sign EIP-712 typed data for anything beyond BSC U-token transfers — e.g. integrate a new x402 service, custom commerce contract, or any TypedData primary type beyond TransferWithAuthorization/ReceiveWithAuthorization. Also covers diagnosing `PolicyViolation` / `X402PolicyError` at runtime and how to safely extend `[wallet.signing]` extra_domains / extra_primary_types in studio.toml.
+description: When the user wants the agent's wallet to sign EIP-712 typed data for anything beyond BSC U-token transfers - e.g. integrate a new x402 service, custom commerce contract, or any TypedData primary type beyond TransferWithAuthorization/ReceiveWithAuthorization. Also covers diagnosing `PolicyViolation` / `X402PolicyError` at runtime and how to safely extend `[wallet.signing]` extra_domains / extra_primary_types in studio.toml.
 ---
 
-> **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-extending-signing
 
-Procedure for **extending the EIP-712 signing allowlist** in a bnbagent-studio project.
-Audience: Claude Code helping a user who hit `PolicyViolation` or wants to integrate a non-default x402 service / custom contract.
+Procedure for **extending the EIP-712 signing allowlist** in a bnbagent-studio project. Audience: Claude Code helping a user who hit `PolicyViolation` or wants to integrate a non-default x402 service / custom contract.
 
-> **v0.0.1 path note**: signing is an **Agent-only** concern. `signing.ts` lives
-> at `<workspace>/app/agent/src/signing.ts` and is called by the
-> `SellerAgentExecutor` skills (`negotiate` / `notify_funded`) — it is **never** an
-> LLM-callable tool. The `[wallet.signing]` config lives in
-> `<workspace>/app/agent/studio.toml`. The workspace is a thin root plus the one
-> `app/agent/` sub-project; every command and edit below targets `app/agent/`.
+> **Current path note**: signing is an **Agent-only** concern. `signing.ts` lives at `<workspace>/app/agent/src/signing.ts` and is called by the `SellerAgentExecutor` skills (`negotiate` / `notify_funded`) - it is **never** an LLM-callable tool. The `[wallet.signing]` config lives in `<workspace>/app/agent/studio.toml`. The workspace is a thin root plus the one `app/agent/` sub-project; every command and edit below targets `app/agent/`.
 
 **Different from**:
-- `-operating` — general ops & doctor / balance / job status
-- `funding-pieverse-llm` — Pieverse LLM credit lifecycle (the money)
-- `-adding-to-project` — adds capabilities (`bnbagent-sdk` modules)
+
+- `-operating` - general ops & doctor / balance / job status
+- `funding-pieverse-llm` - Pieverse LLM credit lifecycle (the money)
+- `-adding-to-project` - adds capabilities (`bnbagent-sdk` modules)
 
 This skill is specifically the **signing-permission** axis. Funding is "do I have the money"; signing policy is "is the wallet allowed to sign this".
 
@@ -29,7 +24,7 @@ This skill is specifically the **signing-permission** axis. Funding is "do I hav
 Every EIP-712 signature goes through SDK `SigningPolicy.strictDefault()`. By default the wallet only signs:
 
 | Allowed | Domain | Primary types |
-|---|---|---|
+| --- | --- | --- |
 | U-token mainnet | chain `56`, `0xcE24439F2D9C6a2289F741120FE202248B666666` | `TransferWithAuthorization`, `ReceiveWithAuthorization` |
 | U-token testnet | chain `97`, `0xc70B8741B8B07A6d61E54fd4B20f22Fa648E5565` | (same) |
 
@@ -38,40 +33,40 @@ Everything else (`Permit`, `PermitSingle`, `PermitBatch`, foreign contracts, for
 Two layers wrap this:
 
 | Layer | What it gates | Where configured | Can agent change at runtime? |
-|---|---|---|---|
-| L2 — HTTP host | which servers the x402 buyer is allowed to fetch from | `[payments.x402].allowed_hosts` in `app/agent/studio.toml` | ⚠️ Only by editing toml + restart |
-| L3 — SigningPolicy | which `(chain_id, contract)` + primary type the wallet will sign | `[wallet.signing]` in `app/agent/studio.toml` (additive over SDK strictDefault) | ⚠️ Only by editing toml + restart |
+| --- | --- | --- | --- |
+| L2 - HTTP host | which servers the x402 buyer is allowed to fetch from | `[payments.x402].allowed_hosts` in `app/agent/studio.toml` | ⚠️ Only by editing toml + restart |
+| L3 - SigningPolicy | which `(chain_id, contract)` + primary type the wallet will sign | `[wallet.signing]` in `app/agent/studio.toml` (additive over SDK strictDefault) | ⚠️ Only by editing toml + restart |
 
-**Both layers must permit a request** for it to succeed. Adding only one half won't work — see Section A.
+**Both layers must permit a request** for it to succeed. Adding only one half won't work - see Section A.
 
 EIP-191 SIWE (the `pieverse_usage` MCP tool / `bag llm activate`) uses a **separate** hardcoded allowlist `{"llm.pieverse.io"}` and is not configurable.
 
 ## Quick triage decision tree
 
 | User said... | Section |
-|---|---|
-| "buy X service via x402" (X is not Pieverse) | A — new x402 service |
-| "sign for custom commerce contract / order / quote" | B — custom primary type |
-| `PolicyViolation` / `X402PolicyError` at runtime | C — diagnosing the rejection |
-| "agent needs to approve unlimited USDC" / Permit / Permit2 | D — refuse the request |
-| "expand the 600s validity window" | E — validity overrides |
+| --- | --- |
+| "buy X service via x402" (X is not Pieverse) | A - new x402 service |
+| "sign for custom commerce contract / order / quote" | B - custom primary type |
+| `PolicyViolation` / `X402PolicyError` at runtime | C - diagnosing the rejection |
+| "agent needs to approve unlimited USDC" / Permit / Permit2 | D - refuse the request |
+| "expand the 600s validity window" | E - validity overrides |
 
 ## A. Integrate a new x402 service
 
 The user wants the agent to pay e.g. `api.example.com` via x402.
 
-**Pre-flight checks (must be true in v0.0.1 — refuse and explain if not):**
+**Pre-flight checks (must be true in the current release; refuse and explain if not):**
 
-1. The service accepts payment on **BSC chain 56 or 97**. v0.0.1 wallets are BSC-only; a service on Base/Ethereum/Polygon won't work until v0.2 multi-chain support lands.
+1. The service accepts payment on **BSC chain 56 or 97**. Current wallets are BSC-only; services on Base, Ethereum, or Polygon are unsupported.
 2. The service uses **EIP-3009 `TransferWithAuthorization`** (or `ReceiveWithAuthorization`). If it uses Permit2 or a custom primary type → goes to Section B.
-3. The token contract address on BSC is known and the user can confirm it. Don't guess from a token symbol — look up the deployed address.
+3. The token contract address on BSC is known and the user can confirm it. Don't guess from a token symbol - look up the deployed address.
 
-If any of (1)–(3) fail, **stop and tell the user**. v0.0.1 cannot integrate cross-chain services or non-EIP-3009 payment rails. Don't try to work around it; the SigningPolicy will refuse and the failure will be confusing.
+If any of (1)-(3) fail, **stop and tell the user**. The current release cannot integrate cross-chain services or non-EIP-3009 payment rails. Do not work around it; the SigningPolicy will refuse the request.
 
-**Steps when (1)–(3) all pass:**
+**Steps when (1)-(3) all pass:**
 
 ```bash
-# 1. Edit app/agent/studio.toml — both gates. `bag config` resolves the app/agent/
+# 1. Edit app/agent/studio.toml - both gates. `bag config` resolves the app/agent/
 #    sub-project automatically from the workspace root
 #    (there is NO --side flag); pass --project-root app/agent to be explicit.
 bag config set payments.x402.allowed_hosts '["llm.pieverse.io", "api.example.com"]'
@@ -98,6 +93,7 @@ bag wallet policy show
 ```
 
 **Hard rules**:
+
 - Do not add a contract to `extra_domains` without verifying its address on a block explorer. The SigningPolicy treats `(chain_id, contract)` as a unit; the wrong address = signing into a phishing contract.
 - Do not silently widen `daily_cap_usd` or `max_per_request_usd` to make the new service "fit". The caps are budget guardrails; surface the proposed values to the user before editing.
 
@@ -114,9 +110,10 @@ extra_domains = [
 extra_primary_types = ["MyOrder", "BondQuote"]
 ```
 
-**Both must be added** — adding a primary type without the matching domain is useless (the contract still gets rejected) and adding the domain without the type still rejects the signature (primary_type allowlist).
+**Both must be added** - adding a primary type without the matching domain is useless (the contract still gets rejected) and adding the domain without the type still rejects the signature (primary_type allowlist).
 
 **Hard rules**:
+
 - The SDK denylist (`Permit`, `PermitSingle`, `PermitBatch`) **always wins** over `extra_primary_types`. Listing them does not enable them.
 - Custom primary types bypass studio's known semantic checks. Be extra careful that the typed data structure matches what the contract expects; an attacker controlling the contract or the LLM input can construct unfavorable messages.
 
@@ -130,7 +127,7 @@ PolicyViolation: unknown (chain_id, verifyingContract): (56, 0xAbc...)
   → Section A or B: add to [wallet.signing].extra_domains, then restart
 
 PolicyViolation: primary type 'Permit' is denylisted
-  → Section D: refuse — do not work around
+  → Section D: refuse - do not work around
 
 PolicyViolation: primary type 'MyOrder' not in allowlist
   → Section B: add to extra_primary_types
@@ -138,14 +135,14 @@ PolicyViolation: primary type 'MyOrder' not in allowlist
 PolicyViolation: validity window 7200s exceeds max 600
   → Section E: max_validity_window_seconds in [wallet.signing]
 
-X402HostNotAllowedError: x402 buyer refusing 'api.example.com' — not in allowed_hosts
-  → L2 HTTP gate (exact hosts only — wildcard entries are not supported)
+X402HostNotAllowedError: x402 buyer refusing 'api.example.com' - not in allowed_hosts
+  → L2 HTTP gate (exact hosts only - wildcard entries are not supported)
   → bag config set payments.x402.allowed_hosts '[..., "api.example.com"]'
   → (L3 may also need updating per Section A)
 
 X402BudgetExhaustedError: x402 402 demands $1.50 > max_usd=$1.00
   → Budget cap; user must explicitly raise via studio.toml.
-  → DON'T silently widen — tell the user.
+  → DON'T silently widen - tell the user.
 ```
 
 Confirm the current state before editing:
@@ -161,13 +158,14 @@ If the user (or, more dangerously, the LLM) asks the agent to sign `Permit`, `Pe
 
 **Stop. Refuse. Explain why.**
 
-These primary types grant unbounded ERC-20 spend authority to a third party. The denylist exists exactly to prevent LLMs being talked into signing one. Even if the user insists, the SDK will refuse with `PolicyViolation` and the message is correct — do not bypass via `_DANGEROUS_signTypedDataNoPolicy`.
+These primary types grant unbounded ERC-20 spend authority to a third party. The denylist exists exactly to prevent LLMs being talked into signing one. Even if the user insists, the SDK will refuse with `PolicyViolation` and the message is correct - do not bypass via `_DANGEROUS_signTypedDataNoPolicy`.
 
 Acceptable alternatives:
-- For paying a known service: use EIP-3009 `TransferWithAuthorization` (Section A — bounded amount, single-use, time-windowed)
-- For session-scoped recurring payments: opt-in to `Permit2 PermitTransferFrom` (Section B — single-use, witness-bound; not Permit / PermitSingle / PermitBatch)
 
-If the user is integrating something that genuinely requires Permit, this is a v0.2+ decision and should go in an ADR — do not make the change ad-hoc.
+- For paying a known service: use EIP-3009 `TransferWithAuthorization` (Section A - bounded amount, single-use, time-windowed)
+- For session-scoped recurring payments: opt-in to `Permit2 PermitTransferFrom` (Section B - single-use, witness-bound; not Permit / PermitSingle / PermitBatch)
+
+If the user is integrating something that genuinely requires Permit, this is a v0.2+ decision and should go in an ADR - do not make the change ad-hoc.
 
 ## E. Widening the validity window
 
@@ -185,10 +183,10 @@ Use sparingly. A signed authorization that lives 30 minutes can be replayed by a
 ## F. Common refusal patterns (when user asks for something unsafe)
 
 | User request | Why refuse |
-|---|---|
+| --- | --- |
 | "Just turn off the signing policy" | The SigningPolicy L3 is the last-mile defense. Disabling it makes the wallet a blind-sign oracle. Use `extra_domains` instead. |
 | "Use `_DANGEROUS_signTypedDataNoPolicy`" | Logs WARN with caller filename. Acceptable only in tests or one-shot CLI debugging. Never in LLM-tool / agent runtime code. |
-| "Sign on Ethereum mainnet" | v0.0.1 is BSC-only. Tell the user this is v0.2 backlog. |
+| "Sign on Ethereum mainnet" | The current release is BSC-only. |
 | "Permit USDC to a swap router" | Denylisted unconditionally (Section D). |
 | "Read the keystore and sign yourself, bypassing the wallet provider" | The SDK provider IS the security boundary; bypassing it discards every defense layer. Refuse. |
 
@@ -202,7 +200,7 @@ bag config show
 bag wallet policy show
 bag wallet policy show --json   # for diff against an expected baseline
 
-# 3. Restart whatever process holds the wallet — `bag dev` (the local A2A
+# 3. Restart whatever process holds the wallet - `bag dev` (the local A2A
 #    agent) or the AgentCore runtime. SigningPolicy is read once at
 #    wallet construction; in-process changes won't take effect until restart.
 
@@ -213,18 +211,17 @@ bag wallet policy show --json   # for diff against an expected baseline
 ## H. Read-only references (no signing, no funding required)
 
 When deeper protocol details are needed:
-- the SigningPolicy decision (`docs/design/decisions.md`) — full defense-in-depth rationale, 6-layer model
-- `docs/guides/user-guide.md` §6.1 — same decision tree in user-doc form
-- `bag wallet policy show --json` — machine-readable current state
-- SDK source `@bnbagent/sdk` (signing policy module) — `SigningPolicy.strictDefault()` + `.extend()` semantics
+
+- the SigningPolicy decision (`docs/design/decisions.md`) - full defense-in-depth rationale, 6-layer model
+- `docs/guides/user-guide.md` §6.1 - same decision tree in user-doc form
+- `bag wallet policy show --json` - machine-readable current state
+- SDK source `@bnbagent/sdk` (signing policy module) - `SigningPolicy.strictDefault()` + `.extend()` semantics
 
 ## Hard rules (security boundary)
 
 - Never bypass the policy with `_DANGEROUS_*` calls in agent code. They exist for tests and incident response.
 - Never instruct the user to widen caps / allowlists "to make it work" without explaining the security tradeoff.
-- Persist the wallet password only in the generated, gitignored, owner-only
-  `.studio/.env.local` for local use or a managed secret channel for deploys;
-  never put it in argv, application code, logs, or chat.
+- Persist the wallet password only in the generated, gitignored, owner-only `.studio/.env.local` for local use or a managed secret channel for deploys; never put it in argv, application code, logs, or chat.
 - Never persist signed payloads outside the keystore.
 - Always run `bag wallet policy show` after editing `[wallet.signing]` to confirm the change took effect.
-- Always restart the process — SigningPolicy is captured at wallet construction.
+- Always restart the process - SigningPolicy is captured at wallet construction.