Sharpen semantic vs grep search responsibility boundary

- SKILL.md: table and "When to Use" section now clearly separate
  semantic search (default, by meaning) from grep (exact text/regex).
  Tool reference descriptions updated.
- search.py: docstring marks it as "the default discovery tool",
  empty-result message guides agent to rephrase or try grep.
- grep.py: docstring explains when to use exact text search,
  empty-result message guides agent to check case or try semantic.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rodion-m

skills/codealive-context-engine/SKILL.md

@@ -38,8 +38,8 @@ Do NOT retry the failed script until setup completes successfully.
 | Tool | Script | Speed | Cost | Best For |
 |------|--------|-------|------|----------|
 | **List Data Sources** | `datasources.py` | Instant | Free | Discovering indexed repos and workspaces |
-| **Semantic Search** | `search.py` | Fast | Low | Finding relevant artifacts by meaning |
-| **Grep Search** | `grep.py` | Fast | Low | Exact text and regex matches with line previews |
+| **Semantic Search** | `search.py` | Fast | Low | Default discovery — finds code by meaning (concepts, behavior, architecture) |
+| **Grep Search** | `grep.py` | Fast | Low | Finds code containing a specific string or regex (identifiers, literals, patterns) |
 | **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content for search results |
 | **Artifact Relationships** | `relationships.py` | Fast | Low | Drilling into call graph, inheritance, references for one artifact |
 | **Chat with Codebase** | `chat.py` | Slow | High | Synthesized answers, architectural explanations |
@@ -64,12 +64,18 @@ or references.
 
 ## When to Use
 
-**Use this skill for semantic understanding:**
+**Semantic search (default) — you describe behavior or concept:**
 - "How is authentication implemented?"
 - "Show me error handling patterns across services"
 - "How does this library work internally?"
 - "Find similar features to guide my implementation"
 
+**Grep search — you know the exact text:**
+- "Find all usages of `RepositoryDeleted`"
+- "Where is `ConnectionString` configured?"
+- "Search for `TODO: fix` across the codebase"
+- Error messages, URLs, config keys, import paths, regex patterns
+
 **Use local file tools instead for:**
 - Finding specific files by name or pattern
 - Exact keyword search in the current directory
@@ -129,9 +135,11 @@ python scripts/datasources.py --all        # All (including processing)
 python scripts/datasources.py --json       # JSON output
 ```
 
-### `search.py` — Semantic Code Search
+### `search.py` — Semantic Code Search (default discovery tool)
 
-Returns file paths, line numbers, descriptions, identifiers, and content sizes. Fast and cheap.
+The default starting point. Finds code by WHAT it does — concepts, behavior,
+architecture — not by exact text. Use when you can describe what you're
+looking for but don't know the exact names in the codebase.
 
 ```bash
 python scripts/search.py <query> <data_sources...> [options]
@@ -150,10 +158,11 @@ source: use `fetch.py <identifier>` for external repos, or your editor's
 file-read tool on the path for repos in the current working directory. Treat
 only that real `content` as ground truth.
 
-### `grep.py` — Exact / Regex Search
+### `grep.py` — Exact Text / Regex Search
 
-Returns artifact-level matches with line previews. Use this when the pattern
-itself matters more than semantic similarity.
+Finds code containing a specific string or regex pattern. Use when you know
+the exact text to look for: identifiers, error messages, config keys, URLs,
+domain events, import paths, TODO comments.
 
 ```bash
 python scripts/grep.py <query> <data_sources...> [--regex] [--max-results N] [--path PATH] [--ext EXT]

skills/codealive-context-engine/scripts/grep.py

@@ -1,6 +1,10 @@
 #!/usr/bin/env python3
 """
-CodeAlive Grep Search - exact text or regex search across indexed repositories.
+CodeAlive Grep Search — exact text or regex search across indexed repositories.
+
+Finds code containing a specific string or pattern. Use when you know the
+exact identifier, error message, config key, or regex to match.
+For concept-based discovery, use search.py instead.
 
 Usage:
     python grep.py "AuthService" my-repo
@@ -19,7 +23,13 @@
 def format_grep_results(results: dict) -> str:
     items = results.get("results", []) if isinstance(results, dict) else []
     if not items:
-        return "No results found."
+        return (
+            "No grep matches found. This does NOT mean the code doesn't exist.\n"
+            "Try: (1) check case — grep is case-sensitive by default; "
+            "(2) use search.py for concept-based discovery if unsure of exact naming; "
+            "(3) check that the data source is correct (run datasources.py); "
+            "(4) remove --path/--ext filters if used."
+        )
 
     output = []
     for idx, result in enumerate(items, 1):

skills/codealive-context-engine/scripts/search.py

@@ -1,6 +1,10 @@
 #!/usr/bin/env python3
 """
-CodeAlive Semantic Search - semantic retrieval across indexed repositories.
+CodeAlive Semantic Search — the default discovery tool.
+
+Finds code by meaning (concepts, behavior, architecture), not by exact text.
+Use when you can describe WHAT the code does but don't know exact names.
+For exact identifiers, literals, or regex, use grep.py instead.
 
 Usage:
     python search.py "How is authentication handled?" my-repo
@@ -36,7 +40,13 @@ def format_search_results(results: dict) -> str:
         items = [results]
 
     if not items:
-        return "No results found."
+        return (
+            "No results found. This does NOT mean the code doesn't exist.\n"
+            "Try: (1) rephrase with synonyms or broader terms; "
+            "(2) use grep.py if you know a specific identifier or literal string; "
+            "(3) check that the data source is correct (run datasources.py); "
+            "(4) remove --path/--ext filters if used."
+        )
 
     output = []
     for idx, result in enumerate(items, 1):