@blockrun/franklin 3.18.0 → 3.20.0

package/dist/agent/context.js

@@ -296,6 +296,22 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
 - \`/v1/pm/{...path}\` — prediction-market data passthrough.
 
+**Surf — crypto data + chat (x402-paid)** via the generic \`BlockRun\` capability. ~55 curated endpoints. Tier-1 $0.001, Tier-2 $0.005, Tier-3 / chat $0.02.
+- \`/v1/surf/exchange/*\` — CEX trading pairs, prices, perps, depth, klines, funding history, long/short ratio.
+- \`/v1/surf/market/*\` — token rankings, fear/greed, futures, ETF flows, options skew, liquidations, on-chain indicators (NUPL/SOPR/MVRV), price indicators (RSI/MACD/BBANDS).
+- \`/v1/surf/news/{feed,detail}\` — AI-curated crypto news.
+- \`/v1/surf/onchain/{bridge,yield,gas-price,tx,schema,query,sql}\` — bridge/yield rankings, gas, tx detail, **raw SQL against 80+ indexed chain tables (Tier-3, $0.02)**, structured chain query, schema introspection.
+- \`/v1/surf/token/{tokenomics,dex-trades,holders,transfers}\` — token analytics.
+- \`/v1/surf/wallet/{detail,history,net-worth,transfers,protocols,labels/batch}\` — wallet intelligence + batch labels (CEX/Whale/Bridge/MEV).
+- \`/v1/surf/social/*\` — KOL/CT mindshare, smart-follower history, tweets, user profiles. The canonical source for crypto-Twitter signal.
+- \`/v1/surf/fund/{detail,portfolio,ranking}\` — VC fund profiles, portfolios, ranking.
+- \`/v1/surf/project/{detail,defi/metrics,defi/ranking}\` — project profiles + DeFi protocol metrics.
+- \`/v1/surf/chat/completions\` — surf-1.5 chat model with first-class citations (\`citation: ["source","chart"]\`). \$0.02/call flat.
+
+For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`, \`/surf-chat\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`).
+
+**Generic gateway primitive**: \`BlockRun({ path, method, params, body })\` is a single capability that signs x402 and forwards to ANY path under \`/api\`. Use it for Surf endpoints (above) and any future BlockRun partner that doesn't have a dedicated capability yet. Always specify the exact path; the primitive will not guess.
+
 **Endpoints that DO NOT exist** (common hallucinations — do NOT call):
 - \`/v1/image/generate\` (singular — use \`/v1/images/generations\`)
 - \`/v1/spending\` (no such route — derive from on-chain history if needed)

package/dist/skills-bundled/surf-chain/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: surf-chain
+description: On-chain analytics via Surf — raw SQL against 80+ indexed chain tables, structured queries, schema introspection, wallet labels (CEX/Whale/Bridge/MEV…), wallet net worth, transfers, DeFi positions, gas prices, bridge volumes, yield pools. Use when the user wants on-chain forensics, wallet intelligence, holder analysis, transfer tracking, or custom chain queries.
+triggers:
+  - "on-chain"
+  - "wallet analysis"
+  - "wallet detail"
+  - "wallet history"
+  - "wallet net worth"
+  - "token holders"
+  - "token transfers"
+  - "gas price"
+  - "bridge volume"
+  - "yield pool"
+  - "label wallet"
+  - "on-chain sql"
+  - "chain query"
+argument-hint: <address, hash, or question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. Use the `BlockRun` tool to call Surf's on-chain endpoints. The flagship capability here is **on-chain SQL** — write a query against 80+ indexed chain tables and get back a result set in sub-second.
+
+**Two different "chains" to keep straight:**
+1. **Payment chain** — where Franklin's wallet signs the x402 USDC payment. Currently `{{wallet_chain}}`. Surf only accepts settlement on **Base** (treasury `0x058a59…`). If the user is on Solana, ask them to `/chain base` before retrying.
+2. **Query chain** — the chain the data is *about*. Passed as a parameter to endpoints like `onchain/gas-price`, `onchain/tx`, `token/holders`, `token/transfers`. Valid values include `ethereum`, `base`, `arbitrum`, `polygon`, `optimism`, `bsc`. When the user doesn't specify and they're on `base`, default to `chain: "base"`. If they ask about Solana on-chain data, note that these EVM-shaped endpoints don't cover Solana — use a Solana-specific tool instead.
+
+## How to use
+
+`BlockRun({ path: "/v1/surf/<endpoint>", method: "<GET|POST>", params|body: { ... } })`. Method is GET unless the catalog says POST.
+
+## Endpoint catalog
+
+### Direct lookups (Tier 1, $0.001)
+| Path | Method | Required | What it returns |
+|---|---|---|---|
+| `/v1/surf/onchain/gas-price` | GET | `chain` | Current gas on the named chain |
+| `/v1/surf/onchain/tx` | GET | `hash`, `chain` | Tx details |
+| `/v1/surf/onchain/bridge/ranking` | GET | — | Bridge protocols ranked by volume |
+| `/v1/surf/onchain/yield/ranking` | GET | — | Yield pools (lending, LP, staking) |
+
+### Raw + structured chain query (Tier 3, $0.02 — premium)
+| Path | Method | Required | What it returns |
+|---|---|---|---|
+| `/v1/surf/onchain/schema` | GET | — | ClickHouse table schema introspection. **Always call this FIRST** before writing SQL so you know the tables, columns, and types. |
+| `/v1/surf/onchain/query` | POST | — (typed body) | Structured chain query with typed predicates. Safer than SQL when the question fits a fixed shape. |
+| `/v1/surf/onchain/sql` | POST | body: `{ query: string }` | Raw SQL against 80+ indexed tables. Sub-second. Use for novel questions that the typed query can't express. |
+
+### Token analytics (Tier 2, $0.005)
+| Path | Method | Required | What it returns |
+|---|---|---|---|
+| `/v1/surf/token/holders` | GET | `address`, `chain` | Top token holders with balances |
+| `/v1/surf/token/transfers` | GET | `address`, `chain` | Token transfer history |
+
+### Wallet intelligence (Tier 2, $0.005)
+| Path | Method | Required | What it returns |
+|---|---|---|---|
+| `/v1/surf/wallet/detail` | GET | `address` | Aggregated wallet profile across chains |
+| `/v1/surf/wallet/history` | GET | `address` | Transaction history |
+| `/v1/surf/wallet/net-worth` | GET | `address` | Net-worth time series |
+| `/v1/surf/wallet/transfers` | GET | `address` | Transfer history |
+| `/v1/surf/wallet/protocols` | GET | `address` | DeFi positions (Aave, Lido, Uniswap, etc.) |
+| `/v1/surf/wallet/labels/batch` | GET | `addresses` (comma-sep) | Batch label lookup: CEX, Whale, Bridge, MEV, Contract, etc. |
+
+## How to choose
+
+- **"What's gas on Base?"** → `onchain/gas-price` with `chain: "base"` ($0.001). One call, done.
+- **"Look up this tx"** → `onchain/tx` with `hash` + `chain`.
+- **"Who owns this token?"** → `token/holders` ($0.005). Pair with `wallet/labels/batch` on the top 20 to see which holders are CEXes vs whales.
+- **"Profile this wallet"** → `wallet/detail` first ($0.005). If they want depth, follow up with `wallet/history`, `wallet/net-worth`, `wallet/protocols`.
+- **"Is this address a CEX / whale / MEV bot?"** → `wallet/labels/batch` — cheapest forensic call.
+- **"Bridge volume this week"** → `onchain/bridge/ranking` ($0.001).
+- **"Best yield on USDC right now"** → `onchain/yield/ranking` ($0.001), filter for USDC.
+
+### On-chain SQL workflow
+
+For novel chain questions (e.g. "all addresses that received >100 ETH from Tornado in 2025"):
+
+1. **Schema first** — `BlockRun({ path: "/v1/surf/onchain/schema", method: "GET" })` ($0.02). Note the tables, columns, types.
+2. **Try structured query** — `BlockRun({ path: "/v1/surf/onchain/query", method: "POST", body: { /* typed predicates */ } })` ($0.02) when the shape fits.
+3. **Raw SQL fallback** — `BlockRun({ path: "/v1/surf/onchain/sql", method: "POST", body: { query: "SELECT …" } })` ($0.02) for anything else.
+4. **Validate** — if SQL fails parse or returns empty unexpectedly, fix the query and re-run. Each retry is $0.02 — be deliberate.
+
+## Cost discipline
+
+- Wallet/token reads are $0.005 each. If you need 5 lookups, expect $0.025.
+- Tier-3 chain queries are $0.02/call. Plan the schema → query → result loop before firing; don't fire speculative SQL.
+- Always include the cost in your summary back to the user.
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/surf-chat/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: surf-chat
+description: Crypto-native chat with citations via the surf-1.5 model. Different from a generic LLM call — surf-1.5 is grounded in live crypto data and returns first-class citations (source links + charts). Use when the user wants research-shaped answers about projects, tokens, market events, or DeFi protocols, with sources attached.
+triggers:
+  - "surf chat"
+  - "crypto research"
+  - "ask surf"
+  - "with citations"
+  - "grounded answer"
+argument-hint: <research question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. The `surf-1.5` model is crypto-native: it knows current market data, projects, on-chain flow, social signal, and returns structured citations. Reach for it when the user wants a sourced answer rather than a vibes-based one.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only. If the user's active chain is `solana`, ask them to `/chain base` before calling — surf-1.5 is $0.02/call, so a failed payment retry isn't free.
+
+## How to use
+
+Call:
+
+```
+BlockRun({
+  path: "/v1/surf/chat/completions",
+  method: "POST",
+  body: {
+    model: "surf-1.5",
+    messages: [
+      { role: "user", content: "<the question>" }
+    ],
+    citation: ["source", "chart"]
+  }
+})
+```
+
+Cost: **flat $0.02 per call** (per-token billing is Phase 2 upstream).
+
+### Response shape
+
+OpenAI-compatible, with two extras:
+- `choices[0].message.content` — the text answer
+- `choices[0].message.citations[]` — array of `{ type: "source" | "chart", url, title }`
+
+When you report back to the user, **always include the citations** as a footer:
+
+```
+[Answer text]
+
+Sources:
+1. <title> — <url>
+2. <title> — <url>
+```
+
+If `citations` is empty, mention that the answer is ungrounded.
+
+### Multi-turn
+
+Pass previous `messages` back in for follow-up turns. Each turn is $0.02.
+
+## When to use surf-chat vs the main agent loop
+
+- **Use surf-chat** when: the question is about market state, project research, narrative tracking, or "what happened to X in the last week" — anywhere fresh crypto context matters and you want citations to share with the user.
+- **Use the main agent loop** (no surf-chat) when: the question is general reasoning, coding, planning, summarization of content already in scope, or anything where adding citations doesn't add value.
+
+The wallet is funding the surf-chat call directly — be deliberate about reaching for it.
+
+## When to use surf-chat vs the data endpoints
+
+- **surf-chat** is good when you don't know which endpoints to compose, or when the answer is qualitative ("what's the bull case for $X?").
+- The **`/surf-market` / `/surf-chain` / `/surf-social` skills** are better when the question is structured ("price of BTC", "RSI on ETH", "wallet net worth") — they're $0.001–$0.005 each and you keep full control of the data.
+
+If you can answer with one $0.001 call to a data endpoint, do that. Only escalate to surf-chat when the question needs synthesis across many endpoints or the user explicitly asks for cited research.
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/surf-market/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: surf-market
+description: Crypto market data via Surf — prices, futures, ETFs, options, fear/greed, technical and on-chain indicators, token DEX flows, news, project profiles, VC fund holdings. Use when the user asks about market conditions, ranking tokens, futures positioning, technical signals, options skew, news context, or VC/fund intelligence.
+triggers:
+  - "market overview"
+  - "fear greed"
+  - "futures"
+  - "etf flow"
+  - "options skew"
+  - "tokenomics"
+  - "rsi"
+  - "macd"
+  - "liquidations"
+  - "vc fund"
+  - "token ranking"
+argument-hint: <symbol or question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. Crypto market data lives behind the `BlockRun` tool, which signs USDC x402 payments from the user's wallet on every call. Pick the cheapest endpoint that answers the question.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only (treasury is `0x058a59…` on Base). If the user's active chain is `solana` and you hit a payment error, tell them to switch with `/chain base` before retrying — the request itself works, the wallet just needs to be on Base to sign the payment.
+
+## How to use
+
+Call `BlockRun({ path: "/v1/surf/<endpoint>", method: "GET", params: { ... } })`. All endpoints below are GET unless noted. Required params must be supplied or you'll get a 400 (no charge).
+
+## Endpoint catalog
+
+### Exchange (CEX intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/exchange/markets` | $0.001 | — | Trading pairs catalog across major CEXes |
+| `/v1/surf/exchange/price` | $0.001 | `pair` | Ticker price for a pair |
+| `/v1/surf/exchange/perp` | $0.001 | `pair` | Perpetual contract snapshot |
+| `/v1/surf/exchange/depth` | $0.005 | `pair` | Order book depth |
+| `/v1/surf/exchange/klines` | $0.005 | `pair` | OHLCV candlesticks |
+| `/v1/surf/exchange/funding-history` | $0.005 | `pair` | Perp funding rate history |
+| `/v1/surf/exchange/long-short-ratio` | $0.005 | `pair` | Long/short positioning |
+
+### Market (broad-market intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/market/ranking` | $0.001 | — | Token ranking (market cap, volume, change) |
+| `/v1/surf/market/fear-greed` | $0.001 | — | Fear & Greed index history |
+| `/v1/surf/market/futures` | $0.001 | — | Futures market overview |
+| `/v1/surf/market/price` | $0.001 | `symbol` | Token price history |
+| `/v1/surf/market/etf` | $0.001 | `symbol` | Spot ETF flow history (BTC, ETH) |
+| `/v1/surf/market/options` | $0.001 | `symbol` | Options skew / IV / volume |
+| `/v1/surf/market/liquidation/exchange-list` | $0.005 | — | Liquidations by exchange |
+| `/v1/surf/market/liquidation/order` | $0.005 | — | Large liquidation orders |
+| `/v1/surf/market/liquidation/chart` | $0.005 | `symbol` | Liquidation chart over time |
+| `/v1/surf/market/onchain-indicator` | $0.005 | `symbol`, `metric` | NUPL, SOPR, MVRV, Puell, NVT |
+| `/v1/surf/market/price-indicator` | $0.005 | `indicator`, `symbol` | RSI, MACD, Bollinger, EMA |
+
+### News
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/news/feed` | $0.001 | — | AI-curated crypto news feed |
+| `/v1/surf/news/detail` | $0.001 | `id` | Full article by ID |
+
+### Project (DeFi protocols + project profiles)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/project/detail` | $0.001 | — | Aggregated project profile (token + DeFi + social) |
+| `/v1/surf/project/defi/metrics` | $0.001 | `metric` | Per-protocol DeFi metrics (TVL, fees, revenue) |
+| `/v1/surf/project/defi/ranking` | $0.001 | `metric` | DeFi protocol ranking |
+
+### Token (on-chain analytics)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/token/tokenomics` | $0.001 | — | Unlock schedule + vesting |
+| `/v1/surf/token/dex-trades` | $0.005 | `address` | DEX trade history |
+
+### Fund (VC + treasury intelligence)
+| Path | Tier | Required params | What it returns |
+|---|---|---|---|
+| `/v1/surf/fund/detail` | $0.001 | — | VC fund profile |
+| `/v1/surf/fund/portfolio` | $0.001 | — | VC fund portfolio holdings |
+| `/v1/surf/fund/ranking` | $0.001 | `metric` | Top VC funds ranking |
+
+## How to choose
+
+- **"How's the market?"** → `market/fear-greed` + `market/ranking` (both $0.001). Cheap snapshot.
+- **"What's BTC doing?"** → `market/price` for history, `exchange/price` for spot tick, `market/etf` for institutional flow.
+- **"Show me liquidations."** → `market/liquidation/chart` for time series, `market/liquidation/order` for whale events.
+- **"Technical signal on ETH"** → `market/price-indicator` with `indicator: "RSI"` (or MACD, BBANDS, EMA).
+- **"On-chain health"** → `market/onchain-indicator` with `metric: "NUPL"` etc.
+- **"Who holds this token / where is it traded?"** → `token/tokenomics` for supply schedule, `token/dex-trades` for flow.
+- **"What VCs back this project?"** → `fund/portfolio` (filter by project).
+
+## Cost discipline
+
+- Most read endpoints are Tier 1 ($0.001). Burn freely.
+- Tier 2 ($0.005) endpoints carry depth, history, or fraud-signal data — use when the cheaper endpoint can't answer.
+- Avoid speculative multi-endpoint scans. Pick the right endpoint for the question; if unsure, ask the user one clarifying question first.
+- Report the cost on every call in your summary: "Pulled fear/greed history ($0.001). Index sits at 62 (greed)."
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/surf-social/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: surf-social
+description: Crypto-Twitter / KOL intelligence via Surf — project mindshare time series, smart-follower history (high-signal accounts), social ranking, tweet + replies fetch, user profile / followers / posts / replies. Use when the user asks about KOL sentiment, project attention, smart money commentary, narrative momentum, or specific Twitter handles.
+triggers:
+  - "kol sentiment"
+  - "mindshare"
+  - "smart followers"
+  - "crypto twitter"
+  - "ct sentiment"
+  - "twitter analysis"
+  - "social ranking"
+  - "tweet"
+  - "twitter handle"
+argument-hint: <project, handle, or question>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. Use the `BlockRun` tool to call Surf's social endpoints. This is the canonical source for crypto-Twitter signal — mindshare scoring, KOL identification, and reply-graph analysis.
+
+**Chain note:** Surf currently settles x402 payments on **Base** only. If the user's active chain is `solana` and you hit a payment error, ask them to `/chain base` before retrying. The social data itself is chain-agnostic.
+
+## How to use
+
+`BlockRun({ path: "/v1/surf/<endpoint>", method: "GET", params: { ... } })`. All endpoints below are GET.
+
+## Endpoint catalog
+
+### Project-level signal (Tier 2, $0.005)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/detail` | — | Aggregated social analytics for a project |
+| `/v1/surf/social/ranking` | — | Mindshare ranking across projects |
+| `/v1/surf/social/smart-followers/history` | — | Smart-follower count history (high-signal accounts only) |
+| `/v1/surf/social/mindshare` | `q`, `interval` | Mindshare time series for a project (`q` = ticker or name, `interval` = `1d` / `7d` / `30d`) |
+
+### Tweet-level (Tier 1, $0.001)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/tweets` | `ids` (comma-sep) | Fetch tweets by ID |
+| `/v1/surf/social/tweet/replies` | `tweet_id` | Replies to a specific tweet |
+
+### User-level (Tier 1, $0.001)
+| Path | Required params | What it returns |
+|---|---|---|
+| `/v1/surf/social/user` | `handle` | Twitter user profile |
+| `/v1/surf/social/user/followers` | `handle` | Followers list |
+| `/v1/surf/social/user/following` | `handle` | Following list |
+| `/v1/surf/social/user/posts` | `handle` | User posts |
+| `/v1/surf/social/user/replies` | `handle` | User replies |
+
+## How to choose
+
+- **"What's the market saying about $X?"** → `social/mindshare` with `q: "X", interval: "7d"` ($0.005). Read the trend, not the absolute number.
+- **"Who's the smart money following $X?"** → `social/smart-followers/history` ($0.005). Compare growth rate to baseline.
+- **"Top projects by attention right now"** → `social/ranking` ($0.005).
+- **"Is @handle a real player?"** → `social/user` then `social/user/followers` (look at follower-to-following ratio + which smart accounts follow them).
+- **"What did @handle say recently?"** → `social/user/posts` ($0.001 each).
+- **"Show me the reply storm under tweet X"** → `social/tweet/replies` ($0.001).
+
+## When NOT to use this skill
+
+- Generic Twitter scraping or non-crypto sentiment → use `BrowserX` or a web search tool. Surf is curated for crypto-relevant accounts.
+- Real-time tweet streaming → not supported; this is historical / batch reads.
+
+## Cost discipline
+
+- User-level reads are cheap ($0.001). Free to fan out across 5–10 handles when profiling.
+- Project-level signal is $0.005/call. One mindshare + one smart-followers call is usually enough to answer "is this thing real?".
+- Always include the cost in your summary.
+
+## The user asked
+
+$ARGUMENTS

