BlockRunAI · VickyXAI · Jul 26, 2026 · Jul 26, 2026
diff --git a/README.md b/README.md
@@ -201,7 +201,7 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 
 **Who it's for:** Developers who don't want to manage 7 different provider accounts and API keys. Pay per request with USDC, one wallet covers everything.
 
-**18 tools included:**
+**<!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools included:**
 
 | Tool | What it does |
 |------|-------------|
@@ -214,10 +214,11 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 | `blockrun_search` | Live web and news search (Grok-grounded) |
 | `blockrun_exa` | Neural semantic search + grounded answers |
 | `blockrun_markets` | Polymarket, Kalshi, sports markets |
+| `blockrun_polymarket` | Place real USDC-settled Polymarket orders (CLOB V2 on Polygon) — discover markets with `blockrun_markets` first |
 | `blockrun_surf` | 84 crypto data endpoints (CEX, on-chain SQL, social, wallet labels) |
 | `blockrun_price` | Pyth quotes: crypto, FX, commodities, stocks |
 | `blockrun_dex` | Live DEX prices and liquidity via DexScreener (free) |
-| `blockrun_rpc` | Raw JSON-RPC on 40+ chains — Ethereum, Base, Solana, Bitcoin, Sui, NEAR (Tatum gateway) |
+| `blockrun_rpc` | Raw JSON-RPC on <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains — Ethereum, Base, Solana, Bitcoin, Sui, NEAR (Tatum gateway) |
 | `blockrun_defi` | DefiLlama — protocol TVL, chain TVL, yield pools (APY), token prices |
 | `blockrun_modal` | Sandboxed code execution — disposable container, optional GPU |
 | `blockrun_phone` | AI voice calls + wallet-owned US/CA numbers |

diff --git a/docs/api-reference/multi-chain-rpc.md b/docs/api-reference/multi-chain-rpc.md
@@ -1,17 +1,17 @@
 ---
 title: Multi-chain RPC
-description: Standard JSON-RPC 2.0 access to 40+ blockchains through one endpoint, paid $0.004 per call in USDC over x402 — no account, no API key, no monthly plan.
+description: Standard JSON-RPC 2.0 access to every supported blockchain through one endpoint, paid $0.004 per call in USDC over x402 — no account, no API key, no monthly plan.
 ---
 
-# Multi-chain RPC — one endpoint, 40+ chains
+# Multi-chain RPC — one endpoint, every chain
 
-Standard JSON-RPC 2.0 access to 40+ blockchains through a single endpoint. No account, no API key, no monthly plan — pay **$0.004 per call** in USDC over x402. Built for AI agents that read on-chain data across many chains from one wallet.
+Standard JSON-RPC 2.0 access to <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> blockchains through a single endpoint. No account, no API key, no monthly plan — pay **$0.004 per call** in USDC over x402. Built for AI agents that read on-chain data across many chains from one wallet.
 
 BlockRun proxies upstream RPC gateways with x402 settlement, so an agent can query any supported chain without onboarding to a node provider.
 
 ## The problem it solves
 
-Traditional RPC providers (Alchemy, Infura, QuickNode) make you sign up, manage an API key, and pick a monthly plan with rate-limit tiers — **per chain**. An agent that needs Ethereum *and* Base *and* Solana *and* Polygon ends up with four accounts and four keys. BlockRun gives you one endpoint for 40+ chains, paid per call, with on-chain settlement receipts.
+Traditional RPC providers (Alchemy, Infura, QuickNode) make you sign up, manage an API key, and pick a monthly plan with rate-limit tiers — **per chain**. An agent that needs Ethereum *and* Base *and* Solana *and* Polygon ends up with four accounts and four keys. BlockRun gives you one endpoint for <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains, paid per call, with on-chain settlement receipts.
 
 ## Endpoint
 

diff --git a/docs/api-reference/prediction-markets.md b/docs/api-reference/prediction-markets.md
@@ -395,7 +395,7 @@ Feed market and wallet data into an LLM to analyze odds and positioning.
 :::
 
 :::card{title="Multi-chain RPC" href="multi-chain-rpc.md" icon="Route"}
