ObolNetwork · OisinKyne · Jul 6, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -472,7 +472,7 @@ The Cloudflare tunnel exposes the cluster to the public internet. Only x402-gate
 | `internal/enclave` | `enclave.go`, `enclave_darwin.go`, `enclave_stub.go` | Secure Enclave keys |
 | `internal/embed` | `embed.go` | Embedded assets (skills, infrastructure, networks) |
 
-**Embedded assets**: `internal/embed/infrastructure/` (K8s templates), `internal/embed/networks/` (ethereum, aztec), `internal/embed/skills/` (21 skills).
+**Embedded assets**: `internal/embed/infrastructure/` (K8s templates), `internal/embed/networks/` (ethereum, aztec), `internal/embed/skills/` (23 skills).
 
 **Tests**: `cmd/obol/sell_test.go` (CLI flags), `internal/x402/*_test.go` (verifier, config, matcher, E2E), `internal/erc8004/*_test.go` (ABI, client), `internal/embed/embed_crd_test.go` (CRD+RBAC validation), `internal/openclaw/integration_test.go` (full-cluster inference), `internal/openclaw/overlay_test.go`, `internal/inference/gateway_test.go`, `internal/serviceoffercontroller/*_test.go` (controller, render).
 

diff --git a/README.md b/README.md
@@ -212,43 +212,43 @@ Use `obol agent` for Obol-managed lifecycle and auth flows. Use `obol hermes` fo
 
 The stack ships with embedded Obol skills installed automatically for the default Hermes agent and OpenClaw instances. Skills give agents domain-specific capabilities — from querying blockchains to buying and selling services.
 
-#### Infrastructure & Commerce
+#### Commerce & Agents
 
 | Skill | Purpose |
 |-------|---------|
+| `sub-agent-business` | The business playbook — design, evaluate, price, and sell specialised sub-agents people pay per turn |
+| `agent-factory` | Spawn durable child agents with their own namespace, wallet, skills, and paid endpoint |
+| `sell` | ServiceOffer CRUD — payment-gated routes, reconciliation status, ERC-8004 registration |
+| `monetize-guide` | Guided end-to-end walkthrough for selling inference or an HTTP API |
 | `buy-x402` | Buy paid services: probe pricing, pre-sign payments, auto-refill, check balances |
-| `monetize` | Manage the agent's own sell offers (ServiceOffer CRUD) |
-| `ethereum-networks` | Read-only Ethereum queries via cast — blocks, balances, contract reads, ERC-20, ENS |
-| `ethereum-local-wallet` | Sign and send Ethereum transactions via the per-agent remote-signer |
-| `obol-stack` | Kubernetes cluster diagnostics — pods, logs, events, deployments |
-| `distributed-validators` | Obol DVT cluster monitoring, operator audit, exit coordination |
+| `discovery` | Find agents registered on the ERC-8004 Identity Registry across chains |
+| `swap` | Treasury moves — swap USDC/ETH/OBOL on Base and mainnet via Uniswap V3 |
+| `autoresearch` | Run autonomous LLM optimization experiments and publish the best checkpoints |
+| `autoresearch-coordinator` | Coordinate distributed experiments across GPU workers, discovered via ERC-8004 and paid via x402 |
+| `autoresearch-worker` | Sell your GPU as a paid experiment worker |
 
-#### Ethereum Development
+#### Ethereum
 
 | Skill | Purpose |
 |-------|---------|
-| `addresses` | Verified contract addresses — DeFi, tokens, bridges, ERC-8004 registries across chains |
-| `building-blocks` | OpenZeppelin patterns, DEX integration, oracle usage, access control |
-| `concepts` | Mental model — state machines, incentive design, gas mechanics, EOAs vs contracts |
-| `gas` | Gas optimization patterns, L2 fee structures, estimation |
-| `indexing` | The Graph, Dune, event indexing for onchain data |
-| `l2s` | L2 comparison — Base, Arbitrum, Optimism, zkSync with gas costs and use cases |
-| `orchestration` | End-to-end dApp build (Scaffold-ETH 2) + AI agent commerce cycle |
-| `security` | Smart contract vulnerability patterns, reentrancy, flash loans, MEV protection |
+| `ethereum-networks` | Read-only Ethereum queries via cast — blocks, balances, contract reads, ERC-20, ENS |
+| `ethereum-local-wallet` | Sign and send Ethereum transactions via the per-agent remote-signer |
+| `addresses` | Verified contract addresses — payment rails, DeFi, tokens, bridges, ERC-8004 registries |
+| `building-blocks` | DeFi legos and protocol composability — Uniswap, Aave, Aerodrome, Pendle |
+| `concepts` | Mental model — state machines, incentive design, why nothing onchain is automatic |
+| `gas` | Real transaction costs today, mainnet vs L2, fee settings |
+| `indexing` | The Graph, Dune, Ponder, event-first design for onchain data at scale |
+| `l2s` | L2 comparison — Base, Arbitrum, Optimism, zkSync with costs and use cases |
 | `standards` | ERC-8004, x402, EIP-3009, EIP-7702, ERC-4337 — spec details and integration patterns |