package/dist/skills-bundled/trade-discussion/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: trade-discussion
+description: Record market commentary, hypotheses, or open observations as a structured note — no trade fired, no position sized. Lighter than /trade-strategy. Saves to ~/.blockrun/notes/ for future reference. Use when the user wants to think out loud about the market.
+triggers:
+  - "market commentary"
+  - "trade discussion"
+  - "observation"
+  - "just thinking"
+  - "market thought"
+  - "log a thought"
+argument-hint: <topic>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This skill is the lightest of the three trading skills — no trade, no full strategy doc, just a short observation with enough structure to be useful later.
+
+## Workflow
+
+1. **Gather context only if cheap or asked.** Don't burn $0.005 on a chain query for a discussion note unless the user requested data. Default: write the note from what you already know.
+
+2. **Write the note.** Use the `Write` tool to create:
+
+   - Path: `~/.blockrun/notes/<YYYY-MM-DD>-<slug>-discussion.md`
+   - Slug: 3–5-word kebab-case (e.g. `etf-flow-divergence-watch`)
+   - Content template:
+
+```markdown
+# Discussion — <Title>
+
+**Date:** <YYYY-MM-DD>
+**Author:** Franklin (skill: /trade-discussion)
+
+## Observation
+
+<1–3 paragraphs.>
+
+## Symbols mentioned
+
+`<SYMBOL1>` `<SYMBOL2>` (etc.)
+
+## Tags
+
+`<sentiment>` `<watch>` `<thesis-fragment>` (etc.)
+
+## Open questions
+
+- <Question 1 — what would confirm or invalidate this?>
+- <Question 2>
+
+## Possible follow-ups
+
+- `/surf-market` for <specific data>
+- `/surf-social` for <specific KOL or mindshare check>
+- `/trade-strategy` if this matures into a plan
+- `/trade-signal` if a clear entry emerges
+```
+
+3. **Confirm.** Report back: "Note saved to `<path>`. Tagged `<tags>`. No trade fired. If this hardens into a plan, run `/trade-strategy <topic>`."
+
+4. **Do not call `TradingOpenPosition`.** Discussion notes are explicitly trade-free.
+
+## When this skill fits vs the alternatives
+
+- **`/trade-discussion`** — open-ended observation, hypothesis, "what if". Cheapest, least structured.
+- **`/trade-strategy`** — committed plan with entry/exit/sizing. Reach for this when an observation has hardened.
+- **`/trade-signal`** — the actual trade. Fires `TradingOpenPosition`, hits the wallet (paper trading) and the journal.
+
+## The user said
+
+$ARGUMENTS

