feat(explorer, analyzer): add exclude param + instance_index disambiguation (v2.0.1)

cortex_code_explorer — exclude dirs at scan time
- Add `exclude: Vec<String>` to map_overview and deep_slice actions
- filter_entry predicate applied to both the primary walker (file discovery)
  and the unfiltered reference walker (scan-count diagnostics)
- Matched against directory base name so pruning applies at every depth
- deep_slice merges per-call exclude list into cfg.scan.exclude_dir_names
  so exclusion flows through build_scan_options -> scan_workspace
- Fixes QA finding #1: repos with node_modules / large asset dirs triggered
  "Massive Directory" mode despite the actual source tree being small

cortex_symbol_analyzer — instance_index for duplicate symbol disambiguation
- Add `instance_index: Option<usize>` param to read_source action
- Collects ALL matching candidates instead of stopping at first match
- When N > 1 instances exist, prepends a disambiguation header showing
  "Found N instances, showing instance X of N, use instance_index to select"
- Clamps out-of-range index to last valid instance (no panic)
- Fixes QA finding #2: agents silently received only the first instance with
  no indication other definitions existed in the same file

MCP schema + docs
- tool_list schemas updated: exclude array and instance_index integer fields
  added to the respective action descriptions
- .github/copilot-instructions.md quick-reference table expanded with
  "Key Optional Params" column surfacing exclude and instance_index
- CHANGELOG.md updated; version bumped 2.0.0 -> 2.0.1

Author: zelda2003

.github/copilot-instructions.md

@@ -9,20 +9,20 @@
 
 **Megatool Quick‑Reference**
 
-| Task | Megatool | Action Enum | Required Params |
-|---|---|---|---|
-| Repo overview (files + public symbols) | `cortex_code_explorer` | `map_overview` | `target_dir` (use `.` for whole repo) |
-| Token-budgeted context slice (XML) | `cortex_code_explorer` | `deep_slice` | `target` |
-| Extract exact symbol source | `cortex_symbol_analyzer` | `read_source` | `path` + `symbol_name` *(or `path` + `symbol_names` for batch)* |
-| Find all usages before signature change | `cortex_symbol_analyzer` | `find_usages` | `symbol_name` + `target_dir` |
-| Find trait/interface implementors | `cortex_symbol_analyzer` | `find_implementations` | `symbol_name` + `target_dir` |
-| Blast radius before rename/move/delete | `cortex_symbol_analyzer` | `blast_radius` | `symbol_name` + `target_dir` |
-| Cross-boundary update checklist | `cortex_symbol_analyzer` | `propagation_checklist` | `symbol_name` *(or legacy `changed_path`)* |
-| Save pre-change snapshot | `cortex_chronos` | `save_checkpoint` | `path` + `symbol_name` + `semantic_tag` |
-| List snapshots | `cortex_chronos` | `list_checkpoints` | *(none)* |
-| Compare snapshots (AST diff) | `cortex_chronos` | `compare_checkpoint` | `symbol_name` + `tag_a` + `tag_b` *(use `tag_b="__live__"` + `path` to diff against current state)* |
-| Delete old snapshots (housekeeping) | `cortex_chronos` | `delete_checkpoint` | `symbol_name` and/or `semantic_tag` *(optional: `path`, `namespace`)* — Automatically searches legacy flat `checkpoints/` if no matches in namespace. |
-| Compile/lint diagnostics | `run_diagnostics` | *(none)* | `repoPath` |
+| Task | Megatool | Action Enum | Required Params | Key Optional Params |
+|---|---|---|---|---|
+| Repo overview (files + public symbols) | `cortex_code_explorer` | `map_overview` | `target_dir` (use `.` for whole repo) | `exclude` — array of dir names to skip; `search_filter`; `max_chars`; `ignore_gitignore` |
+| Token-budgeted context slice (XML) | `cortex_code_explorer` | `deep_slice` | `target` | `exclude` — array of dir names to skip; `budget_tokens`; `skeleton_only`; `query`; `query_limit` |
+| Extract exact symbol source | `cortex_symbol_analyzer` | `read_source` | `path` + `symbol_name` *(or `path` + `symbol_names` for batch)* | `instance_index` — 0-based, selects specific instance when duplicates exist; `skeleton_only` |
+| Find all usages before signature change | `cortex_symbol_analyzer` | `find_usages` | `symbol_name` + `target_dir` | |
+| Find trait/interface implementors | `cortex_symbol_analyzer` | `find_implementations` | `symbol_name` + `target_dir` | |
+| Blast radius before rename/move/delete | `cortex_symbol_analyzer` | `blast_radius` | `symbol_name` + `target_dir` | |
+| Cross-boundary update checklist | `cortex_symbol_analyzer` | `propagation_checklist` | `symbol_name` *(or legacy `changed_path`)* | `aliases` — cross-language name variants |
+| Save pre-change snapshot | `cortex_chronos` | `save_checkpoint` | `path` + `symbol_name` + `semantic_tag` | `namespace` |
+| List snapshots | `cortex_chronos` | `list_checkpoints` | *(none)* | `namespace` |
+| Compare snapshots (AST diff) | `cortex_chronos` | `compare_checkpoint` | `symbol_name` + `tag_a` + `tag_b` *(use `tag_b="__live__"` + `path` to diff against current state)* | `namespace`; `path` |
+| Delete old snapshots (housekeeping) | `cortex_chronos` | `delete_checkpoint` | `symbol_name` and/or `semantic_tag` *(optional: `path`, `namespace`)* — Automatically searches legacy flat `checkpoints/` if no matches in namespace. | |
+| Compile/lint diagnostics | `run_diagnostics` | *(none)* | `repoPath` | |
 
 ## The Ultimate CortexAST Refactoring SOP
 
