@blockrun/franklin 3.2.4 → 3.3.1

package/README.md

@@ -6,11 +6,11 @@
   <code>◆</code> &nbsp; Franklin &nbsp; <code>◆</code>
 </h1>
 
-<h3>The AI agent with a wallet.</h3>
+<h3>The wallet-native economic agent.</h3>
 
 <p>
-  While others chat, Franklin spends.<br>
-  One wallet. Every model. Every paid API. Pay per action in USDC.
+  While others generate text, Franklin deploys capital.<br>
+  One wallet. Every model. Every paid API. Budgeted execution in USDC.
 </p>
 
 <p>
@@ -27,12 +27,11 @@
 
 <p>
   <a href="#quick-start">Quick&nbsp;start</a> ·
-  <a href="#what-it-looks-like">Demo</a> ·
-  <a href="#why-franklin">Why</a> ·
+  <a href="#a-new-category">New&nbsp;category</a> ·
+  <a href="#what-franklin-can-execute">What&nbsp;it&nbsp;does</a> ·
+  <a href="#the-comparison">Compare</a> ·
   <a href="#features">Features</a> ·
-  <a href="#plugin-sdk">Plugins</a> ·
   <a href="#how-it-works">Architecture</a> ·
-  <a href="#roadmap">Roadmap</a> ·
   <a href="#community">Community</a>
 </p>
 
@@ -42,9 +41,9 @@
 
 ## The pitch in one paragraph
 
