docs(mcp): align tool docs with codex parity

- Document web_search as the canonical MCP tool name and retain the legacy web.search alias across README, changelog, and mode docs.
- Explain how to mirror Codex CLI MCP installs with codex mcp add and note the common server bundle.
- Point the configuration guide at spec-compliant naming and runtime toggles for Codex users.

Acceptance Criteria:
- Documentation stops advertising dotted tool names as canonical and references Codex-compatible installs.

Test Notes:
- docs-only change; no automated tests run.

CHANGELOG.md

@@ -39,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `McpMode` support was restored with explicit validation; `remote_only`, `remote_preferred`, and `local_only` now behave predictably.
 - Configuration loading performs structural validation and fails fast on missing default providers or invalid MCP definitions.
 - Ollama provider error handling now distinguishes timeouts, missing models, and authentication failures.
-- The `web.search` tool now proxies through Ollama Cloud’s `/api/web_search` endpoint and is hidden whenever the active provider cannot reach the cloud.
+- The `web_search` tool now proxies through Ollama Cloud’s `/api/web_search` endpoint and is hidden whenever the active provider cannot reach the cloud. The legacy `web.search` alias stays enabled for older sessions.
 - `owlen` warns when the active terminal likely lacks 256-color support.
 - `config.toml` now carries a schema version (`1.2.0`) and is migrated automatically; deprecated keys such as `agent.max_tool_calls` trigger warnings instead of hard failures.
 - Model selector navigation (Tab/Shift-Tab) now switches between local and cloud tabs while preserving selection state.
@@ -52,7 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Cloud usage tracker now persists hourly and weekly token totals, exposes a `:limits` command, and renders live gradient gauges in the header with 80 %/95 % toast notifications.
-- Web search tooling is available whenever Ollama Cloud is configured, giving the assistant automatic access to the `web.search` function with runtime toggles via `:web on|off`.
+- Web search tooling is available whenever Ollama Cloud is configured, giving the assistant automatic access to the `web_search` function with runtime toggles via `:web on|off`. Legacy dotted references continue to resolve through the alias layer.
 - Provider registry aggregates local and cloud Ollama models, including health checks, scope badges, and graceful fallback between providers.
 - Release documentation covers the migration from v0.1, including the new config schema defaults, cloud setup guide, and troubleshooting steps for common errors.
 

README.md

@@ -43,9 +43,21 @@ The refreshed chrome introduces a cockpit-style header with live gradient gauges
 
 - **Local + Cloud resiliency**: Owlen now distinguishes the on-device daemon from Ollama Cloud and gracefully falls back to local if the hosted key is missing or unauthorized. Cloud requests include `Authorization: Bearer <API_KEY>` and reuse the canonical `https://ollama.com` base URL so you no longer hit 401 loops.
 - **Context + quota cockpit**: The header shows `context used / window (percentage)` and a second gauge for hourly/weekly cloud token usage. Configure soft limits via `providers.ollama_cloud.hourly_quota_tokens` and `weekly_quota_tokens`; Owlen tracks consumption locally even when the provider omits token counters.
-- **Web search tooling**: When cloud is enabled, models can call the `web.search` tool automatically. Toggle availability at runtime with `:web on` / `:web off` if you need a local-only session.
+- **Web search tooling**: When cloud is enabled, models can call the spec-compliant `web_search` tool automatically (the legacy `web.search` alias remains for backward compatibility). Toggle availability at runtime with `:web on` / `:web off` if you need a local-only session.
 - **Docs & config parity**: Ship-ready config templates now include per-provider `list_ttl_secs` and `default_context_window` values, plus explicit `OLLAMA_API_KEY` guidance. Run `owlen config doctor` after upgrading from v0.1 to normalize legacy keys and receive deprecation warnings for `OLLAMA_CLOUD_API_KEY` and `OWLEN_OLLAMA_CLOUD_API_KEY`.