-Read on-chain data across 40+ chains to complement wallet identity lookups.
+Read on-chain data across <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains to complement wallet identity lookups.
 :::
 
 :::card{title="Error handling" href="errors.md" icon="Code"}

diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -16,7 +16,7 @@ A terminal, and ~$5 of USDC on **Base** (or Solana). Don't have USDC yet? Any Co
 ::::tabs
 
 :::tab{label="Claude Code (MCP)"}
-Best for Claude Code, Cursor, and other MCP clients — natural-language access to all 18 tools.
+Best for Claude Code, Cursor, and other MCP clients — natural-language access to all <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools.
 
 ```bash
 claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest

diff --git a/docs/mcp/blockrun-mcp.md b/docs/mcp/blockrun-mcp.md
@@ -96,7 +96,7 @@ Then send USDC (SPL) on the **Solana** network — from Coinbase (pick "Solana")
 
 ## Available Tools
 
-The MCP exposes 18 tools to Claude:
+The MCP exposes <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools to Claude:
 
 ### `blockrun_chat`
 

diff --git a/docs/mcp/skills.md b/docs/mcp/skills.md
@@ -179,7 +179,7 @@ Generate images via micropayments with the bundled skill.
 :::
 
 :::card{title="BlockRun MCP" href="blockrun-mcp.md" icon="Boxes"}
-The MCP server and the 18 tools skills build on.
+The MCP server and the <!-- br:mcp.tools -->19<!-- /br:mcp.tools --> tools skills build on.
 :::
 
 :::card{title="Troubleshooting" href="troubleshooting.md" icon="Search"}

diff --git a/docs/products/intelligence/overview.md b/docs/products/intelligence/overview.md
@@ -101,7 +101,7 @@ The 5% covers:
 **No subscriptions. No minimums. No prepaid credits.**
 
 :::tip{title="Cut costs automatically"}
-Don't want to pick models by hand? [ClawRouter](../routing/clawrouter.md) routes each request to the cheapest model that can handle it — up to 78% lower cost.
+Don't want to pick models by hand? [ClawRouter](../routing/clawrouter.md) routes each request to the cheapest model that can handle it — <!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% lower cost than pinning one flagship for every request.
 :::
 
 ## Quick Start

diff --git a/docs/products/routing/clawrouter.md b/docs/products/routing/clawrouter.md
@@ -1,11 +1,11 @@
 ---
 title: ClawRouter
-description: ClawRouter is a smart LLM router for OpenClaw that picks the optimal model per prompt — up to 78% lower cost with no API keys.
+description: ClawRouter is a smart LLM router for OpenClaw that picks the optimal model per prompt — materially lower cost with no API keys.
 ---
 
 # ClawRouter
 
-**Save 78% on LLM costs. Automatically.**
+**<!-- br:savings.autoVsBaselinePct -->87<!-- /br:savings.autoVsBaselinePct -->% cheaper than pinning one flagship for every request — <!-- br:savings.ecoVsBaselinePct -->98<!-- /br:savings.ecoVsBaselinePct -->% on `eco`. Automatically.**
 
 ClawRouter is a smart LLM router for OpenClaw that routes every request to the cheapest model that can handle it. One wallet, 64 models, zero API keys.
 

diff --git a/docs/resources/ecosystem.md b/docs/resources/ecosystem.md
@@ -33,7 +33,7 @@ Projects, integrations, and partners building with BlockRun and x402.
 | **Search** | `/v1/search` | $0.025/source | ✅ Live |
 | **Exa Web Search** | `/api/v1/exa/*` | $0.002–0.012 | ✅ Live |
 | **0x Swap (DEX)** | `/api/v1/zerox/*` | Free | ✅ Live |
-| **Multi-chain RPC** | `/api/v1/rpc/{network}` (40+ chains) | $0.004/call | ✅ Live |
+| **Multi-chain RPC** | `/api/v1/rpc/{network}` (<!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains) | $0.004/call | ✅ Live |
 | **Prediction Markets** | `/v1/pm/*` | $0.0095 | ✅ Live |
 | **Trading Markets** | `/api/v1/markets/*` | $0.003 | ✅ Live |
 | **Modal Sandbox** | `/v1/modal/*` | $0.003–0.012 | ✅ Live |

diff --git a/docs/sdks/python.md b/docs/sdks/python.md
@@ -344,7 +344,7 @@ catalog = surf.endpoints()                                     # static: every p
 
 Tiers: T1 `$0.0095` (reads/lists), T2 `$0.0095` (AI rankings/trends/search), T3 `$0.0095` (heavy LLM + on-chain SQL). Use `surf.get(path, params)` / `surf.post(path, body)` for explicit verbs.
 
-#### `RpcClient` — multi-chain JSON-RPC (40+ chains)
+#### `RpcClient` — multi-chain JSON-RPC
 
 ```python
 from blockrun_llm import RpcClient

diff --git a/docs/x402/endpoints.md b/docs/x402/endpoints.md
@@ -136,7 +136,7 @@ Real-time and historical prices. All `list` endpoints are free. **Crypto, FX, an
 
 ## Blockchain RPC (Tatum)
 
-Standard JSON-RPC 2.0 to 40+ chains through one endpoint — no API key. EVM (`eth_*`) and non-EVM methods. See [Multi-chain RPC](../api-reference/multi-chain-rpc.md).
+Standard JSON-RPC 2.0 to <!-- br:chains.rpc -->40<!-- /br:chains.rpc --> chains through one endpoint — no API key. EVM (`eth_*`) and non-EVM methods. See [Multi-chain RPC](../api-reference/multi-chain-rpc.md).
 
 | Method | Path | Purpose | Pricing |
 |---|---|---|---|

diff --git a/scripts/sync-brand-numbers.mjs b/scripts/sync-brand-numbers.mjs
@@ -19,7 +19,7 @@
  * and wrap the WHOLE token, so a badge URL, its alt text and the prose number
  * can all regenerate from one key.
  */