-Every AI coding tool today writes text. `franklin` **spends money** — your USDC, from your wallet, on your behalf, under a hard budget cap — to actually get work done. One agent. 55+ models. Every paid API routed through the [x402](https://x402.org) micropayment protocol. No subscriptions. No API keys. No account. The wallet is your identity.
+`franklin` is not a coding copilot and not just another task runner. Franklin is a **wallet-native economic agent**: software with purchasing power. You give it a goal and a budget. Franklin decides what model to call, what tool to use, what API is worth paying for, and when to stop. Every paid action routes through the [x402](https://x402.org) micropayment protocol and settles against your own wallet. No subscriptions. No API keys. No account. The wallet is the identity.
 
-Built by the [BlockRun](https://blockrun.ai) team. Apache‑2.0. TypeScript. Ships as one npm package.
+Built by the [BlockRun](https://blockrun.ai) team. Apache-2.0. TypeScript. Ships as one npm package.
 
 ---
 
@@ -66,32 +65,117 @@ That's it. Zero signup, zero credit card, zero phone verification. Send **$5 of
 
 ---
 
-## What it looks like
+## A new category
+
+> **Economic Agent**
+> 
+> Software that can hold a wallet, price its own actions, spend toward an outcome, and stop at a hard budget cap.
+
+That definition matters.
+
+Most AI products fit into one of three buckets:
+- They answer questions.
+- They write code.
+- They automate a fixed workflow.
+
+Franklin does something different. It combines:
+- **Purchasing power** — it can pay for models, tools, and APIs.
+- **Budget awareness** — it knows spend is part of the problem, not an afterthought.
+- **Cross-vertical execution** — marketing, trading, research, code, ops.
+- **Hard stopping conditions** — when the wallet or budget says stop, it stops.
+
+That is why Franklin is an economic agent, not just a task agent.
+
+---
+
+## What Franklin can execute
+
+Franklin is **chat-first**. You do not wire a DAG, configure six API keys, or commit to one model vendor. You state an outcome. Franklin decides what to read, search, fetch, call, and pay for.
+
+### 📈 Trading signals
+
+```text
+> what's BTC looking like today?
+
+  ✓ TradingSignal  BTC
+
+  ## BTC Signal Report
+
+  Price: $71,056 USD (+2.3% 24h)
+  Market Cap: $1.42T
+  24h Volume: $29.6B
+
+  ### Technical Indicators (30d)
+  - RSI(14): 53.2 — neutral
+  - MACD: 339.21 / Signal: 280.45 — bullish crossover
+  - Bollinger: within band (upper $73,773 / lower $64,545)
+  - Volatility: 35.3% annualized — medium
+
+> if I enter at 65000 with $1000, where should my stop be?
+
+  Based on ATR(14) and support at $63,500:
+  Entry: $65,000 · Stop: $63,200 (−2.8%) · Risk: $27.69
+  Risk/reward to $70K target: 1:2.8 ✓
+```
+
+Live data from CoinGecko. RSI, MACD, Bollinger, and volatility computed locally. No API key needed.
+
+### 🎯 Social growth
 
 ```text
- ███████╗██████╗  █████╗ ███╗   ██╗██╗  ██╗██╗     ██╗███╗   ██╗
- ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║ ██╔╝██║     ██║████╗  ██║
- █████╗  ██████╔╝███████║██╔██╗ ██║█████╔╝ ██║     ██║██╔██╗ ██║
- ██╔══╝  ██╔══██╗██╔══██║██║╚██╗██║██╔═██╗ ██║     ██║██║╚██╗██║
- ██║     ██║  ██║██║  ██║██║ ╚████║██║  ██╗███████╗██║██║ ╚████║
- ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝
-  Franklin  ·  The AI agent with a wallet  ·  v3.1.0
+> find X posts complaining about AI rate limits
+
+  ✓ SearchX  "AI rate limits"
 
-  Model : anthropic/claude-sonnet-4.6
-  Wallet: 0x7a9…4e2  ·  12.47 USDC
+  Found 8 candidates:
+  1. "Claude keeps throttling me in the middle of shipping..." — @buildermax (2h)
+  2. "I need an agent that can switch models automatically." — @indiedev (5h)
+  ...
 
+> write a reply to #2 — mention Franklin uses a wallet instead of subscriptions
+
+  Draft:
+  "That was my pain too. Franklin routes across 55+ models,
+   pays per action from a USDC wallet, and doesn't trap you
+   inside a monthly seat. Better economics, better uptime."
+
+> looks good, post it
+
+  ✓ PostToX  Reply posted to x.com/indiedev/status/...
+```
+
+Search X, generate contextual replies, and post with confirmation. Uses Playwright for browser automation, so there is no X API key, no OAuth maze, and no $100/month developer account.
+
+### 🔎 Research, code, anything with a budget
+
+```text
+> compare the top 5 AI agent pricing models, summarize the patterns, and save a note for me
+
+  ✓ WebSearch  ai agent pricing models
+  ✓ WebFetch   5 articles
+  ✓ Write      notes/agent-pricing.md
+
+  Summary:
+  - Most agents hide pricing behind monthly seats
+  - Usage-based products win with power users and teams
+  - Wallet-based billing is still basically empty whitespace
+```
+
+```text
 > refactor src/auth.ts to use the new jwt helper, then run the tests
 
-  ✓ Read  src/auth.ts                                     $0.0024
-  ✓ Read  src/lib/jwt.ts                                  $0.0011
-  ✓ Edit  src/auth.ts  (-24 +31 lines)                    $0.0082
-  ✓ Bash  npm test                                        $0.0000
+  ✓ Read   src/auth.ts                    $0.002
+  ✓ Read   src/lib/jwt.ts                 $0.001
+  ✓ Edit   src/auth.ts (-24 +31 lines)    $0.008
+  ✓ Bash   npm test                       $0.000
     › 142 passing · 0 failing · 2.4s
 
-  Done in 18s · 4 tool calls · 12.8k in / 2.1k out · $0.0117
+  Done in 18s · $0.011
 ```
 
-Every tool call is itemised. Every token is priced. The wallet is the source of truth — when it hits zero, Franklin stops. No overdraft, no surprise bill, no rate-limit wall at 3am.
+Code is still first-class. It is just **one workload**, not the category.
+
+Every tool call is itemized. Every token is priced. When the wallet hits zero, Franklin stops. No overdraft, no surprise bill, no rate-limit wall at 3am.
 
 ---
 
@@ -101,23 +185,23 @@ Every tool call is itemised. Every token is priced. The wallet is the source of
 <tr>
 <td width="33%" valign="top">
 
-### 💳 &nbsp;Pay per action
+### 💳 &nbsp;Budget is native
 
-No subscriptions. No "Pro" tier. You fund a wallet once and Franklin spends atomically per API call via HTTP 402. Cheap models cost fractions of a cent. Frontier models cost what they cost. When the wallet is empty, Franklin stops.
+Franklin does not bolt spend tracking on afterward. Cost is part of the loop. The agent can choose free, cheap, or premium paths per step, and every paid action settles against your wallet.
 
 </td>
 <td width="33%" valign="top">
 
 ### 🔐 &nbsp;Wallet is identity
 
-No email. No phone. No KYC. Your Base or Solana address is your account. Portable across machines — `franklin setup` imports an existing wallet in one command. Your sessions, your config, your money.
+No email. No phone. No KYC. Your Base or Solana address is your account. Portable across machines. Your sessions, your config, your money.
 
 </td>
 <td width="33%" valign="top">
 
-### 🧠 &nbsp;55+ models, one interface
+### 🧠 &nbsp;One runtime, many verticals
 
-Claude Sonnet/Opus 4.6, GPT‑5.4, Gemini 2.5 Pro, Grok 4, DeepSeek V3, GLM‑5.1, Kimi, Minimax, plus NVIDIA's free tier (Nemotron, Qwen3 Coder). Switch mid‑session with `/model`. Automatic fallback if one provider is down.
+Marketing, trading, research, code, and anything else you can express as tools plus budgeted execution. Franklin is a runtime for economic workflows, not a single-purpose copilot.
 
 </td>
 </tr>
@@ -127,19 +211,18 @@ Claude Sonnet/Opus 4.6, GPT‑5.4, Gemini 2.5 Pro, Grok 4, DeepSeek V3, GLM‑5.
 
 ## The comparison
 
-|                                   | Claude Code    | Aider         | Cursor         | **Franklin**          |
-| --------------------------------- | -------------- | ------------- | -------------- | --------------------- |
-| Writes and edits code             | ✅             | ✅            | ✅             | ✅                    |
-| Multi‑model support               | ❌ Claude only | ✅ BYOK        | ⚠️ limited     | ✅ **55+ via 1 wallet** |
-| Pricing model                     | Subscription   | BYOK          | Subscription   | **Pay per action**    |
-| Identity                          | Account        | API keys      | Account        | **Wallet**            |
-| Spend budget cap enforced on‑chain | ❌             | ❌            | ❌             | ✅                    |
-| Pay any API (images, search…)      | ❌             | ❌            | ❌             | ✅ via x402           |
-| Plugin SDK for custom workflows    | ❌             | ⚠️            | ❌             | ✅                    |
-| Persistent sessions + search       | ⚠️             | ⚠️            | ⚠️             | ✅                    |
-| Start free, no signup              | ❌             | ⚠️ BYOK        | ❌             | ✅                    |
+|                                      | Chatbots        | Coding agents    | Workflow tools   | **Franklin**                    |
+| ------------------------------------ | --------------- | ---------------- | ---------------- | ------------------------------- |
+| Main unit of value                   | Answers         | Code changes     | Fixed automations| **Budgeted outcomes**           |
+| Has purchasing power                 | ❌              | ❌               | ❌               | ✅ **wallet-native**            |
+| Can choose tools/models per step     | ⚠️ limited      | ✅ mostly coding | ❌ usually fixed | ✅ **yes**                      |
+| Works across marketing/trading/code  | ⚠️              | ❌ code-first    | ⚠️ integration-bound | ✅ **cross-vertical**       |
+| Hard spend cap                       | ❌              | ❌               | ⚠️ external billing | ✅ **wallet balance**        |
+| Identity                             | Account         | Account / API key| Account          | ✅ **wallet**                   |
+| Start free, no signup                | ⚠️              | ❌ / BYOK        | ❌               | ✅                              |
+| Paid APIs through one interface      | ❌              | ⚠️               | ❌               | ✅ **55+ models + paid tools**  |
 
-Franklin is the first agent in the **Autonomous Economic Agent** category — an agent that takes a goal, decides what to spend on, and executes within a hard budget cap enforced by the wallet.
+**Franklin is the economic agent category in one sentence:** software with a wallet that can spend toward a result.
 
 ---
 
@@ -149,44 +232,44 @@ Franklin is the first agent in the **Autonomous Economic Agent** category — an
 <tr>
 <td width="50%" valign="top">
 
-**🧠 55+ models via one wallet**
-Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One URL, one wallet, automatic fallback.
+**💼 Wallet-native economic execution**
+Franklin can decide what is worth paying for, route the call, sign the micropayment, and keep going until the goal is done or the budget is exhausted.
 
-**💳 x402 micropayments**
-HTTP 402 native. Every tool call is a tiny signed transaction against your USDC balance. No escrow, no refund API, no subscription.
+**📈 Trading signals**
+Ask "what's BTC looking like?" — Franklin fetches live price data, computes RSI/MACD/Bollinger/volatility, and synthesizes a signal.
 
-**🚦 Smart tier routing**
-Mark steps as `free` / `cheap` / `premium` — Franklin picks the best model per tier, per task. Configurable defaults in `franklin config`.
+**🎯 Social growth**
+Ask "find X posts about my category" — Franklin searches X, drafts replies, and posts with your confirmation.
 
-**🔌 Plugin SDK**
-Core is workflow‑agnostic. Ship a new vertical (marketing, trading, research) without touching the agent loop. See [docs/plugin-sdk.md](docs/plugin-sdk.md).
+**🧠 55+ models via one wallet**
+Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier. One wallet, one interface, automatic fallback.
 
-**💾 Persistent sessions**
-Every turn is streamed to disk with full metadata. Resume any session by ID. Survives crashes, reboots, context compaction.
+**💳 x402 micropayments**
+HTTP 402 native. Every paid action is a signed micropayment against your USDC balance. No subscriptions. No refund loop. No account lock-in.
 
-**🔍 Full‑text session search**
-`franklin search "payment loop"` — tokenised search across every past session. No SQLite, no indexing daemon, just fast.
+**🚦 Smart spend routing**
+Free / cheap / premium per step. Franklin picks the cheapest model that can do the job, then escalates when quality matters.
 
 </td>
 <td width="50%" valign="top">
 
-**📊 Cost insights**
-`franklin insights` — daily spend sparklines, per‑model breakdown, projections. Never wonder where the USDC went.
+**🛠 16 built-in tools**
+Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, ImageGen, AskUser, SubAgent, TradingSignal, TradingMarket, SearchX, PostToX.
 
-**⚡ Anthropic prompt caching**
-Multi‑turn Sonnet/Opus sessions use ephemeral cache breakpoints (`system_and_3` strategy). Large input savings on long conversations.
+**💾 Persistent sessions**
+Every turn is streamed to disk with metadata. Resume any session by ID. Survives crashes, reboots, and compaction.
 
-**🛠 12 built‑in tools**
-Read · Write · Edit · Bash · Glob · Grep · WebFetch · WebSearch · Task · ImageGen · AskUser · SubAgent.
+**🔍 Full-text session search**
+`franklin search "payment loop"` from the CLI, or `/session-search "payment loop"` in chat.
 
-**🔗 MCP auto‑discovery**
-Drop‑in Model Context Protocol servers from `~/.blockrun/mcp.json`. Ships with awareness of `blockrun-mcp` (markets, X, prediction markets) and `unbrowse` (any site → API).
+**📊 Cost insights**
+`franklin insights` shows spend breakdowns, trends, and projections. Never wonder where the USDC went.
 
-**🧭 Plan / Execute modes**
-`/plan` to design read‑only, `/execute` to commit. No accidental writes while exploring.
+**⚡ Anthropic prompt caching**
+Multi-turn Sonnet/Opus sessions use ephemeral cache breakpoints to reduce input spend on long conversations.
 
-**🪄 Slash ergonomics**
-`/commit`, `/push`, `/pr`, `/review`, `/ultrathink`, `/compact`, `/model`, `/cost`, `/wallet`, and 20+ more.
+**🔌 Plugin SDK + MCP**
+Core is workflow-agnostic. Add new verticals without touching the loop. Discover external tools automatically through MCP.
 
 </td>
 </tr>
@@ -194,121 +277,40 @@ Drop‑in Model Context Protocol servers from `~/.blockrun/mcp.json`. Ships with
 
 ---
 
-## Plugin SDK
-
-Franklin is plugin‑first. The core agent doesn't know what a "marketing campaign" or "trading signal" is — it just runs workflows. Adding a new vertical is a single TypeScript file.
-
-```typescript
-import type { Plugin, Workflow } from '@blockrun/franklin/plugin-sdk';
-
-const researchWorkflow: Workflow = {
-  id: 'research',
-  name: 'Competitor Research',
-  description: 'Find and summarise 10 competitors in a given space',
-  steps: [
-    {
-      name: 'search',
-      modelTier: 'none',          // pure API call, no LLM
-      execute: async (ctx) => {
-        const results = await ctx.exa.search(ctx.input.topic, { limit: 10 });
-        return { output: `Found ${results.length}`, data: { results } };
-      },
-    },
-    {
-      name: 'summarise',
-      modelTier: 'cheap',         // bulk work — use GLM or DeepSeek
-      execute: async (ctx) => {
-        const summaries = await ctx.llm.map(ctx.data.results, (r) =>
-          `Summarise in 3 bullets: ${r.text}`);
-        return { output: 'Summaries written', data: { summaries } };
-      },
-    },
-    {
-      name: 'synthesise',
-      modelTier: 'premium',       // final output — use Claude Opus
-      execute: async (ctx) => {
-        const report = await ctx.llm.complete({
-          system: 'You are a strategy analyst.',
-          user: `Synthesise these into a 1‑page report: ${JSON.stringify(ctx.data.summaries)}`,
-        });
-        return { output: report };
-      },
-    },
-  ],
-};
-
-export const myPlugin: Plugin = {
-  id: 'research',
-  name: 'Research',
-  version: '0.1.0',
-  workflows: [researchWorkflow],
-};
-```
-
-Three steps, three tiers, three prices. The agent routes each step to the cheapest model that can do the job. Full guide: **[docs/plugin-sdk.md](docs/plugin-sdk.md)**.
-
----
-
 ## Slash commands
 
-A curated subset of what `franklin` exposes inside an interactive session:
-
 | Command                          | What it does                                         |
 | -------------------------------- | ---------------------------------------------------- |
 | `/model [name]`                  | Interactive model picker, or switch directly         |
-| `/plan` · `/execute`             | Read‑only planning mode → commit mode                |
+| `/plan` / `/execute`             | Read-only planning mode / execution mode             |
 | `/ultrathink <q>`                | Deep reasoning mode for hard problems                |
-| `/compact`                       | Structured context compression (Goal/Progress/Next)  |
-| `/search <q>`                    | Full‑text search across past sessions                |
-| `/history` · `/resume <id>`      | Session management                                   |
-| `/commit` · `/push` · `/pr`      | Git workflow helpers (Franklin writes the message)   |
-| `/review` · `/fix` · `/test`     | One‑shot code review, bugfix, or test generation     |
-| `/explain <file>` · `/refactor`  | Targeted explanation or refactor                     |
-| `/cost` · `/wallet`              | Session cost, wallet address & USDC balance          |
+| `/compact`                       | Structured context compression                       |
+| `/search <q>`                    | Search the codebase                                  |
+| `/session-search <q>`            | Search past sessions                                 |
+| `/history` / `/resume [id]`      | Inspect or restore conversation state                |
+| `/commit` / `/push` / `/pr`      | Git workflow helpers                                 |
+| `/review` / `/fix` / `/test`     | One-shot code review, bugfix, or test runs           |
+| `/cost` / `/wallet`              | Session cost, wallet address, and balance            |
 | `/insights [--days N]`           | Rich usage analytics                                 |
-| `/mcp` · `/doctor` · `/context`  | Diagnostics                                          |
 | `/help`                          | Full command list                                    |
 
-Run `franklin` and type `/help` to see everything.
-
----
-
-## CLI commands
-
-Top‑level commands (`franklin --help`):
-
-```text
-setup [chain]     Create a wallet for payments (base | solana)
-start             Start the interactive agent (default command)
-models            List available models and pricing
-balance           Check wallet USDC balance
-config <action>   Manage config: default‑model, sonnet‑model, routing…
-stats             Usage statistics and cost savings vs. Claude Opus
-insights          Rich usage analytics (also /insights in session)
-search <q>        Full‑text session search (also /search in session)
-social            AI‑powered social engagement plugin
-plugins           List installed plugins
-proxy             Run a payment proxy for Claude Code compatibility
-init / uninit     Install/remove the background daemon (macOS LaunchAgent)
-daemon <action>   start | stop | status
-logs              Tail debug logs
-```
-
 ---
 
 ## How it works
 
-```
+```text
 ┌──────────────────────────────────────────────────────────────┐
-│  Franklin Agent                                              │
-│  Plugin SDK · Tool loop · Router · Session · Compaction      │
+│  Franklin Runtime                                            │
+│  Intent → Routing → Tool Use → Spend Decisions → Result      │
+├──────────────────────────────────────────────────────────────┤
+│  Agent Loop                                                  │
+│  16 tools · Sessions · Compaction · Pricing · Plugin SDK     │
 ├──────────────────────────────────────────────────────────────┤
 │  BlockRun Gateway                                            │
-│  55+ LLMs · Exa search · DALL·E · (soon) Runway · Suno       │
-│  CoinGecko · Dune · Apollo                                   │
+│  55+ LLMs · CoinGecko · Search · Image APIs · paid services  │
 ├──────────────────────────────────────────────────────────────┤
 │  x402 Micropayment Protocol                                  │
-│  HTTP 402 · USDC on Base & Solana · on‑chain budget cap      │
+│  HTTP 402 · USDC on Base & Solana · signed payment payloads  │
 └──────────────────────────────────────────────────────────────┘
                             │
                             ▼
@@ -318,91 +320,87 @@ logs              Tail debug logs
                      └─────────────┘
 ```
 
-Every API call resolves to a signed micropayment against your wallet. You fund once; Franklin spends per task, priced by the upstream provider. No middlemen, no refund loop, no subscription renewal date.
+The loop is simple:
+1. You state an outcome.
+2. Franklin chooses what to read, call, and pay for.
+3. The payment settles against your wallet.
+4. Franklin reports the result and the spend.
+
+That economic loop is the product.
 
 ---
 
 ## Project layout
 
-```
+```text
 src/
 ├── index.ts           CLI entry (franklin + runcode alias)
-├── banner.ts          FRANKLIN gold→emerald gradient
+├── banner.ts          Ben Franklin portrait + FRANKLIN gradient text
 ├── agent/             Agent loop, LLM client, compaction, commands
-├── tools/             12 built‑in tools (Read/Write/Edit/Bash/…)
+├── tools/             16 built-in tools (Read/Write/Edit/Bash/Glob/Grep/
+│                      WebFetch/WebSearch/Task/ImageGen/AskUser/SubAgent/
+│                      TradingSignal/TradingMarket/SearchX/PostToX)
+├── trading/           Market data (CoinGecko) + technical indicators
+├── social/            X browser automation (Playwright) + reply engine
+├── events/            Internal event bus (signals, posting, workflow events)
 ├── plugin-sdk/        Public plugin contract (Workflow/Plugin/Channel)
-├── plugins/           Plugin registry + runner (plugin‑agnostic)
-├── plugins-bundled/   Plugins shipped with Franklin
-│   └── social/        AI‑powered social engagement
-├── session/           Persistent sessions + FTS search
+├── plugins/           Plugin registry + runner (plugin-agnostic)
+├── session/           Persistent sessions + search
 ├── stats/             Usage tracking + insights engine
-├── ui/                Ink‑based terminal UI
-├── proxy/             Payment proxy for Claude Code compatibility
-├── router/            Smart model tier routing (free/cheap/premium)
+├── ui/                Ink-based terminal UI
+├── proxy/             Payment proxy for external tools
+├── router/            Smart model routing (free/cheap/premium)
 ├── wallet/            Wallet management (Base + Solana)
-├── mcp/               MCP server auto‑discovery
+├── mcp/               MCP server auto-discovery
 └── commands/          CLI subcommands
 ```
 
 ---
 
-## Roadmap
-
-### ✅ Shipped in v3.1.0
-- Interactive agent with 12 built‑in tools
-- 55+ models across Anthropic, OpenAI, Google, xAI, DeepSeek, GLM, Kimi, Minimax, NVIDIA free tier
-- Plugin SDK (workflow, channel, plugin) — plugin‑first architecture
-- **Social plugin** — AI‑powered engagement on Reddit / X
-- x402 micropayment integration
-- Wallet setup (Base + Solana), balance, funding flow
-- Persistent sessions + full‑text search
-- Cost insights engine with daily sparklines
-- Anthropic prompt caching (ephemeral, multi‑breakpoint)
-- Plan/Execute modes, slash commands, compaction, smart routing
-- MCP auto‑discovery
-- Proxy mode for Claude Code compatibility
-
-### 🚧 In progress
-- **Marketing plugin** — campaigns, Reddit/IG outreach, content generation pipelines
-- **Trading plugin** — signals, market research, risk analysis
-- Video (Runway) and audio (Suno) paid tool routes
-- Per‑step budget caps inside workflows
-- More languages in `franklin config` (`.yaml` support)
-
-### 💭 Under consideration
-- Shared plugin registry (install community plugins with `franklin plugins add`)
-- Fiat on‑ramp inside `franklin setup`
-- Mobile wallet handoff via WalletConnect
+## Free tier, for real
+
+Start with **zero dollars**. Franklin defaults to free NVIDIA models that need no wallet funding.
+
+```bash
+franklin --model nvidia/nemotron-ultra-253b
+```
+
+When you fund the wallet, Franklin gets more purchasing power: Claude, GPT, Gemini, Grok, and paid tools like Exa, DALL-E, and CoinGecko Pro.
 
 ---
 
-## Free tier, for real
+## Social automation (advanced)
 
-Start with **zero dollars**. Franklin defaults to free NVIDIA models (Nemotron 70B, Qwen3 Coder 480B) that need no wallet funding. Rate‑limited to 60 requests/hour on the gateway, but genuinely free.
+Once you've tuned Franklin's reply style in chat, you can graduate to **automated batch mode**:
 
 ```bash
-franklin --model nvidia/nemotron-ultra-253b
+franklin social setup              # install Chromium, write default config
+franklin social login x            # log in to X once (cookies persist)
+franklin social config edit        # set handle, products, search queries
+franklin social run                # dry-run — preview drafts
+franklin social run --live         # actually post to X
+franklin social stats              # posted / drafted / skipped / cost
 ```
 
-Only fund a wallet when you want Claude, GPT, Gemini, Grok, or paid tools like Exa and DALL·E.
+The chat-based social tools (`SearchX`, `PostToX`) and the batch CLI (`franklin social run`) share the same engine. Chat first, automate later.
 
 ---
 
 ## Documentation
 
-- 📖 **[Plugin SDK guide](docs/plugin-sdk.md)** — build your own workflow
-- 📜 **[Changelog](CHANGELOG.md)** — every release explained
-- 🗺 **[Roadmap](docs/ROADMAP.md)** — what's coming next
-- 🧭 **[Claude Code compatibility](docs/)** — use Franklin as a payment proxy
+- [Plugin SDK guide](docs/plugin-sdk.md) — build your own workflow vertical
+- [Changelog](CHANGELOG.md) — every release explained
+- [Roadmap](docs/ROADMAP.md) — what's coming next
+- [Claude Code compatibility](docs/) — use Franklin as a payment proxy
 
 ---
 
 ## Community
 
-- 💬 **[Telegram](https://t.me/blockrunAI)** — realtime help, bug reports, feature requests
-- 🐦 **[@BlockRunAI](https://x.com/BlockRunAI)** — release notes, demos
-- 🐛 **[Issues](https://github.com/BlockRunAI/franklin/issues)** — bugs and feature requests
-- 💡 **[Discussions](https://github.com/BlockRunAI/franklin/discussions)** — ideas, Q&A, show & tell
+- [Telegram](https://t.me/blockrunAI) — realtime help, bug reports, feature requests
+- [@BlockRunAI](https://x.com/BlockRunAI) — release notes, demos
+- [Issues](https://github.com/BlockRunAI/franklin/issues) — bugs and feature requests
+- [Discussions](https://github.com/BlockRunAI/franklin/discussions) — ideas, Q&A, show & tell
 
 ---
 
@@ -418,20 +416,7 @@ npm run test:e2e      # live e2e tests — hits real models, needs wallet
 node dist/index.js --help
 ```
 
-**Contributing:** please open an issue first to discuss meaningful changes. For new features, prefer a plugin over a core change — [docs/plugin-sdk.md](docs/plugin-sdk.md) exists exactly so the core stays lean. PRs welcome on bugs, docs, typos, new models in pricing.
-
----
-
-## Migrating from RunCode
-
-If you were a RunCode user: **nothing breaks**. The `runcode` binary still works as an alias for `franklin` through the 60‑day compatibility window (until ~June 2026). Your config at `~/.blockrun/`, your wallet, your sessions — all migrate automatically.
-
-To update when convenient:
-
-```bash
-npm uninstall -g @blockrun/runcode
-npm install -g @blockrun/franklin
-```
+**Contributing:** open an issue first to discuss meaningful changes. PRs welcome on bugs, docs, new models in pricing, and new tools.
 
 ---
 
@@ -449,16 +434,14 @@ npm install -g @blockrun/franklin
 
 ## License
 
-Apache‑2.0. See [LICENSE](LICENSE).
-
-Built on the shoulders of giants: [x402](https://x402.org), [Anthropic](https://anthropic.com), [@modelcontextprotocol](https://github.com/modelcontextprotocol), [Ink](https://github.com/vadimdemedes/ink), [commander](https://github.com/tj/commander.js).
+Apache-2.0. See [LICENSE](LICENSE).
 
 ---
 
 <div align="center">
 
-**Franklin runs your money.**<br>
-<sub>Your wallet. Your agent. Your results.</sub>
+**Franklin is the economic agent.**<br>
+<sub>Your wallet. Your budget. Your results.</sub>
 
 <br>