-- **Runtime toggles**: Use `:web on` / `:web off` in the TUI or `owlen providers web --enable/--disable` from the CLI to expose or hide the `web.search` tool without editing `config.toml`.
+- **Runtime toggles**: Use `:web on` / `:web off` in the TUI or `owlen providers web --enable/--disable` from the CLI to expose or hide the `web_search` tool without editing `config.toml`.
+
+## MCP Naming & Codex Compatibility
+
+To stay interoperable with Codex and the broader Model Context Protocol (MCP) ecosystem, Owlen now documents the underscore form (`web_search`) as the canonical tool identifier. This matches Codex’s own configuration flags (`tools.web_search`) and avoids dotted names that fall outside MCP’s identifier rules.citeturn6view0
+
+When you need Codex parity, mirror the CLI workflow Codex documents:
+
+- List or install servers with `codex mcp add <server-name> -- <command>` (e.g., Context7, Figma local/remote, Playwright, Chrome DevTools, Sentry, GitHub).citeturn4view0
+- Keep legacy `web.search` in Owlen as an alias so older transcripts still replay, but prefer `web_search` in configs, prompts, and tests.
+- Use Owlen’s tooling registry to pair those servers with the same identifier Codex emits (for example `context7__search` once names are qualified during Codex handshakes).
+
+The documentation set below explains how to register those servers, how to export Codex’s MCP configuration if you want to share the exact JSON with Owlen, and how to toggle `web_search` at runtime.
 
 ## Security & Privacy
 

docs/configuration.md

@@ -202,9 +202,9 @@ Requests target the same `/api/chat` endpoint documented by Ollama and automatic
 
 The quota fields are optional and purely informational—they are never sent to the provider. Owlen uses them to display hourly/weekly token usage in the chat header, emit pre-limit toasts at 80% and 95%, and power the `:limits` command. Adjust the numbers to reflect the soft limits on your account or remove the keys altogether if you do not want usage tracking.
 
-If your deployment exposes the web search endpoint under a different path, set `web_search_endpoint` in the same table. The default (`/api/web_search`) matches the Ollama Cloud REST API documented in the web retrieval guide.
+If your deployment exposes the web search endpoint under a different path, set `web_search_endpoint` in the same table. The default (`/api/web_search`) matches the Ollama Cloud REST API documented in the web retrieval guide. Tools should be registered as `web_search` to stay within MCP’s identifier rules; Owlen keeps `web.search` as a backward-compatible alias but treats the underscored form as canonical.citeturn6view0
 
-Toggle the feature at runtime with `:web on` / `:web off` from the TUI or `owlen providers web --enable/--disable` on the CLI; both commands persist the change back to `config.toml`.
+Toggle the feature at runtime with `:web on` / `:web off` from the TUI or `owlen providers web --enable/--disable` on the CLI; both commands persist the change back to `config.toml`. Codex users can mirror this setup by running `codex mcp add` for each server (Context7, Figma, Playwright, Chrome DevTools, Sentry, GitHub, etc.) and then binding the exposed tool identifiers to Owlen’s registry.citeturn4view0turn6view0
 
 > **Tip:** If the official `ollama signin` flow fails on Linux v0.12.3, follow the [Linux Ollama sign-in workaround](#linux-ollama-sign-in-workaround-v0123) in the troubleshooting guide to copy keys from a working machine or register them manually.
 

docs/phase5-mode-system.md

@@ -14,7 +14,7 @@ Phase 5 has been fully implemented according to the specification in `.agents/ne
 - `ModeConfig` for configuring tool availability per mode
 - `ModeToolConfig` with wildcard (`*`) support for allowing all tools
 - Default configuration:
-  - Chat mode: only `web_search` allowed
+  - Chat mode: only `web_search` allowed (legacy `web.search` alias still resolves)
   - Code mode: all tools allowed (`*`)
 
 ### 2. Configuration Integration (✅ Complete)
@@ -27,7 +27,7 @@ Phase 5 has been fully implemented according to the specification in `.agents/ne
 
 ```toml
 [modes.chat]
-allowed_tools = ["web_search"]
+allowed_tools = ["web_search"]  # Legacy `web.search` alias still accepted
 
 [modes.code]
 allowed_tools = ["*"]  # All tools allowed
@@ -132,6 +132,7 @@ default_model = "llama3.2:latest"
 
 [modes.chat]
 # In chat mode, only web search is allowed
+# When migrating older configs you can still list `web.search`, but Owlen rewrites it internally.
 allowed_tools = ["web_search"]
 
 [modes.code]
@@ -166,7 +167,7 @@ owlen -c
 ### Tool Filtering Behavior
 
 **In Chat Mode:**
-- ✅ `web_search` - Allowed
+- ✅ `web_search` - Allowed (legacy `web.search` alias also resolves)
 - ❌ `code_exec` - Blocked (suggests switching to code mode)
 - ❌ `file_write` - Blocked
 - ❌ `file_delete` - Blocked