@@ -74,6 +74,17 @@ Follow this sequence for any non-trivial refactor (especially renames, signature
   5. Find-up heuristic on the tool's own `path` / `target_dir` / `target` argument — walks ancestors looking for `.git`, `Cargo.toml`, `package.json`
   6. `cwd` — **refused if it equals `$HOME` or OS root** (CRITICAL error)
 
+**`exclude` best practice (map_overview + deep_slice):**
+- If `map_overview` returns "Massive Directory" or the file count is inflated by generated/dependency folders, pass `exclude: ["node_modules", "vendor", "__pycache__", "build"]` to skip them at scan time.
+- The `exclude` array matches against each directory's **base name** (not full path), so it prunes at every depth.
+- Prefer using `exclude` over widening `target_dir` — it keeps the scan scoped while removing noise.
+- Example: `cortex_code_explorer(action="map_overview", target_dir=".", exclude=["node_modules", ".next", "dist"])`
+
+**`instance_index` best practice (read_source):**
+- When `read_source` returns a disambiguation header like `⚠️ Found N instances of 'symbol_name'`, the file contains multiple definitions with the same name (e.g. overloaded methods, duplicate arrow functions).
+- The response **always shows instance 1 of N by default** (0-based index 0). To read a different one, pass `instance_index: 1` (second), `instance_index: 2` (third), etc.
+- If you need to understand all instances, use `find_usages` to locate each one across the codebase, then call `read_source` multiple times with different `instance_index` values.
+
 **Propagation best practice (Hybrid Omni‑Match):**
 - `propagation_checklist` automatically matches common casing variants of `symbol_name` (PascalCase / camelCase / snake_case).
 - When a symbol is renamed across boundaries (e.g. Rust `TrainingEngineCapabilities` → TS `trainingCaps`), pass `aliases: ["trainingCaps"]` to catch cross-language usage without heavy import tracing.

CHANGELOG.md

@@ -9,7 +9,27 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - _No unreleased changes yet._
 
-## [2.0.0] — Megatool API
+## [2.0.1] — 2026-02-21
+
+### Added
+- **`exclude` parameter for `cortex_code_explorer`** (`map_overview` + `deep_slice`)  
+  Agents can now pass `exclude: ["node_modules", "vendor", "__pycache__", "build"]` to prune directories at scan time.  
+  - Applied as a `filter_entry` predicate on **both** the filtered walker (file discovery) and the unfiltered walker (scan-count diagnostics), so dropped counts remain accurate.  
+  - Matched against each directory's **base name** — pruning applies at every depth without requiring full path patterns.  
+  - `deep_slice` merges per-call `exclude` into `cfg.scan.exclude_dir_names` so the same exclusion list flows through `build_scan_options → scan_workspace`.  
+  - Fixes the QA finding where repos with `node_modules` or large asset folders triggered "Massive Directory" mode despite the source tree being small.
+- **`instance_index` parameter for `cortex_symbol_analyzer` `read_source`**  
+  Resolves the QA finding where files with multiple same-named symbols (overloaded methods, duplicate arrow functions) silently returned only the first instance with no indication that others existed.  
+  - When `N > 1` matches are found, the response prepends a disambiguation header:  
+    `// ⚠️ Disambiguation: Found N instances of 'name'. Showing instance 1 of N (1-based). Use instance_index param (0-based, 0..N-1) to select a specific one.`  
+  - Pass `instance_index: 1` for the second, `instance_index: 2` for the third, etc. Clamps silently to the last valid index.  
+  - Batch mode (`symbol_names`) defaults to instance 0 for each symbol.
+
+### Changed
+- **`cortex_code_explorer` MCP schema** updated: `exclude` array field documented under both `map_overview` and `deep_slice` action descriptions.
+- **`cortex_symbol_analyzer` MCP schema** updated: `instance_index` integer field added to `read_source` action description.
+- **`.github/copilot-instructions.md`** quick-reference table expanded with a "Key Optional Params" column surfacing `exclude` and `instance_index` for faster agent discovery.
+ — Megatool API
 
 ### Breaking Changes (with shims)
 - **10 standalone MCP tools consolidated into 4 Megatools** using `action` enum routing.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "cortexast"
-version = "2.0.0"
+version = "2.0.1"
 edition = "2021"
 description = "God-tier AST intelligence for LLM agents. Pure Rust MCP server with semantic code navigation, hybrid vector search, and Chronos AST time machine."
 authors = ["Thanon Aphithanawat <thanon@aphithanawat.me>"]

Cargo.toml

@@ -2180,13 +2180,14 @@ pub fn extract_symbols_from_source(path: &Path, source_text: &str) -> Vec<Symbol
 /// }
 /// ```
 pub fn read_symbol(path: &Path, symbol_name: &str) -> Result<String> {
-    read_symbol_with_options(path, symbol_name, false)
+    read_symbol_with_options(path, symbol_name, false, None)
 }
 
 pub fn read_symbol_with_options(
     path: &Path,
     symbol_name: &str,
     skeleton_only: bool,
+    instance_index: Option<usize>,
 ) -> Result<String> {
     let abs: PathBuf = if path.is_absolute() {
         path.to_path_buf()
@@ -2243,17 +2244,22 @@ pub fn read_symbol_with_options(
         candidates.extend(impl_blocks);
     }
 
-    // ── Step 2: find best match (exact → case-insensitive) ───────────────
-    let found = candidates
+    // ── Step 2: find best match (exact → case-insensitive), collect ALL instances ──
+    let mut all_matches: Vec<&(String, String, usize, usize)> = candidates
         .iter()
-        .find(|(name, _, _, _)| name == symbol_name)
-        .or_else(|| {
-            candidates
-                .iter()
-                .find(|(name, _, _, _)| name.eq_ignore_ascii_case(symbol_name))
-        });
+        .filter(|(name, _, _, _)| name == symbol_name)
+        .collect();
+
+    if all_matches.is_empty() {
+        all_matches = candidates
+            .iter()
+            .filter(|(name, _, _, _)| name.eq_ignore_ascii_case(symbol_name))
+            .collect();
+    }
 
-    let Some((name, kind, start_byte, end_byte)) = found else {
+    let total_matches = all_matches.len();
+
+    if total_matches == 0 {
         let mut available: Vec<String> = candidates
             .iter()
             .map(|(n, k, _, _)| format!("  {k} {n}"))
@@ -2278,7 +2284,11 @@ pub fn read_symbol_with_options(
             rendered.join("\n"),
             symbol_name
         ));
-    };
+    }
+
+    // Select the requested instance (default: first).
+    let idx = instance_index.unwrap_or(0).min(total_matches.saturating_sub(1));
+    let (name, kind, start_byte, end_byte) = all_matches[idx];
 
     // ── Step 3: format and return ─────────────────────────────────────────
     const MAX_SYMBOL_LINES: usize = 500;
@@ -2296,8 +2306,22 @@ pub fn read_symbol_with_options(
         + 1;
     let symbol_lines = end_line.saturating_sub(start_line) + 1;
 
+    // Build disambiguation preamble when multiple instances exist.
+    let disambiguation = if total_matches > 1 {
+        format!(
+            "// ⚠️ Disambiguation: Found {total_matches} instances of `{name}` in this file. \
+Showing instance {} of {total_matches} (1-based). \
+Use `instance_index` param (0-based, 0..{}) to select a specific one. \
+Consider using find_usages to inspect all occurrences across the codebase.\n",
+            idx + 1,
+            total_matches - 1,
+        )
+    } else {
+        String::new()
+    };
+
     let header = format!(
-        "// {kind} `{name}` — {}:L{start_line}-L{end_line}\n",
+        "{disambiguation}// {kind} `{name}` — {}:L{start_line}-L{end_line}\n",
         abs.display()
     );
 
@@ -3448,14 +3472,15 @@ fn extract_context_lines(lines: &[&str], target_0: usize, ctx: usize) -> String
 ///       [struct  ] User
 /// ```
 pub fn repo_map(target_dir: &Path) -> Result<String> {
-    repo_map_with_filter(target_dir, None, None, false)
+    repo_map_with_filter(target_dir, None, None, false, &[])
 }
 
 pub fn repo_map_with_filter(
     target_dir: &Path,
     search_filter: Option<&str>,
     max_chars: Option<usize>,
     ignore_gitignore: bool,
+    exclude_dirs: &[String],
 ) -> Result<String> {
     use ignore::WalkBuilder;
     use std::collections::{BTreeMap, BTreeSet, HashSet};
@@ -3484,9 +3509,27 @@ pub fn repo_map_with_filter(
             .join(target_dir)
     };
 
+    // Build exclude set from caller-supplied directory names.
+    let excluded_dir_set: HashSet<String> = exclude_dirs
+        .iter()
+        .map(|s| s.trim().trim_matches('/').to_string())
+        .filter(|s| !s.is_empty())
+        .collect();
+    let excluded_dir_set_clone = excluded_dir_set.clone();
+
     let walker_filtered = WalkBuilder::new(&abs_dir)
         .standard_filters(!ignore_gitignore)
         .hidden(true)
+        .filter_entry(move |dent| {
+            if dent.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+                if let Some(name) = dent.path().file_name().and_then(|s| s.to_str()) {
+                    if excluded_dir_set_clone.contains(name) {
+                        return false;
+                    }
+                }
+            }
+            true
+        })
         .build();
 
     let cfg = language_config();
@@ -3611,9 +3654,20 @@ pub fn repo_map_with_filter(
 
     // Compute gitignore/ignore-filter drops by comparing against an unfiltered walk.
     let (scanned_total, dropped_by_gitignore_or_error) = if !ignore_gitignore {
+        let excluded_dir_set_all = excluded_dir_set.clone();
         let walker_all = WalkBuilder::new(&abs_dir)
             .standard_filters(false)
             .hidden(true)
+            .filter_entry(move |dent| {
+                if dent.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+                    if let Some(name) = dent.path().file_name().and_then(|s| s.to_str()) {
+                        if excluded_dir_set_all.contains(name) {
+                            return false;
+                        }
+                    }
+                }
+                true
+            })
             .build();
 
         let mut all_file_count: usize = 0;