@bnbagent/studio-cli 0.0.6-alpha.1

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

@@ -0,0 +1,222 @@
+---
+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.
+---
+
+> **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.
+
+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.
+
+> **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.
+
+## 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.
+
+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)
+- Wallet has ≥ 0.05 tBNB (gas) and ≥ 0.2 U (token + slack). On BSC testnet the
+  ERC-8183 kernel writes (`createJob` / `fund` deposit / `settle` …) are
+  gas-sponsored via the SDK's MegaFuel paymaster, 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.)
+- 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
+
+## Stage 1 — Pre-flight checks
+
+```bash
+# 1. Confirm wallet + balances
+bag wallet show
+bag doctor       # tBNB + U checks should be PASS
+
+# 2. Confirm the provider's 8004 record (optional but recommended)
+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.
+
+## 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.
+
+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.
+
+## Stage 3 — Buy
+
+```bash
+bag erc8183 buy --provider <provider_addr> "<task description>" \
+  --budget-u <amount>           \  # capped by policy.budget_cap_u
+  --deadline-min <minutes>      \  # default 30; this is the seller's submission window
+  --network bsc-testnet
+# provider is a REQUIRED flag (--provider <addr> OR --agent-id <id>), not a positional;
+# `--agent-id` resolves the endpoint + negotiates first.
+```
+
+> **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
+
+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).
+
+## 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:
+
+```bash
+bag erc8183 status <job_id>
+```
+
+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`
+
+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
+
+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": {...}}`.
+
+## Stage 6 — Settle
+
+```bash
+# Happy path: accept the deliverable. NOTE: must wait 24h dispute_window first.
+bag erc8183 settle <job_id> --action approve
+
+# Bad deliverable: dispute (within dispute_window, no wait needed)
+bag erc8183 settle <job_id> --action dispute
+
+# (rare) you're a quorum voter and want to reject:
+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.
+
+## 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()`).
+
+## End-to-end smoke (one-shot, for testing your setup)
+
+```bash
+# Buyer side (this assumes the seller's A2A agent is already deployed somewhere)
+PROVIDER=<seller_address>
+JOB=$(bag erc8183 buy --provider $PROVIDER "test task" --budget-u 0.5 | awk -F': *' '/job_id:/{print $2; exit}')
+# send a `notify_funded` A2A message to the seller for that JOB (buyer-push),
+# then poll the chain (the seller acks at once and delivers in the background):
+sleep 60
+bag erc8183 status $JOB
+bag erc8183 settle $JOB --action dispute
+```
+
+This is the exact end-to-end flow used to validate real-chain buying. See the
+references below for the canonical picture.
+
+## Reference
+
+- `docs/design/erc8183-reference.md` (SDK surface map / negotiation envelope)
+- `docs/design/single-seller-agent.md` + `docs/design/erc8183-buyer-push.md` (the v1 single-agent model + buyer-push flow)
+- `docs/guides/verification.md` (manual on-chain verification)

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