package/dist/skills-bundled/trade-signal/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: trade-signal
+description: Open a paper-trade position with a structured rationale — direction, price target, stop, time horizon, conviction, evidence, tags, thesis. The journal scores the trade on discipline (verifiability, evidence, specificity, novelty, review), not P&L, and surfaces the trend in TradingPortfolio. Use any time the user wants to open a position with intent, not vibes.
+triggers:
+  - "open a trade"
+  - "buy"
+  - "long"
+  - "short"
+  - "take a position"
+  - "trade signal"
+  - "trade idea"
+argument-hint: <symbol or thesis>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This is paper trading — fills are simulated against a live mark — so the value is the discipline, not the dollars. Every trade entered through this skill carries a rationale that the journal scorer evaluates on five dimensions:
+
+| Dimension | Weight | Earned by |
+|---|---|---|
+| verifiability | 30% | direction + priceTarget both set |
+| evidence | 25% | thesis ≥ 200 chars + 3 evidence items + indicator keywords (RSI/MACD/funding/etc.) |
+| specificity | 20% | symbol + ≥ 2 tags |
+| novelty | 15% | not the 4th identical revenge-trade this week |
+| review | 10% | post-trade note left at close |
+
+Total is a 0–5 score, persisted with the trade and averaged across the last 10 entries in the portfolio footer.
+
+## Workflow
+
+1. **Read the request.** The user's argument is below under "The user said". If it's a complete thesis (symbol + direction + reasoning + numbers), proceed to step 3. If anything's vague, ask **one** clarifying question — the cheapest call you have on the wallet is "tell me more before I burn $0.001 on a market quote."
+
+2. **Optional context** — if you don't already have a recent quote, call `TradingMarket({ ticker, assetClass })` (free for crypto, $0.001 for stocks). For thesis support beyond price, the `/surf-market`, `/surf-chain`, or `/surf-social` skills can be invoked, each documenting their own endpoint costs.
+
+3. **Construct the rationale.** Fill as many fields as the request justifies:
+
+   - `direction`: `"long"` for buys (paper trading is long-only today).
+   - `priceTarget`: where you expect to take profit (USD).
+   - `stopLoss`: where you'll exit if wrong (USD).
+   - `timeHorizon`: `"1h"`, `"1d"`, `"1w"`, `"1m"`, `"3m"` — match the trade type.
+   - `conviction`: 1 (low, "small probe") → 5 (high, "size up").
+   - `evidence`: 2–4 items. Indicator readings, news links, on-chain stats, comparable trades.
+   - `tags`: 2+ categories — `"momentum"`, `"mean-reversion"`, `"macro"`, `"event"`, `"sentiment"`, etc.
+   - `thesis`: a paragraph (target 200+ chars) connecting the evidence to the trade. Mention at least one named indicator if you cite one.
+
+4. **Size with discipline.** Default per-position cap is $400, total exposure $900 (see TradingPortfolio for current utilization). Don't size beyond what conviction justifies — a conviction-2 trade at the cap is a discipline red flag.
+
+5. **Fire the trade** by calling `TradingOpenPosition`:
+
+```
+TradingOpenPosition({
+  symbol: "<TICKER>",
+  qty: <quantity>,
+  priceUsd: <fill price>,
+  rationale: {
+    direction: "long",
+    priceTarget: <number>,
+    stopLoss: <number>,
+    timeHorizon: "<period>",
+    conviction: <1-5>,
+    evidence: ["<source 1>", "<source 2>", ...],
+    tags: ["<tag 1>", "<tag 2>"],
+    thesis: "<200+ char paragraph>"
+  }
+})
+```
+
+6. **Surface the score.** The tool result shows the fill. Then call `TradingPortfolio` once and quote the new discipline score back to the user — "Trade booked. Journal score on this entry: 4.2/5. Discipline trend over the last 10 trades: 3.6/5 (evidence flagged below 3 — keep citing indicators)."
+
+7. **Stop.** Don't fan out to multiple trades unless the user explicitly asks for portfolio construction. One disciplined trade beats five vibes-trades.
+
+## Anti-patterns
+
+- Firing `TradingOpenPosition` without a rationale block. The journal still records the trade but it scores ~1/5 on discipline. Don't do this.
+- Inventing evidence. If the user says "feels like a top" and you can't find supporting data, write that into the thesis verbatim and let the score reflect it. The journal is a mirror, not a press release.
+- Trading the same symbol + direction four times in a week. The novelty penalty fires for a reason — that's revenge trading.
+
+## The user said
+
+$ARGUMENTS

