Make 'search' the default unified entrypoint

Introduce a unified `search` tool as the recommended default across docs and skills, with examples, parameter reference, and response envelope. Update decision trees and best-practices to auto-route intents to specialized tools (repo_search, context_answer, symbol_graph, etc.), add override parameters and usage guidance. Replace/rename neo4j_graph_query references to a generic graph_query (with symbol_graph fallback) and add predict_related commit co-change usage. Changes touch SKILL docs, tool-reference, and CLAUDE example to align tooling guidance and examples.

Author: m1rl0k

.codex/skills/context-engine/SKILL.md

@@ -11,18 +11,33 @@ Hybrid vector search (semantic + lexical) with neural reranking for codebase ret
 
 ```
 Need to find code?
-├── Simple lookup → info_request
-├── Need filters/control → repo_search
+├── UNSURE / GENERAL QUERY → search (RECOMMENDED DEFAULT)
+│   └── Auto-routes to the best tool based on query intent
+├── Simple lookup → search OR info_request
+├── Need filters/control → search OR repo_search
 ├── Search across multiple repos → cross_repo_search
-├── Want LLM explanation → context_answer
+├── Want LLM explanation → search OR context_answer
 ├── Find similar patterns → pattern_search (if enabled)
-├── Find relationships → symbol_graph (DEFAULT, always available)
+├── Find relationships → search OR symbol_graph (DEFAULT, always available)
 └── Store/recall knowledge → memory_store, memory_find
 ```
 
 ## Primary Tools
 
-**repo_search** - Main code search tool:
+**search** - Unified entry point (RECOMMENDED DEFAULT):
+```json
+{"query": "authentication middleware"}
+```
+Auto-detects intent and routes to the best tool. Returns:
+```json
+{
+  "ok": true, "intent": "search", "confidence": 0.92,
+  "tool": "repo_search", "result": {...}, "execution_time_ms": 245
+}
+```
+Handles: code search, Q&A, tests, config, symbols, imports. Use specialized tools only for cross-repo, memory, or admin operations.
+
+**repo_search** - Direct code search (full control):
 ```json
 {"query": "authentication middleware", "limit": 10, "include_snippet": true}
 ```
@@ -77,12 +92,13 @@ Use `depth=2` for multi-hop (callers of callers).
 
 ## Best Practices
 
-1. **NEVER use grep/cat/find for code exploration** - Use MCP tools instead
-2. **Start with `symbol_graph`** for all relationship queries
-3. **Use multi-query** for complex searches: pass 2-3 variations
-4. **Two-phase search**: Discovery (`limit=3, compact=true`) → Deep dive (`limit=8, include_snippet=true`)
-5. **Fire parallel calls** - Multiple independent searches in one message
-6. **Set session defaults early**: `set_session_defaults(output_format="toon", compact=true)`
+1. **Use `search` as your default tool** - Auto-routes to the best specialized tool
+2. **NEVER use grep/cat/find for code exploration** - Use MCP tools instead
+3. **Start with `symbol_graph`** for all relationship queries
+4. **Use multi-query** for complex searches: pass 2-3 variations
+5. **Two-phase search**: Discovery (`limit=3, compact=true`) → Deep dive (`limit=8, include_snippet=true`)
+6. **Fire parallel calls** - Multiple independent `search`, `repo_search`, `symbol_graph` in one message
+7. **Set session defaults early**: `set_session_defaults(output_format="toon", compact=true)`
 
 ## Filters (for repo_search)
 

.codex/skills/context-engine/references/tool-reference.md

@@ -2,6 +2,24 @@
 
 Complete parameter reference for all MCP tools.
 
+## search (UNIFIED - DEFAULT)
+
+**Use this by DEFAULT for any code search, exploration, or question.** Automatically detects query intent and routes to the optimal specialized tool.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Natural language query describing what you need |
+| `collection` | string | Target a specific collection |
+| `limit` | int | Max results (default varies by detected intent) |
+| `language` | string | Filter by programming language |
+| `under` | string | Filter by directory path prefix |
+| `include_snippet` | bool | Include code snippets in results |
+| `compact` | bool | Compact output format |
+
+**Returns:** `{ok, intent, confidence, tool, result, plan, execution_time_ms}`
+
+**Dispatchable tools:** `repo_search`, `context_answer`, `search_tests_for`, `search_config_for`, `symbol_graph`, `search_callers_for`, `search_importers_for`, `info_request`, `context_search`
+
 ## repo_search / code_search
 
 Primary hybrid search tool. Reranking enabled by default.

docs/CLAUDE.example.md

@@ -96,10 +96,55 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
   - Don't ignore per_path limits (duplicate results from same file)
   - Don't use context lines for pure discovery (unnecessary tokens)
 
+  Tool Selection Decision Tree:
+
+  ```
+  Need to search code?
+  ├── DEFAULT: Use search() — auto-routes to the best tool based on query intent
+  ├── Single repo, know collection → repo_search(collection="...")
+  ├── Single repo, need explanation → context_answer or info_request
+  ├── Multiple repos or unsure → cross_repo_search(discover="auto")
+  ├── Tracing frontend→backend flow → cross_repo_search(trace_boundary=true)
+  ├── Finding callers/definitions → symbol_graph
+  └── Exact literal string only → grep (last resort)
+  ```
+
+  ## Unified Search Tool (DEFAULT)
+
+  **Use `search` as your DEFAULT tool for any code search, exploration, or question.**
+  It automatically detects query intent and routes to the optimal specialized tool.
+
+  ```
+  search_context-engine(query: "authentication middleware")
+  # → Detects intent: "search", routes to repo_search
+  # → Returns: {ok, intent, confidence, tool, result, plan, execution_time_ms}
+
+  search_context-engine(query: "how does the caching layer work?")
+  # → Detects intent: "answer", routes to context_answer
+
+  search_context-engine(query: "who calls authenticate()")
+  # → Detects intent: "symbol_callers", routes to symbol_graph
+
+  search_context-engine(query: "tests for payment processing")
+  # → Detects intent: "search_tests", routes to search_tests_for
+  ```
+
+  **When to use `search` vs specialized tools:**
+  - Use `search` by DEFAULT — it picks the right tool for you
+  - Use specialized tools when you need specific parameters not exposed by search
+  - Use `cross_repo_search` for explicit multi-repo scenarios
+  - Use `memory_store`/`memory_find` for memory operations (not handled by search)
+
   Tool Roles Cheat Sheet:
 
   **Note:** All tools below have the `_context-engine` suffix when called (e.g., `repo_search_context-engine`).
 