@@ -0,0 +1,227 @@
+---
+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.
+---
+
+> **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.
+
+> **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/`.
+
+**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)
+
+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".
+
+## Mental model (defense in depth)
+
+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) |
+
+Everything else (`Permit`, `PermitSingle`, `PermitBatch`, foreign contracts, foreign chains, custom primary types) is **refused with `PolicyViolation`** at sign-time.
+
+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 |
+
+**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 |
+
+## 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):**
+
+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.
+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.
+
+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.
+
+**Steps when (1)–(3) all pass:**
+
+```bash
+# 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"]'
+
+# 2. Add the EIP-712 domain to wallet.signing (additive)
+#    bag config does not yet handle nested array-of-arrays elegantly; edit the
+#    toml directly with this snippet (targets app/agent/studio.toml only):
+cat >> app/agent/studio.toml <<'EOF'
+
+[wallet.signing]
+extra_domains = [
+  [56, "0xAbcdef0123456789abcdef0123456789abcdef01"],   # api.example.com token on mainnet
+  [97, "0x1234567890abcdef1234567890abcdef12345678"],   # same on testnet
+]
+EOF
+
+# 3. Verify the policy reflects both allowlists
+bag wallet policy show
+# expect 3 entries in domain_allowlist: U mainnet, U testnet, your new contract
+
+# 4. Restart the agent process for the new policy to take effect.
+#    SigningPolicy is read at wallet construction; running `bag dev` again
+#    is enough.
+```
+
+**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.
+
+## B. Custom typed-data primary type
+
+If the new service or contract requires the wallet to sign a non-standard primary type (e.g. `"MyOrder"`, `"BondQuote"`, `"NegotiateAgreement"`), edit `<workspace>/app/agent/studio.toml`:
+
+```toml
+# app/agent/studio.toml
+[wallet.signing]
+extra_domains = [
+  [56, "0xContractAddress..."],
+]
+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).
+
+**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.
+
+## C. Diagnosing PolicyViolation / X402PolicyError at runtime
+
+User reports an error from `bag dev` / agent runtime. Map the message → fix:
+
+```
+PolicyViolation: unknown (chain_id, verifyingContract): (56, 0xAbc...)
+  → L3 SigningPolicy rejection
+  → 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
+
+PolicyViolation: primary type 'MyOrder' not in allowlist
+  → Section B: add to extra_primary_types
+
+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)
+  → 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.
+```
+
+Confirm the current state before editing:
+
+```bash
+bag wallet policy show                       # L3 SigningPolicy (reads app/agent/studio.toml)
+bag config get payments.x402                 # L2 allowed_hosts + caps (auto-resolves app/agent/)
+```
+
+## D. Refuse: Permit / Permit2 unbounded allowance
+
+If the user (or, more dangerously, the LLM) asks the agent to sign `Permit`, `PermitSingle`, or `PermitBatch`:
+
+**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`.
+
+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.
+
+## E. Widening the validity window
+
+Default: 600s past / 900s future. Longer windows give the agent more time to settle but increase replay surface if a signature leaks. Edit `<workspace>/app/agent/studio.toml`:
+
+```toml
+# app/agent/studio.toml
+[wallet.signing]
+max_validity_window_seconds = 1800   # default 600
+max_future_validity_seconds = 2400   # default 900
+```
+
+Use sparingly. A signed authorization that lives 30 minutes can be replayed by a downstream tx executor for 30 minutes. Make sure the receiving contract enforces nonces (EIP-3009 does; many custom types don't).
+
+## 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. |
+| "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. |
+
+## G. After-edit verification (always run)
+
+```bash
+# 1. The toml is parseable (auto-resolves app/agent/; or --project-root app/agent)
+bag config show
+
+# 2. The new policy looks right (extra entries should be visible)
+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
+#    agent) or the AgentCore runtime. SigningPolicy is read once at
+#    wallet construction; in-process changes won't take effect until restart.
+
+# 4. Sanity-check one signing call (if there's a CLI path)
+#    e.g. bag llm test, bag erc8183 status, etc.
+```
+
+## 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
+
+## 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.
+- Never persist the wallet password or signed payloads anywhere 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.

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

@@ -0,0 +1,211 @@
+---
+name: bnbagent-studio-operating
+description: When the user wants to run, debug, diagnose, or operate a bnbagent-studio agent project. Covers dev server, doctor checks, balance/RPC queries, job status reads, and incident triage — including the delegated deploy lifecycle (`bag deploy status` / `logs` / `verify` / `destroy`), twak-wallet issues, and `PolicyViolation` / `X402PolicyError` signing-policy errors (deep-dive playbooks for those ship as references of the `bnbagent-studio` router skill; read them on demand).
+---
+
+> **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-operating
+
+Procedure for **day-to-day operation** of an existing bnbagent-studio project.
+Audience: Claude Code in a v0.0.1 workspace (thin root with the `agentcore/`
+config dir + the workspace-root `.studio/wallets/` + funded wallet, plus the
+single sub-project `app/agent/` holding `studio.toml` + `src/main.ts` /
+`src/sellerCore.ts` / `src/executor.ts` / `src/agentCard.ts` /
+`src/signing.ts`). Most commands run from the workspace root; the v0.0.1
+project-root fallback locates the `app/agent/` sub-project automatically for
+wallet/LLM/budget ops.
+
+**Different from**:
+- `bnbagent-studio-scaffolding-agent.md` (in this same references/ directory) — creates a brand new project
+- `bnbagent-studio-selling-via-8183.md` (in this same references/ directory) — seller flow (`runWork` value, rule-based quote pricing, dispute defense)
+- `funding-pieverse-llm` (project-scope skill, Pieverse projects only) — Pieverse credit lifecycle / topup decisions
+
+**Deep-dive references** — plain markdown files in this SAME references/
+directory (Claude Code: `~/.claude/skills/bnbagent-studio/references/`; Cursor:
+`bnbagent-studio/references/` beside the `.mdc` rules). READ
+the file when the topic comes up — don't answer from memory:
+- `bnbagent-studio-use-aws-agentcore.md` — the delegated AgentCore lifecycle (`bag deploy --provider aws` / `status` / `logs` / `verify` / `destroy`, `provision-cognito`) + AWS prerequisites
+- `bnbagent-studio-use-bnb-trial.md` — GitHub device login, 48h eligibility, staging verification, and the delegated BNB trial lifecycle
+- `bnbagent-studio-use-azure-foundry.md` — the delegated Azure Foundry lifecycle (`bag deploy --provider azure`; no `az`/`azd` CLI)
+- `bnbagent-studio-using-twak-wallet.md` — `[wallet].kind = "twak"` create / fund / SIWE-bind / container deploy / limitations
+- `bnbagent-studio-extending-signing.md` — `PolicyViolation` / `X402PolicyError` diagnosis + extending the EIP-712 allowlist
+- `bnbagent-studio-adding-to-project.md` — adding the seller runtime to an existing TypeScript project
+- `bnbagent-studio-buying-via-8183.md` — buyer flow (find provider → buy → fetch → settle)
+
+This playbook covers **generic ops**: dev / doctor / balances / RPC / incident triage.
+For seller job-lifecycle decisions (settle / submit / dispute defense), read
+`bnbagent-studio-selling-via-8183.md` (same directory); for the buyer side, read the buying reference.
+
+## Quick triage decision tree
+
+| User said... | Run first |
+|---|---|
+| "is it healthy?" / "doctor" | `bag doctor` (scans the `app/agent/` sub-project from the workspace root) |
+| "run locally" / "start it" / "dev" | `bag dev` (serves the selected protocol: A2A on `:9000`, MCP on `:8000/mcp` — same for any destination) |
+| "what's my balance?" / "how much U?" | `bag wallet balance` (native + U; `--network X` / `--all` available. `--address X` is **v0.2 backlog — not in v0.0.x**) |
+| "send X tBNB / U to another address" | ⚠️ **v0.2 backlog — `bag wallet transfer` does not exist in v0.0.x.** No transfer CLI yet; move funds with an external wallet |
+| "approve commerce contract to spend U" | ⚠️ **v0.2 backlog — `bag erc20` group does not exist in v0.0.x** (funding flows auto-approve U; no manual approve CLI) |
+| "how much have I approved 0x... for?" | ⚠️ **v0.2 backlog — `bag erc20 allowance` does not exist in v0.0.x** |
+| "is my agent registered?" | `bag erc8004 show` (note: registration is normally automatic at `bag deploy verify` — manual `bag erc8004 register` only if you need an identity before deploy) |
+| "what's the status of job X?" | `bag erc8183 status <id>` (read-only — neutral) |
+| "settle job X" | `bag erc8183 settle <id> --action approve\|reject\|dispute` (default `approve`) — **seller's manual step** after the dispute window; deeper context in `bnbagent-studio-selling-via-8183.md` (same directory) |
+| "submit work for job X" | **seller action** — read `bnbagent-studio-selling-via-8183.md` (same directory) for the submit/dispute flow |
+| "tx not confirming" | Read BscScan link from prior tx output + check `eth_getTransactionCount` |
+| "wallet balance is wrong" | Check both tBNB (gas) and U (token); see balance section |
+| "is it deployed?" / "deploy status" | `bag deploy status` lists every locally recorded BNB/AWS/Azure deployment and asks `bnbagent-deploy` for live state; add `--no-probe` for record-only output |
+| "deploy logs" / "verify" / "tear it down" | With one recorded deployment, `bag deploy {logs,verify,destroy}` selects it automatically. With multiple, choose interactively or pass `--provider bnb\|aws\|azure` in automation. Cloud calls always go through `bnbagent-deploy`. `bag platform credit` shows the BNB trial countdown. |
+
+## Common ops procedures
+
+### A. Run the agent locally (the default)
+
+```bash
+# Configure secrets (idempotent — does NOT duplicate existing keys).
+# These write into .studio/.env.local (the Agent's secrets):
+bag env set WALLET_PASSWORD <your password>
+bag env set OPENROUTER_API_KEY <your key>   # or whichever provider app/agent/studio.toml [llm] uses
+
+# From the workspace root — `bag dev` serves the selected protocol:
+bag dev                # A2A agent on :9000, MCP on :8000/mcp (same for any destination)
+bag dev --port 9100    # override the port
+```
+
+`bag dev` sets `STORAGE_LOCAL_PATH=~/.bag/deliverables/<workspace-name>/` for the
+agent subprocess and runs it **without** Cognito env, so the local endpoint is
+reachable without a token (Cognito is mandatory only on the deployed AgentCore
+runtime). For A2A projects, the agent
+(`app/agent/src/main.ts`) exposes `/.well-known/agent-card.json` +
+JSON-RPC `message/send` + `GET /ping` on `:9000`. Smoke-test the card with curl:
+
+```bash
+curl http://localhost:9000/.well-known/agent-card.json
+```
+
+Expect the agent card with its two skills (`negotiate`, `notify_funded`).
+For MCP projects, connect an MCP client to `http://localhost:8000/mcp`.
+
+> ⚠️ **The AgentCore inspector chat box cannot test a seller agent.** A seller's
+> skills are structured A2A `DataPart`s (`message/send`), but the inspector chat
+> box can only send plain text — it can never construct a `{"skill":"negotiate", …}`
+> part, so it can't reach the agent's real product surface (and its streaming view
+> expects Task events, not the `message` reply the agent emits). **Test locally
+> with curl or an A2A client sending a `DataPart`**, not the chat box.
+
+Drive a sale by sending the skills directly (`negotiate` `terms` MUST include
+`deliverables` + `quality_standards`, else the quote is rejected `reason_code 0x04`):
+
+```bash
+# negotiate → signed quote envelope
+curl -s -X POST http://localhost:9000/ -H "Content-Type: application/json" -d '{
+  "jsonrpc":"2.0","id":1,"method":"message/send",
+  "params":{"message":{"role":"user","parts":[{"kind":"data","data":{
+    "skill":"negotiate",
+    "task_description":"...",
+    "terms":{"deliverables":"...","quality_standards":"..."}
+  }}],"messageId":"nego-1"}}}'
+
+# notify_funded → ack (then background delivery; poll the chain for the result)
+curl -s -X POST http://localhost:9000/ -H "Content-Type: application/json" -d '{
+  "jsonrpc":"2.0","id":2,"method":"message/send",
+  "params":{"message":{"role":"user","parts":[{"kind":"data","data":{
+    "skill":"notify_funded","job_id":<int>
+  }}],"messageId":"notify-1"}}}'
+```
+
+See `erc8183-buyer-push.md` for the full line protocol. Ctrl-C to stop.
+
+### B. Doctor — full project health
+
+```bash
+bag doctor
+```
+
+Returns a rich table of checks across the `app/agent/` sub-project:
+
+| Check | What FAIL means | Fix |
+|---|---|---|
+| app/agent/studio.toml parseable | Missing or syntax error | `bag init` to regenerate, or hand-fix TOML |
+| Agent entrypoint imports | Protocol entrypoint raises on load (`src/main.ts` for A2A, `src/mcpMain.ts` for MCP) | Fix the error printed by the check (often a missing env var or a broken import) |
+| wallet keystore | No `<workspace>/.studio/wallets/*.json` | `bag wallet new` (writes to the workspace root keystore dir) |
+| WALLET_PASSWORD env | Not in `.studio/.env.local` / not exported | `bag env set WALLET_PASSWORD ...` (targets .studio/.env.local) |
+| LLM provider key | API key env not set | Edit `.studio/.env.local` or export the right `*_API_KEY` |
+| Network reachable | RPC down/wrong URL | Override via `STUDIO_BSC_TESTNET_RPC=...` (testnet) / `STUDIO_BSC_RPC=...` (mainnet) — per-network env vars read by `@bnbagent/studio-runtime/networks` `getNetwork` |
+| Wallet tBNB balance | 0 tBNB | Faucet: testnet.bnbchain.org/faucet-smart |
+| Wallet U balance | 0 U | Transfer from holder, or ask for sponsor U |
+| 8004 registered | Not registered | Normally registered automatically at `bag deploy verify`. Manual: `bag erc8004 register --endpoint <url>` (only if you need an on-chain identity before deploy). WARN-only in `bag doctor` — it doesn't block local dev. |
+| Cognito authorizer (W9) | External-buyer readiness: `agentcore.json` carries no `authorizerConfiguration` / protocol metadata has placeholder `OAUTH_*` values | WARN-only (does NOT block) — needed to serve **external** buyers, not to deploy. With no authorizer the runtime is IAM/SigV4 owner-only (never anonymous). To open it to buyers: `bag deploy provision-cognito` → `cdk deploy --outputs-file cdk-outputs.json` → `bag deploy provision-cognito --wire`. |
+
+WARN-only items don't block; FAIL items do (exit 1).
+
+### C. Balance / wallet inspection
+
+```bash
+bag wallet show     # local view: address + keystore path (workspace root .studio/wallets/)
+bag wallet list     # all keystores in <workspace>/.studio/wallets/
+```
+
+For on-chain balance of the configured wallet (BNB + U):
+
+```bash
+bag wallet balance                       # [network].default — BNB + U
+bag wallet balance --network bsc-mainnet # override to a specific network
+bag wallet balance --all                 # both [network].default AND [llm.pieverse].network
+```
+
+The `--all` form is the right move when `app/agent/studio.toml`'s
+`[network].default = bsc-testnet` and `[llm].provider = pieverse-llm`:
+testnet U pays ERC-8183 jobs, mainnet U pays the Pieverse LLM auto-renew.
+Same wallet address on both chains.
+
+> ⚠️ **v0.2 backlog — not in v0.0.x.** There is **no** `bag wallet transfer`,
+> no `bag erc20 approve/allowance` group, and no `bag wallet balance --address`
+> / `--token` flag in v0.0.x — running any of them errors with
+> `invalid choice` / `unrecognized arguments`. To move funds or set allowances
+> today, use an external wallet; ERC-8183 funding auto-approves U as part of the
+> buy flow. These CLIs are planned for v0.2.
+
+For programmatic access from inside an agent's code, the MCP tools (when wired
+into Claude Code) provide `balance_u` / `balance_native` as well — but the CLI
+is the fastest path during dev.
+
+### D. Job state inspection (8183)
+
+```bash
+bag erc8183 list --mine                    # all jobs where I'm the client
+bag erc8183 list --provider 0xPROV         # jobs I could serve as seller
+bag erc8183 status <job_id>                # one job's full record
+```
+
+JobStatus enum: `OPEN` (0) → `FUNDED` (1) → `SUBMITTED` (2) → `COMPLETED` (3) /
+`REJECTED` (4) / `EXPIRED` (5).
+
+`FUNDED` jobs are what the deployed agent delivers — either when the buyer sends a
+`notify_funded` A2A message (the agent acks then delivers in the **background**;
+read the result from the chain) or via the deduped background sweep on the next
+notify (see `erc8183-buyer-push.md`). While background work is in flight the
+runtime stays warm via `/ping` `HEALTHY_BUSY`; a scaled-to-zero idle agent won't
+deliver until the next notify (a v2 Lambda poller closes that cold window).
+`SUBMITTED` jobs trigger the **buyer decision
+tree** (approve / dispute / reject within the dispute window) — full flow in the
+`bnbagent-studio-buying-via-8183.md` reference (see the Deep-dive references
+list above). From the seller side, defending a dispute is
+covered in `bnbagent-studio-selling-via-8183.md` (same directory).
+
+### E. Common errors + remediation
+
+| Error pattern | Cause | Fix |
+|---|---|---|
+| `Submission deadline has passed` | Buyer set `expiredAt` too soon (< dispute_window) | Use `--deadline-min` ≥ 1 (workflow auto-adds dispute_window now) |
+| `Transaction would revert: ('0x17be5b7b', ...)` | Trying to `settle approve` before dispute_window | Wait 24h or use `--action dispute` |
+| `notify_funded` replies `{"status":"rejected","reason":...}` | `verifySignedJob` failed synchronously in the ack — a **permanent** failure | `reason` names it: not our signature / tampered terms / underfunded / expired (or `error` for a malformed `job_id`). The job is refused outright; re-fund/re-notify with a correct, fully-funded job |
+| Job stays `FUNDED`, never reaches `SUBMITTED` after an `accepted` ack | Background delivery failed (`runWork` / `submitResult` raised) — **not** visible in the A2A reply | The ack only confirms verify passed; delivery runs in the background. Observe the failure via the chain (job never leaves `FUNDED`) + CloudWatch logs; a later `notify_funded` re-attempts it via the sweep |
+| `ERC8183JobOps` has no such export from `@bnbagent/sdk` | package.json pinned an old `@bnbagent/sdk` (missing class) | Bump the dependency and reinstall |
+| `OPENROUTER_API_KEY env var is required` | Loading the entrypoint triggers the emitted `buildModel()` factory | Set the env var even for `bag dev --help` smoke |
+| RPC `limit exceeded` | Public RPC throttle | Retry, or set `STUDIO_BSC_TESTNET_RPC=<private rpc>` |
+
+## Reference
+
+- `docs/design/single-seller-agent.md` (the A2A deploy model and history)
+- `docs/design/erc8183-buyer-push.md` (how a buyer drives an A2A sale)
+- `docs/design/architecture.md §2.5` (the single seller runtime — as-built truth)