package/dist/skills-bundled/trade-strategy/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: trade-strategy
+description: Write a long-form trading strategy document — thesis, entry triggers, exit rules, position sizing, hold horizon, kill criteria. No trade is fired. Saves a structured markdown note to ~/.blockrun/notes/. Use when the user wants to plan an approach before committing capital.
+triggers:
+  - "trading strategy"
+  - "write a strategy"
+  - "strategy doc"
+  - "trade plan"
+  - "planning a trade"
+argument-hint: <topic or thesis>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This skill captures *intent* before *action*. The user wants a written strategy, not an executed trade. Result: a markdown file under `~/.blockrun/notes/` that the user (and future Franklin sessions) can reference when the actual trade fires via `/trade-signal`.
+
+## Workflow
+
+1. **Clarify if needed.** If the argument is just a ticker ("BTC") without a direction, ask one clarifying question about what the user is trying to do (long, short, range, event-driven).
+
+2. **Gather supporting context.** Use the `/surf-market`, `/surf-chain`, or `/surf-social` skills to pull data that informs the strategy. Each surfaces its own cost; mention what you spent at the end.
+
+3. **Write the strategy doc.** Use the `Write` tool to create:
+
+   - Path: `~/.blockrun/notes/<YYYY-MM-DD>-<slug>-strategy.md` (replace `~` with the user's actual home dir; ask if you don't know it, or run `Bash("echo $HOME")` once)
+   - Slug: short kebab-case identifier derived from the topic (e.g. `btc-pre-halving-long`)
+   - Content template:
+
+```markdown
+# Strategy — <Title>
+
+**Date:** <YYYY-MM-DD>
+**Author:** Franklin (skill: /trade-strategy)
+**Status:** draft
+
+## Thesis
+
+<2–4 paragraphs: why this trade now. Cite the data sources you pulled.>
+
+## Symbols & direction
+
+- Primary: <SYMBOL> <long|short>
+- Hedges (if any): <SYMBOL> <long|short>
+
+## Entry triggers
+
+- <Specific price levels, indicator readings, or events that must hold>
+- <…>
+
+## Position sizing
+
+- Per-symbol notional cap: $<N> (vs Franklin's $400 default)
+- Conviction tier: <1–5> — justification: <…>
+
+## Exit rules
+
+- Take profit: <price | indicator | event>
+- Stop loss: <price | indicator | event>
+- Time stop: exit by <date / horizon> regardless
+
+## Kill criteria
+
+What invalidates the entire thesis? (Be specific — name a level, a metric, or a market regime change.)
+
+## Evidence
+
+- <source 1>
+- <source 2>
+- <indicator reading>
+
+## Tags
+
+`<momentum>` `<macro>` `<event>` (etc.)
+
+## Linked trades
+
+(Populated as `/trade-signal` invocations reference this doc.)
+```
+
+4. **Confirm the path.** Report back to the user: "Strategy saved to `<path>`. Open it with your editor or pull it into your next `/trade-signal` call as context. Discipline score on the strategy is captured when the first trade fires."
+
+5. **Do not call `TradingOpenPosition`.** This skill is plan-only. The user fires the trade separately via `/trade-signal` when ready.
+
+## Anti-patterns
+
+- Skipping kill criteria. Every strategy has them; "I'll know when to exit" is not a strategy.
+- Position sizing without conviction-justified caps. A conviction-2 strategy that loads the full $400 cap is theater.
+- Writing a strategy doc and immediately firing a trade. The point of separating the two is to force a pause. If the user wants both, run `/trade-strategy` first, then `/trade-signal` referencing the saved file.
+
+## The user said
+
+$ARGUMENTS

package/dist/tools/blockrun.d.ts

@@ -0,0 +1,21 @@
+/**
+ * BlockRun primitive — the generic x402-paid gateway capability.
+ *
+ * One tool, every BlockRun endpoint. Replaces the per-API hardcoded pattern
+ * (ImageGen, VideoGen, Phone tools, etc) for new integrations. Skills in
+ * src/skills-bundled/<name>/SKILL.md describe which paths to call for which
+ * user intents; this tool just signs the x402 payment and forwards.
+ *
+ * Why the indirection: BlockRun keeps shipping new partner APIs (Surf,
+ * Phone & Voice, future ML/data partners). Hardcoding each as a fresh
+ * CapabilityHandler means a Franklin npm release per partner and a bigger
+ * tool list for the LLM to reason about. This primitive plus markdown
+ * skill files decouples API expansion from agent releases — new partners
+ * ship as a new SKILL.md, no code change.
+ *
+ * Signing pattern mirrors src/tools/modal.ts and src/phone/client.ts; we
+ * deliberately keep the copy-paste rather than refactor those into a
+ * shared module (out of scope; would touch unrelated tools).
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const blockrunCapability: CapabilityHandler;