docs: add watchdog troubleshooting for auto-refresh issues

Add troubleshooting section to README documenting the uvx environment
watchdog issue where automatic index updates may fail due to environment
isolation preventing file system monitoring APIs access.

- Add warning in Quick Start section for immediate visibility
- Include workaround solution: pip install watchdog
- Explain suspected cause related to uvx environment isolation
- Provide alternative manual refresh options
- Mark as under investigation to set proper expectations

Author: johnhuang316

README.md

@@ -136,6 +136,8 @@ The easiest way to get started with any MCP-compatible application:
 
 **Prerequisites:** Python 3.10+, [uv](https://github.com/astral-sh/uv), and [watchdog](https://pypi.org/project/watchdog/) for file monitoring
 
+> **⚠️ Auto-refresh Issue:** If automatic index updates don't work after setup, try `pip install watchdog`. This may be due to environment isolation preventing file system monitoring. See [Troubleshooting](#troubleshooting) for details.
+
 1. **Add to your MCP configuration** (e.g., `claude_desktop_config.json` or `~/.claude.json`):
    ```json
    {
@@ -305,6 +307,27 @@ I added new components, please refresh the project index
 
 </details>
 
+## Troubleshooting
+
+### 🔄 **Auto-refresh Not Working**
+
+If the automatic index updates aren't working when files change, this may be related to environment isolation issues with the `watchdog` dependency.
+
+**Quick Solution:**
+```bash
+pip install watchdog
+```
+
+**What we suspect is happening:**
+- The `uvx` environment provides isolated dependency management
+- On some systems (particularly Windows), environment isolation may prevent `watchdog` from accessing the file system monitoring APIs properly
+- Installing `watchdog` in your system Python environment appears to resolve this issue while maintaining all other benefits of `uvx` isolation
+- This is still under investigation, but the workaround above should get you working immediately
+
+**Alternative solutions:**
+- Use manual refresh: Call the `refresh_index` tool after making file changes
+- Check file watcher status: Use `get_file_watcher_status` to verify monitoring is active
+
 ## Development & Contributing
 
 ### 🔧 **Building from Source**

README_ja.md

@@ -136,6 +136,8 @@ Code Index MCPは、AIモデルと複雑なコードベースの橋渡しをす
 
 **前提条件：** Python 3.10+、[uv](https://github.com/astral-sh/uv)、ファイル監視用の [watchdog](https://pypi.org/project/watchdog/) がインストール済み
 
+> **⚠️ 自動リフレッシュの問題：** セットアップ後に自動インデックス更新が動作しない場合、`pip install watchdog` を試してください。これは環境分離によりファイルシステム監視が妨げられることが原因の可能性があります。詳細は [トラブルシューティング](#トラブルシューティング) をご覧ください。
+
 1. **MCP設定に追加**（例：`claude_desktop_config.json` または `~/.claude.json`）：
    ```json
    {
@@ -305,6 +307,27 @@ Pythonファイルのみで "API_ENDPOINT" を検索してください
 
 </details>
 
+## トラブルシューティング
+
+### 🔄 **自動リフレッシュが動作しない**
+
+ファイル変更時に自動インデックス更新が動作しない場合、これは `watchdog` 依存関係の環境分離の問題が関連している可能性があります。
+
+**クイック解決策：**
+```bash
+pip install watchdog
+```
+
+**推定される原因：**
+- `uvx` 環境は分離された依存関係管理を提供します
+- 一部のシステム（特にWindows）では、環境分離により `watchdog` がファイルシステム監視APIに適切にアクセスできない場合があります
+- システムPython環境に `watchdog` をインストールすることで、`uvx` 分離の他のすべての利点を維持しながら、この問題が解決されるようです
+- これはまだ調査中ですが、上記の回避策ですぐに動作するはずです
+
+**代替解決策：**
+- 手動リフレッシュを使用：ファイル変更後に `refresh_index` ツールを呼び出す
+- ファイルウォッチャーステータスを確認：`get_file_watcher_status` を使用して監視がアクティブかどうかを確認
+
 ## 開発・貢献
 
 ### 🔧 **ソースからのビルド**

README_zh.md

@@ -136,6 +136,8 @@
 
 **先決條件：** Python 3.10+、[uv](https://github.com/astral-sh/uv) 和用於檔案監控的 [watchdog](https://pypi.org/project/watchdog/) 已安裝
 
+> **⚠️ 自動刷新問題：** 如果設定後自動索引更新無法運作，請嘗試 `pip install watchdog`。這可能是由於環境隔離導致檔案系統監控無法正常運作。詳情請參閱 [故障排除](#故障排除)。
+
 1. **新增到您的 MCP 配置**（例如 `claude_desktop_config.json` 或 `~/.claude.json`）：
    ```json
    {
@@ -305,6 +307,27 @@ pip install code-index-mcp
 
 </details>
 
+## 故障排除
+
+### 🔄 **自動刷新無法運作**
+
+如果檔案變更時自動索引更新無法運作，這可能與 `watchdog` 依賴項的環境隔離問題有關。
+
+**快速解決方案：**
+```bash
+pip install watchdog
+```
+
+**我們懷疑發生的情況：**
+- `uvx` 環境提供隔離的依賴管理
+- 在某些系統上（特別是 Windows），環境隔離可能會阻止 `watchdog` 正確存取檔案系統監控 API
+- 在系統 Python 環境中安裝 `watchdog` 似乎可以解決此問題，同時維持 `uvx` 隔離的所有其他優點
+- 這仍在調查中，但上述解決方法應該能讓您立即恢復工作
+
+**替代解決方案：**
+- 使用手動刷新：在檔案變更後呼叫 `refresh_index` 工具
+- 檢查檔案監視器狀態：使用 `get_file_watcher_status` 驗證監控是否處於活動狀態
+
 ## 開發與貢獻
 
 ### 🔧 **從原始碼建構**