surf-skill 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## v2.1.0 — Brave Search as 3rd provider + `--mode` flag
+
+### What's new
+
+- **Brave Search added as 3rd provider** (`--provider brave`). Brave runs
+  its own index (independent from Google/Bing) and currently offers $5/mo
+  in API credit + metered usage (~$0.003/query) after the free tier was
+  retired in Feb 2026. Search only — Brave has no extract/crawl/map/
+  research equivalents, so the capability map keeps those Tavily-only.
+- **New `--mode <fast|normal|slow>` flag** for `search`. Each provider
+  translates the mode to its native tier:
+
+  | Mode | Tavily | Parallel | Brave |
+  |---|---|---|---|
+  | `fast`   | `search_depth=fast` | (ignored) | `count=5` |
+  | `normal` | `search_depth=basic` | `/v1/search` | `count=10` |
+  | `slow`   | `search_depth=advanced` | (ignored) | `count=20` |
+
+  `--depth basic|advanced` continues to work as a legacy alias for Tavily.
+
+- **Library API gets `opts.mode`, `opts.braveKey`, `opts.braveKeys`**:
+  ```js
+  await search('claude api', { mode: 'fast', braveKey: 'BS...' });
+  ```
+
+- **`BRAVE_API_KEY` / `BRAVE_API_KEYS` env vars** now part of the discovery
+  hierarchy (env > .env > ~/.config/surf/keys.json).
+
+- **Setup wizard** now prompts for Brave keys after Tavily + Parallel.
+
+- **State migration is transparent**: existing `~/.config/surf/keys.json`
+  files from v2.0.x get a `brave` section added automatically on next
+  `loadState()` — no manual upgrade step needed.
+
+### Default chain order
+
+`search` chain is now `[tavily, parallel, brave]`. Existing users see no
+behavior change (Tavily still tried first); Brave is the 3rd fallback.
+`last_ok_provider` still wins.
+
+### Breaking changes
+
+None. CLI and library APIs are backward compatible.
+
+### Files added
+
+- `src/lib/providers/brave.mjs` — adapter, `mapError()`, `/web/search`
+  with mode → count translation.
+
+### Files modified
+
+- `src/lib/providers/index.mjs` — register brave + add to capabilityMap.search
+- `src/lib/state.mjs` — `PROVIDERS = ['tavily', 'parallel', 'brave']` +
+  `normalizeFullState()` for graceful schema migration
+- `src/env.mjs` — `discoverKeys()` returns `{ tavily, parallel, brave }`
+- `src/lib/cost.mjs` — `estimateBrave()` returns 1 credit/search
+- `src/lib/setup.mjs` — 3-provider wizard
+- `src/lib/providers/tavily.mjs` — mode → search_depth resolution
+- `src/lib/api/search.mjs` — library opts.mode
+- `bin/surf-skill.mjs` — HELP + `--mode` flag wiring
+- `src/lib/harness-install.mjs` — skeleton with brave section
+- `package.json`, `SKILL.md`, `README.md` — bump 2.0.0 → 2.1.0, doc updates
+
+### Fora de escopo
+
+- Brave `/summarizer/search` endpoint — defer to v2.2 (different rate
+  limit, response shape adds `data.answer`).
+- Brave Goggles support (`--goggle <id>`) — defer.
+- News / Images / Videos / Local / Spellcheck endpoints — defer.
+
+---
+
 ## v2.0.0 — npm package, cross-OS install, library mode
 
 ### What's new

package/README.md

@@ -1,24 +1,40 @@
-# surf-skill
+<p align="center">
+  <img src="logo.png" alt="surf-skill logo" width="160" />
+</p>
 
-**One bash command. Two providers. Zero MCP.** A multi-provider web skill
-for AI coding agents that fronts **Tavily** and **Parallel AI** behind a
-single CLI (`surf-skill`). The agent calling this skill **never picks the
-provider** — `surf-skill` does, with automatic key rotation, provider
-fallback, and last-known-good persistence.
+<h1 align="center">surf-skill</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/surf-skill"><img src="https://img.shields.io/npm/v/surf-skill?style=flat-square&color=black" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/surf-skill"><img src="https://img.shields.io/npm/dt/surf-skill?style=flat-square&color=black" alt="downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/surf-skill?style=flat-square&color=black" alt="MIT" /></a>
+  <img src="https://img.shields.io/node/v/surf-skill?style=flat-square&color=black" alt="node>=18" />
+</p>
+
+<p align="center">
+  Multi-provider web skill for AI coding agents.<br/>
+  Fronts <strong>Tavily</strong> and <strong>Parallel AI</strong> behind a single CLI + Node library, with automatic key rotation, provider fallback, and last-known-good persistence.
+</p>
+
+---
+
+**One command. Three providers. Zero MCP.** Install with `npm i -g surf-skill`.
+The agent calling this skill **never picks the provider** — `surf-skill` does.
 
 ```
-search ─┐
-extract ┤            ┌──▶ Tavily   (search, extract, crawl, map, research)
-crawl ──┼──▶ surf ───┤
-map  ───┤            └──▶ Parallel (search, extract, research async)
-research┘
+search ─┐            ┌──▶ Tavily   (search, extract, crawl, map, research)
+extract ┤            │
+crawl ──┼──▶ surf ───┼──▶ Parallel (search, extract, research async)
+map  ───┤            │
+research┘            └──▶ Brave    (search only — own index)
 ```
 
 | | |
 |---|---|
