docs: update README files to clarify indexing commands and their usage

Author: johnhuang316

README.md

@@ -66,7 +66,7 @@ The easiest way to get started with any MCP-compatible application:
 - **Direct Tree-sitter Integration**: No regex fallbacks for specialized languages - fail fast with clear errors
 - **Advanced Search**: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)
 - **Universal File Support**: Comprehensive coverage from advanced AST parsing to basic file indexing
-- **File Analysis**: Deep insights into structure, imports, classes, methods, and complexity metrics
+- **File Analysis**: Deep insights into structure, imports, classes, methods, and complexity metrics after running `build_deep_index`
 
 ### 🗂️ **Multi-Language Support**  
 - **7 Languages with Tree-sitter AST Parsing**: Python, JavaScript, TypeScript, Java, Go, Objective-C, Zig
@@ -81,7 +81,7 @@ The easiest way to get started with any MCP-compatible application:
 - **File Watcher**: Automatic index updates when files change
 - **Cross-platform**: Native OS file system monitoring
 - **Smart Processing**: Batches rapid changes to prevent excessive rebuilds
-- **Rich Metadata**: Captures symbols, references, definitions, and relationships
+- **Shallow Index Refresh**: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata
 
 ### ⚡ **Performance & Efficiency**
 - **Tree-sitter AST Parsing**: Native syntax parsing for accurate symbol extraction
@@ -218,15 +218,18 @@ Then configure:
 | Tool | Description |
 |------|-------------|
 | **`set_project_path`** | Initialize indexing for a project directory |
-| **`refresh_index`** | Rebuild the project index after file changes |
+| **`refresh_index`** | Rebuild the shallow file index after file changes |
+| **`build_deep_index`** | Generate the full symbol index used by deep analysis |
 | **`get_settings_info`** | View current project configuration and status |
 
+*Run `build_deep_index` when you need symbol-level data; the default shallow index powers quick file discovery.*
+
 ### 🔍 **Search & Discovery**
 | Tool | Description |
 |------|-------------|
 | **`search_code_advanced`** | Smart search with regex, fuzzy matching, and file filtering |
 | **`find_files`** | Locate files using glob patterns (e.g., `**/*.py`) |
-| **`get_file_summary`** | Analyze file structure, functions, imports, and complexity |
+| **`get_file_summary`** | Analyze file structure, functions, imports, and complexity (requires deep index) |
 
 ### 🔄 **Monitoring & Auto-refresh**
 | Tool | Description |
