Improve Agent Focus and some misc docs cleanup

SUMMARY.md

@@ -115,7 +115,9 @@
 * [Introduction](obol-stack/README.md)
 * [Quickstart](obol-stack/quickstart.md)
 * [Build a Profitable Obol Stack](obol-stack/build-a-profitable-stack.md)
+* [Agents & Skills](obol-stack/agents-and-skills.md)
 * [Selling Agent Services](obol-stack/selling-services.md)
+* [Buying Services](obol-stack/buying-services.md)
 * [Set up a Permanent URL](obol-stack/permanent-url.md)
 * [Installing Networks](obol-stack/installing-networks.md)
 * [Installing Apps](obol-stack/installing-apps.md)

obol-stack/README.md

@@ -128,7 +128,9 @@ Running full Ethereum nodes requires significant disk space. Mainnet execution c
 
 - [Quickstart](quickstart.md) — install the stack, talk to your agent, and run `obol sell demo`.
 - [Build a profitable Obol Stack](build-a-profitable-stack.md) — end-to-end: bounded archive node → index → paid service → specialized agent → listed on marketplaces.
+- [Agents & Skills](agents-and-skills.md) — create specialised sub-agents and see the embedded skill set they ship with.
 - [Selling agent services](selling-services.md) — full orientation on the three `sell` shapes, x402 economics, ERC-8004 registration, and Telegram notifications.
+- [Buying services](buying-services.md) — rent remote models with `obol buy inference`, or pay any x402 endpoint from your agent.
 - [Installing Networks](installing-networks.md) — sync Ethereum / Aztec, including bounded archives via `--since`.
 
 ## Need assistance?

obol-stack/agents-and-skills.md

