webctx 0.2.8 → 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 {
@@ -197,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]
@@ -208,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/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/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.8",
+  "version": "0.2.9",
   "description": "Go CLI for agent-friendly web research, structured-data discovery, and source-native querying",
   "license": "MIT",
   "author": "amxv",