@@ -263,6 +266,7 @@ Find all TypeScript component files in src/components
 Give me a summary of src/api/userService.ts
 ```
 *Uses: `get_file_summary` to show functions, imports, and complexity*
+*Tip: run `build_deep_index` first if you get a `needs_deep_index` response.*
 
 ### 🔍 **Advanced Search Examples**
 

README_ja.md

@@ -66,7 +66,7 @@ Code Index MCPは、AIモデルと複雑なコードベースの橋渡しをす
 - **直接Tree-sitter統合**：特化言語で正規表現フォールバックなし - 明確なエラーメッセージで高速フェイル
 - **高度な検索**：最適なツール（ugrep、ripgrep、ag、grep）を自動検出・使用
 - **汎用ファイルサポート**：高度なAST解析から基本ファイルインデックスまでの包括的カバレッジ
-- **ファイル解析**：構造、インポート、クラス、メソッド、複雑度メトリクスへの深い洞察
+- **ファイル解析**：`build_deep_index` 実行後に構造、インポート、クラス、メソッド、複雑度メトリクスを深く把握
 
 ### 🗂️ **多言語サポート**
 - **7言語でTree-sitter AST解析**：Python、JavaScript、TypeScript、Java、Go、Objective-C、Zig
@@ -81,7 +81,7 @@ Code Index MCPは、AIモデルと複雑なコードベースの橋渡しをす
 - **ファイルウォッチャー**：ファイル変更時の自動インデックス更新
 - **クロスプラットフォーム**：ネイティブOSファイルシステム監視
 - **スマート処理**：急速な変更をバッチ処理して過度な再構築を防止
-- **豊富なメタデータ**：シンボル、参照、定義、関連性をキャプチャ
+- **浅いインデックス更新**：ファイル変更を監視して最新のファイル一覧を維持し、シンボルが必要な場合は `build_deep_index` を実行
 
 ### ⚡ **パフォーマンス・効率性**
 - **Tree-sitter AST解析**：正確なシンボル抽出のためのネイティブ構文解析
@@ -240,15 +240,18 @@ pip install code-index-mcp
 | ツール | 説明 |
 |--------|------|
 | **`set_project_path`** | プロジェクトディレクトリのインデックス作成を初期化 |
-| **`refresh_index`** | ファイル変更後にプロジェクトインデックスを再構築 |
+| **`refresh_index`** | ファイル変更後に浅いファイルインデックスを再構築 |
+| **`build_deep_index`** | 深い解析で使う完全なシンボルインデックスを生成 |
 | **`get_settings_info`** | 現在のプロジェクト設定と状態を表示 |
 
+*シンボルレベルのデータが必要な場合は `build_deep_index` を実行してください。デフォルトの浅いインデックスは高速なファイル探索を担います。*
+
 ### 🔍 **検索・発見**
 | ツール | 説明 |
 |--------|------|
 | **`search_code_advanced`** | 正規表現、ファジーマッチング、ファイルフィルタリング対応のスマート検索 |
 | **`find_files`** | globパターンを使用したファイル検索（例：`**/*.py`） |
-| **`get_file_summary`** | ファイル構造、関数、インポート、複雑度の解析 |
+| **`get_file_summary`** | ファイル構造、関数、インポート、複雑度の解析（深いインデックスが必要） |
 
 ### 🔄 **監視・自動更新**
 | ツール | 説明 |
@@ -285,6 +288,7 @@ src/components で全てのTypeScriptコンポーネントファイルを見つ
 src/api/userService.ts の要約を教えてください
 ```
 *使用ツール：`get_file_summary` で関数、インポート、複雑度を表示*
+*ヒント：`needs_deep_index` が返った場合は `build_deep_index` を先に実行してください。*
 
 ### 🔍 **高度な検索例**
 

README_zh.md

@@ -66,7 +66,7 @@
 - **直接 Tree-sitter 整合**：專業化語言無正則表達式備用 - 快速失敗並提供清晰錯誤訊息
 - **進階搜尋**：自動偵測並使用最佳工具（ugrep、ripgrep、ag 或 grep）
 - **通用檔案支援**：從進階 AST 解析到基本檔案索引的全面覆蓋
-- **檔案分析**：深入了解結構、匯入、類別、方法和複雜度指標
+- **檔案分析**：執行 `build_deep_index` 後深入了解結構、匯入、類別、方法和複雜度指標
 
 ### 🗂️ **多語言支援**
 - **7 種語言使用 Tree-sitter AST 解析**：Python、JavaScript、TypeScript、Java、Go、Objective-C、Zig
@@ -81,7 +81,7 @@
 - **檔案監控器**：檔案變更時自動更新索引
 - **跨平台**：原生作業系統檔案系統監控
 - **智慧處理**：批次處理快速變更以防止過度重建
-- **豐富元資料**：捕獲符號、引用、定義和關聯性
+- **淺層索引更新**：監控檔案變更並維持檔案清單最新；需要符號資料時請執行 `build_deep_index`
 
 ### ⚡ **效能與效率**
 - **Tree-sitter AST 解析**：原生語法解析以實現準確的符號提取
@@ -240,15 +240,18 @@ pip install code-index-mcp
 | 工具 | 描述 |
 |------|------|
 | **`set_project_path`** | 為專案目錄初始化索引 |
-| **`refresh_index`** | 在檔案變更後重建專案索引 |
+| **`refresh_index`** | 在檔案變更後重建淺層檔案索引 |
+| **`build_deep_index`** | 產生供深度分析使用的完整符號索引 |
 | **`get_settings_info`** | 檢視目前專案配置和狀態 |
 
+*需要符號層級資料時，請執行 `build_deep_index`；預設的淺層索引提供快速檔案探索。*
+
 ### 🔍 **搜尋與探索**
 | 工具 | 描述 |
 |------|------|
 | **`search_code_advanced`** | 智慧搜尋，支援正規表達式、模糊匹配和檔案篩選 |
 | **`find_files`** | 使用萬用字元模式尋找檔案（例如 `**/*.py`） |
-| **`get_file_summary`** | 分析檔案結構、函式、匯入和複雜度 |
+| **`get_file_summary`** | 分析檔案結構、函式、匯入和複雜度（需要深度索引） |
 
 ### 🔄 **監控與自動刷新**
 | 工具 | 描述 |
@@ -285,6 +288,7 @@ pip install code-index-mcp
 給我 src/api/userService.ts 的摘要
 ```
 *使用：`get_file_summary` 顯示函式、匯入和複雜度*
+*提示：若收到 `needs_deep_index` 回應，請先執行 `build_deep_index`。*
 
 ### 🔍 **進階搜尋範例**