@@ -0,0 +1,100 @@
+---
+description: Create specialised sub-agents, manage their wallets, and understand the skills your agents ship with
+---
+
+# Agents & Skills
+
+## The default agent
+
+`obol stack up` creates a default **Hermes** agent in the `hermes-obol-agent` namespace, with its own Ethereum signing wallet (backed by an in-cluster remote signer — the agent never touches raw private keys) and a full embedded skill set. Talk to it with `obol hermes chat`, get its API bearer token with `obol agent auth`.
+
+{% hint style="warning" %}
+Back up the agent's wallet before you put anything on it. Losing the keystore loses the agent's on-chain identity and funds.
+
+```shell
+obol agent wallet backup -o ~/obol-wallet-backup.json --passphrase "..."
+```
+
+Store the backup **outside** `~/.config/obol/` — `obol stack purge -f` deletes that directory.
+{% endhint %}
+
+## Creating sub-agents
+
+Additional agents are where the Stack gets interesting: each one is a separate, long-lived specialist with its own namespace, state, skills, and (optionally) its own wallet.
+
+```shell
+obol agent new research \
+  --model qwen3.5:9b \
+  --skills ethereum-networks,buy-x402,indexing \
+  --objective "Research onchain data and sell reports. Cite the block number your data came from." \
+  --create-wallet
+```
+
+* `--objective` becomes the agent's identity — spend real effort on it: scope, output format, refusal policy, tone. One sharp paragraph beats a page of vibes.
+* `--skills` should be **narrow**. A specialist selling on-chain analysis doesn't need generalist skills; a tight list keeps a smaller model focused and makes the agent's edge legible to buyers.
+* `--create-wallet` gives the sub-agent its own wallet. Skip it if the agent doesn't need to hold or sign funds — payments for its services can go to your main agent's wallet instead.
+
+Manage the fleet:
+
+```shell
+obol agent list                    # all agents
+obol agent auth research           # bearer token for a specific agent
+obol agent sync                    # re-render agent deployments after config changes
+obol agent delete research         # remove one
+```
+
+An agent created this way can be put on sale in one command — `obol sell agent research --price 0.05 --token USDC --chain base` — turning it into an OpenAI-compatible paid endpoint. See [Selling Agent Services](selling-services.md).
+
+{% hint style="info" %}
+OpenClaw remains supported as an alternate runtime: `obol agent new --runtime openclaw`, then `obol openclaw dashboard`.
+{% endhint %}
+
+## Embedded skills
+
+Every agent ships with Obol's embedded skills — self-contained playbooks (instructions + scripts) the agent loads on demand. The default set gives your agent working knowledge of the commerce loop, Ethereum, and its own cluster:
+
+### Commerce & agents
+
+| Skill | What the agent can do with it |
+| ----- | ----------------------------- |
+| `sub-agent-business` | Design, evaluate, price, and sell specialised sub-agents people pay per turn — the business playbook |
+| `agent-factory` | Spawn durable child agents with their own namespace, wallet, skills, and paid endpoint |
+| `sell` | Create and manage payment-gated ServiceOffers, track reconciliation, register on ERC-8004 |
+| `monetize-guide` | Guided end-to-end walkthrough for selling inference or an HTTP API |
+| `buy-x402` | Buy from any x402 endpoint — probe pricing, pre-sign payments, auto-refill, check balances |
+| `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, with quotes and slippage guards |
+| `autoresearch` / `autoresearch-coordinator` / `autoresearch-worker` | Run, coordinate, or sell GPU time for autonomous LLM optimization experiments |
+
+### Ethereum
+
+| Skill | What the agent can do with it |
+| ----- | ----------------------------- |
+| `ethereum-networks` | Read-only chain queries via the local RPC gateway — blocks, balances, contract reads, ERC-20, ENS |
+| `ethereum-local-wallet` | Sign and send transactions via the per-agent remote signer |
+| `addresses` | Verified contract addresses — payment rails first, then DeFi, tokens, bridges, registries |
+| `building-blocks` | DeFi protocol composability — Uniswap, Aave, Aerodrome, Pendle |
+| `concepts` | The onchain mental model — state machines, incentives, why nothing is automatic |
+| `gas` | Real transaction costs today, mainnet vs L2 |
+| `indexing` | Reading historical onchain data at scale — The Graph, Dune, Ponder, event-first design |
+| `l2s` | The L2 landscape — which chain for which job |
+| `standards` | ERC-8004, x402, EIP-3009, EIP-7702, ERC-4337 |
+| `wallets` | Wallet architecture and key safety for AI agents |
+| `why` | Why Ethereum for agents — the ERC-8004 + x402 loop |
+
+### Operations
+
+| Skill | What the agent can do with it |
+| ----- | ----------------------------- |
+| `obol-stack` | Kubernetes diagnostics from inside the cluster — pods, logs, events |
+| `distributed-validators` | Obol DVT cluster monitoring via the Obol API |
+
+The list evolves — ask your agent, or run:
+
+```shell
+obol hermes skills list            # live catalogue (default agent)
+obol hermes skills add <package>   # add a skill
+obol hermes skills remove <name>   # remove one
+```
+
+Custom skills are just directories with a `SKILL.md` — drop your own curated data and playbooks into an agent's skills directory to give it an edge nobody else has. That curation is exactly what makes a sub-agent worth paying for: see [Build a Profitable Obol Stack](build-a-profitable-stack.md).

obol-stack/build-a-profitable-stack.md

@@ -67,7 +67,7 @@ obol sell http my-index \
     --per-request 0.001 \
     --chain base \
     --token USDC \
-    --wallet 0x...your-wallet...
+    --pay-to 0x...your-wallet...
 ```
 
 Confirm it reconciles to `Ready`:
@@ -124,10 +124,7 @@ Confirm it's live with `obol tunnel status`. For the full dashboard walkthrough
 Register your agent on [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) so buyers can find it:
 
 ```shell
-obol sell register \
-    --chain mainnet \
-    --name my-quant \
-    --private-key-file ~/.config/obol/agents/my-quant/wallet.json
+obol sell register --chain mainnet --name my-quant
 ```
 
 Registration writes to the on-chain Identity Registry. From there, multiple marketplaces and explorers index your offer:

obol-stack/buying-services.md

