feat(FN-3901): add builtin research web-search provider as default

The merge adds a builtin web-search research provider as the default, replacing the need for external research provider configuration and removing the setup gate for builtin defaults. Dashboard settings UX for research defaults was aligned (ResearchView, SettingsModal), CLI research commands were up

Fusion-Task-Id: FN-3901

docs/agents.md

@@ -307,11 +307,11 @@ Expected behavior and boundaries:
 - Agents should use research only when repository/local context is insufficient
 - Queries should stay narrow and task-scoped; avoid open-ended exploration
 - When `experimentalFeatures.researchView` is disabled, sessions do not register `fn_research_*` tools and prompts do not advertise research capabilities
-- If the research surface is enabled but provider setup is incomplete, tools return actionable `setup` responses instead of crashing
+- If the research surface is enabled but an explicitly selected external provider is misconfigured (or web search is explicitly disabled), tools return actionable `setup` responses instead of crashing
 - Durable conclusions should be persisted with `fn_task_document_write` (for example, `key="research"`)
 - Research runs require the project engine to be running for processing; `fn_research_run` creates the run but does not block for completion unless `wait_for_completion` is set
 
-For the full research workflow, provider setup, CLI commands, and API reference, see the [Research guide](./research.md).
+For the full research workflow, builtin-default behavior, optional external provider setup, CLI commands, and API reference, see the [Research guide](./research.md).
 
 ## Built-In Agent Prompt Templates
 

docs/research.md

@@ -2,7 +2,7 @@
 
 [← Docs index](./README.md)
 
-Fusion Research lets you create bounded research runs that search, fetch, and synthesize information from configured providers, then turn structured findings into actionable tasks — all from the dashboard, CLI, or agent sessions.
+Fusion Research lets you create bounded research runs that search, fetch, and synthesize information with built-in web tools by default, then turn structured findings into actionable tasks — all from the dashboard, CLI, or agent sessions.
 
 ---
 
@@ -35,7 +35,7 @@ Research is **not** a replacement for reading source code or local docs — use
 
 ## Prerequisites
 
-Research requires both the experimental flag and provider configuration before runs can execute. If setup is incomplete, the dashboard shows a setup prompt and CLI/agent tools return actionable error codes.
+Research requires the experimental feature flag. Web search works out of the box using built-in agent tools, and external provider setup is optional advanced configuration.
 
 ### 1. Enable the feature flag
 
@@ -51,21 +51,26 @@ The Research view is gated behind an experimental feature flag. Set in global se
 
 This also reveals the **Research Defaults** and **Research** settings sections in the dashboard Settings modal, and enables agent/CLI research tools (`fn_research_*`).
 
-### 2. Configure a web search provider
+### 2. Built-in web search is the default
 
-Set `researchGlobalWebSearchProvider` in global settings to one of the supported backends:
+By default, `researchGlobalWebSearchProvider` resolves to `"builtin"`. Search and fetch run through the agent runtime's native `WebSearch` and `WebFetch` tools, so no API key is required for baseline usage.
+
+### 3. Optional: external search backends
+
+You can opt into external providers in global settings:
 
 | Provider | Required settings |
 |---|---|
+| `"builtin"` | No API key required (default) |
 | `"searxng"` | `researchGlobalSearxngUrl` — URL of your SearXNG instance |
 | `"brave"` | `researchGlobalBraveApiKey` — Brave Search API key |
 | `"google"` | `researchGlobalGoogleSearchApiKey` + `researchGlobalGoogleSearchCx` — Google Custom Search credentials |
 | `"tavily"` | `researchGlobalTavilyApiKey` — Tavily API key |
-| `"none"` | Disables web search (other sources still work) |
+| `"none"` | Disables web search (Page Fetch, Local Docs, GitHub, and LLM synthesis can still run) |
 
 API keys are stored through Fusion's auth credential pipeline (`/api/auth/api-key`), not in settings JSON directly.
 
-### 3. (Optional) Configure synthesis model
+### 4. (Optional) Configure synthesis model
 
 If LLM synthesis is enabled (default: on), set a synthesis provider and model:
 
