docs: document You.com (YouSearch) provider

Amp-Thread-ID: https://ampcode.com/threads/T-019e45ff-4976-750c-b2e6-121d0e5991ef
Co-authored-by: Amp <amp@ampcode.com>

3 files changed, 18 insertions, 4 deletions

diff --git a/README.md b/README.md
index cee7c22..61e20f0 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ It has got improved capabilities for Go code understanding (for example, create
   - Auto-detects Cursor, Amp, Aider (WIP), and other agents
   - OpenAI Codex CLI and Claude Code CLI have native external-editor support via `Ctrl+G`
   - Config-driven: add new agents via `[tmux_edit]` in config.toml
-* Support for Ollama (local + Ollama Cloud), OpenAI, OpenRouter, and Anthropic — Ollama Cloud (`kimi-k2.6` at `https://ollama.com`) is the default
+* Support for Ollama (local + Ollama Cloud), OpenAI, OpenRouter, Anthropic, and You.com (YouSearch Research API) — Ollama Cloud (`kimi-k2.6` at `https://ollama.com`) is the default
 
 > **Note on hexai-mcp-server:** This component is currently experimental and not actively maintained. The author manages prompts through slash commands and meta-commands in the hexai agent system, making the MCP server redundant for its original purpose. The code is preserved for potential future enhancements with different functionality beyond prompt management. See the [MCP documentation](docs/mcp-setup.md) for reference only.
 
diff --git a/config.toml.example b/config.toml.example
index 4f7d26a..5526e7f 100644
--- a/config.toml.example
+++ b/config.toml.example
@@ -70,7 +70,7 @@ chat_prefixes = ["?", "!", ":", ";"]  # single-character items
 [provider]
 # Ollama Cloud (ollama.ai) is the recommended default. The API key is read
 # from HEXAI_OLLAMA_API_KEY (falling back to OLLAMA_API_KEY).
-name = "ollama"                      # ollama | openai | openrouter | anthropic
+name = "ollama"                      # ollama | openai | openrouter | anthropic | yousearch
 
 [ollama]
 model       = "kimi-k2.6"
@@ -96,6 +96,12 @@ model       = "claude-3-5-sonnet-20241022"
 base_url    = "https://api.anthropic.com/v1"
 temperature = 0.2
 
+[yousearch]
+# You.com Research API (https://api.you.com/v1/research). The API key is read
+# from HEXAI_YOUSEARCH_API_KEY (falling back to YOU_API_KEY).
+# research_effort accepts: lite | standard | deep | exhaustive (default: standard).
+research_effort = "standard"
+
 # Prompt templates (optional). Leave commented to use defaults.
 [prompts]
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 81de647..fd5a703 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -29,6 +29,7 @@ Environment overrides
   - `HEXAI_OPENAI_MODEL`, `HEXAI_OPENAI_BASE_URL`, `HEXAI_OPENAI_TEMPERATURE`
   - `HEXAI_OPENROUTER_MODEL`, `HEXAI_OPENROUTER_BASE_URL`, `HEXAI_OPENROUTER_TEMPERATURE`
   - `HEXAI_OLLAMA_MODEL`, `HEXAI_OLLAMA_BASE_URL`, `HEXAI_OLLAMA_TEMPERATURE`
+  - `HEXAI_YOUSEARCH_RESEARCH_EFFORT` (`lite` | `standard` | `deep` | `exhaustive`)
   - Per-surface overrides: `HEXAI_MODEL_COMPLETION`, `HEXAI_MODEL_CODE_ACTION`, `HEXAI_MODEL_CHAT`, `HEXAI_MODEL_CLI`
   - Per-surface temperatures: `HEXAI_TEMPERATURE_COMPLETION`, `HEXAI_TEMPERATURE_CODE_ACTION`, `HEXAI_TEMPERATURE_CHAT`, `HEXAI_TEMPERATURE_CLI`
 
@@ -54,7 +55,7 @@ Per-surface models
 
 - Repeating the table (`[[models.<surface>]]`) configures multiple provider/model pairs. Completion requests and the Hexai CLI fan out to every configured entry concurrently and label the responses with `provider:model`. Code actions continue to use the first entry only; any extra [[models.code_action]] tables are ignored at runtime and the loader logs a warning so you know an additional entry was skipped.
 
-- When a per-surface value is omitted, Hexai falls back to the provider’s configured default. Temperatures inherit from `coding_temperature` unless explicitly set, and OpenAI `gpt-5*` models automatically raise an unspecified coding temperature to `1.0` for exploratory behavior. Provider overrides support `"openai"`, `"openrouter"`, `"anthropic"`, or `"ollama"` and read the matching credential variables.
+- When a per-surface value is omitted, Hexai falls back to the provider’s configured default. Temperatures inherit from `coding_temperature` unless explicitly set, and OpenAI `gpt-5*` models automatically raise an unspecified coding temperature to `1.0` for exploratory behavior. Provider overrides support `"openai"`, `"openrouter"`, `"anthropic"`, `"ollama"`, or `"yousearch"` and read the matching credential variables.
 
 Runtime reloads
 
@@ -70,10 +71,11 @@ API keys:
 - OpenAI: prefer `HEXAI_OPENAI_API_KEY`, falling back to `OPENAI_API_KEY`.
 - OpenRouter: prefer `HEXAI_OPENROUTER_API_KEY`, falling back to `OPENROUTER_API_KEY`.
 - Anthropic: prefer `HEXAI_ANTHROPIC_API_KEY`, falling back to `ANTHROPIC_API_KEY`.
+- You.com (YouSearch): prefer `HEXAI_YOUSEARCH_API_KEY`, falling back to `YOU_API_KEY`.
 
 Selecting a provider
 
-- Sectioned: set `[provider] name = "ollama" | "openai" | "openrouter" | "anthropic"`.
+- Sectioned: set `[provider] name = "ollama" | "openai" | "openrouter" | "anthropic" | "yousearch"`.
 - If omitted, Hexai defaults to `ollama` (Ollama Cloud at `https://ollama.com` with model `kimi-k2.6`).
 - Selecting `openrouter` uses https://openrouter.ai/api/v1 by default and automatically sends the required `HTTP-Referer` (`https://github.com/snonux/hexai`) and `X-Title` (`Hexai`) headers. Override the base URL via `[openrouter]` or environment variables when needed.
 
@@ -83,6 +85,12 @@ Notes on Ollama:
 - To use a local Ollama server instead, set `[ollama] base_url = "http://localhost:11434"` and pick a locally pulled model (e.g. `ollama pull qwen3-coder:30b-a3b-q4_K_M`). No API key is required when targeting localhost.
 - Alternatively, run Ollama in OpenAI‑compatible mode and use the OpenAI provider with `openai_base_url` pointed at your local endpoint.
 
+Notes on YouSearch (You.com Research API):
+
+- Calls `https://api.you.com/v1/research` with the last user message as the research query; system messages are ignored because the Research API has its own reasoning pipeline.
+- Configure the research effort under `[yousearch]` (or via `HEXAI_YOUSEARCH_RESEARCH_EFFORT`): `lite`, `standard` (default), `deep`, or `exhaustive`.
+- Sources returned by the API are appended to the response as a `**Sources:**` markdown section.
+
 Hexai Action (TUI) configuration
 
 This is mostly useful when Helix runs in a [tmux](https://tmux.github.io/) session!