@@ -0,0 +1,67 @@
+---
+description: Rent a remote model with obol buy inference, or pay any x402 endpoint straight from your agent
+---
+
+# Buying Services
+
+The Obol Stack closes the commerce loop from both sides. Selling is covered in [Selling Agent Services](selling-services.md); this page is the buy side — how to spend from your agent's wallet on other people's services.
+
+There are two distinct buy paths. Don't conflate them:
+
+* **Buying inference is renting a brain.** You have no local Ollama, no provider API key, or you want a hosted model you don't otherwise have access to. What you get back is tokens.
+* **Buying from an agent is renting specialised work.** You pay another agent per turn for a task — analysis, monitoring, drafting — not per token for completions. Drive this from `obol hermes chat`; your agent's embedded `buy-x402` skill handles the probe-pay-consume loop.
+
+## Rent a model: `obol buy inference`
+
+```shell
+obol buy inference https://seller.example/
+```
+
+Point it at any Obol Stack storefront URL (or omit the URL to use the default storefront). The command:
+
+1. Walks the seller's `/api/services.json` catalog and resolves the model and payment token from the offer.
+2. Prompts you through the purchase on a TTY: auto-top-up yes/no → how many requests, with a cost preview → final confirmation.
+3. Pre-signs payment authorizations via your agent's remote signer and creates a `PurchaseRequest`.
+4. Publishes the model as `paid/<remote-model>` through your cluster's LiteLLM.
+
+After that, the remote model is just another model in your roster. Your agent (or any OpenAI-compatible client pointed at LiteLLM) can call it, and the in-cluster `x402-buyer` sidecar spends exactly one pre-signed authorization per request — **your maximum loss is bounded by what you pre-authorized**, and your agent never touches raw keys.
+
+### Useful flags
+
+```shell
+obol buy inference https://seller.example/ --agent research   # pay from agent `research`'s wallet
+                                                              # and switch only that agent to the paid model
+obol buy inference https://seller.example/ --set-default      # promote the paid model globally, sync every agent
+```
+
+| Flag | What it does |
+| ---- | ------------ |
+| `--model <id>` | Pick a model when the seller offers several on one URL |
+| `--count <N>` / `--budget <amt>` | Size the purchase non-interactively (CI / scripts) |
+| `--auto-refill` | Let the agent top up the budget when it runs low (`--refill-threshold`, `--refill-count`) |
+| `--cost-cap <price>` | Refuse refills if the seller raises the per-request price above this ceiling |
+| `--expected-agent-id <id>` | Opt-in ERC-8004 identity check of the seller (skipped by default) |
+
+{% hint style="info" %}
+Call paid models with `"stream": true`. Responses buffered longer than ~100 seconds get dropped by Cloudflare quick tunnels on the seller side — streaming keeps the wire warm.
+{% endhint %}
+
+## Pay any x402 endpoint from your agent
+
+Your agent ships with the `buy-x402` skill, which can probe and pay arbitrary x402-gated endpoints — one-shot HTTP calls, paid agent turns, or batch pre-authorizations. Just ask it in `obol hermes chat`:
+
+> "Probe https://seller.example/services/quant and tell me what it costs. If it's under 0.05 USDC per request, pay for one analysis of ETH gas trends."
+
+The skill checks pricing from the `402 Payment Required` response before spending, supports USDC (EIP-3009) and OBOL (Permit2), and tracks balances — ask your agent for `balance` any time.
+
+## Prefer a cloud provider instead?
+
+If you just want a good model and don't need the crypto rails, bring your own key:
+
+```shell
+obol model setup                                        # interactive picker (defaults to OpenRouter + free models)
+obol model setup --provider anthropic --api-key sk-ant-...
+obol model setup custom --endpoint http://192.168.1.20:8000/v1 --model my-model   # any OpenAI-compatible endpoint
+```
+
+`obol buy inference` and `obol model setup` end in the same place — a model your agents can use — they just differ in who you pay and how.

obol-stack/faq.md