-import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { join, relative, extname } from "node:path";
 
 const ROOT = process.cwd();
@@ -43,7 +43,10 @@ const SKIP_DIRS = new Set([
   "node_modules", ".git", "dist", "build", "out", ".next", "coverage",
   "vendor", "target", "__pycache__", ".venv", "venv",
 ]);
-const TEXT_EXT = new Set([".md", ".mdx"]);
+// .txt is here for llms.txt, which is a first-class marketing surface: it is
+// what agents read to find out what BlockRun serves. Scanning other .txt files
+// costs a read and changes nothing — only files with markers are ever written.
+const TEXT_EXT = new Set([".md", ".mdx", ".txt"]);
 
 /* ── 1. numbers ──────────────────────────────────────────────────────────── */
 
@@ -194,9 +197,20 @@ function* walk(dir) {
   for (const name of readdirSync(dir)) {
     if (SKIP_DIRS.has(name)) continue;
     const p = join(dir, name);
-    const s = statSync(p);
-    if (s.isDirectory()) yield* walk(p);
-    else if (TEXT_EXT.has(extname(name))) yield p;
+    // lstat, not stat: a symlinked directory is reached by its real path or not
+    // at all. blockrun's docs/ -> awesome-blockrun/docs is exactly the case that
+    // matters — following it would edit a submodule's files behind the skip
+    // below, and a link pointing at an ancestor would recurse forever.
+    const s = lstatSync(p);
+    if (s.isSymbolicLink()) continue;
+    if (s.isDirectory()) {
+      // A nested repo is a submodule or vendored checkout: it carries its own
+      // brand-numbers.json and syncs itself. Rewriting its markers from THIS
+      // repo's snapshot would dirty a submodule nobody asked us to touch, and
+      // would report drift that belongs to another repo's CI.
+      if (existsSync(join(p, ".git"))) continue;
+      yield* walk(p);
+    } else if (TEXT_EXT.has(extname(name))) yield p;
   }
 }