-| `ship` | Architecture planning — onchain vs offchain, chain selection, agent service patterns |
-| `testing` | Foundry testing — unit, fuzz, fork, invariant tests |
-| `tools` | Development tooling — Foundry, Hardhat, Scaffold-ETH 2, verification |
 | `wallets` | Wallet management — EOAs, Safe multisig, EIP-7702, key safety for AI agents |
+| `why` | Why Ethereum — the AI agent angle with ERC-8004 and x402 |
 
-#### Frontend & QA
+#### Operations
 
 | Skill | Purpose |
 |-------|---------|
-| `frontend-playbook` | Deployment — IPFS, Vercel, ENS subdomains |
-| `frontend-ux` | Web3 UX patterns — wallet connection, transaction flows, error handling |
-| `qa` | Quality assurance — testing strategy, coverage, CI/CD patterns |
-| `why` | Why Ethereum — the AI agent angle with ERC-8004 and x402 |
+| `obol-stack` | Kubernetes cluster diagnostics — pods, logs, events, deployments |
+| `distributed-validators` | Obol DVT cluster monitoring, operator audit, exit coordination |
 
 Manage skills at runtime:
 

diff --git a/internal/embed/embed_skills_test.go b/internal/embed/embed_skills_test.go
@@ -19,7 +19,8 @@ func TestGetEmbeddedSkillNames(t *testing.T) {
 	coreSkills := []string{
 		"addresses", "agent-factory", "building-blocks", "buy-x402", "concepts", "discovery",
 		"distributed-validators", "ethereum-networks", "ethereum-local-wallet",
-		"gas", "indexing", "l2s", "sell", "obol-stack", "standards", "wallets", "why",
+		"gas", "indexing", "l2s", "sell", "obol-stack", "standards", "sub-agent-business",
+		"swap", "wallets", "why",
 	}
 
 	sort.Strings(names)

diff --git a/internal/embed/skills/addresses/SKILL.md b/internal/embed/skills/addresses/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: addresses
-description: Verified contract addresses for major Ethereum protocols across mainnet and L2s. Use this instead of guessing. SKILL.md is an index — load the appropriate references/*.md file for the addresses you need. Categories include stablecoins, staking + Obol/Splits, DEXs, lending and DeFi, L2-native protocols, infrastructure (Safe, AA, Chainlink, EigenLayer, ENS, OpenSea), bridges (CCIP, Across), agents (ERC-8004), and major token addresses. Always verify on-chain via eth_getCode + eth_call before sending value.
+description: Verified contract addresses for major Ethereum protocols across mainnet and L2s. Use this instead of guessing. SKILL.md is an index — load the appropriate references/*.md file for the addresses you need. Start with references/obol-payments.md for the Stack's own rails (USDC + OBOL + Permit2 + ERC-8004 on the supported chains). Other categories include stablecoins, staking + Obol/Splits, DEXs, lending and DeFi, L2-native protocols, infrastructure (Safe, AA, Chainlink, EigenLayer, ENS, OpenSea), bridges (CCIP, Across), and major token addresses. Always verify on-chain via eth_getCode + eth_call before sending value.
 ---
 
 # Contract Addresses
@@ -19,6 +19,7 @@ Open the file that matches the category you need:
 
 | Reference | What's in it |
 |-----------|--------------|
+| [`references/obol-payments.md`](references/obol-payments.md) | **Start here for anything payment-related** — USDC + OBOL on the chains the Stack supports, Permit2, ERC-8004 registries, facilitator |
 | [`references/stablecoins.md`](references/stablecoins.md) | USDC, USDT, DAI, WETH on mainnet + L2s |
 | [`references/staking.md`](references/staking.md) | Lido (stETH, wstETH, withdrawals), Rocket Pool, Obol Splits, Splits.org |
 | [`references/dex.md`](references/dex.md) | Uniswap V2/V3/V4, Universal Router, Permit2, 1inch, UNI token |

diff --git a/internal/embed/skills/addresses/references/obol-payments.md b/internal/embed/skills/addresses/references/obol-payments.md
@@ -0,0 +1,58 @@
+# Obol Stack payment rails
+
+The addresses the Stack's own commerce loop runs on. **Check here first** —
+these are the chains and tokens `sell`, `buy-x402`, and `agent-factory`
+actually support, and they are canonical in the Stack's source
+(`internal/x402/tokens.go` / `chains.go`).
+
+**Last verified on-chain (`eth_getCode`): 2026-07-06.**
+
+## Payment tokens
+
+### USDC (6 decimals, EIP-3009 `transferWithAuthorization` — gasless x402 transfers)
+
+| Chain | Address | Notes |
+|-------|---------|-------|
+| Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | Primary "cheap real money" rail |
+| Base Sepolia | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` | Dev/testing only — label it as such |
+| Ethereum mainnet | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | |
+| Polygon | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | |
+| Arbitrum One | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | |
+| Avalanche | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` | |
+
+(Testnets registered in the Stack: Polygon Amoy
+`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`, Avalanche Fuji
+`0x5425890298aed601595a70AB815c96711a31Bc65`, Arbitrum Sepolia
+`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`.)
+
+### OBOL (18 decimals, Permit2 + EIP-2612)
+
+| Chain | Address |
+|-------|---------|
+| Ethereum mainnet | `0x0B010000b7624eb9B3DfBC279673C76E9D29D5F7` |
+| Base Sepolia | `0x0a09371a8b011d5110656ceBCc70603e53FD2c78` |
+
+OBOL's headline property: the Obol-operated facilitator
+(`https://x402.gcp.obol.tech`) batches the EIP-2612 `permit()` with the
+transfer at settlement — **buyers pay zero gas** and skip the one-time
+`approve(Permit2, max)` step.
+
+## Infrastructure
+
+| Contract | Address | Chains |
+|----------|---------|--------|
+| Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` | Same on every EVM chain (CREATE2) |
+| ERC-8004 IdentityRegistry | `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432` | Mainnet, Base, Arbitrum, Optimism (CREATE2) |
+| ERC-8004 ReputationRegistry | `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63` | Mainnet, Base (CREATE2) |
+| ERC-8004 IdentityRegistry (testnets) | `0x8004A818BFB912233c491871b3d84c89A494BD9e` | Base Sepolia, Sepolia |
+
+## Which rail for what
+
+- **Selling**: quote OBOL on Ethereum mainnet (gasless buyers) and/or USDC
+  on Base (cheapest real-money settlement). Use Base Sepolia only for dev
+  smoke tests.
+- **Chain names** as the Stack's tooling expects them: `ethereum` (alias
+  `mainnet`), `base`, `base-sepolia`, `polygon`, `arbitrum-one`,
+  `avalanche` — plus CAIP-2 forms (`eip155:8453` = Base).
+- **Native vs bridged**: all USDC addresses above are native Circle
+  deployments, not bridged variants.
diff --git a/internal/embed/skills/agent-factory/SKILL.md b/internal/embed/skills/agent-factory/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: agent-factory
-description: "Spawn durable child Hermes agents from inside Obol Stack. Creates child namespaces, optional profile/env Secrets, Agent CRDs, and optional ServiceOffers for x402-paid child services."
+description: "Spawn durable child Hermes agents from inside Obol Stack. Creates child namespaces, optional profile/env Secrets, Agent CRDs, and optional ServiceOffers for x402-paid child services. Use when the user says 'spawn an agent', 'create a sub-agent', 'child agent', or wants a separate long-lived service agent. For deciding WHAT agent to build, whether it's good enough to sell, and how to price it, load sub-agent-business first."
 metadata: { "openclaw": { "requires": { "bins": ["python3"] } } }
 ---
 

diff --git a/internal/embed/skills/monetize-guide/SKILL.md b/internal/embed/skills/monetize-guide/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: monetize-guide
-description: "End-to-end guide for monetizing GPU resources or HTTP services through obol-stack. Covers pre-flight checks, model detection, pricing research, selling via x402, ERC-8004 registration, and verification. Use this skill when the user wants to monetize their machine."
+description: "End-to-end guide for monetizing GPU resources or HTTP services through obol-stack. Covers pre-flight checks, model detection, pricing research, selling via x402, ERC-8004 registration, and verification. Use when the user says 'monetize my machine', 'sell my GPU', or 'expose a paid API' — i.e. selling raw inference or a plain HTTP service. For selling a specialised agent's replies (the higher-margin path), use sub-agent-business instead."
 metadata: { "openclaw": { "emoji": "🚀", "requires": { "bins": ["python3"] } } }
 ---
 

diff --git a/internal/embed/skills/sell/SKILL.md b/internal/embed/skills/sell/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: sell
-description: "Sell access to services via x402 payment gating. Create ServiceOffer CRDs that automatically health-check upstreams, create payment-gated routes, and optionally pull models and register on ERC-8004. Supports inference, HTTP, and fine-tuning service types."
+description: "Sell access to services via x402 payment gating. Create ServiceOffer CRDs that automatically health-check upstreams, create payment-gated routes, and optionally pull models and register on ERC-8004. Supports inference, HTTP, and fine-tuning service types. Use for ServiceOffer plumbing: listing offers, checking/waiting on reconciliation status, creating or deleting offers. For the guided end-to-end walkthrough use monetize-guide; for selling a child agent's turns use sub-agent-business + agent-factory."
 metadata: { "openclaw": { "emoji": "\ud83d\udcb0", "requires": { "bins": ["python3"] } } }
 ---