-| **Status** | v1.0.0 |
-| **Runtime** | Node ≥ 18, bash. Zero npm deps. |
-| **Storage** | `~/.config/surf/keys.json` (chmod 600). Never read from env at runtime. |
+| **Status** | v2.1.0 (npm) |
+| **Install** | `npm i -g surf-skill` (Linux · macOS · Windows) |
+| **Runtime** | Node ≥ 18. Zero npm deps. |
+| **Storage** | `~/.config/surf/keys.json` (chmod 600). Never read from env at runtime by the CLI. |
 | **Supported agents** | Claude Code · GitHub Copilot CLI · Pi Coding Agent · OpenCode · Codex CLI |
 | **Spec** | [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) |
 
@@ -200,7 +216,7 @@ If you see timeouts, the order of fixes:
 |---|---|---|
 | `setup` | Interactive wizard to add keys (TTY) | n/a |
 | `project-config` | Write per-project bash-timeout config | n/a |
-| `search <q> [q2 ...]` | Web search; multiple positional args = **batch** | tavily, parallel |
+| `search <q> [q2 ...]` | Web search; multiple positional args = **batch** | tavily, parallel, **brave** |
 | `extract <url> ...` | Pull markdown from URLs | tavily, parallel |
 | `crawl <url>` | Recursive site crawl | tavily |
 | `map <url>` | Sitemap discovery | tavily |
@@ -217,13 +233,33 @@ Full reference: `skills/surf-skill/SKILL.md`.
 Global flags every command accepts:
 
 ```
---provider <tavily|parallel>   Force provider (disables fallback)
---no-fallback                  Keep default provider, no cross-provider fallback
---no-cache                     Skip response cache
---json                         Normalized envelope as JSON
---raw-json                     Raw provider response (bypasses cache)
---confirm-expensive            Allow operations estimated > 10 credits
---quiet                        Silence progress logs (stderr)
+--provider <tavily|parallel|brave>  Force provider (disables fallback)
+--mode <fast|normal|slow>           Search tier. Per-provider mapping:
+                                      fast   = Tavily depth=fast / Brave count=5
+                                      normal = default
+                                      slow   = Tavily depth=advanced / Brave count=20
+                                      (Parallel ignores — single mode.)
+--no-fallback                       Keep default provider, no cross-provider fallback
+--no-cache                          Skip response cache
+--json                              Normalized envelope as JSON
+--raw-json                          Raw provider response (bypasses cache)
+--confirm-expensive                 Allow operations estimated > 10 credits
+--quiet                             Silence progress logs (stderr)
+```
+
+### Search modes
+
+```bash
+surf-skill search "X" --mode fast    # 5 results / 1 credit Tavily / minimal latency
+surf-skill search "X" --mode normal  # 10 results / default everywhere
+surf-skill search "X" --mode slow    # 20 results / Tavily advanced / deeper signal
+```
+
+Want to force a specific provider for a given mode?
+
+```bash
+surf-skill search "X" --provider brave --mode slow    # 20 brave results, no fallback
+surf-skill search "X" --provider tavily --mode fast   # Tavily fast tier
 ```
 
 ---

package/SKILL.md

@@ -39,6 +39,7 @@ Or non-interactive:
 ```bash
 surf-skill keys add --provider tavily tvly-...
 surf-skill keys add --provider parallel <key>
+surf-skill keys add --provider brave <key>
 ```
 
 Keys live in `~/.config/surf/keys.json` (chmod 600) — never read from env at
@@ -52,21 +53,34 @@ The connector decides which provider to call based on:
 3. Which keys are healthy (`burned` keys are skipped, auto-reset monthly).
 
 Force a specific provider **only for debugging** with
-`--provider tavily|parallel`. That disables fallback — failure means failure.
+`--provider tavily|parallel|brave`. That disables fallback — failure means failure.
 
 ## Capability table
 
-| Operation | Tavily | Parallel | Default order |
-|---|---|---|---|
-| `search` | ✓ | ✓ | tavily → parallel |
-| `extract` | ✓ | ✓ | tavily → parallel |
-| `crawl` | ✓ | ✗ | tavily only |
-| `map` | ✓ | ✗ | tavily only |
-| `research-start` / `research` | ✓ | ✓ | parallel → tavily |
-| `research-poll` | by `request_id` prefix | by `request_id` prefix | sticky |
+| Operation | Tavily | Parallel | Brave | Default order |
+|---|---|---|---|---|
+| `search` | ✓ | ✓ | ✓ | tavily → parallel → brave |
+| `extract` | ✓ | ✓ | ✗ | tavily → parallel |
+| `crawl` | ✓ | ✗ | ✗ | tavily only |
+| `map` | ✓ | ✗ | ✗ | tavily only |
+| `research-start` / `research` | ✓ | ✓ | ✗ | parallel → tavily |
+| `research-poll` | by `request_id` prefix | by `request_id` prefix | (n/a) | sticky |
 
 When `last_ok_provider` is in the chain, it is promoted to the front.
 
+## Search modes (`--mode`)
+
+`--mode <fast|normal|slow>` is the canonical search-tier flag. Each provider
+maps it differently:
+
+| Mode | Tavily | Parallel | Brave |
+|---|---|---|---|
+| `fast`   | `search_depth=fast` (1 credit, ~1-3 s) | (ignored) | `count=5`  (5 results, fastest) |
+| `normal` (default) | `search_depth=basic` (1 credit, ~2 s) | `/v1/search` | `count=10` (10 results) |
+| `slow`   | `search_depth=advanced` (2 credits, ~5 s) | (ignored) | `count=20` (20 results) |
+
+`--depth basic|advanced` continues to work as a legacy alias for Tavily users.
+
 ## Timeouts per harness — IMPORTANT
 
 This skill runs as a bash command. Each agent harness has its own default
@@ -143,6 +157,7 @@ surf-skill research "narrow question" --model mini --confirm-expensive
 # Keys management
 surf-skill keys add --provider tavily tvly-...
 surf-skill keys add --provider parallel <key>
+surf-skill keys add --provider brave <key>
 surf-skill keys list
 surf-skill keys remove --provider tavily 0
 surf-skill keys reset                    # un-burn all keys

package/bin/surf-skill.mjs

@@ -15,7 +15,7 @@ import { runProjectConfig, formatProjectConfigResult } from '../src/lib/project-
 import { providerFromRequestId } from '../src/lib/providers/index.mjs';
 import { progress, setSilent } from '../src/lib/progress.mjs';
 
-const VERSION = '2.0.0';
+const VERSION = '2.1.0';
 
 // Catch SIGTERM/SIGINT so a harness-driven kill surfaces a useful message
 // instead of dying silently. This is defense-in-depth: dispatch already
@@ -54,7 +54,12 @@ Commands:
   keys <add|remove|list|reset|clear> [...]
 
 Global flags:
-  --provider <tavily|parallel>   Force provider, disables fallback
+  --provider <tavily|parallel|brave>  Force provider, disables fallback
+  --mode <fast|normal|slow>      Search tier (per-provider mapping):
+                                   fast   = Tavily depth=fast   / Brave count=5
+                                   normal = Tavily depth=basic  / Brave count=10 (default)
+                                   slow   = Tavily depth=advanced / Brave count=20
+                                   Parallel ignores (single mode).
   --no-fallback                  Stay on default provider, no cross-provider fallback
   --no-cache                     Skip response cache
   --json                         Print normalized envelope as JSON
@@ -112,9 +117,13 @@ function emitResult(envelope, flags) {
 }
 
 function buildSearchArgs(query, flags) {
+  // --mode is the canonical flag. --depth (Tavily-ism) is still accepted as
+  // legacy alias; if neither is set, default to depth='advanced' (Tavily) which
+  // also resolves to mode='slow' on Brave.
   return {
     query,
-    depth: flags.depth || 'advanced',
+    mode: flags.mode,
+    depth: flags.depth || (flags.mode ? undefined : 'advanced'),
     max: flags.max,
     topic: flags.topic,
     time: flags.time,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "surf-skill",
-  "version": "2.0.0",
-  "description": "Multi-provider web skill (Tavily + Parallel AI) for AI coding agents — CLI + Node library + Anthropic Agent Skill. Auto-fallback, multi-key rotation, per-project timeout config.",
+  "version": "2.1.0",
+  "description": "Multi-provider web skill (Tavily + Parallel AI + Brave Search) for AI coding agents — CLI + Node library + Anthropic Agent Skill. Auto-fallback, multi-key rotation, --mode tiers, per-project timeout config.",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": {
@@ -32,6 +32,7 @@
     "agent-skill",
     "tavily",
     "parallel-ai",
+    "brave-search",
     "web-search",
     "connector",
     "claude-code",

package/src/env.mjs

@@ -1,7 +1,9 @@
 // Key discovery for library mode.
 // Priority (each level can contribute; results merged + deduped):
-//   1. Explicit opts (opts.tavilyKey / opts.tavilyKeys / parallel*)
-//   2. process.env (TAVILY_API_KEYS comma-separated + TAVILY_API_KEY)
+//   1. Explicit opts (opts.tavilyKey / opts.tavilyKeys / parallel* / brave*)
+//   2. process.env  (TAVILY_API_KEYS comma-separated + TAVILY_API_KEY,
+//                    PARALLEL_API_KEYS + PARALLEL_API_KEY,
+//                    BRAVE_API_KEYS + BRAVE_API_KEY)
 //   3. .env file at process.cwd() (lightweight regex parser, no dotenv dep)
 //   4. ~/.config/surf/keys.json (CLI persistent store, fallback only)
 
@@ -39,73 +41,73 @@ function arrayify(v) {
   return Array.isArray(v) ? v.filter(Boolean) : [v].filter(Boolean);
 }
 
+function readFromObject(obj, base) {
+  // base = 'TAVILY' | 'PARALLEL' | 'BRAVE'
+  return [
+    ...splitCsv(obj[`${base}_API_KEYS`]),
+    obj[`${base}_API_KEY`],
+  ].filter(Boolean);
+}
+
 /**
- * Resolve API keys for both providers using the discovery hierarchy.
+ * Resolve API keys for all 3 providers using the discovery hierarchy.
  *
  * @param {object} opts
- * @param {string|string[]} [opts.tavilyKey] - single key or array
- * @param {string[]} [opts.tavilyKeys] - array (alias)
- * @param {string|string[]} [opts.parallelKey] - single or array
- * @param {string[]} [opts.parallelKeys] - array (alias)
- * @param {boolean} [opts.skipDotenv=false] - skip .env scanning
- * @param {boolean} [opts.skipConfigFile=false] - skip ~/.config/surf/keys.json
+ * @param {string|string[]} [opts.tavilyKey|opts.tavilyKeys]
+ * @param {string|string[]} [opts.parallelKey|opts.parallelKeys]
+ * @param {string|string[]} [opts.braveKey|opts.braveKeys]
+ * @param {boolean} [opts.skipDotenv=false]
+ * @param {boolean} [opts.skipConfigFile=false]
  * @param {string} [opts.cwd=process.cwd()]
- * @returns {Promise<{tavily: string[], parallel: string[]}>}
+ * @returns {Promise<{tavily: string[], parallel: string[], brave: string[]}>}
  */
 export async function discoverKeys(opts = {}) {
   const cwd = opts.cwd || process.cwd();
 
   // Level 1: explicit
-  const explicitTavily = [
-    ...arrayify(opts.tavilyKey),
-    ...arrayify(opts.tavilyKeys),
-  ];
-  const explicitParallel = [
-    ...arrayify(opts.parallelKey),
-    ...arrayify(opts.parallelKeys),
-  ];
+  const explicit = {
+    tavily:   [...arrayify(opts.tavilyKey),   ...arrayify(opts.tavilyKeys)],
+    parallel: [...arrayify(opts.parallelKey), ...arrayify(opts.parallelKeys)],
+    brave:    [...arrayify(opts.braveKey),    ...arrayify(opts.braveKeys)],
+  };
 
   // Level 2: process.env
-  const envTavily = [
-    ...splitCsv(process.env.TAVILY_API_KEYS),
-    process.env.TAVILY_API_KEY,
-  ].filter(Boolean);
-  const envParallel = [
-    ...splitCsv(process.env.PARALLEL_API_KEYS),
-    process.env.PARALLEL_API_KEY,
-  ].filter(Boolean);
+  const env = {
+    tavily:   readFromObject(process.env, 'TAVILY'),
+    parallel: readFromObject(process.env, 'PARALLEL'),
+    brave:    readFromObject(process.env, 'BRAVE'),
+  };
 
   // Level 3: .env file
-  let dotenvTavily = [];
-  let dotenvParallel = [];
+  let dotenv = { tavily: [], parallel: [], brave: [] };
   if (!opts.skipDotenv) {
-    const env = await loadDotenv(cwd);
-    dotenvTavily = [
-      ...splitCsv(env.TAVILY_API_KEYS),
-      env.TAVILY_API_KEY,
-    ].filter(Boolean);
-    dotenvParallel = [
-      ...splitCsv(env.PARALLEL_API_KEYS),
-      env.PARALLEL_API_KEY,
-    ].filter(Boolean);
+    const parsed = await loadDotenv(cwd);
+    dotenv = {
+      tavily:   readFromObject(parsed, 'TAVILY'),
+      parallel: readFromObject(parsed, 'PARALLEL'),
+      brave:    readFromObject(parsed, 'BRAVE'),
+    };
   }
 
-  // Level 4: ~/.config/surf/keys.json (only if nothing yet from 1-3)
-  let cfgTavily = [];
-  let cfgParallel = [];
-  const noneSoFarTavily = !explicitTavily.length && !envTavily.length && !dotenvTavily.length;
-  const noneSoFarParallel = !explicitParallel.length && !envParallel.length && !dotenvParallel.length;
-  if (!opts.skipConfigFile && (noneSoFarTavily || noneSoFarParallel)) {
-    try {
-      const state = await loadState();
-      if (noneSoFarTavily) cfgTavily = state.tavily.keys || [];
-      if (noneSoFarParallel) cfgParallel = state.parallel.keys || [];
-    } catch {}
+  // Level 4: ~/.config/surf/keys.json (per-provider, only if 1-3 are empty
+  // for that provider)
+  const cfg = { tavily: [], parallel: [], brave: [] };
+  if (!opts.skipConfigFile) {
+    const needCfg = (p) => !explicit[p].length && !env[p].length && !dotenv[p].length;
+    if (needCfg('tavily') || needCfg('parallel') || needCfg('brave')) {
+      try {
+        const state = await loadState();
+        if (needCfg('tavily'))   cfg.tavily   = state.tavily.keys   || [];
+        if (needCfg('parallel')) cfg.parallel = state.parallel.keys || [];
+        if (needCfg('brave'))    cfg.brave    = state.brave.keys    || [];
+      } catch {}
+    }
   }
 
   return {
-    tavily: [...new Set([...explicitTavily, ...envTavily, ...dotenvTavily, ...cfgTavily])],
-    parallel: [...new Set([...explicitParallel, ...envParallel, ...dotenvParallel, ...cfgParallel])],
+    tavily:   [...new Set([...explicit.tavily,   ...env.tavily,   ...dotenv.tavily,   ...cfg.tavily])],
+    parallel: [...new Set([...explicit.parallel, ...env.parallel, ...dotenv.parallel, ...cfg.parallel])],
+    brave:    [...new Set([...explicit.brave,    ...env.brave,    ...dotenv.brave,    ...cfg.brave])],
   };
 }
 
@@ -114,11 +116,12 @@ export async function discoverKeys(opts = {}) {
  * without touching ~/.config/surf/keys.json.
  */
 export async function buildInMemoryState(opts = {}) {
-  const { tavily, parallel } = await discoverKeys(opts);
+  const { tavily, parallel, brave } = await discoverKeys(opts);
   return {
     schema_version: 1,
-    tavily: { keys: tavily, current: 0, burned: [] },
+    tavily:   { keys: tavily,   current: 0, burned: [] },
     parallel: { keys: parallel, current: 0, burned: [] },
+    brave:    { keys: brave,    current: 0, burned: [] },
     last_ok_provider: null,
     _inMemory: true,
   };

package/src/lib/api/search.mjs

@@ -63,7 +63,8 @@ export async function search(query, opts = {}) {
 function buildArgs(query, opts) {
   return {
     query,
-    depth: opts.depth || 'advanced',
+    mode: opts.mode, // 'fast' | 'normal' | 'slow' (per-provider mapping)
+    depth: opts.depth || (opts.mode ? undefined : 'advanced'),
     max: opts.max,
     topic: opts.topic,
     time: opts.time,

package/src/lib/cost.mjs

@@ -1,6 +1,6 @@
-// Credit estimation. We model both providers on the same "credit" scale that
-// Tavily uses (since that's the only published one). Parallel costs are
-// estimated coarsely from documented processor tiers.
+// Credit estimation. We model all providers on a unified "credit" scale
+// (Tavily uses real credits; Parallel uses processor tiers we map; Brave is
+// metered in USD per query, which we model as 1 credit per search).
 
 import { clamp, ceilDiv } from './flags.mjs';
 
@@ -68,10 +68,23 @@ function estimateParallel(op, args) {
   }
 }
 
+// Brave — metered at ~$0.003/query for /web/search; we report 1 credit as
+// a proxy so the cost guard never blocks Brave searches. Operations Brave
+// doesn't support return Infinity so the chain estimator skips them.
+function estimateBrave(op, _args) {
+  switch (op) {
+    case 'search': return 1;
+    default:        return Infinity;
+  }
+}
+
 export function estimateCreditsForChain(operation, args, chain) {
   let worst = 0;
   for (const p of chain) {
-    const est = p === 'tavily' ? estimateTavily(operation, args) : estimateParallel(operation, args);
+    const est = p === 'tavily'   ? estimateTavily(operation, args)
+              : p === 'parallel' ? estimateParallel(operation, args)
+              : p === 'brave'    ? estimateBrave(operation, args)
+              : 0;
     if (Number.isFinite(est) && est > worst) worst = est;
   }
   return worst;

package/src/lib/harness-install.mjs

@@ -137,6 +137,7 @@ export async function ensureKeysSkeleton() {
       schema_version: 1,
       tavily: { keys: [], current: 0, burned: [] },
       parallel: { keys: [], current: 0, burned: [] },
+      brave: { keys: [], current: 0, burned: [] },
       last_ok_provider: null,
     };
     await fs.writeFile(file, JSON.stringify(skeleton, null, 2) + '\n');

package/src/lib/providers/brave.mjs

@@ -0,0 +1,168 @@
+// Brave Search adapter — talks to https://api.search.brave.com/res/v1 with
+// X-Subscription-Token header.
+//
+// Capability:
+//   - search:    GET /web/search  (only operation supported)
+//   - extract / crawl / map / research-*: NOT supported (Brave has no equivalents)
+//
+// Auth: header `X-Subscription-Token: <key>` (NOT Bearer; NOT ?apikey=).
+// Rate limits: 50 RPS for /web/search (2 RPS for /summarizer/* — not used here).
+// Pricing as of 2026-05: $5/mo credit + metered (~$0.003/query). Free tier
+// (2,000 queries/mo) was discontinued in Feb 2026.
+
+import { compactObject, clamp } from '../flags.mjs';
+
+const BASE = process.env.SURF_BRAVE_API_BASE || 'https://api.search.brave.com/res/v1';
+const DEFAULT_TIMEOUT = Number(process.env.SURF_TIMEOUT_MS) || 45000;
+
+// Mode → count mapping. Brave doesn't have native fast/slow tiers, so we use
+// `count` (max 20) as the differentiator. fast = fewer results, slow = more.
+const MODE_TO_COUNT = { fast: 5, normal: 10, slow: 20 };
+
+export const braveProvider = {
+  name: 'brave',
+  supports: {
+    search: true,
+    extract: false,
+    crawl: false,
+    map: false,
+    'research-start': false,
+    'research-poll': false,
+    usage: false,
+  },
+  search,
+  extract: notSupported('extract'),
+  crawl: notSupported('crawl'),
+  map: notSupported('map'),
+  'research-start': notSupported('research-start'),
+  'research-poll': notSupported('research-poll'),
+  usage: notSupported('usage'),
+  mapError,
+};
+
+function notSupported(op) {
+  return async () => {
+    throw Object.assign(new Error(`brave does not support '${op}'`), {
+      kind: 'not_supported', statusCode: 0,
+    });
+  };
+}
+
+function buildHeaders(key, version) {
+  return {
+    'X-Subscription-Token': key,
+    'Accept': 'application/json',
+    'X-Client-Name': `surf-skill/${version || '2.1.0'}`,
+  };
+}
+
+async function doFetch(path, params, ctx) {
+  const url = new URL(`${BASE}${path}`);
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null && v !== '') url.searchParams.set(k, String(v));
+  }
+  const timeout = ctx.timeout || DEFAULT_TIMEOUT;
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort('timeout'), timeout);
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: buildHeaders(ctx.key, ctx.version),
+      signal: ctl.signal,
+    });
+    clearTimeout(t);
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { raw: text }; }
+    return { status: res.status, ok: res.ok, data, latency_ms: Date.now() - t0 };
+  } catch (e) {
+    clearTimeout(t);
+    if (e.name === 'AbortError' || /timeout/i.test(e.message)) {
+      throw Object.assign(new Error(`Brave request exceeded ${timeout}ms`), { kind: 'network' });
+    }
+    throw Object.assign(new Error(`Brave network error: ${e.message}`), { kind: 'network' });
+  }
+}
+
+function mapError(status, body) {
+  const msg = (body && (body.error?.message || body.message)) || '';
+  if (status === 401) return { kind: 'auth', statusCode: status, message: 'invalid Brave key' };
+  if (status === 402) return { kind: 'auth', statusCode: status, message: msg || 'Brave: insufficient credits / billing required' };
+  if (status === 403) return { kind: 'auth', statusCode: status, message: msg || 'forbidden (plan/billing)' };
+  if (status === 422) return { kind: 'caller_4xx', statusCode: status, message: msg || 'invalid params' };
+  if (status === 429) return { kind: 'rate_limit_429', statusCode: status, message: msg || 'Brave rate limit (50 RPS search)' };
+  if (status >= 500)  return { kind: 'server_5xx', statusCode: status, message: msg || 'Brave server error' };
+  if (status >= 400)  return { kind: 'caller_4xx', statusCode: status, message: msg || `HTTP ${status}` };
+  return { kind: 'caller_4xx', statusCode: status, message: msg || `unexpected HTTP ${status}` };
+}
+
+function asError(status, body) {
+  const m = mapError(status, body);
+  return Object.assign(new Error(`brave ${m.kind} (HTTP ${status}): ${m.message}`), m, { body });
+}
+
+function resolveMode(args) {
+  if (args.mode === 'fast' || args.mode === 'normal' || args.mode === 'slow') return args.mode;
+  // Backward compat with --depth (Tavily-ism):
+  if (args.depth === 'advanced') return 'slow';
+  if (args.depth === 'fast' || args.depth === 'ultra-fast') return 'fast';
+  return 'normal';
+}
+
+async function search(args, ctx) {
+  const query = args.query;
+  if (!query) {
+    throw Object.assign(new Error('brave search requires a query'), {
+      kind: 'caller_4xx', statusCode: 400,
+    });
+  }
+
+  const mode = resolveMode(args);
+  // If user explicitly passed --max, honor it (capped at Brave's max=20);
+  // otherwise derive from mode.
+  const count = args.max
+    ? clamp(Number(args.max), 1, 20)
+    : (MODE_TO_COUNT[mode] || 10);
+
+  const params = compactObject({
+    q: query,
+    count,
+    offset: args.offset != null ? clamp(Number(args.offset), 0, 9) : undefined,
+    country: args.country,
+    search_lang: args.searchLang,
+    ui_lang: args.uiLang,
+    safesearch: args.safesearch,         // 'off' | 'moderate' | 'strict'
+    goggles_id: args.goggle,             // Brave-only ranking filter
+    result_filter: args.resultFilter,    // 'web,news,faq,...'
+    spellcheck: args.spellcheck === false ? 0 : undefined,
+  });
+
+  const { status, ok, data, latency_ms } = await doFetch('/web/search', params, ctx);
+  if (!ok) throw asError(status, data);
+
+  return {
+    provider: 'brave',
+    operation: 'search',
+    raw: data,
+    usage: { credits: 1 }, // ~$0.003/query metered; we report 1 credit as proxy
+    latency_ms,
+    data: {
+      query,
+      // /web/search response may include a `summarizer` block when the user's
+      // plan + query qualify. We surface the summary text as `answer` for
+      // schema parity with Tavily.
+      answer: data.summarizer && (data.summarizer.summary || data.summarizer.title),
+      results: (data.web && data.web.results || []).map(it => ({
+        url: it.url,
+        title: it.title,
+        // Brave returns rich HTML-ish `description`. Caller usually wants
+        // plain-ish text; we pass through as-is.
+        content: it.description || '',
+        score: undefined,         // Brave does not expose a numeric score
+        raw_content: undefined,   // No raw content in /web/search
+        published_date: it.age,   // Brave returns a human string ("2 days ago")
+      })),
+    },
+  };
+}

package/src/lib/providers/index.mjs

@@ -2,15 +2,20 @@
 
 import { tavilyProvider } from './tavily.mjs';
 import { parallelProvider } from './parallel.mjs';
+import { braveProvider } from './brave.mjs';
 
 export const PROVIDERS = {
   tavily: tavilyProvider,
   parallel: parallelProvider,
+  brave: braveProvider,
 };
 
 // Default fallback chain per operation. Adjust with care: order matters.
+// Brave is search-only (no extract/crawl/map/research equivalents). It joins
+// the search chain as the 3rd option — Tavily/Parallel keep their precedence
+// to preserve hot-path behavior for existing users.
 export const capabilityMap = {
-  search:           ['tavily', 'parallel'],
+  search:           ['tavily', 'parallel', 'brave'],
   extract:          ['tavily', 'parallel'],
   crawl:            ['tavily'],
   map:              ['tavily'],

package/src/lib/providers/tavily.mjs

@@ -83,9 +83,16 @@ function wrap(operation, raw, data, latency_ms) {
 }
 
 async function search(args, ctx) {
+  // Mode (canonical) → Tavily search_depth. Falls back to --depth (legacy
+  // alias) and finally to 'basic'.
+  const depth = args.mode === 'fast'   ? 'fast'
+              : args.mode === 'normal' ? 'basic'
+              : args.mode === 'slow'   ? 'advanced'
+              : (args.depth || 'basic');
+
   const body = compactObject({
     query: args.query,
-    search_depth: args.depth || 'basic',
+    search_depth: depth,
     max_results: clamp(Number(args.max) || 5, 1, 20),
     topic: args.topic,
     time_range: args.time,

package/src/lib/setup.mjs

@@ -2,6 +2,7 @@
 // `surf-skill keys add` directly.
 //
 // Multi-key: prompts for N keys per provider (Enter to finish that provider).
+// 3 providers: Tavily, Parallel, Brave.
 
 import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
@@ -13,24 +14,26 @@ const BANNER = `
 │ (Enter empty to finish a provider; Enter twice in a row to
 │ skip it entirely).
 │
-│ Tavily:    https://app.tavily.com    (1,000 free credits/mo)
+│ Tavily:    https://app.tavily.com                       (1,000 free credits/mo)
 │ Parallel:  https://platform.parallel.ai
+│ Brave:     https://api-dashboard.search.brave.com       ($5/mo credit, metered)
 │
 │ Keys live in ${KEYS_FILE} (chmod 600).
 └──────────────────────────────────────────────────────────
 `;
 
 const CHEAT_SHEET_TPL = (counts) => `
-✓ Saved ${counts.tav} Tavily key${counts.tav === 1 ? '' : 's'}, ${counts.par} Parallel key${counts.par === 1 ? '' : 's'}.
+✓ Saved. Now have ${counts.tav} Tavily key${counts.tav === 1 ? '' : 's'}, ${counts.par} Parallel key${counts.par === 1 ? '' : 's'}, ${counts.brv} Brave key${counts.brv === 1 ? '' : 's'}.
 
 Try one of:
   surf-skill search "your query"
-  surf-skill search "q1" "q2" "q3"      # batch (N queries)
+  surf-skill search "q1" "q2" "q3"                # batch (N queries)
+  surf-skill search "x" --provider brave --mode fast
   surf-skill extract https://example.com
   surf-skill keys list
 
 Add another key later with:
-  surf-skill keys add --provider <tavily|parallel> <key>
+  surf-skill keys add --provider <tavily|parallel|brave> <key>
 
 🛠  IMPORTANT — in each project where you'll use surf-skill, run:
       surf-skill project-config
@@ -72,7 +75,8 @@ export async function runSetup() {
   if (!stdin.isTTY) {
     const err = new Error(`'setup' requires a TTY. Use:
   surf-skill keys add --provider tavily <key>
-  surf-skill keys add --provider parallel <key>`);
+  surf-skill keys add --provider parallel <key>
+  surf-skill keys add --provider brave <key>`);
     err.code = 'NO_TTY';
     throw err;
   }
@@ -83,29 +87,39 @@ export async function runSetup() {
   const rl = readline.createInterface({ input: stdin, output: stdout });
   let newTav = [];
   let newPar = [];
+  let newBrv = [];
   try {
     newTav = await promptKeys(rl, 'Tavily', state.tavily.keys);
     stdout.write('\n');
     newPar = await promptKeys(rl, 'Parallel', state.parallel.keys);
+    stdout.write('\n');
+    newBrv = await promptKeys(rl, 'Brave', state.brave.keys);
   } finally {
     rl.close();
   }
 
-  if (!newTav.length && !newPar.length) {
+  if (!newTav.length && !newPar.length && !newBrv.length) {
     stdout.write('\nNo new keys provided. Rerun with: surf-skill setup\n');
-    return { addedTavily: 0, addedParallel: 0 };
+    return { addedTavily: 0, addedParallel: 0, addedBrave: 0 };
   }
 
   for (const k of newTav) state.tavily.keys.push(k);
   for (const k of newPar) state.parallel.keys.push(k);
+  for (const k of newBrv) state.brave.keys.push(k);
   if (state.tavily.keys.length && state.tavily.current >= state.tavily.keys.length) state.tavily.current = 0;
   if (state.parallel.keys.length && state.parallel.current >= state.parallel.keys.length) state.parallel.current = 0;
+  if (state.brave.keys.length && state.brave.current >= state.brave.keys.length) state.brave.current = 0;
 
   await saveStateAtomic(state);
 
   stdout.write(CHEAT_SHEET_TPL({
     tav: state.tavily.keys.length,
     par: state.parallel.keys.length,
+    brv: state.brave.keys.length,
   }));
-  return { addedTavily: newTav.length, addedParallel: newPar.length };
+  return {
+    addedTavily: newTav.length,
+    addedParallel: newPar.length,
+    addedBrave: newBrv.length,
+  };
 }

package/src/lib/state.mjs

@@ -14,7 +14,7 @@ export const LOCK_FILE = join(CONFIG_DIR, '.keys.lock');
 export const CACHE_DIR = join(homedir(), '.cache', 'surf');
 export const LEGACY_CACHE_DIR = join(homedir(), '.cache', 'tavily-skill');
 
-export const PROVIDERS = ['tavily', 'parallel'];
+export const PROVIDERS = ['tavily', 'parallel', 'brave'];
 export const SCHEMA_VERSION = 1;
 
 const BURNED_CAP = 50;
@@ -24,12 +24,9 @@ function blankProvider() {
 }
 
 function blankState() {
-  return {
-    schema_version: SCHEMA_VERSION,
-    tavily: blankProvider(),
-    parallel: blankProvider(),
-    last_ok_provider: null,
-  };
+  const s = { schema_version: SCHEMA_VERSION, last_ok_provider: null };
+  for (const p of PROVIDERS) s[p] = blankProvider();
+  return s;
 }
 
 async function ensureConfigDir() {
@@ -115,6 +112,23 @@ export async function migrateLegacy() {
   }
 }
 
+// Normalize a parsed keys.json to the current schema. Crucially, this
+// auto-adds any provider section that's missing from older keys.json files
+// (e.g. v2.0.x users upgrading to v2.1.x get a fresh `brave` section without
+// any manual migration step).
+function normalizeFullState(parsed) {
+  const out = {
+    schema_version: (parsed && parsed.schema_version) || SCHEMA_VERSION,
+    last_ok_provider: parsed && PROVIDERS.includes(parsed.last_ok_provider)
+      ? parsed.last_ok_provider
+      : null,
+  };
+  for (const p of PROVIDERS) {
+    out[p] = normalizeProvider(parsed && parsed[p]);
+  }
+  return out;
+}
+
 export async function loadState({ skipMonthlyReset = false } = {}) {
   await ensureConfigDir();
   let raw = blankState();
@@ -122,12 +136,7 @@ export async function loadState({ skipMonthlyReset = false } = {}) {
     try {
       const txt = await readFile(KEYS_FILE, 'utf8');
       const parsed = JSON.parse(txt);
-      raw = {
-        schema_version: parsed.schema_version || SCHEMA_VERSION,
-        tavily: normalizeProvider(parsed.tavily),
-        parallel: normalizeProvider(parsed.parallel),
-        last_ok_provider: PROVIDERS.includes(parsed.last_ok_provider) ? parsed.last_ok_provider : null,
-      };
+      raw = normalizeFullState(parsed);
     } catch {
       raw = blankState();
     }
@@ -142,12 +151,7 @@ export async function saveStateAtomic(state) {
   await ensureConfigDir();
   await acquireLock();
   try {
-    const safe = {
-      schema_version: SCHEMA_VERSION,
-      tavily: normalizeProvider(state.tavily),
-      parallel: normalizeProvider(state.parallel),
-      last_ok_provider: PROVIDERS.includes(state.last_ok_provider) ? state.last_ok_provider : null,
-    };
+    const safe = normalizeFullState(state);
     const tmp = KEYS_FILE + '.tmp';
     const payload = JSON.stringify(safe, null, 2);
     await writeFile(tmp, payload, { mode: 0o600 });