+  - search (UNIFIED - DEFAULT):
+    - **Use this by DEFAULT for any code search, exploration, or question.**
+    - Automatically detects intent (search, answer, tests, config, callers, etc.) and routes to the optimal tool.
+    - Returns unified envelope: `{ok, intent, confidence, tool, result, plan, execution_time_ms}`.
+    - Think: "find auth middleware", "how does caching work?", "who calls authenticate()".
+    - Use specialized tools only when you need parameters not exposed by search.
   - repo_search / code_search:
     - Use for: finding relevant files/spans and inspecting raw code.
     - Think: "where is X implemented?", "show me usages of Y".
@@ -125,13 +170,13 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
     - Think: "who calls this function?", "where is this class defined?".
     - **Note**: Results are "hydrated" with ~500-char source snippets for immediate context.
     - Supports `depth` for multi-hop traversals (depth=2 = callers of callers).
-    - Use this FIRST for any graph query. Do NOT attempt neo4j_graph_query unless it's in your tool list.
-  - neo4j_graph_query (OPTIONAL — only when NEO4J_GRAPH=1):
-    - **Only available when NEO4J_GRAPH=1. If not in your tool list, use symbol_graph instead.**
+    - Use this FIRST for any graph query. Do NOT attempt graph_query unless it's in your tool list.
+  - graph_query (OPTIONAL — only when NEO4J_GRAPH=1 or MEMGRAPH_GRAPH=1):
+    - **Only available when NEO4J_GRAPH=1 or MEMGRAPH_GRAPH=1. If not in your tool list, use symbol_graph instead.**
     - Use for: advanced graph traversals that grep CANNOT do.
     - Query types: `callers`, `callees`, `transitive_callers`, `transitive_callees`, `impact`, `dependencies`, `cycles`.
     - Think: "what would break if I change X?" (impact), "callers of callers" (transitive_callers), "circular deps?" (cycles).
-    - Example: `neo4j_graph_query(symbol="normalize_path", query_type="impact", depth=2)` → finds all code that would break.
+    - Example: `graph_query(symbol="normalize_path", query_type="impact", depth=2)` → finds all code that would break.
     - **Never error or warn about Neo4j being unavailable — just use symbol_graph.**
   - info_request:
     - Use for: rapid broad discovery and architectural overviews.
@@ -148,6 +193,9 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
   - Step 3 – Pull commit lineage for a specific behavior:
     - Use search_commits_for with short behavior phrases plus an optional path filter, e.g. `search_commits_for_context-engine(query: "remote upload timeout retry", path: "scripts/remote_upload_client.py")`.
     - Read lineage_goal / lineage_symbols / lineage_tags to understand intent and related concepts.
+  - Step 3b – Predict co-changing files:
+    - Use `search_commits_for_context-engine(path: "scripts/remote_upload_client.py", predict_related: true)` to get ranked files that historically change alongside the target file, with commit messages explaining why.
+    - Read lineage_goal / lineage_symbols / lineage_tags to understand intent and related concepts.
   - Step 4 – Optionally summarize current behavior:
     - After you have the right file/symbol from repo_search, use context_answer to explain what the module does now; treat commit lineage as background, not as primary code context.
   - For exact line-level changes (e.g. "when did this literal constant change?"), use lineage tools to narrow candidate commits, then inspect diffs with git tooling; do not guess purely from summaries.
@@ -170,10 +218,11 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
 
   - Indexer / Qdrant tools:
     - qdrant_index_root, qdrant_index, qdrant_prune
-    - qdrant_list, qdrant_status
+    - qdrant_status, qdrant_list
     - workspace_info, list_workspaces, collection_map
     - set_session_defaults
   - Search / QA tools:
+    - search (UNIFIED - DEFAULT entry point, auto-routes to specialized tools)
     - repo_search, code_search, context_search, context_answer
     - pattern_search (optional; structural code pattern matching, cross-language)
     - search_tests_for, search_config_for, search_callers_for, search_importers_for
@@ -192,7 +241,7 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
   - You're unsure which collection to target
 
   ```
-  qdrant_list_context-engine()
+  qdrant_status_context-engine(list_all: true)
   collection_map_context-engine(include_samples: true)
   ```
 
@@ -304,5 +353,5 @@ The ONLY acceptable use of grep/Read: confirming exact literal strings (e.g., `R
 
   - context_answer timeout → repo_search + info_request(include_explanation=true)
   - pattern_search unavailable → repo_search with structural query terms
-  - neo4j_graph_query unavailable → symbol_graph (Qdrant-backed, ALWAYS available — this is the DEFAULT)
+  - graph_query unavailable → symbol_graph (Qdrant-backed, ALWAYS available — this is the DEFAULT)
   - grep / Read File → repo_search, symbol_graph, info_request (ALWAYS use MCP instead)