@@ -161,13 +161,21 @@ USDC and other tokens settle on the rail their issuer supports (EIP-3009 for USD
 ### How do I list my service on a public agent registry?
 
 ```shell
-obol sell register --chain mainnet --name my-service --private-key-file <path>
+obol sell register --chain mainnet --name my-service
 ```
 
 This publishes the agent's wallet + service catalog to the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry on the chain you specify. Note that this requires ETH on the registering wallet for gas.
 
 `obol sell demo` deliberately skips registration by default — run `obol sell register` later when you want on-chain discovery.
 
+### How do I buy inference from another stack?
+
+```shell
+obol buy inference https://seller.example/
+```
+
+The command walks the seller's catalog, previews the cost, pre-signs payment authorizations from your agent's wallet, and publishes the remote model as `paid/<model>` through your LiteLLM — your agents can then use it like any local model, with spend bounded by what you pre-authorized. See [Buying Services](buying-services.md).
+
 ## Stack operations
 
 ### The cluster fails to start

obol-stack/quickstart.md

@@ -29,7 +29,7 @@ If you'd rather route through Anthropic or OpenAI, you can configure that with `
 Run the bootstrap installer:
 
 ```shell
-bash <(curl -s https://stack.obol.org)
+bash <(curl -fsSL https://stack.obol.org)
 ```
 
 The installer will:
@@ -42,7 +42,7 @@ The installer will:
 {% tabs %}
 {% tab title="Default installation" %}
 ```shell
-bash <(curl -s https://stack.obol.org)
+bash <(curl -fsSL https://stack.obol.org)
 ```
 
 Files are installed to:
@@ -54,7 +54,7 @@ Files are installed to:
 
 {% tab title="Specific version" %}
 ```shell
-OBOL_RELEASE=v0.9.0 bash <(curl -s https://stack.obol.org)
+OBOL_RELEASE=v0.9.0 bash <(curl -fsSL https://stack.obol.org)
 ```
 {% endtab %}
 
@@ -137,9 +137,12 @@ Once you've watched a demo settle end-to-end, the same machinery lets you sell a
 ```shell
 obol sell inference my-model --model qwen3.5:9b --per-mtok 0.01 --token USDC --chain base
 obol sell http my-api --upstream my-svc --port 8080 --namespace my-ns \
-  --per-request 0.001 --chain base --wallet <your-wallet>
+  --per-request 0.001 --chain base --pay-to <your-wallet>
+obol sell agent my-analyst --price 0.05 --token USDC --chain base
 ```
 
+`sell agent` is the highest-margin shape — buyers pay for a whole specialised agent's replies (skills + memory + curated data), not just raw tokens. See [Agents & Skills](agents-and-skills.md) for building one worth paying for.
+
 The mental model is: **anything in your cluster that exposes a Service can be wrapped in a `ServiceOffer` and gated behind x402**. The goal of v0.9 is to make that loop short enough that you can actually iterate on what's worth selling.
 
 See [Selling agent services](selling-services.md) for the full orientation on the three `sell` shapes (`http`, `inference`, `agent`), x402 economics, ERC-8004 registration, and marketplaces.
@@ -155,7 +158,7 @@ Sellers receive `$OBOL` directly into their agent wallet. Read more about the [O
 `obol sell demo` skips on-chain registration by default (to avoid double-register reverts and the need for ETH on the agent wallet). When you're ready to be discoverable on a public agent registry:
 
 ```shell
-obol sell register --chain mainnet --name my-service --private-key-file <path>
+obol sell register --chain mainnet --name my-service
 ```
 
 This publishes the agent's wallet + service catalog to the [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Identity Registry on the chain you specify.
@@ -215,6 +218,8 @@ obol stack purge -f               # remove everything, including data
 
 * [Build a profitable Obol Stack](build-a-profitable-stack.md) — the end-to-end narrative: sync a bounded archive node, build an index, wrap it as a paid service, and turn it into a specialized agent business.
 * [Selling agent services](selling-services.md) — depth on the three `sell` shapes, x402 economics, and getting listed on marketplaces.
+* [Buying services](buying-services.md) — rent a remote model with `obol buy inference`, or pay any x402 endpoint from your agent.
+* [Agents & Skills](agents-and-skills.md) — create specialised sub-agents and see everything your agent can already do.
 * [Installing Networks](installing-networks.md) — sync local Ethereum / Aztec nodes (including bounded archives via `--since`).
 * [Installing Apps](installing-apps.md) — deploy any Helm chart.
 * [FAQ](faq.md) — common questions and troubleshooting.

obol-stack/selling-services.md

@@ -53,7 +53,7 @@ obol sell http my-index \
     --per-request 0.001 \
     --chain base \
     --token USDC \
-    --wallet 0x...your-wallet...
+    --pay-to 0x...your-wallet...
 ```
 
 This is the path to take when **the value is in the data**: you've synced an archive node from a specific block, built an index on top, and you want to sell access to queries against it that no public RPC will serve.
@@ -111,10 +111,7 @@ When quoting prices, name the unit explicitly — `0.01 OBOL / MTok`, `0.001 USD
 Buyers need to find you. The Obol Stack publishes an [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent registration document at `/.well-known/agent-registration.json` describing your services, supported payment methods, and endpoints. To list your agent on a public registry:
 
 ```shell
-obol sell register \
-    --chain mainnet \
-    --name my-quant \
-    --private-key-file ~/.config/obol/agents/my-quant/wallet.json
+obol sell register --chain mainnet --name my-quant
 ```
 
 This publishes your agent's wallet and service catalog to the ERC-8004 Identity Registry on the chain you specify. **Note that this requires ETH on the registering wallet for gas** — registration is not gas-sponsored.
@@ -131,6 +128,19 @@ Once registered, several marketplaces and explorers index ERC-8004 registries an
 
 We do not recommend a single "official" marketplace — the agent-registry ecosystem is evolving fast, and the best strategy is to register on-chain and let multiple indexers pick you up.
 
+### Brand your storefront
+
+Your tunnel hostname serves a public storefront landing page and a machine-readable catalog at `/api/services.json` (plus `/skill.md` for agent buyers). Make it look like a business, not a default install:
+
+```shell
+obol sell info                     # buyer's-eye view: branding + every on-sale service
+obol sell info my-quant            # focus one service + how-to-buy
+obol sell info set --display-name "Acme Labs" --tagline "Paid onchain analysis." --logo-url "https://…"
+obol sell info reset               # back to defaults
+```
+
+`obol sell info` shows exactly what buyers see — only operationally-ready offers appear. Operator-side health and conditions (including draining or not-ready offers) stay under `obol sell status`. After any change, run `sell info` and ask yourself: *would I buy from this storefront?*
+
 ## Iterating on an agent business
 
 Selling the same agent forever at the same quality is leaving money on the table. The loop that compounds:
@@ -156,6 +166,19 @@ obol sell delete my-quant --namespace my-ns
 
 Deletion removes the ServiceOffer CR, cascades the underlying Middleware and HTTPRoute via owner references, and deactivates the ERC-8004 registration (sets `active=false`). The agent's wallet and accumulated revenue are untouched.
 
+### Surviving restarts
+
+Offers are persisted and replayed automatically: `obol stack up` re-publishes every offer after a reboot. To replay on demand — or to make it happen with nobody at the keyboard:
+
+```shell
+obol sell resume                        # replay all persisted offers now
+obol sell resume --install-boot-unit    # Linux: install a systemd user unit that does it on boot
+```
+
+### Bonus shape: paid MCP tools
+
+`obol sell mcp [name]` runs a foreground x402-paid MCP server that forwards buyer JSON arguments to a backend HTTP service, injecting **your** API key server-side — the buyer pays per call and never sees the key. Useful for reselling metered access to an upstream API as an MCP tool. It's foreground-only: no ServiceOffer, and it is not replayed by `sell resume`.
+
 ## Verifying your paths
 
 When you've shipped your first real (non-demo) offer, walk these checks: