docs(mcp): document reference connector bundles

- Replace brand-specific guidance with spec-compliant naming rules and connector categories.
- Add docs/mcp-reference.md outlining common MCP connectors and installation workflow.
- Point configuration docs at the new guide and reiterate the naming regex.

Acceptance Criteria:
- Documentation directs users toward a combined reference bundle without citing specific vendors.

Test Notes:
- Docs-only change; link checks not run.

README.md

@@ -43,21 +43,23 @@ 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 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.
+- **Web search tooling**: When cloud is enabled, models can call the spec-compliant `web_search` tool automatically. 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`.
 
-## MCP Naming & Codex Compatibility
+## MCP Naming & Reference Bundles
 
-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
+Owlen enforces spec-compliant tool identifiers: stick to `^[A-Za-z0-9_-]{1,64}$`, avoid dotted names, and keep identifiers short so the host can qualify them when multiple servers are present.citeturn11search0 Define your tools with underscores or hyphens (for example, `web_search`, `filesystem_read`, `notion_query`) and treat any legacy dotted forms as incompatible.
 
-When you need Codex parity, mirror the CLI workflow Codex documents:
+Modern MCP hosts converge on a common bundle of connectors that cover three broad categories: local operations (filesystem, terminal, git, structured HTTP fetch, browser automation), compute sandboxes (Python, notebook adapters, sequential-thinking planners, test runners), and SaaS integrations (GitHub issues, Notion workspaces, Slack, Stripe, Sentry, Google Drive, Zapier-style automation, design system search).citeturn12search3turn12search10 Owlen’s configuration examples mirror that baseline so a fresh install can wire up the same capabilities without additional mapping.
 
-- List or install servers with `codex mcp add <server-name> -- <command>` (e.g., Context7, Figma local/remote, Playwright, Chrome DevTools, Sentry, GitHub).citeturn4view0
+To replicate the reference bundle today:
-- 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.
+1. Enable the built-in tools that ship with Owlen (`web_search`, filesystem resource APIs, execution sandboxes).
+2. Add external servers under `[mcp_servers]`, keeping names spec-compliant (e.g., `filesystem`, `terminal`, `git`, `browser`, `http_fetch`, `python`, `notebook`, `sequential_thinking`, `sentry`, `notion`, `slack`, `stripe`, `google_drive`, `memory_bank`, `automation_hub`).
+3. Qualify tool identifiers in prompts and configs using the `{server}__{tool}` pattern once multiple servers contribute overlapping operations (`filesystem__read`, `browser__request`, `notion__query_database`).
+
+See the updated MCP guide in `docs/` for detailed installation commands, environment variables, and health checks for each connector. The documentation set below walks through configuration and runtime toggles for `web_search` and the rest of the reference bundle.
 
 ## 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. 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
+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 must be registered with spec-compliant identifiers (for example `web_search`, `browser_fetch`); dotted names are rejected.citeturn11search0
 
-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
+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`. See `docs/mcp-reference.md` for the full connector bundle, installation commands, and health checks.citeturn1search6turn1search8
 
 > **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/mcp-reference.md

@@ -0,0 +1,41 @@
+# MCP Reference Bundles
+
+Owlen’s MCP configuration guidance now targets the same canonical toolset shipped by leading desktop and IDE clients, without relying on brand-specific heuristics. This document distills the common naming rules, connector categories, and installation patterns you should follow when wiring those tools into Owlen.
+
+## Naming Rules
+
+- Tool identifiers must match the regular expression `^[A-Za-z0-9_-]{1,64}$`.citeturn11search0
+- Avoid dots or spaces in identifiers; use underscores when you need multiword names (`sequential_thinking`, `browser_fetch`).
+- When multiple servers expose similarly named tools, qualify the call using `{server}__{tool}` (for example, `filesystem__read` or `browser__request`).
+
+## Connector Categories
+
+| Category | Connector | Capability Highlights | Typical Command Snippet |
+| --- | --- | --- | --- |
+| Core context | `filesystem` | Mount local directories for read/write access during a chat session.citeturn1search6 | `npx -y @modelcontextprotocol/server-filesystem <paths…>` |
+| Core context | `sequential-thinking` | Structured problem solving with persistent reasoning chains and Memory Bank integration.citeturn1search0turn1search6 | `npx -y @modelcontextprotocol/server-sequential-thinking` |
+| Core context | `fetch` | Lightweight HTTP client for REST/JSON retrieval.citeturn1search6 | `npx -y @kazuph/mcp-fetch` |
+| Automation | `puppeteer` | Headless browser automation (navigation, screenshots, DOM scripting).citeturn1search5turn1search7 | `npx -y @modelcontextprotocol/server-puppeteer` |
+| Automation | `browser-tools` / `devtools` | Deep Chrome DevTools integration for inspection and profiling.citeturn1search6 | `npx -y @modelcontextprotocol/server-browser-tools` |
+| Retrieval | `brave-search`, `firecrawl` | API-driven web search and scraping for current information (requires API keys).citeturn1search6turn1search8 | `claude mcp add brave-search …` (replace with `owlen mcp add brave_search …`) |
+| Retrieval | `perplexity`, `tavily`, `search1api` | Aggregated search/QA endpoints with structured responses.citeturn1search8 | `owlen mcp add tavily -- npx -y @tavily/mcp-server` |
+| Observability | `sentry`, `raygun` | Incident and crash analytics access for production systems.citeturn1search8 | `owlen mcp add sentry -- npx -y @sentry/mcp-server` |
+| Productivity | `notion`, `slack`, `stripe`, `zapier`, `google_drive` | Common SaaS integrations for knowledge bases, messaging, payments, automation, and storage.citeturn1search8 | `owlen mcp add notion -- npx -y @notion/mcp-server` |
+| Data | `postgresql`, `sqlite`, `qdrant`, `redis`, `tinybird` | Database and vector-store connectors for analytics and retrieval.citeturn1search8 | `owlen mcp add postgresql -- npx -y @modelcontextprotocol/server-postgresql` |
+| Execution | `python`, `notebook`, `riza`, `semgrep` | Sandbox code execution, notebook orchestration, security linting.citeturn1search8 | `owlen mcp add python -- npx -y @modelcontextprotocol/server-python` |
+
+> **Tip:** Replace any vendor-specific CLI (for example, `claude mcp add`) with the upcoming `owlen mcp add` command when working within Owlen. Until that lands, copy the arguments into `config.toml` directly or wrap them in project scripts—the syntax is intentionally mirrored so the migration is mechanical.
+
+## Installation Workflow
+
+1. **Plan your bundle.** Start with the core context servers (`filesystem`, `sequential-thinking`, `fetch`, `puppeteer`). Layer in retrieval, observability, productivity, and execution connectors as your project requires.
+2. **Add each server under `[mcp_servers]`.** Use spec-compliant names and consider grouping them by category inside `config.toml`.
+3. **Qualify tool calls.** When writing prompts or unit tests, address tools using `{server}__{tool}` to avoid collisions once you enable multiple servers that expose similar endpoints.
+4. **Document required secrets.** Many SaaS connectors need API keys. Store their environment variables in your preferred secret manager and reference them in the `[mcp_servers.<name>.env]` table.
+5. **Run health checks.** Each connector listed above includes a health or status endpoint; wire these into your startup scripts so Owlen can surface actionable errors before a chat begins.
+
+## Next Steps
+
+- Update `config.toml` with the reference bundle (see `docs/configuration.md`).
+- Use `owlen tools audit` to remove or disable any legacy MCP servers that do not meet the naming constraints.
+- Track connector-specific onboarding (API keys, OAuth scopes) in team documentation so new contributors can reproduce the setup quickly.