docs: document tree-sitter usage and symbol references tool

- call out generic analyzer tree-sitter symbol extraction and guardrails
- add get_symbol_references to README + capabilities tool list

Author: PatrickSys

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Added
 
+- Tree-sitter-backed symbol extraction is now used by the Generic analyzer when available (with safe fallbacks).
+- New tool: `get_symbol_references` for concrete symbol usage evidence (usageCount + top snippets).
 - Multi-codebase eval runner: `npm run eval -- <codebaseA> <codebaseB>` with per-codebase reports and combined summary.
 - Shared eval scoring/reporting module (`src/eval/*`) used by both the CLI runner and the test suite.
 - Second frozen eval fixture plus an in-repo controlled TypeScript codebase for fully-offline eval runs.

README.md

@@ -169,6 +169,7 @@ Record a decision once. It surfaces automatically in search results and prefligh
 | ------------------------------ | ----------------------------------------------------------------------------------------- |
 | `search_codebase`              | Hybrid search with enrichment + preflight. Pass `intent="edit"` for edit readiness check. |
 | `get_team_patterns`            | Pattern frequencies, golden files, conflict detection                                     |
+| `get_symbol_references`        | Find concrete references to a symbol (usageCount + top snippets)                          |
 | `get_component_usage`          | "Find Usages" - where a library or component is imported                                  |
 | `remember`                     | Record a convention, decision, gotcha, or failure                                         |
 | `get_memory`                   | Query team memory with confidence decay scoring                                           |

docs/capabilities.md

@@ -4,17 +4,18 @@ Technical reference for what `codebase-context` ships today. For the user-facing
 
 ## Tool Surface
 
-10 MCP tools + 1 optional resource (`codebase://context`).
+11 MCP tools + 1 optional resource (`codebase://context`).
 
 ### Core Tools
 
-| Tool                  | Input                                                             | Output                                                                                                                                                                               |
-| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `search_codebase`     | `query`, optional `intent`, `limit`, `filters`, `includeSnippets` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`) + `searchQuality` (with `hint` when low confidence) + `preflight` ({ready, reason}). Snippets opt-in. |
-| `get_team_patterns`   | optional `category`                                               | Pattern frequencies, trends, golden files, conflicts                                                                                                                                 |
-| `get_component_usage` | `name` (import source)                                            | Files importing the given package/module                                                                                                                                             |
-| `remember`            | `type`, `category`, `memory`, `reason`                            | Persists to `.codebase-context/memory.json`                                                                                                                                          |
-| `get_memory`          | optional `category`, `type`, `query`, `limit`                     | Memories with confidence decay scoring                                                                                                                                               |
+| Tool                    | Input                                                             | Output                                                                                                                                                                               |
+| ----------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `search_codebase`       | `query`, optional `intent`, `limit`, `filters`, `includeSnippets` | Ranked results (`file`, `summary`, `score`, `type`, `trend`, `patternWarning`) + `searchQuality` (with `hint` when low confidence) + `preflight` ({ready, reason}). Snippets opt-in. |
+| `get_team_patterns`     | optional `category`                                               | Pattern frequencies, trends, golden files, conflicts                                                                                                                                 |
+| `get_symbol_references` | `symbol`, optional `limit`                                        | Concrete symbol usage evidence: total `usageCount` + top usage snippets                                                                                                              |
+| `get_component_usage`   | `name` (import source)                                            | Files importing the given package/module                                                                                                                                             |
+| `remember`              | `type`, `category`, `memory`, `reason`                            | Persists to `.codebase-context/memory.json`                                                                                                                                          |
+| `get_memory`            | optional `category`, `type`, `query`, `limit`                     | Memories with confidence decay scoring                                                                                                                                               |
 
 ### Utility Tools