webctx 0.2.7 → 0.2.9

package/AGENTS.md

@@ -47,13 +47,14 @@ Direct commands:
 Preserve these commands unless the user explicitly asks to change them:
 
 - `webctx search <query> [--exclude domain1,domain2] [--keyword phrase]`
+- `webctx status` and `webctx providers enable|disable <brave|tavily|exa>`
 - `webctx read-link <url>`
 - `webctx map-site <url>`
 - `webctx --version`
 
 Behavioral expectations:
 
-- `search` combines Brave, Tavily, and Exa results, then re-ranks them with duplicate-aware scoring.
+- `search` combines enabled Brave, Tavily, and Exa results, then re-ranks them with duplicate-aware scoring; an unavailable Exa can fall back to quoted-phrase Brave/Tavily queries for `--keyword` (not a strict text filter).
 - `read-link` keeps the current GitHub raw-content and `.md` fast paths. Firecrawl uses its built-in 30-minute cache, automatic and enhanced proxies, then browser extraction as a final fallback.
 - `map-site` keeps the current Firecrawl map request settings.
 - The CLI should remain agent-friendly and emit plain markdown/text output.
@@ -100,3 +101,11 @@ When cutting a release, update `src/content/docs/changelog.md` before tagging.
 - Do not include docs-site-only changes such as site styling, Zuedocs/package bumps, deploy plumbing, footer/layout changes, or documentation navigation changes.
 - Rewrite commit subjects into clear release notes instead of pasting raw commit messages.
 - If a release contains only tagging/release metadata, write: `Maintenance release. No direct code behavior changes beyond release preparation.`
+
+### Docs deployment
+
+The Docs GitHub Actions workflow deploys production only for the watched site paths; Vercel Git auto-deployments and `ignoreCommand` stay disabled. Keep the project-scoped `VERCEL_TOKEN` Actions secret and ID variables configured. Check Astro locally; builds run in CI.
+
+### Origo deployment
+
+The separate `Origo API` GitHub Actions workflow deploys the Go function only for changes to its import graph and Vercel configuration. Use `VERCEL_ORIGO_TOKEN` and `VERCEL_ORIGO_PROJECT_ID` exclusively for Origo; never substitute the WebCTX Docs token or a static `--prebuilt` site bundle. Keep the `/mcp` rewrite and Origo production environment variables intact.

package/CONTRIBUTORS.md

@@ -108,9 +108,9 @@ gh workflow run npm-publish-retry.yml --repo amxv/webctx --ref main -f version=0
 
 ## Origo deployment
 
-The `origo-api` Vercel project is linked to this GitHub repo and uses `ORIGO_DEPLOYMENT=1` to select its Go Function configuration. It needs `ORIGO_API_KEY` and `FIRECRAWL_API_KEY` production environment variables; optionally add `GH_TOKEN` for native authenticated GitHub reads. The docs project remains `webctx-docs` and never receives the Origo connection key.
+The `origo-api` Vercel project uses `ORIGO_DEPLOYMENT=1` to select its Go Function configuration. It needs `ORIGO_API_KEY` and `FIRECRAWL_API_KEY` production environment variables; optionally add `GH_TOKEN` for native authenticated GitHub reads. The docs project remains `webctx-docs` and never receives the Origo connection key.
 
-Both projects deploy automatically from `main`. `scripts/should-build.mjs` gates docs and API builds independently, while `v*` GitHub tags still drive the CLI release workflow.
+The independent `Docs` and `Origo API` GitHub Actions workflows filter their own build inputs before deploying to Vercel. Origo uses the `VERCEL_ORIGO_TOKEN` Actions secret and `VERCEL_ORIGO_PROJECT_ID` variable, separate from the docs credentials. Git-triggered Vercel deployments are disabled; `v*` tags still drive CLI releases.
 
 ## Notes on package naming
 

package/README.md

@@ -95,7 +95,7 @@ Recognized native GitHub auth, private/not-found, and rate-limit failures stay a
 
 ## Search
 
-Normal search asks Brave, Tavily, and Exa, removes duplicate URLs, automatically reads promising sources, follows relevant links, and returns excerpts plus the ranked list. Alexandria discovery is included when available; use `execute` when you need provider-native data.
+Normal search asks the enabled Brave, Tavily, and Exa providers, removes duplicate URLs, automatically reads promising sources, follows relevant links, and returns excerpts plus the ranked list. One working search provider is enough; Alexandria discovery is included when available. Use `execute` when you need provider-native data.
 
 ```bash
 webctx search "next.js server components"
@@ -103,6 +103,20 @@ webctx search "react hooks" --exclude youtube.com,medium.com
 webctx search "drizzle orm" --keyword "migration guide"
 ```
 
+### Enable or disable search providers
+
+```bash
+webctx status                 # enabled/disabled providers and locally configured keys
+webctx providers disable exa  # stop all Exa search requests, even with a key present
+webctx providers enable exa   # turn Exa back on later
+webctx providers disable brave
+webctx providers enable brave
+```
+
+Provider settings persist across runs, independently of environment variables and Keychain credentials. The settings file lives in the OS user config directory (`webctx/config.json`); set `WEBCTX_CONFIG_FILE` to override its location. Disabled providers are never queried. `status` only reports key presence, **not** live credit balances or API health.
+
+`--keyword` prefers Exa's strict include-text filter when available. If Exa is disabled, unconfigured, or fails, Brave/Tavily search for the quoted phrase instead; the output explicitly notes that this fallback cannot guarantee the phrase appears in the page text. Firecrawl is a separate reading/site-map/Alexandria integration, not one of these three search providers.
+
 ## Map a site
 
 Use `map-site` when you want to discover the useful pages before reading them.
@@ -131,7 +145,7 @@ FIRECRAWL_API_KEY=...
 GH_TOKEN=...
 ```
 
-- `BRAVE_API_KEY`, `TAVILY_API_KEY`, and `EXA_API_KEY` power normal `search`.
+- `BRAVE_API_KEY`, `TAVILY_API_KEY`, and `EXA_API_KEY` power normal `search`. Configure any one or more, and optionally disable providers you no longer want to query.
 - `FIRECRAWL_API_KEY` powers `map-site`, page-crawl fallbacks, and Alexandria discovery/inspection/paid execution.
 - `GH_TOKEN` or `GITHUB_TOKEN` is optional. It increases GitHub capacity and unlocks reads such as blame, Discussions, some Actions job logs, private resources the token can access, and richer PR review state.
 

package/internal/app/app.go

@@ -16,8 +16,6 @@ const commandName = "webctx"
 var version = buildinfo.CurrentVersion()
 
 func Run(args []string, stdout, stderr io.Writer) int {
-	loadEnvLocal()
-
 	if len(args) == 0 || isHelpArg(args[0]) {
 		_, _ = fmt.Fprintln(stdout, usageText())
 		return 0
@@ -29,6 +27,37 @@ func Run(args []string, stdout, stderr io.Writer) int {
 	}
 
 	tool := args[0]
+	isProviderTool := tool == "status" || tool == "providers" || tool == "provider"
+	isProviderStatus := (tool == "status" && len(args) == 1) ||
+		((tool == "providers" || tool == "provider") && (len(args) == 1 || (len(args) == 2 && args[1] == "status")))
+	if !isProviderTool || isProviderStatus {
+		loadEnvLocal()
+	}
+	if isProviderTool {
+		if isProviderStatus {
+			if err := printProviderStatus(stdout); err != nil {
+				_, _ = fmt.Fprintln(stderr, err)
+				return 1
+			}
+			return 0
+		}
+		if tool == "status" || len(args) != 3 || (args[1] != "enable" && args[1] != "disable") {
+			_, _ = fmt.Fprintln(stderr, "Usage: webctx providers [status|enable <brave|tavily|exa>|disable <brave|tavily|exa>]")
+			return 1
+		}
+		enabled := args[1] == "enable"
+		if _, err := setSearchProviderEnabled(args[2], enabled); err != nil {
+			_, _ = fmt.Fprintln(stderr, err)
+			return 1
+		}
+		state := "disabled"
+		if enabled {
+			state = "enabled"
+		}
+		_, _ = fmt.Fprintf(stdout, "%s %s. Run 'webctx status' to inspect all providers.\n", strings.ToLower(strings.TrimSpace(args[2])), state)
+		return 0
+	}
+
 	flags, positional := parseArgs(args[1:])
 	input := ""
 	if len(positional) > 0 {
@@ -89,6 +118,7 @@ func Run(args []string, stdout, stderr io.Writer) int {
 			result, e := MapSitePage(MapSiteInput{
 				URL: input, Limit: limit, Offset: offset, Query: flags["query"],
 				PathPrefix: flags["path-prefix"], Language: flags["language"],
+				limitProvided: flags["limit"] != "",
 			})
 			if e != nil {
 				return cliDataError(stderr, e)
@@ -196,6 +226,8 @@ func usageText() string {
 
 Usage:
   webctx search <query> [--exclude domain1,domain2] [--keyword phrase]
+  webctx status
+  webctx providers [status|enable <brave|tavily|exa>|disable <brave|tavily|exa>]
   webctx read-link <url> [--question 'what to find']
   webctx map-site <url> [--query topic] [--limit 30] [--offset 0] [--path-prefix /api] [--language en|all]
   webctx research [question] [--view sources|groups|operations] [--sources IDs] [--include inputs,output,examples] [--limit N] [--offset N]
@@ -207,6 +239,8 @@ Examples:
   webctx search "next.js server components"
   webctx search "react hooks" --exclude youtube.com,vimeo.com
   webctx search "drizzle orm" --keyword "migration guide"
+  webctx providers disable exa
+  webctx providers enable exa
   webctx research "podcast conversations about AI agents"
   webctx research --view sources --limit 5
   webctx inspect particle/podcasts/episodes/search

package/internal/app/app_test.go

@@ -84,6 +84,7 @@ func TestScoreAndRankResultsPreservesInsertionOrderForTies(t *testing.T) {
 }
 
 func TestSearchMissingCredentialsErrorIsHelpful(t *testing.T) {
+	t.Setenv("WEBCTX_CONFIG_FILE", filepath.Join(t.TempDir(), "config.json"))
 	t.Setenv("BRAVE_API_KEY", "")
 	t.Setenv("TAVILY_API_KEY", "")
 	t.Setenv("EXA_API_KEY", "")

package/internal/app/data_audit_test.go

@@ -34,6 +34,16 @@ func TestAuditPerRecordBoundsFromActualOperations(t *testing.T) {
 				"options": []any{map[string]any{"name": "ids", "type": "array"}}},
 			map[string]any{"ids": []any{"A", "B"}}, 4,
 		},
+		{
+			map[string]any{"id": "fullenrich/contacts/mobile", "creditsCost": 175, "perRecord": true,
+				"response": map[string]any{"paginated": true, "about": "One record in results when a mobile number was found, an empty array when not."}},
+			map[string]any{"linkedin_url": "https://www.linkedin.com/in/example-test-person/"}, 175,
+		},
+		{
+			map[string]any{"id": "example/search", "creditsCost": 2, "perRecord": true,
+				"options": []any{map[string]any{"name": "k", "type": "integer"}, map[string]any{"name": "limit", "type": "integer"}}},
+			map[string]any{"limit": 1, "k": 120}, 240,
+		},
 	}
 	for _, tt := range tests {
 		got, err := expectedCallCredits(tt.contract, tt.inputs)
@@ -43,6 +53,92 @@ func TestAuditPerRecordBoundsFromActualOperations(t *testing.T) {
 	}
 }
 
+func TestFilteredCataloguePaginationBeyondFirstHundred(t *testing.T) {
+	previous := http.DefaultClient
+	t.Cleanup(func() { http.DefaultClient = previous })
+	t.Setenv("FIRECRAWL_API_KEY", "test-filtered-pagination")
+	const total = 215
+	var upstreamOffsets []int
+	http.DefaultClient = &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		if req.URL.Path != "/v2/scrape" {
+			return nil, fmt.Errorf("unexpected endpoint %s", req.URL.Path)
+		}
+		var body map[string]any
+		if err := json.NewDecoder(req.Body).Decode(&body); err != nil {
+			return nil, err
+		}
+		options := mapField(mapField(body["alexandria"])["options"])
+		offset, _ := numberField(options["offset"])
+		upstreamOffsets = append(upstreamOffsets, int(offset))
+		start, end := int(offset), int(offset)+100
+		if end > total {
+			end = total
+		}
+		var items []any
+		for i := start; i < end; i++ {
+			items = append(items, map[string]any{
+				"id":   fmt.Sprintf("fred-stlouisfed-org/data/series_%03d", i),
+				"name": "Inflation series observations", "description": "Retrieve inflation observations",
+				"creditsCost": 5, "provider": "fred-stlouisfed-org",
+			})
+		}
+		encoded, _ := json.Marshal(map[string]any{"success": true, "data": map[string]any{
+			"alexandria": []any{map[string]any{"provider": "firecrawl", "capability": "find-tools",
+				"data": map[string]any{"items": items, "total": total}}}}})
+		return testHTTPResponse(req, 200, string(encoded), nil), nil
+	})}
+	input := ResearchDataInput{Query: "inflation series", Mode: "ranked", Sources: []string{"fred-stlouisfed-org"}, Limit: 10}
+	first, err := ResearchData(input)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first["ranking_incomplete"] != true || first["ranking_scope"] != "catalogue_page" {
+		t.Fatalf("ranked first page should disclose scope: %+v", first)
+	}
+	seen := map[string]bool{}
+	pages := 0
+	next := first
+	for {
+		pages++
+		rows := next["results"].([]map[string]any)
+		if len(rows) == 0 {
+			t.Fatalf("empty page %d", pages)
+		}
+		for _, row := range rows {
+			id := row["id"].(string)
+			if seen[id] {
+				t.Fatalf("pagination repeated %s", id)
+			}
+			seen[id] = true
+		}
+		cont := mapField(next["next"])
+		if cont == nil {
+			break
+		}
+		if pages > 30 {
+			t.Fatal("pagination did not terminate")
+		}
+		args := cont["arguments"].(ResearchDataInput)
+		next, err = ResearchData(args)
+		if err != nil {
+			t.Fatalf("page %d: %v", pages, err)
+		}
+	}
+	if len(seen) != total || pages != 22 {
+		t.Fatalf("pagination missed items: got %d of %d over %d pages", len(seen), total, pages)
+	}
+	hasSecondBatch := false
+	for _, offset := range upstreamOffsets {
+		if offset == 100 {
+			hasSecondBatch = true
+			break
+		}
+	}
+	if !hasSecondBatch {
+		t.Fatalf("never fetched beyond the first 100 entries: %v", upstreamOffsets)
+	}
+}
+
 func TestAuditPaginationAdaptersPreserveFilters(t *testing.T) {
 	tests := []struct {
 		name   string
@@ -327,6 +423,46 @@ func TestAuditWorkerIdempotentReplayAndCollision(t *testing.T) {
 	}
 }
 
+func TestConcurrentSameIDHasExactlyOnePaidExecution(t *testing.T) {
+	mock := installDataTestTransport(t)
+	const workers = 12
+	id := "audit-parallel-replay-20261010"
+	input := ExecuteDataInput{RequestID: id, Calls: []DataCall{{
+		ID:     "particle/podcasts/episodes/search",
+		Inputs: map[string]any{"semantic_search": "AI agents", "limit": float64(2)},
+	}}}
+	start := make(chan struct{})
+	type result struct {
+		output map[string]any
+		err    error
+	}
+	out := make(chan result, workers)
+	for range workers {
+		go func() {
+			<-start
+			response, err := ExecuteData(input)
+			out <- result{response, err}
+		}()
+	}
+	close(start)
+	replays := 0
+	for range workers {
+		r := <-out
+		if r.err != nil {
+			t.Fatalf("same-ID concurrent request failed: %v", r.err)
+		}
+		if r.output["replayed"] == true {
+			replays++
+		}
+	}
+	mock.mu.Lock()
+	calls := mock.executions
+	mock.mu.Unlock()
+	if calls != 1 || replays != workers-1 {
+		t.Fatalf("concurrent same-ID calls executed %d provider requests; %d cached replays; wanted 1 and %d", calls, replays, workers-1)
+	}
+}
+
 func TestAuditMixedTermsBatchKeepsIndependentResultsAndCredits(t *testing.T) {
 	previous := http.DefaultClient
 	t.Cleanup(func() { http.DefaultClient = previous })
@@ -374,7 +510,7 @@ func TestAuditMixedTermsBatchKeepsIndependentResultsAndCredits(t *testing.T) {
 		{ID: "fred/data/search", Inputs: map[string]any{"query": "inflation"}},
 		{ID: "sec/data/search", Inputs: map[string]any{"query": "filings"}},
 	}
-	result, err := ExecuteData(ExecuteDataInput{Calls: calls})
+	result, err := ExecuteData(ExecuteDataInput{Calls: calls, RequestID: "audit-partial-replay-20261010"})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -400,6 +536,11 @@ func TestAuditMixedTermsBatchKeepsIndependentResultsAndCredits(t *testing.T) {
 	if paid["particle"] != 1 || paid["fred"] != 1 || paid["sec"] != 1 {
 		t.Fatalf("provider calls were not independent: %+v", paid)
 	}
+	replayed, err := ExecuteData(ExecuteDataInput{Calls: calls, RequestID: "audit-partial-replay-20261010"})
+	if err != nil || replayed["replayed"] != true || paid["fred"] != 1 || paid["sec"] != 1 ||
+		replayed["credits_charged_this_request"] != 0 {
+		t.Fatalf("replay of partial batch re-executed charged successes: reply=%+v paid=%+v error=%v", replayed, paid, err)
+	}
 }
 
 func TestAuditHighPriceOperationCannotBeRecommendedAsRunnable(t *testing.T) {

package/internal/app/data_execute.go

@@ -210,14 +210,16 @@ func expectedCallCredits(contract map[string]any, inputs map[string]any) (int, e
 		count := 0.0
 		for _, key := range []string{"limit", "k", "top_k", "topK", "per_page", "page_size", "max_results", "count", "size", "num_results", "max_records", "results_per_page"} {
 			if n, ok := numberField(inputs[key]); ok && n >= 1 {
-				count = n
-				break
+				// Providers occasionally accept several independent count
+				// fields. Use the largest explicit bound instead of
+				// underestimating charges from the first matching key.
+				count = math.Max(count, n)
 			}
 		}
 		// For bulk identifier lookups, a response may be charged per input.
 		for _, key := range []string{"ids", "domains", "urls", "companies", "people", "symbols"} {
-			if records := listField(inputs[key]); count == 0 && len(records) > 0 {
-				count = float64(len(records))
+			if records := listField(inputs[key]); len(records) > 0 {
+				count = math.Max(count, float64(len(records)))
 			}
 		}
 		if count == 0 {
@@ -226,7 +228,7 @@ func expectedCallCredits(contract map[string]any, inputs map[string]any) (int, e
 				for _, key := range []string{"limit", "k", "top_k", "topK", "per_page", "page_size", "max_results", "count", "size", "num_results", "max_records", "results_per_page"} {
 					if stringField(f["name"]) == key {
 						if n, ok := numberField(f["default"]); ok && n >= 1 {
-							count = n
+							count = math.Max(count, n)
 						}
 					}
 				}
@@ -252,6 +254,20 @@ func expectedCallCredits(contract map[string]any, inputs map[string]any) (int, e
 					count = 1
 				}
 			}
+			// FullEnrich's contact mobile enrichment is per one result even
+			// though its contract sets paginated=true. The response expressly
+			// states "One record in results", with empty/no-match free.
+			response := mapField(contract["response"])
+			description := strings.ToLower(stringField(response["about"]))
+			if count == 0 && strings.Contains(description, "one record in results") &&
+				(strings.HasSuffix(id, "/mobile") || strings.HasSuffix(id, "/lookup")) {
+				for _, key := range []string{"linkedin_url", "first_name", "domain", "professional_network_url"} {
+					if strings.TrimSpace(stringField(inputs[key])) != "" {
+						count = 1
+						break
+					}
+				}
+			}
 		}
 		if count == 0 {
 			return 0, dataError("unbounded_per_record_cost",
@@ -476,6 +492,8 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 		}
 	}
 	if input.RequestID != "" {
+		unlock := lockPaidRequest(requestID)
+		defer unlock()
 		if cached, err := cachedPaidReplay(requestID, input.Calls); err != nil {
 			return nil, err
 		} else if cached != nil {
@@ -540,9 +558,10 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 	if input.Raw {
 		output["raw"] = rawResponses
 	}
-	if failed == 0 {
-		storePaidReplay(requestID, input.Calls, output)
-	}
+	// Cache partial responses too. Retrying a mixed batch must not resubmit
+	// already successful paid operations just because a different provider
+	// rejected its terms.
+	storePaidReplay(requestID, input.Calls, output)
 	return output, nil
 }
 

package/internal/app/data_replay.go

@@ -20,6 +20,41 @@ var paidReplayMemory = struct {
 	items map[string]localPaidReplay
 }{items: map[string]localPaidReplay{}}
 
+// In a single warm worker, serialize requests with the same idempotency key.
+// Without this, two concurrent requests can both miss the replay cache and
+// execute before either writes the receipt.
+type paidReplayGate struct {
+	mu    sync.Mutex
+	users int
+}
+
+var paidReplayGates = struct {
+	sync.Mutex
+	items map[string]*paidReplayGate
+}{items: map[string]*paidReplayGate{}}
+
+func lockPaidRequest(id string) func() {
+	key := localReplayKey(id)
+	paidReplayGates.Lock()
+	gate := paidReplayGates.items[key]
+	if gate == nil {
+		gate = &paidReplayGate{}
+		paidReplayGates.items[key] = gate
+	}
+	gate.users++
+	paidReplayGates.Unlock()
+	gate.mu.Lock()
+	return func() {
+		gate.mu.Unlock()
+		paidReplayGates.Lock()
+		gate.users--
+		if gate.users == 0 {
+			delete(paidReplayGates.items, key)
+		}
+		paidReplayGates.Unlock()
+	}
+}
+
 func localReplayKey(id string) string {
 	h := sha256.Sum256([]byte(os.Getenv("FIRECRAWL_API_KEY") + "\x00" + id))
 	return hex.EncodeToString(h[:])

package/internal/app/data_research.go

@@ -70,6 +70,12 @@ func normalizeResearchInput(input ResearchDataInput) (ResearchDataInput, string,
 	if input.Offset < 0 || input.Offset > 100000 {
 		return input, "", nil, dataError("invalid_offset", "offset must be between 0 and 100000.")
 	}
+	if input.Mode == "ranked" && input.Offset > 0 && strings.TrimSpace(input.Query) != "" &&
+		len(input.Sources) == 0 && len(input.URLs) == 0 && len(input.Groups) == 0 &&
+		len(input.Categories) == 0 && len(input.Operations) == 0 {
+		return input, "", nil, dataError("ranked_search_not_pageable",
+			"Ranked semantic search has no native pagination cursor. Use mode=catalogue with offset, or supply a source/category filter to browse and rerank catalogue pages.")
+	}
 	for _, target := range input.URLs {
 		if err := validateSourceURL(target); err != nil {
 			return input, "", nil, dataError("invalid_url", "Website filters require public HTTP(S) URLs.")
@@ -212,11 +218,13 @@ func ResearchData(input ResearchDataInput) (map[string]any, error) {
 		if localFilteredRanking {
 			// Provider-specified lexical filters can exclude operations whose
 			// descriptions describe the requested data indirectly. Fetch a
-			// catalogue slice from the actual source, then rank it ourselves.
+			// catalogue page from the actual source, then rank that page.
+			// Do not reset every continuation to offset zero: large sources
+			// can have hundreds of operations.
 			delete(options, "query")
 			options["limit"] = 100
-			options["offset"] = 0
-			note = "The source/category filters select candidates first. The question ranks those candidates locally, rather than excluding matching source operations."
+			options["offset"] = (input.Offset / 100) * 100
+			note = "Source/category filters select candidates first. The question ranks each catalogue page locally (up to 100 operations per page); this is not a global ranking across unvisited pages."
 			if input.Mode != "catalogue" {
 				mode = "ranked_filtered"
 			}
@@ -261,7 +269,7 @@ func ResearchData(input ResearchDataInput) (map[string]any, error) {
 	}
 	if localFilteredRanking {
 		count := len(items)
-		start := input.Offset
+		start := input.Offset % 100
 		if start > count {
 			start = count
 		}
@@ -270,12 +278,16 @@ func ResearchData(input ResearchDataInput) (map[string]any, error) {
 			end = count
 		}
 		items = items[start:end]
-		if count > end {
+		sourceTotal, hasTotal := numberField(total)
+		more := count > end || (hasTotal && sourceTotal > float64((input.Offset/100)*100+count))
+		if more {
 			next = map[string]any{"tool": "research", "arguments": ResearchDataInput{
 				Query: input.Query, Mode: input.Mode, URLs: input.URLs, Sources: input.Sources,
 				Categories: input.Categories, Groups: input.Groups, View: niceDataView(view),
-				Include: input.Include, Limit: input.Limit, Offset: end,
+				Include: input.Include, Limit: input.Limit, Offset: input.Offset + len(items),
 			}}
+		} else {
+			next = nil
 		}
 	}
 	results := make([]map[string]any, 0, len(items))
@@ -359,6 +371,12 @@ func ResearchData(input ResearchDataInput) (map[string]any, error) {
 	if note != "" {
 		output["mode_note"] = note
 	}
+	if localFilteredRanking {
+		output["ranking_scope"] = "catalogue_page"
+		if sourceTotal, ok := numberField(total); ok {
+			output["ranking_incomplete"] = sourceTotal > 100
+		}
+	}
 	if len(input.URLs) > 0 && len(input.Sources) > 0 {
 		output["resolved_url_sources"] = input.Sources
 	}

package/internal/app/providers.go

@@ -0,0 +1,161 @@
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+)
+
+// These are the configurable search providers. Firecrawl powers independent
+// read-link, map-site, and Alexandria operations, not federated web search.
+var searchProviderKeys = []struct {
+	name string
+	key  string
+}{
+	{"brave", "BRAVE_API_KEY"},
+	{"tavily", "TAVILY_API_KEY"},
+	{"exa", "EXA_API_KEY"},
+}
+
+type providerConfig struct {
+	DisabledProviders []string `json:"disabled_providers,omitempty"`
+}
+
+func providerConfigPath() (string, error) {
+	if custom := strings.TrimSpace(os.Getenv("WEBCTX_CONFIG_FILE")); custom != "" {
+		return custom, nil
+	}
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		return "", fmt.Errorf("locate WebCTX config directory: %w", err)
+	}
+	return filepath.Join(dir, "webctx", "config.json"), nil
+}
+
+func readProviderConfig(path string) (providerConfig, error) {
+	contents, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return providerConfig{}, nil // all providers default to enabled
+	}
+	if err != nil {
+		return providerConfig{}, fmt.Errorf("read provider settings %s: %w", path, err)
+	}
+	var config providerConfig
+	if err := json.Unmarshal(contents, &config); err != nil {
+		return providerConfig{}, fmt.Errorf("invalid provider settings %s: %w", path, err)
+	}
+	return config, nil
+}
+
+func currentProviderConfig() (providerConfig, error) {
+	path, err := providerConfigPath()
+	if err != nil {
+		return providerConfig{}, err
+	}
+	return readProviderConfig(path)
+}
+
+func (c providerConfig) enabled(name string) bool {
+	return !slices.Contains(c.DisabledProviders, name)
+}
+
+func validSearchProvider(name string) bool {
+	for _, p := range searchProviderKeys {
+		if p.name == name {
+			return true
+		}
+	}
+	return false
+}
+
+func setSearchProviderEnabled(name string, enabled bool) (string, error) {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if !validSearchProvider(name) {
+		return "", fmt.Errorf("unknown search provider %q (choose brave, tavily, or exa)", name)
+	}
+	path, err := providerConfigPath()
+	if err != nil {
+		return "", err
+	}
+	config, err := readProviderConfig(path)
+	if err != nil {
+		return "", err
+	}
+	if config.enabled(name) == enabled {
+		return path, nil
+	}
+	if enabled {
+		config.DisabledProviders = slices.DeleteFunc(config.DisabledProviders, func(p string) bool { return p == name })
+	} else {
+		config.DisabledProviders = append(config.DisabledProviders, name)
+	}
+	slices.Sort(config.DisabledProviders)
+	if err := writeProviderConfig(path, config); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+func writeProviderConfig(path string, config providerConfig) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return fmt.Errorf("create provider config directory: %w", err)
+	}
+	data, err := json.MarshalIndent(config, "", "  ")
+	if err != nil {
+		return err
+	}
+	file, err := os.CreateTemp(filepath.Dir(path), ".webctx-config-*")
+	if err != nil {
+		return fmt.Errorf("write provider settings: %w", err)
+	}
+	defer os.Remove(file.Name())
+	if err := file.Chmod(0o600); err != nil {
+		_ = file.Close()
+		return err
+	}
+	if _, err := file.Write(append(data, '\n')); err != nil {
+		_ = file.Close()
+		return err
+	}
+	if err := file.Close(); err != nil {
+		return err
+	}
+	if err := os.Rename(file.Name(), path); err != nil {
+		return fmt.Errorf("save provider settings: %w", err)
+	}
+	return nil
+}
+
+func printProviderStatus(out io.Writer) error {
+	path, err := providerConfigPath()
+	if err != nil {
+		return err
+	}
+	config, err := readProviderConfig(path)
+	if err != nil {
+		return err
+	}
+	_, _ = fmt.Fprintf(out, "Search providers (settings: %s)\n", path)
+	for _, p := range searchProviderKeys {
+		state, key := "enabled", "key missing"
+		if !config.enabled(p.name) {
+			state = "disabled"
+		}
+		if strings.TrimSpace(os.Getenv(p.key)) != "" {
+			key = "key configured"
+		}
+		_, _ = fmt.Fprintf(out, "  %-7s %-9s %s\n", p.name, state, key)
+	}
+	_, _ = fmt.Fprintln(out, "\nFirecrawl (page reading, site maps, and Alexandria; separate from search):")
+	if strings.TrimSpace(os.Getenv("FIRECRAWL_API_KEY")) != "" {
+		_, _ = fmt.Fprintln(out, "  key configured")
+	} else {
+		_, _ = fmt.Fprintln(out, "  key missing")
+	}
+	_, _ = fmt.Fprintln(out, "\nKey presence is local configuration only; quotas and API availability are not checked.")
+	return nil
+}

package/internal/app/providers_test.go

@@ -0,0 +1,302 @@
+package app
+
+import (
+	"bytes"
+	"compress/gzip"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+func TestProviderCommandsPersistAndReport(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "webctx", "config.json")
+	t.Setenv("WEBCTX_CONFIG_FILE", path)
+	t.Setenv("BRAVE_API_KEY", "test-brave-secret")
+	t.Setenv("TAVILY_API_KEY", "")
+	t.Setenv("EXA_API_KEY", "test-exa-secret")
+	t.Setenv("FIRECRAWL_API_KEY", "")
+
+	run := func(args ...string) (int, string, string) {
+		t.Helper()
+		var out, errOut bytes.Buffer
+		code := Run(args, &out, &errOut)
+		return code, out.String(), errOut.String()
+	}
+	if code, text, errText := run("status"); code != 0 || !strings.Contains(text, "exa     enabled") || !strings.Contains(text, "brave   enabled") || errText != "" {
+		t.Fatalf("default status: code=%d text=%q error=%q", code, text, errText)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("status should not create config file, got error %v", err)
+	}
+	if code, text, errText := run("providers", "disable", "ExA"); code != 0 || !strings.Contains(text, "exa disabled") || errText != "" {
+		t.Fatalf("disable: code=%d text=%q error=%q", code, text, errText)
+	}
+	if code, text, _ := run("providers"); code != 0 || !strings.Contains(text, "exa     disabled") || !strings.Contains(text, "key configured") {
+		t.Fatalf("persisted status: code=%d text=%q", code, text)
+	} else if strings.Contains(text, "test-exa-secret") || strings.Contains(text, "test-brave-secret") {
+		t.Fatalf("status exposed a credential: %q", text)
+	}
+	content, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var config providerConfig
+	if err := json.Unmarshal(content, &config); err != nil || !strings.EqualFold(strings.Join(config.DisabledProviders, ","), "exa") {
+		t.Fatalf("settings not persisted: %s; error=%v", content, err)
+	}
+	if info, err := os.Stat(path); err != nil || info.Mode().Perm() != 0o600 {
+		t.Fatalf("config permissions: info=%v error=%v", info, err)
+	}
+	if code, text, errText := run("providers", "enable", "exa"); code != 0 || !strings.Contains(text, "exa enabled") || errText != "" {
+		t.Fatalf("enable: code=%d text=%q error=%q", code, text, errText)
+	}
+	if code, text, _ := run("status"); code != 0 || !strings.Contains(text, "exa     enabled") {
+		t.Fatalf("restored status: code=%d text=%q", code, text)
+	}
+}
+
+func TestProviderCommandsRejectInvalidInputAndMalformedConfig(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv("WEBCTX_CONFIG_FILE", path)
+	for _, args := range [][]string{{"providers", "disable", "firecrawl"}, {"providers", "disable", "unknown"}, {"providers", "disable"}, {"status", "enable", "exa"}} {
+		var out, errOut bytes.Buffer
+		if Run(args, &out, &errOut) == 0 || errOut.Len() == 0 {
+			t.Fatalf("invalid command %q succeeded: %q", args, out.String())
+		}
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("invalid command wrote config: %v", err)
+	}
+	if err := os.WriteFile(path, []byte("{invalid"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	if Run([]string{"status"}, &out, &errOut) == 0 || !strings.Contains(errOut.String(), "invalid provider settings") {
+		t.Fatalf("malformed config not reported: %q", errOut.String())
+	}
+	if Run([]string{"providers", "disable", "exa"}, &out, &errOut) == 0 {
+		t.Fatal("malformed config should not be overwritten")
+	}
+}
+
+type providerRequests struct {
+	mu        sync.Mutex
+	queries   map[string][]string
+	failedExa bool
+	emptyExa  bool
+}
+
+func mockSearchProviders(t *testing.T, exaFailure bool) *providerRequests {
+	t.Helper()
+	prev := http.DefaultClient.Transport
+	stats := &providerRequests{queries: make(map[string][]string), failedExa: exaFailure}
+	http.DefaultClient.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		provider, query := "", ""
+		switch req.URL.Host {
+		case "api.search.brave.com":
+			provider, query = "brave", req.URL.Query().Get("q")
+		case "api.tavily.com", "api.exa.ai":
+			if req.URL.Host == "api.tavily.com" {
+				provider = "tavily"
+			} else {
+				provider = "exa"
+			}
+			data, _ := io.ReadAll(req.Body)
+			var payload map[string]any
+			_ = json.Unmarshal(data, &payload)
+			query, _ = payload["query"].(string)
+		case "provider-test.example":
+			return testHTTPResponse(req, http.StatusOK, "# Example documentation\n\nThis markdown page contains enough content for a test.", map[string]string{"Content-Type": "text/markdown"}), nil
+		default:
+			return testHTTPResponse(req, http.StatusNotFound, "", nil), nil
+		}
+		stats.mu.Lock()
+		stats.queries[provider] = append(stats.queries[provider], query)
+		stats.mu.Unlock()
+		switch provider {
+		case "brave":
+			return testHTTPResponse(req, http.StatusOK, `{"web":{"results":[{"url":"https://provider-test.example/guide.md","title":"Guide","description":"Documentation"}]}}`, nil), nil
+		case "tavily":
+			return testHTTPResponse(req, http.StatusOK, `{"results":[]}`, nil), nil
+		case "exa":
+			if stats.failedExa {
+				return testHTTPResponse(req, http.StatusPaymentRequired, `{"error":"NO_MORE_CREDITS"}`, nil), nil
+			}
+			if stats.emptyExa {
+				return testHTTPResponse(req, http.StatusOK, `{"results":[]}`, nil), nil
+			}
+			return testHTTPResponse(req, http.StatusOK, `{"results":[{"url":"https://provider-test.example/guide.md","title":"Guide","text":"Documentation"}]}`, nil), nil
+		}
+		return testHTTPResponse(req, http.StatusNotFound, "", nil), nil
+	})
+	t.Cleanup(func() { http.DefaultClient.Transport = prev })
+	return stats
+}
+
+func (p *providerRequests) received(provider string) []string {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return append([]string(nil), p.queries[provider]...)
+}
+
+func searchTestEnv(t *testing.T) {
+	t.Helper()
+	t.Setenv("WEBCTX_CONFIG_FILE", filepath.Join(t.TempDir(), "config.json"))
+	t.Setenv("BRAVE_API_KEY", "test-brave")
+	t.Setenv("TAVILY_API_KEY", "test-tavily")
+	t.Setenv("EXA_API_KEY", "test-exa")
+	t.Setenv("FIRECRAWL_API_KEY", "")
+}
+
+func TestSearchDoesNotCallDisabledExa(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	if _, err := setSearchProviderEnabled("exa", false); err != nil {
+		t.Fatal(err)
+	}
+	result, err := Search(SearchParams{Query: "runtime docs"})
+	if err != nil || !strings.Contains(result, "Total Results: 1") {
+		t.Fatalf("search without Exa failed: %v; %q", err, result)
+	}
+	if got := stats.received("exa"); len(got) != 0 {
+		t.Fatalf("Exa was contacted despite being disabled: %v", got)
+	}
+	if got := stats.received("brave"); len(got) != 1 || got[0] != "runtime docs" {
+		t.Fatalf("Brave was not used: %v", got)
+	}
+	if got := stats.received("tavily"); len(got) != 1 {
+		t.Fatalf("Tavily was not used: %v", got)
+	}
+}
+
+func TestSearchSupportsOnlyBraveEnabled(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	for _, name := range []string{"exa", "tavily"} {
+		if _, err := setSearchProviderEnabled(name, false); err != nil {
+			t.Fatal(err)
+		}
+	}
+	result, err := Search(SearchParams{Query: "runtime docs"})
+	if err != nil || !strings.Contains(result, "Total Results: 1") {
+		t.Fatalf("single-provider search failed: %v; %q", err, result)
+	}
+	if len(stats.received("exa")) != 0 || len(stats.received("tavily")) != 0 || len(stats.received("brave")) != 1 {
+		t.Fatalf("unexpected requests: %#v", stats.queries)
+	}
+}
+
+func TestKeywordFallbackSkipsDisabledExa(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	if _, err := setSearchProviderEnabled("exa", false); err != nil {
+		t.Fatal(err)
+	}
+	result, err := Search(SearchParams{Query: "drizzle orm", IncludeKeyword: "migration guide"})
+	if err != nil || !strings.Contains(result, "Keyword fallback") {
+		t.Fatalf("keyword fallback failed: %v; %q", err, result)
+	}
+	if len(stats.received("exa")) != 0 {
+		t.Fatal("disabled Exa received keyword request")
+	}
+	for _, provider := range []string{"brave", "tavily"} {
+		got := stats.received(provider)
+		if len(got) != 1 || !strings.Contains(got[0], `"migration guide"`) {
+			t.Fatalf("%s did not receive a quoted phrase: %v", provider, got)
+		}
+	}
+}
+
+func TestKeywordFallbackOnExaCreditExhaustion(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, true)
+	result, err := Search(SearchParams{Query: "drizzle orm", IncludeKeyword: "migration guide"})
+	if err != nil || !strings.Contains(result, "Keyword fallback") || !strings.Contains(result, "Total Results: 1") {
+		t.Fatalf("keyword fallback after Exa error failed: %v; %q", err, result)
+	}
+	if len(stats.received("exa")) != 1 || len(stats.received("brave")) != 1 {
+		t.Fatalf("unexpected provider request sequence: %#v", stats.queries)
+	}
+}
+
+func TestKeywordExaSuccessDoesNotContactOtherProviders(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	result, err := Search(SearchParams{Query: "drizzle orm", IncludeKeyword: "migration guide"})
+	if err != nil || strings.Contains(result, "Keyword fallback") || !strings.Contains(result, "Total Results: 1") {
+		t.Fatalf("unexpected keyword results: %v; %q", err, result)
+	}
+	if len(stats.received("exa")) != 1 || len(stats.received("brave")) != 0 || len(stats.received("tavily")) != 0 {
+		t.Fatalf("unexpected provider requests: %#v", stats.queries)
+	}
+}
+
+func TestKeywordExaNoMatchesDoesNotBroadenSearch(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	stats.emptyExa = true
+	_, err := Search(SearchParams{Query: "drizzle orm", IncludeKeyword: "migration guide"})
+	if err == nil || !strings.Contains(err.Error(), "failed to return results") {
+		t.Fatalf("unexpected result for zero Exa matches: %v", err)
+	}
+	if len(stats.received("exa")) != 1 || len(stats.received("brave")) != 0 || len(stats.received("tavily")) != 0 {
+		t.Fatalf("strict keyword search was broadened: %#v", stats.queries)
+	}
+}
+
+func TestSearchWithAllProvidersDisabledFailsFast(t *testing.T) {
+	searchTestEnv(t)
+	stats := mockSearchProviders(t, false)
+	for _, name := range []string{"brave", "tavily", "exa"} {
+		if _, err := setSearchProviderEnabled(name, false); err != nil {
+			t.Fatal(err)
+		}
+	}
+	_, err := Search(SearchParams{Query: "anything"})
+	if err == nil || !strings.Contains(err.Error(), "all search providers are disabled") {
+		t.Fatalf("unexpected error when all disabled: %v", err)
+	}
+	if len(stats.received("exa"))+len(stats.received("tavily"))+len(stats.received("brave")) != 0 {
+		t.Fatal("search contacted provider with all disabled")
+	}
+}
+
+func TestBraveSearchTransparentlyDecodesGzip(t *testing.T) {
+	t.Setenv("BRAVE_API_KEY", "test-brave")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Accept-Encoding") != "gzip" {
+			t.Errorf("expected Go HTTP transport to request gzip, got %q", r.Header.Get("Accept-Encoding"))
+		}
+		w.Header().Set("Content-Encoding", "gzip")
+		w.Header().Set("Content-Type", "application/json")
+		writer := gzip.NewWriter(w)
+		_, _ = writer.Write([]byte(`{"web":{"results":[{"url":"https://example.com/guide","title":"Guide","description":"Documentation"}]}}`))
+		_ = writer.Close()
+	}))
+	defer server.Close()
+
+	originalTransport := http.DefaultClient.Transport
+	http.DefaultClient.Transport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		if req.Header.Get("Accept-Encoding") != "" {
+			t.Errorf("Brave search forced Accept-Encoding instead of letting Go decode it: %q", req.Header.Get("Accept-Encoding"))
+		}
+		copy := req.Clone(req.Context())
+		copy.URL.Scheme = "http"
+		copy.URL.Host = strings.TrimPrefix(server.URL, "http://")
+		copy.Host = copy.URL.Host
+		return http.DefaultTransport.RoundTrip(copy)
+	})
+	t.Cleanup(func() { http.DefaultClient.Transport = originalTransport })
+
+	result, err := searchWithBrave(context.Background(), "Go docs")
+	if err != nil || len(result.Docs) != 1 || result.Docs[0].Title != "Guide" {
+		t.Fatalf("Brave gzip response not decoded: %v; %#v", err, result)
+	}
+}

package/internal/app/site_map_page.go

@@ -1,6 +1,7 @@
 package app
 
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
@@ -20,12 +21,30 @@ import (
 // MapSiteInput retrieves an agent-sized page rather than dumping thousands
 // of URLs. An omitted language prefers English; "all" allows all locales.
 type MapSiteInput struct {
-	URL        string `json:"url" jsonschema:"Website URL to map; HTTP(S) only"`
-	Query      string `json:"query,omitempty" jsonschema:"Optional topic to filter and rank discovered pages"`
-	Limit      int    `json:"limit,omitempty" jsonschema:"Number of URLs to return, 1-100; defaults to 30"`
-	Offset     int    `json:"offset,omitempty" jsonschema:"Pagination offset, zero-based"`
-	PathPrefix string `json:"path_prefix,omitempty" jsonschema:"Optional URL path prefix, e.g. /api/"`
-	Language   string `json:"language,omitempty" jsonschema:"Locale code such as en or fr; defaults to English, use all for all languages"`
+	URL           string `json:"url" jsonschema:"Website URL to map; HTTP(S) only"`
+	Query         string `json:"query,omitempty" jsonschema:"Optional topic to filter and rank discovered pages"`
+	Limit         int    `json:"limit,omitempty" jsonschema:"Number of URLs to return, 1-100; defaults to 30"`
+	Offset        int    `json:"offset,omitempty" jsonschema:"Pagination offset, zero-based"`
+	PathPrefix    string `json:"path_prefix,omitempty" jsonschema:"Optional URL path prefix, e.g. /api/"`
+	Language      string `json:"language,omitempty" jsonschema:"Locale code such as en or fr; defaults to English, use all for all languages"`
+	limitProvided bool   `json:"-"`
+}
+
+func (input *MapSiteInput) UnmarshalJSON(raw []byte) error {
+	type fields MapSiteInput
+	var parsed fields
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&parsed); err != nil {
+		return err
+	}
+	var presence map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &presence); err != nil {
+		return err
+	}
+	*input = MapSiteInput(parsed)
+	_, input.limitProvided = presence["limit"]
+	return nil
 }
 
 type siteMapCacheValue struct {
@@ -139,7 +158,7 @@ func mapPageLocale(raw string) string {
 }
 
 func MapSitePage(input MapSiteInput) (map[string]any, error) {
-	if input.Limit == 0 {
+	if input.Limit == 0 && !input.limitProvided {
 		input.Limit = 30
 	}
 	if input.Limit < 1 || input.Limit > 100 {

package/internal/app/tools.go

@@ -10,6 +10,7 @@ import (
 	"net/url"
 	"os"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
 	"time"
@@ -37,6 +38,11 @@ type providerDocs struct {
 	Err      error
 }
 
+type namedSearch struct {
+	name string
+	fn   func(context.Context) (SearchResult, error)
+}
+
 type scoredURL struct {
 	Result         SearchDoc
 	InsertionOrder int
@@ -47,6 +53,13 @@ type scoredURL struct {
 }
 
 func Search(params SearchParams) (string, error) {
+	config, err := currentProviderConfig()
+	if err != nil {
+		return "", err
+	}
+	if !config.enabled("brave") && !config.enabled("tavily") && !config.enabled("exa") {
+		return "", errors.New("Error searching the web: all search providers are disabled; run 'webctx providers enable brave', 'webctx providers enable tavily', or 'webctx providers enable exa'")
+	}
 	defaultExcludedDomains := []string{"youtube.com", "vimeo.com", "dailymotion.com", "twitch.tv", "tiktok.com", "instagram.com", "facebook.com"}
 	allExcludedDomains := append(append([]string{}, defaultExcludedDomains...), params.ExcludeDomains...)
 	truncatedKeyword := truncateWords(params.IncludeKeyword, 5)
@@ -56,46 +69,44 @@ func Search(params SearchParams) (string, error) {
 	alexandriaDone := make(chan string, 1)
 	go func() { alexandriaDone <- discoverAlexandria(params.Query) }()
 
-	type namedSearch struct {
-		name string
-		fn   func(context.Context) (SearchResult, error)
-	}
-
 	searches := []namedSearch{}
+	keywordFallback := false
 	if strings.TrimSpace(truncatedKeyword) != "" {
-		searches = append(searches, namedSearch{name: "Exa", fn: func(ctx context.Context) (SearchResult, error) {
-			return searchWithExa(ctx, params.Query, nil, truncatedKeyword)
-		}})
+		if config.enabled("exa") && strings.TrimSpace(os.Getenv("EXA_API_KEY")) != "" {
+			searches = append(searches, namedSearch{name: "Exa", fn: func(ctx context.Context) (SearchResult, error) {
+				return searchWithExa(ctx, params.Query, nil, truncatedKeyword)
+			}})
+		}
 	} else {
-		searches = append(searches,
-			namedSearch{name: "Brave", fn: func(ctx context.Context) (SearchResult, error) { return searchWithBrave(ctx, params.Query) }},
-			namedSearch{name: "Tavily", fn: func(ctx context.Context) (SearchResult, error) { return searchWithTavily(ctx, params.Query, nil) }},
-			namedSearch{name: "Exa", fn: func(ctx context.Context) (SearchResult, error) { return searchWithExa(ctx, params.Query, nil, "") }},
-		)
+		searches = append(searches, alternativeSearches(config, params.Query)...)
+		if config.enabled("exa") {
+			searches = append(searches, namedSearch{name: "Exa", fn: func(ctx context.Context) (SearchResult, error) {
+				return searchWithExa(ctx, params.Query, nil, "")
+			}})
+		}
 	}
 
-	results := make([]providerDocs, len(searches))
-	var wg sync.WaitGroup
-	for i, s := range searches {
-		wg.Add(1)
-		go func(i int, s namedSearch) {
-			defer wg.Done()
-			ctx, cancel := context.WithTimeout(context.Background(), 40*time.Second)
-			defer cancel()
-			res, err := s.fn(ctx)
-			if err != nil {
-				results[i] = providerDocs{Provider: s.name, Docs: []SearchDoc{}, Err: err}
-				return
-			}
-			results[i] = providerDocs{Provider: s.name, Docs: res.Docs}
-		}(i, s)
+	results := runSearches(searches)
+	if truncatedKeyword != "" && (len(searches) == 0 || (len(results) == 1 && results[0].Err != nil)) {
+		// Exa's includeText filter has no equivalent in Brave or Tavily. When Exa
+		// is disabled, unconfigured, or fails, search for the quoted phrase instead
+		// of making keyword searches unusable. Disclose the weaker semantics.
+		fallbackQuery := params.Query + " " + strconv.Quote(truncatedKeyword)
+		fallbackSearches := alternativeSearches(config, fallbackQuery)
+		if len(fallbackSearches) > 0 {
+			results = append(results, runSearches(fallbackSearches)...)
+			keywordFallback = true
+		} else if len(searches) == 0 && config.enabled("exa") {
+			// Preserve the helpful missing-key error if Exa is the only enabled
+			// provider and it has no key.
+			results = append(results, providerDocs{Provider: "Exa", Err: errors.New("missing EXA_API_KEY")})
+		}
 	}
-	wg.Wait()
-
-	total := 0
-	for _, r := range results {
-		total += len(r.Docs)
+	if len(results) == 0 {
+		return "", errors.New("Error searching the web: no enabled search providers are available for this query; use 'webctx status' to inspect settings")
 	}
+
+	total := countSearchDocs(results)
 	if total == 0 {
 		missingKeys := uniqueMissingCredentialKeys(results)
 		if len(missingKeys) > 0 {
@@ -123,6 +134,9 @@ func Search(params SearchParams) (string, error) {
 	}
 
 	parts := []string{fmt.Sprintf("Total Results: %d\n", len(ranked))}
+	if keywordFallback {
+		parts = append(parts, "> **Keyword fallback:** Exa was disabled or unavailable. Brave/Tavily searched for the quoted phrase; this is not a strict page-text inclusion filter.", "")
+	}
 	// The ranked index remains available, but agents also get useful source
 	// context without having to issue several follow-up read-link calls.
 	if context := enrichSearch(params.Query, ranked); context != "" {
@@ -144,6 +158,46 @@ func Search(params SearchParams) (string, error) {
 	return strings.Join(parts, "\n"), nil
 }
 
+func alternativeSearches(config providerConfig, query string) []namedSearch {
+	searches := []namedSearch{}
+	if config.enabled("brave") {
+		searches = append(searches, namedSearch{name: "Brave", fn: func(ctx context.Context) (SearchResult, error) { return searchWithBrave(ctx, query) }})
+	}
+	if config.enabled("tavily") {
+		searches = append(searches, namedSearch{name: "Tavily", fn: func(ctx context.Context) (SearchResult, error) { return searchWithTavily(ctx, query, nil) }})
+	}
+	return searches
+}
+
+func countSearchDocs(results []providerDocs) int {
+	count := 0
+	for _, r := range results {
+		count += len(r.Docs)
+	}
+	return count
+}
+
+func runSearches(searches []namedSearch) []providerDocs {
+	results := make([]providerDocs, len(searches))
+	var wg sync.WaitGroup
+	for i, s := range searches {
+		wg.Add(1)
+		go func(i int, s namedSearch) {
+			defer wg.Done()
+			ctx, cancel := context.WithTimeout(context.Background(), 40*time.Second)
+			defer cancel()
+			res, err := s.fn(ctx)
+			if err != nil {
+				results[i] = providerDocs{Provider: s.name, Docs: []SearchDoc{}, Err: err}
+				return
+			}
+			results[i] = providerDocs{Provider: s.name, Docs: res.Docs}
+		}(i, s)
+	}
+	wg.Wait()
+	return results
+}
+
 func ReadLink(rawURL string) (string, error) {
 	if err := validateSourceURL(rawURL); err != nil {
 		return "", err
@@ -338,7 +392,6 @@ func searchWithBrave(ctx context.Context, query string) (SearchResult, error) {
 	params.Set("limit", "20")
 	body, err := doRawRequest(ctx, http.MethodGet, "https://api.search.brave.com/res/v1/web/search?"+params.Encode(), map[string]string{
 		"Accept":               "application/json",
-		"Accept-Encoding":      "gzip",
 		"x-subscription-token": apiKey,
 	}, nil)
 	if err != nil {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webctx",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Go CLI for agent-friendly web research, structured-data discovery, and source-native querying",
   "license": "MIT",
   "author": "amxv",

package/pkg/origo/data_test.go

@@ -74,6 +74,7 @@ func TestAuditMCPRejectsZeroLimitAndInvalidSourceURLsWithoutExceptions(t *testin
 		code string
 	}{
 		{"research", map[string]any{"mode": "catalogue", "view": "sources", "limit": 0}, "invalid_limit"},
+		{"map_site", map[string]any{"url": "https://docs.firecrawl.dev", "limit": 0}, "invalid_limit"},
 		{"read_link", map[string]any{"url": "file:///etc/passwd", "question": "summarize"}, "invalid_url"},
 		{"map_site", map[string]any{"url": "file:///etc/passwd"}, "invalid_url"},
 	} {