@@ -78,7 +83,7 @@ If LLM synthesis is enabled (default: on), set a synthesis provider and model:
 }
 ```
 
-If no synthesis model is configured, the synthesis phase may fail with a `PROVIDER_UNAVAILABLE` error.
+If no synthesis model is configured, Research falls back to the global default model lane. If no global default model is resolvable, synthesis may fail with a `PROVIDER_UNAVAILABLE` error.
 
 ### Settings hierarchy
 
@@ -296,10 +301,10 @@ All tools return:
 
 Before creating runs, `fn_research_run` checks:
 1. Research is enabled in settings
-2. At least one search provider is configured
-3. Required API keys are present
+2. Web search is available (`"builtin"` by default, or an explicitly configured external backend)
+3. Required API keys are present for external providers
 
-If any check fails, the tool returns an actionable error with setup guidance instead of crashing.
+If a check fails, the tool returns an actionable error with setup guidance instead of crashing. In practice, with the default `"builtin"` backend, provider-setup errors are mostly limited to explicit external-provider selections or explicit `"none"` opt-out.
 
 ### Best practices for agents
 
@@ -432,7 +437,7 @@ When all retries are exhausted, the run transitions to `retry_exhausted`.
 | Symptom | Cause | Resolution |
 |---|---|---|
 | "Research is disabled in settings" | `researchGlobalEnabled` or `researchSettings.enabled` is `false` | Enable in Settings → Research |
-| "Research provider is not configured" | No search provider credentials set | Add API key for your chosen provider in Settings |
+| "Research provider is not configured" | Web search was explicitly disabled (`researchGlobalWebSearchProvider: "none"`) or external provider setup is incomplete | Re-enable builtin search, or finish configuring your selected external provider in Settings |
 | "Missing API key for {provider}" | Auth credential not found | Configure provider credentials in Settings → Authentication |
 | Run stuck in `queued` | Engine not running or no available concurrency slots | Start the project engine; check `maxConcurrentRuns` |
 | Run times out | Provider slow or `maxDurationMs` too low | Increase timeout in project research settings |

docs/settings-reference.md

@@ -82,13 +82,13 @@ In **Settings → Notifications**, use **Test message notification** to exercise
 > Mesh lifecycle note: settings sync is executed by the process-level `PeerExchangeService` started by `fn serve`/`fn dashboard`. `InProcessRuntime` does not instantiate settings-sync mesh services per project.
 | `dashboardCurrentProjectIdByNode` | `Record<string, string>` | `undefined` | Map of node ID to last-selected project ID. Use key `"local"` for the local node. Persists project context across browser restarts and PWA sessions. |
 | `persistAgentToolOutput` | `boolean` | `true` | Controls whether detailed `detail` payloads are persisted for `tool`, `tool_result`, and `tool_error` agent log entries. When disabled, tool timeline rows are still recorded, but verbose payloads are omitted. |
-| `researchGlobalDefaults` | `ResearchGlobalDefaults` | `{ searchProvider: undefined, synthesisProvider: undefined, synthesisModelId: undefined, enabledSources: { webSearch: true, pageFetch: true, github: false, localDocs: true, llmSynthesis: true }, maxSourcesPerRun: 20, defaultExportFormat: "markdown" }` | Global Research defaults shared by all projects. Project overrides come from `researchSettings`. |
+| `researchGlobalDefaults` | `ResearchGlobalDefaults` | `{ searchProvider: "builtin", synthesisProvider: undefined, synthesisModelId: undefined, enabledSources: { webSearch: true, pageFetch: true, github: false, localDocs: true, llmSynthesis: true }, maxSourcesPerRun: 20, defaultExportFormat: "markdown" }` | Global Research defaults shared by all projects. Web search defaults to the built-in WebSearch/WebFetch-backed provider; project overrides come from `researchSettings`. |
 | `researchGlobalEnabled` | `boolean` | `true` | Enable or disable the research subsystem globally. When false, dashboard/API/CLI/agent entrypoints reject new runs. |
 | `researchGlobalMaxConcurrentRuns` | `number` | `3` | Maximum concurrent research runs across all projects. |
 | `researchGlobalDefaultTimeout` | `number` | `300000` | Default timeout for end-to-end research runs in milliseconds (5 minutes). |
 | `researchGlobalMaxSourcesPerRun` | `number` | `20` | Maximum number of sources per research run. |
 | `researchGlobalMaxSynthesisRounds` | `number` | `2` | Maximum synthesis rounds per research run. |
-| `researchGlobalWebSearchProvider` | `"searxng" \| "brave" \| "google" \| "tavily" \| "none"` | `"none"` | Web search backend for research. Default: `"none"` (disabled). |
+| `researchGlobalWebSearchProvider` | `"builtin" \| "searxng" \| "brave" \| "google" \| "tavily" \| "none"` | `"builtin"` | Web search backend for research. Default: `"builtin"` (uses agent-native WebSearch/WebFetch tools with no API key requirement). |
 | `researchGlobalSearxngUrl` | `string` | `undefined` | SearXNG instance URL (required when provider is `"searxng"`). |
 | `researchGlobalBraveApiKey` | `string` | `undefined` | Brave Search API key (required when provider is `"brave"`). |
 | `researchGlobalGoogleSearchApiKey` | `string` | `undefined` | Google Custom Search API key (required when provider is `"google"`). |
@@ -312,7 +312,7 @@ When that flag is disabled, the Settings modal also hides both Research sections
 Research failures are normalized to a shared error-code contract (`FEATURE_DISABLED`, `MISSING_CREDENTIALS`, `PROVIDER_UNAVAILABLE`, `RATE_LIMITED`, `PROVIDER_TIMEOUT`, `RUN_CANCELLED`, `RETRY_EXHAUSTED`, `INVALID_TRANSITION`, `NON_RETRYABLE_PROVIDER_ERROR`, `INTERNAL_ERROR`) with retryability metadata so dashboard, API, CLI, and agent tooling show consistent recovery guidance.
 
 Recovery entrypoints in the dashboard:
-- **Settings → Research Defaults**: fix missing default provider configuration and provider-level readiness.
+- **Settings → Research Defaults**: choose between builtin web search (default) or optional external provider configuration.
 - **Settings → Authentication**: repair missing provider credentials (`MISSING_CREDENTIALS`).
 - **Settings → Research (project)**: re-enable project research or source toggles when runs are blocked by project settings.
 - **Settings → Experimental Features**: enable `researchView` when Research surfaces or `fn_research_*` tools report feature-disabled.