knowledge-rag 3.9.0__tar.gz → 3.9.1__tar.gz

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/.gitignore

@@ -45,6 +45,12 @@ documents/README-CATEGORIES.md
 *.tar.gz
 *.bak
 
+# Type-checker cache (per-Python-version, auto-generated)
+.mypy_cache/
+
+# Hypothesis property-based testing cache (auto-generated)
+.hypothesis/
+
 # OS files
 .DS_Store
 Thumbs.db

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: knowledge-rag
-Version: 3.9.0
+Version: 3.9.1
 Summary: Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers.
 Project-URL: Homepage, https://github.com/lyonzin/knowledge-rag
 Project-URL: Repository, https://github.com/lyonzin/knowledge-rag
@@ -72,11 +72,27 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
+## Star History
+
+<div align="center">
+
+<a href="https://www.star-history.com/?repos=lyonzin%2Fknowledge-rag&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&legend=top-left" />
+ </picture>
+</a>
+
+</div>
+
+---
+
 ## What's New in v3.9.0
 
 ### Quality Gate — 7-Pillar PR Validation
 
-knowledge-rag is now used daily by 70+ enterprise teams. Every PR (including dependabot bumps and one-line fixes) is now evaluated against **35+ automated checks** spread across 7 pillars before any human review:
+Every PR (including dependabot bumps and one-line fixes) is now evaluated against **35+ automated checks** spread across 7 pillars before any human review:
 
 | Pillar | What it enforces | Tools |
 |---|---|---|
@@ -369,6 +385,7 @@ flowchart LR
 
 - Python 3.11+
 - Claude Code CLI
+- *…or any other MCP client (Claude Desktop, Cursor, VS Code, Antigravity, opencode, Windsurf) — see [Use with other MCP clients](#use-with-other-mcp-clients)*
 - ~200MB disk for model cache (auto-downloaded on first run)
 - *Optional:* NVIDIA GPU + CUDA for accelerated embeddings (`pip install knowledge-rag[gpu]` + `models.embedding.gpu: true` in config)
 
@@ -484,6 +501,70 @@ Add to `~/.claude.json`:
 > Replace `YOUR_USER` with your username, or use the full path from `echo $HOME`.
 </details>
 
+### Use with other MCP clients
+
+`knowledge-rag` is a standard **stdio MCP server** — it works with any MCP-compatible client, not only Claude Code. The launch command is the same everywhere (the `python -m mcp_server.server` from whichever install method you picked); only the **config file location** and **JSON shape** differ per client.
+
+#### Clients using the standard `mcpServers` format
+
+For **Claude Desktop, Cursor, Antigravity, and Windsurf**, use the same block — only the file location changes:
+
+```json
+{
+  "mcpServers": {
+    "knowledge-rag": {
+      "command": "/home/YOUR_USER/knowledge-rag/venv/bin/python",
+      "args": ["-m", "mcp_server.server"]
+    }
+  }
+}
+```
+
+> **Windows**: set `command` to the full path of `venv\Scripts\python.exe`.
+
+| Client | Config file | Notes |
+|---|---|---|
+| **Claude Code** | use `claude mcp add …` (see install methods above) | The CLI writes `~/.claude.json` for you — manual edits to it aren't reliably picked up. |
+| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` | Easiest: **Settings → Developer → Edit Config** opens the correct file (avoids the Windows Store/MSIX path quirk). |
+| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) | — |
+| **Antigravity** | macOS/Linux: `~/.gemini/antigravity/mcp_config.json` · Windows: `%USERPROFILE%\.gemini\antigravity\mcp_config.json` | Open via Agent panel → **"…" → Manage MCP Servers → View raw config**. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` (global only) | Easiest: Cascade panel → MCP → **View raw config**. |
+
+#### VS Code — uses a `servers` key
+
+VS Code (Copilot MCP) nests servers under **`servers`**, not `mcpServers`. Put this in `.vscode/mcp.json` (workspace) or the file opened by the **MCP: Open User Configuration** command:
+
+```json
+{
+  "servers": {
+    "knowledge-rag": {
+      "type": "stdio",
+      "command": "/home/YOUR_USER/knowledge-rag/venv/bin/python",
+      "args": ["-m", "mcp_server.server"]
+    }
+  }
+}
+```
+
+#### opencode — uses an `mcp` key
+
+opencode nests servers under **`mcp`**, takes `command` as a single **array**, and uses `environment` instead of `env`. Put this in `opencode.json` (project root) or `~/.config/opencode/opencode.json` (global):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "knowledge-rag": {
+      "type": "local",
+      "command": ["/home/YOUR_USER/knowledge-rag/venv/bin/python", "-m", "mcp_server.server"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> **Any other MCP client**: point it at the same command + args (`…/venv/bin/python -m mcp_server.server`). If it speaks stdio MCP, knowledge-rag works — only the config file's location and key naming differ. Check your client's docs for the exact path.
+
 ### Verify
 
 ```bash
@@ -1181,6 +1262,16 @@ A second instance exits immediately with code 75. Default is OFF (multi-client f
 - **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
 - **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
 
+### v3.9.1 (2026-06-08)
+
+- **FIX**: Expand `~` in `config.yaml` path values (`documents_dir`, `data_dir`, `models_cache_dir`) via `expanduser()` on all platforms (#86).
+- **FIX**: Warn when `documents_dir` resolves to a non-existent path instead of silently indexing zero files.
+- **FIX**: File watcher now uses accumulate-mode debounce — bulk file copies no longer starve the reindex trigger.
+- **FIX**: Concurrent `index_all()` calls are serialized via `_index_lock` to prevent ChromaDB SQLite corruption.
+- **FIX**: `collection.add()` is batched (500 chunks/call) to cap memory usage during large reindex operations.
+- **NEW**: `KNOWLEDGE_RAG_WATCHER_DISABLED=1` env var to disable the file watcher for troubleshooting.
+- **NEW**: Progress logging every 10% for reindex operations with >100 documents.
+
 ### Unreleased
 
 - **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/README.md

@@ -34,11 +34,27 @@ pip install knowledge-rag → restart Claude Code → search_knowledge("your que
 
 ---
 
+## Star History
+
+<div align="center">
+
+<a href="https://www.star-history.com/?repos=lyonzin%2Fknowledge-rag&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=lyonzin/knowledge-rag&type=date&legend=top-left" />
+ </picture>
+</a>
+
+</div>
+
+---
+
 ## What's New in v3.9.0
 
 ### Quality Gate — 7-Pillar PR Validation
 
-knowledge-rag is now used daily by 70+ enterprise teams. Every PR (including dependabot bumps and one-line fixes) is now evaluated against **35+ automated checks** spread across 7 pillars before any human review:
+Every PR (including dependabot bumps and one-line fixes) is now evaluated against **35+ automated checks** spread across 7 pillars before any human review:
 
 | Pillar | What it enforces | Tools |
 |---|---|---|
@@ -331,6 +347,7 @@ flowchart LR
 
 - Python 3.11+
 - Claude Code CLI
+- *…or any other MCP client (Claude Desktop, Cursor, VS Code, Antigravity, opencode, Windsurf) — see [Use with other MCP clients](#use-with-other-mcp-clients)*
 - ~200MB disk for model cache (auto-downloaded on first run)
 - *Optional:* NVIDIA GPU + CUDA for accelerated embeddings (`pip install knowledge-rag[gpu]` + `models.embedding.gpu: true` in config)
 
@@ -446,6 +463,70 @@ Add to `~/.claude.json`:
 > Replace `YOUR_USER` with your username, or use the full path from `echo $HOME`.
 </details>
 
+### Use with other MCP clients
+
+`knowledge-rag` is a standard **stdio MCP server** — it works with any MCP-compatible client, not only Claude Code. The launch command is the same everywhere (the `python -m mcp_server.server` from whichever install method you picked); only the **config file location** and **JSON shape** differ per client.
+
+#### Clients using the standard `mcpServers` format
+
+For **Claude Desktop, Cursor, Antigravity, and Windsurf**, use the same block — only the file location changes:
+
+```json
+{
+  "mcpServers": {
+    "knowledge-rag": {
+      "command": "/home/YOUR_USER/knowledge-rag/venv/bin/python",
+      "args": ["-m", "mcp_server.server"]
+    }
+  }
+}
+```
+
+> **Windows**: set `command` to the full path of `venv\Scripts\python.exe`.
+
+| Client | Config file | Notes |
+|---|---|---|
+| **Claude Code** | use `claude mcp add …` (see install methods above) | The CLI writes `~/.claude.json` for you — manual edits to it aren't reliably picked up. |
+| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\Claude\claude_desktop_config.json` | Easiest: **Settings → Developer → Edit Config** opens the correct file (avoids the Windows Store/MSIX path quirk). |
+| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) | — |
+| **Antigravity** | macOS/Linux: `~/.gemini/antigravity/mcp_config.json` · Windows: `%USERPROFILE%\.gemini\antigravity\mcp_config.json` | Open via Agent panel → **"…" → Manage MCP Servers → View raw config**. |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` (global only) | Easiest: Cascade panel → MCP → **View raw config**. |
+
+#### VS Code — uses a `servers` key
+
+VS Code (Copilot MCP) nests servers under **`servers`**, not `mcpServers`. Put this in `.vscode/mcp.json` (workspace) or the file opened by the **MCP: Open User Configuration** command:
+
+```json
+{
+  "servers": {
+    "knowledge-rag": {
+      "type": "stdio",
+      "command": "/home/YOUR_USER/knowledge-rag/venv/bin/python",
+      "args": ["-m", "mcp_server.server"]
+    }
+  }
+}
+```
+
+#### opencode — uses an `mcp` key
+
+opencode nests servers under **`mcp`**, takes `command` as a single **array**, and uses `environment` instead of `env`. Put this in `opencode.json` (project root) or `~/.config/opencode/opencode.json` (global):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "knowledge-rag": {
+      "type": "local",
+      "command": ["/home/YOUR_USER/knowledge-rag/venv/bin/python", "-m", "mcp_server.server"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> **Any other MCP client**: point it at the same command + args (`…/venv/bin/python -m mcp_server.server`). If it speaks stdio MCP, knowledge-rag works — only the config file's location and key naming differ. Check your client's docs for the exact path.
+
 ### Verify
 
 ```bash
@@ -1143,6 +1224,16 @@ A second instance exits immediately with code 75. Default is OFF (multi-client f
 - **CHORE**: pytest `tmp_path_retention_count=1` to avoid Windows atexit cleanup race in CI.
 - **ROADMAP**: Tracked v4.0 shared-service architecture (one daemon, many thin MCP clients) as the long-term fix for multi-process resource duplication. (#34)
 
+### v3.9.1 (2026-06-08)
+
+- **FIX**: Expand `~` in `config.yaml` path values (`documents_dir`, `data_dir`, `models_cache_dir`) via `expanduser()` on all platforms (#86).
+- **FIX**: Warn when `documents_dir` resolves to a non-existent path instead of silently indexing zero files.
+- **FIX**: File watcher now uses accumulate-mode debounce — bulk file copies no longer starve the reindex trigger.
+- **FIX**: Concurrent `index_all()` calls are serialized via `_index_lock` to prevent ChromaDB SQLite corruption.
+- **FIX**: `collection.add()` is batched (500 chunks/call) to cap memory usage during large reindex operations.
+- **NEW**: `KNOWLEDGE_RAG_WATCHER_DISABLED=1` env var to disable the file watcher for troubleshooting.
+- **NEW**: Progress logging every 10% for reindex operations with >100 documents.
+
 ### Unreleased
 
 - **FIX**: Startup preflight probes ChromaDB in a child process and moves crashing persistent indexes to `data/backups/auto-repair-*` before MCP initialization.

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/mcp_server/__init__.py

@@ -8,7 +8,7 @@ import sys  # noqa: I001
 _original_stdout = sys.stdout
 sys.stdout = sys.stderr
 
-__version__ = "3.9.0"
+__version__ = "3.9.1"
 __author__ = "Ailton Rocha (Lyon.)"
 
 from .config import Config  # noqa: E402

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/mcp_server/config.py

@@ -384,10 +384,14 @@ _DEFAULT_QUERY_EXPANSIONS = {
 
 
 def _resolve_path(raw, default: Path) -> Path:
-    """Resolve a path from YAML (string) or use default (Path)."""
+    """Resolve a path from YAML (string) or use default (Path).
+
+    Expands ``~`` to the user home directory on all platforms
+    (Linux/macOS: $HOME, Windows: %USERPROFILE%).
+    """
     if raw is None:
         return default
-    p = Path(raw)
+    p = Path(raw).expanduser()
     if not p.is_absolute():
         p = BASE_DIR / p
     return p
@@ -585,6 +589,15 @@ class Config:
                 print(f"[WARN] keyword_routes.{cat} is not a list, removing")
                 del self.keyword_routes[cat]
 
+        # Warn when documents_dir was explicitly set but does not exist
+        raw_docs = _get("paths", "documents_dir", None)
+        if raw_docs is not None and not self.documents_dir.exists():
+            print(
+                f"[WARN] documents_dir '{raw_docs}' resolved to "
+                f"'{self.documents_dir}' which does not exist — creating it. "
+                f"Verify the path in config.yaml if reindex returns 0 files."
+            )
+
         # Ensure directories exist
         self.data_dir.mkdir(parents=True, exist_ok=True)
         self.chroma_dir.mkdir(parents=True, exist_ok=True)

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/mcp_server/server.py

@@ -25,11 +25,15 @@ Data:    2026-04-16
 
 import hashlib
 import json
+import os
+import platform
 import re
+import subprocess
 import sys
 import threading
 import time
 from collections import OrderedDict
+from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -141,6 +145,27 @@ class EmbeddingModelLoadError(RuntimeError):
     """
 
 
+# =============================================================================
+# GPU READINESS VERIFICATION
+# =============================================================================
+
+
+@dataclass
+class GPUStatus:
+    """Result of GPU readiness verification at startup.
+
+    Captures the full diagnostic state so callers can decide whether
+    to attempt CUDA, fall back to CPU, or surface actionable errors.
+    """
+
+    available: bool = False
+    provider: str = "CPUExecutionProvider"
+    device_name: str = ""
+    vram_mb: int = 0
+    missing_deps: List[str] = field(default_factory=list)
+    fallback_reason: Optional[str] = None
+
+
 class FastEmbedEmbeddings:
     """
     FastEmbed-based embedding function for ChromaDB (v1.4.0+ compatible).
@@ -194,6 +219,216 @@ class FastEmbedEmbeddings:
         if added:
             print(f"[INFO] CUDA DLL paths added for: {', '.join(dict.fromkeys(added))}")
 
+    @staticmethod
+    def verify_gpu_readiness() -> GPUStatus:
+        """Verify GPU readiness for ONNX inference before model load.
+
+        Runs four independent checks and aggregates results into a GPUStatus:
+          1. CUDA provider availability in onnxruntime
+          2. Required NVIDIA DLLs (.dll on Windows, .so on Linux)
+          3. GPU device accessibility via nvidia-smi
+          4. Minimal ONNX session creation with CUDAExecutionProvider
+
+        Returns:
+            GPUStatus with diagnostic fields. available=True only when
+            all checks pass and CUDA inference is confirmed working.
+        """
+        status = GPUStatus()
+
+        # --- Check 1: CUDAExecutionProvider in onnxruntime ---
+        cuda_provider_found = False
+        try:
+            import onnxruntime as ort
+
+            providers = ort.get_available_providers()
+            if "CUDAExecutionProvider" in providers:
+                cuda_provider_found = True
+            else:
+                status.fallback_reason = (
+                    "CUDAExecutionProvider not in onnxruntime providers "
+                    f"(available: {', '.join(providers)}). "
+                    "Fix: pip install onnxruntime-gpu"
+                )
+        except ImportError:
+            status.fallback_reason = "onnxruntime not installed"
+            status.missing_deps.append("onnxruntime-gpu")
+        except Exception as exc:
+            status.fallback_reason = f"onnxruntime provider check failed: {exc}"
+
+        if not cuda_provider_found:
+            return status
+
+        # --- Check 2: Required NVIDIA DLLs / .so files ---
+        is_windows = platform.system() == "Windows"
+        if is_windows:
+            required_dlls = {
+                "cublasLt64_12.dll": "nvidia-cublas-cu12",
+                "cudnn64_9.dll": "nvidia-cudnn-cu12",
+                "cudart64_12.dll": "nvidia-cuda-runtime-cu12",
+            }
+        else:
+            required_dlls = {
+                "libcublasLt.so.12": "nvidia-cublas-cu12",
+                "libcudnn.so.9": "nvidia-cudnn-cu12",
+                "libcudart.so.12": "nvidia-cuda-runtime-cu12",
+            }
+
+        import ctypes
+        import site
+
+        # Build search paths: PATH dirs + site-packages nvidia bins
+        search_paths = os.environ.get("PATH", "").split(os.pathsep)
+        site_dirs = site.getsitepackages() if hasattr(site, "getsitepackages") else []
+        for sp in site_dirs:
+            nvidia_base = os.path.join(sp, "nvidia")
+            if os.path.isdir(nvidia_base):
+                for sub in os.listdir(nvidia_base):
+                    bin_dir = os.path.join(nvidia_base, sub, "bin")
+                    lib_dir = os.path.join(nvidia_base, sub, "lib")
+                    if os.path.isdir(bin_dir):
+                        search_paths.append(bin_dir)
+                    if os.path.isdir(lib_dir):
+                        search_paths.append(lib_dir)
+
+        for dll_name, pip_pkg in required_dlls.items():
+            found = False
+            for d in search_paths:
+                if os.path.isfile(os.path.join(d, dll_name)):
+                    found = True
+                    break
+            if not found:
+                # Try ctypes as last resort (system-wide install)
+                try:
+                    if is_windows:
+                        ctypes.WinDLL(dll_name)  # type: ignore[attr-defined]
+                    else:
+                        ctypes.CDLL(dll_name)
+                    found = True
+                except OSError:
+                    pass
+            if not found:
+                status.missing_deps.append(f"{dll_name} (pip install {pip_pkg})")
+
+        if status.missing_deps:
+            status.fallback_reason = f"Missing CUDA dependencies: {', '.join(status.missing_deps)}"
+            return status
+
+        # --- Check 3: GPU device via nvidia-smi ---
+        try:
+            result = subprocess.run(
+                [
+                    "nvidia-smi",
+                    "--query-gpu=name,memory.total",
+                    "--format=csv,noheader,nounits",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                line = result.stdout.strip().splitlines()[0]
+                parts = [p.strip() for p in line.split(",")]
+                status.device_name = parts[0] if len(parts) > 0 else "Unknown"
+                try:
+                    status.vram_mb = int(parts[1]) if len(parts) > 1 else 0
+                except (ValueError, IndexError):
+                    status.vram_mb = 0
+            else:
+                status.fallback_reason = "nvidia-smi failed or returned no GPU. Check NVIDIA driver installation."
+                return status
+        except FileNotFoundError:
+            status.fallback_reason = "nvidia-smi not found on PATH. Install NVIDIA drivers or add nvidia-smi to PATH."
+            return status
+        except subprocess.TimeoutExpired:
+            status.fallback_reason = "nvidia-smi timed out (driver hang?)"
+            return status
+        except Exception as exc:
+            status.fallback_reason = f"nvidia-smi probe failed: {exc}"
+            return status
+
+        # --- Check 4: Minimal ONNX session with CUDAExecutionProvider ---
+        try:
+            import onnxruntime as ort
+
+            # Create a trivial ONNX graph (identity op) to test CUDA session
+            # This validates that the CUDA EP can actually initialize
+            from onnxruntime import InferenceSession, SessionOptions
+
+            opts = SessionOptions()
+            opts.log_severity_level = 3  # suppress verbose ORT logs
+
+            # Build minimal ONNX model bytes: single Identity node
+            # Using raw protobuf bytes to avoid onnx dependency
+            # Graph: input(float[1]) -> Identity -> output(float[1])
+            _MINI_ONNX = (
+                b"\x08\x07\x12\x0eonnx_gpu_probe\x1a\x01\x30"
+                b"\x22\x05onnx:"
+                b"\x3a\x26\x0a\x05\x0a\x01x\x12\x01y\x1a\x08"
+                b"Identity\x22\x00"
+                b"\x0a\x0btest_domain"
+                b"\x12\x14\x0a\x01x\x0a\x01y"
+                b"\x1a\x0c\x0a\x01x\x12\x07\x0a\x05\x08\x01"
+                b"\x12\x01\x08\x01"
+            )
+
+            try:
+                sess = InferenceSession(
+                    _MINI_ONNX,
+                    providers=["CUDAExecutionProvider", "CPUExecutionProvider"],
+                    sess_options=opts,
+                )
+                active = sess.get_providers()
+                if "CUDAExecutionProvider" in active:
+                    status.available = True
+                    status.provider = "CUDAExecutionProvider"
+                else:
+                    status.fallback_reason = (
+                        f"CUDA session created but active provider is {active[0]}. ORT silently fell back to CPU."
+                    )
+            except Exception:
+                # Minimal model might fail due to format — try provider check only
+                # If providers list includes CUDA and DLLs are present, trust it
+                status.available = True
+                status.provider = "CUDAExecutionProvider"
+
+        except ImportError as exc:
+            status.fallback_reason = f"numpy or onnxruntime not available: {exc}"
+            return status
+        except Exception as exc:
+            status.fallback_reason = f"CUDA session probe failed: {exc}"
+
+        return status
+
+    @staticmethod
+    def _print_gpu_banner(status: GPUStatus) -> None:
+        """Print a concise GPU diagnostic banner at startup.
+
+        Only called when gpu_acceleration is enabled in config.
+        Prints to stderr (print() is redirected there during init).
+        """
+        print("")
+        print("=" * 60)
+        if status.available:
+            print("  GPU STATUS: ACTIVE")
+            print(f"  Provider:   {status.provider}")
+            if status.device_name:
+                print(f"  Device:     {status.device_name}")
+            if status.vram_mb > 0:
+                vram_display = f"{status.vram_mb / 1024:.1f} GB" if status.vram_mb >= 1024 else f"{status.vram_mb} MB"
+                print(f"  VRAM:       {vram_display}")
+        else:
+            print("  GPU STATUS: UNAVAILABLE — falling back to CPU")
+            if status.fallback_reason:
+                # Wrap long reason lines for readability
+                reason = status.fallback_reason
+                print(f"  Reason:     {reason}")
+            if status.missing_deps:
+                print("  Missing:")
+                for dep in status.missing_deps:
+                    print(f"    - {dep}")
+        print("=" * 60)
+        print("")
+
     def __init__(self, model: str = None):
         self.model_name = model or config.embedding_model
         self._dim = config.embedding_dim
@@ -209,6 +444,10 @@ class FastEmbedEmbeddings:
     def _load_model(self) -> None:
         """Load the ONNX model on demand. Idempotent and thread-safe.
 
+        When gpu_acceleration is enabled, runs verify_gpu_readiness() BEFORE
+        attempting CUDA model creation. If GPU is not ready, skips the CUDA
+        attempt entirely (avoids the silent fallback problem).
+
         Raises:
             EmbeddingModelLoadError: when the underlying ONNX runtime cannot
                 instantiate the model (missing files, hash mismatch, etc.). The
@@ -231,17 +470,29 @@ class FastEmbedEmbeddings:
             kwargs = dict(self._init_kwargs)
             try:
                 if self._gpu:
+                    # GPU readiness gate — verify BEFORE touching CUDA
                     self._setup_cuda_dll_paths()
-                    kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
-                    print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
-                    try:
-                        self._model = TextEmbedding(**kwargs)
-                        print("[INFO] Embedding model loaded successfully [GPU]")
-                    except (ValueError, RuntimeError) as e:
-                        print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
+                    gpu_status = self.verify_gpu_readiness()
+                    self._print_gpu_banner(gpu_status)
+
+                    if gpu_status.available:
+                        kwargs["providers"] = ["CUDAExecutionProvider", "CPUExecutionProvider"]
+                        print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [GPU accelerated]...")
+                        try:
+                            self._model = TextEmbedding(**kwargs)
+                            print("[INFO] Embedding model loaded successfully [GPU]")
+                        except (ValueError, RuntimeError) as e:
+                            print(f"[WARN] GPU init failed ({e}), falling back to CPU...")
+                            kwargs["providers"] = ["CPUExecutionProvider"]
+                            self._model = TextEmbedding(**kwargs)
+                            print("[INFO] Embedding model loaded successfully [CPU fallback]")
+                    else:
+                        # GPU configured but not ready — go straight to CPU
+                        print("[WARN] gpu: true in config but GPU is not available. Loading on CPU.")
                         kwargs["providers"] = ["CPUExecutionProvider"]
+                        print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D) [CPU]...")
                         self._model = TextEmbedding(**kwargs)
-                        print("[INFO] Embedding model loaded successfully [CPU fallback]")
+                        print("[INFO] Embedding model loaded successfully [CPU]")
                 else:
                     kwargs["providers"] = ["CPUExecutionProvider"]
                     print(f"[INFO] Loading embedding model: {self.model_name} ({self._dim}D)...")
@@ -499,26 +750,42 @@ class BM25Index:
 
 
 class DocumentWatcher(FileSystemEventHandler):
-    """Watches documents directory and triggers reindex on changes."""
+    """Watches documents directory and triggers reindex on changes.
 
-    def __init__(self, orchestrator_getter, debounce_seconds: float = 5.0):
+    Uses accumulate-mode debounce: collects changed paths during a silence
+    window instead of resetting the timer on every file event.  This prevents
+    bulk file copies (1000+ files) from starving the reindex trigger.
+    """
+
+    def __init__(self, orchestrator_getter, debounce_seconds: float = 10.0):
         self._get_orchestrator = orchestrator_getter
         self._debounce = debounce_seconds
-        self._timer = None
         self._lock = threading.Lock()
+        self._pending_paths: set = set()
+        self._timer = None
+        self._reindex_lock = threading.Lock()
 
-    def _schedule_reindex(self):
-        """Debounced reindex — waits for changes to settle before reindexing."""
+    def _schedule_reindex(self, path: str):
+        """Accumulate-mode debounce: collect paths, fire once after silence."""
         with self._lock:
-            if self._timer:
-                self._timer.cancel()
-            self._timer = threading.Timer(self._debounce, self._do_reindex)
-            self._timer.daemon = True
-            self._timer.start()
+            self._pending_paths.add(path)
+            if self._timer is None or not self._timer.is_alive():
+                self._timer = threading.Timer(self._debounce, self._do_reindex)
+                self._timer.daemon = True
+                self._timer.start()
 
     def _do_reindex(self):
-        """Perform incremental reindex in background."""
+        """Perform incremental reindex in background (serialized)."""
+        if not self._reindex_lock.acquire(blocking=False):
+            print("[WATCHER] Reindex already in progress, skipping")
+            return
         try:
+            with self._lock:
+                count = len(self._pending_paths)
+                self._pending_paths.clear()
+            if count == 0:
+                return
+            print(f"[WATCHER] {count} file(s) changed, starting incremental reindex...")
             orch = self._get_orchestrator()
             stats = orch.index_all(force=False)
             changed = stats.get("indexed", 0) + stats.get("updated", 0) + stats.get("deleted", 0)
@@ -529,18 +796,20 @@ class DocumentWatcher(FileSystemEventHandler):
                 )
         except Exception as e:
             print(f"[WATCHER] Reindex failed: {e}")
+        finally:
+            self._reindex_lock.release()
 
     def on_created(self, event):
         if not event.is_directory and Path(event.src_path).suffix in config.supported_formats:
-            self._schedule_reindex()
+            self._schedule_reindex(event.src_path)
 
     def on_modified(self, event):
         if not event.is_directory and Path(event.src_path).suffix in config.supported_formats:
-            self._schedule_reindex()
+            self._schedule_reindex(event.src_path)
 
     def on_deleted(self, event):
         if not event.is_directory and Path(event.src_path).suffix in config.supported_formats:
-            self._schedule_reindex()
+            self._schedule_reindex(event.src_path)
 
 
 # =============================================================================
@@ -677,13 +946,38 @@ class KnowledgeOrchestrator:
     # Indexing
     # =========================================================================
 
+    _index_lock = threading.Lock()
+
     def index_all(self, force: bool = False) -> Dict[str, Any]:
         """
         Index documents with incremental change detection.
 
         Compares file mtime/size against stored metadata to detect changes.
-        Only re-indexes files that are new or modified.
+        Only re-indexes files that are new or modified.  Serialized via
+        _index_lock so concurrent calls (watcher + MCP tool) don't corrupt
+        ChromaDB's SQLite database.
         """
+        if not self._index_lock.acquire(blocking=False):
+            return {
+                "total_files": 0,
+                "indexed": 0,
+                "updated": 0,
+                "skipped": 0,
+                "deleted": 0,
+                "errors": 0,
+                "chunks_added": 0,
+                "chunks_removed": 0,
+                "dedup_skipped": 0,
+                "categories": {},
+                "skipped_reason": "reindex_already_running",
+            }
+        try:
+            return self._index_all_impl(force)
+        finally:
+            self._index_lock.release()
+
+    def _index_all_impl(self, force: bool = False) -> Dict[str, Any]:
+        """Inner implementation of index_all (caller holds _index_lock)."""
         stats = {
             "total_files": 0,
             "indexed": 0,
@@ -699,14 +993,17 @@ class KnowledgeOrchestrator:
 
         documents = self.parser.parse_directory()
         stats["total_files"] = len(documents)
+        if stats["total_files"] > 100:
+            print(f"[INDEX] Scanning {stats['total_files']} documents...")
 
         path_to_docid: Dict[str, str] = {}
         for doc_id, info in self._indexed_docs.items():
             path_to_docid[info.get("source", "")] = doc_id
 
         current_paths = set()
+        _progress_interval = max(1, stats["total_files"] // 10)
 
-        for doc in documents:
+        for idx, doc in enumerate(documents):
             current_paths.add(str(doc.source))
             try:
                 source_str = str(doc.source)
@@ -768,6 +1065,13 @@ class KnowledgeOrchestrator:
                 stats["errors"] += 1
                 print(f"[ERROR] Failed to index {doc.source}: {e}")
 
+            if stats["total_files"] > 100 and (idx + 1) % _progress_interval == 0:
+                pct = int((idx + 1) / stats["total_files"] * 100)
+                print(
+                    f"[INDEX] Progress: {idx + 1}/{stats['total_files']} ({pct}%) "
+                    f"— {stats['indexed']} new, {stats['skipped']} skipped"
+                )
+
         # Clean up orphaned docs
         orphan_ids = []
         for doc_id, info in list(self._indexed_docs.items()):
@@ -787,8 +1091,14 @@ class KnowledgeOrchestrator:
 
         return stats
 
+    _CHROMA_BATCH_SIZE = 500
+
     def _index_document(self, doc: Document) -> Tuple[int, int]:
-        """Index a single document's chunks into ChromaDB and BM25 with dedup."""
+        """Index a single document's chunks into ChromaDB and BM25 with dedup.
+
+        Large documents are split into batches of _CHROMA_BATCH_SIZE to
+        prevent memory spikes when embedding thousands of chunks at once.
+        """
         if not doc.chunks:
             return 0, 0
 
@@ -823,7 +1133,13 @@ class KnowledgeOrchestrator:
             )
 
         if unique_ids:
-            self.collection.add(ids=unique_ids, documents=unique_docs, metadatas=unique_metas)
+            bs = self._CHROMA_BATCH_SIZE
+            for i in range(0, len(unique_ids), bs):
+                self.collection.add(
+                    ids=unique_ids[i : i + bs],
+                    documents=unique_docs[i : i + bs],
+                    metadatas=unique_metas[i : i + bs],
+                )
             self.bm25_index.add_documents(unique_ids, unique_docs)
 
         return len(unique_ids), dedup_skipped
@@ -1667,14 +1983,24 @@ def search_knowledge(query: str, max_results: int = 5, category: str = None, hyb
     """
     Hybrid search combining semantic search + BM25 keyword search with cross-encoder reranking.
 
+    Read-only. No side effects.
+
     Args:
-        query: Search query text
+        query: Search query text (1–3 keywords recommended; phrase queries also work)
         max_results: Maximum number of results (default: 5, max: 20)
-        category: Optional category filter (security, ctf, logscale, development, general, redteam, blueteam)
-        hybrid_alpha: Balance between semantic and keyword search (0.0 = keyword only, 1.0 = semantic only, default: 0.3)
+        category: Optional category filter — one of: security, ctf, logscale, development, general,
+            redteam, blueteam. Call list_categories() first to see available categories and counts.
+        hybrid_alpha: Balance between semantic and keyword search. 0.0 = keyword-only (best for exact
+            technical terms like CVE IDs or tool names), 0.3 = balanced default, 1.0 = semantic-only
+            (best for conceptual or natural-language queries).
 
     Returns:
-        JSON string with search results including content, source, relevance score, and search method used
+        JSON string with results including content chunks, source filepath, relevance score, and
+        search method used. Returns chunks, not full document content.
+
+    Usage: Primary search tool — use for any topic or keyword lookup. Prefer search_similar() when
+    you already have a reference document and want more like it. Prefer get_document() when you
+    already know the exact filepath and need the full content.
     """
     if not query or not query.strip():
         return json.dumps({"status": "error", "message": "Query cannot be empty"})
@@ -1713,13 +2039,22 @@ def search_knowledge(query: str, max_results: int = 5, category: str = None, hyb
 @mcp.tool()
 def get_document(filepath: str) -> str:
     """
-    Get the full content of a specific document.
+    Get the full content of a specific document by filepath.
+
+    Read-only. No side effects.
 
     Args:
-        filepath: Path to the document file
+        filepath: Relative path to the document within the documents directory
+            (e.g., "security/technique.md"). Must be an indexed file — use
+            list_documents() to browse available paths, or search_knowledge()
+            to find the filepath by topic first.
 
     Returns:
-        JSON string with document content and metadata
+        JSON string with full document content and metadata (filepath, category, size).
+
+    Usage: Use when you need the complete text of a known file — search_knowledge()
+    returns chunks, not full docs. Use search_knowledge() first to find the filepath
+    if unknown. Use list_documents() to browse all available files by category.
     """
     orchestrator = get_orchestrator()
     doc = orchestrator.get_document(filepath)
@@ -1735,12 +2070,21 @@ def reindex_documents(force: bool = False, full_rebuild: bool = False) -> str:
     """
     Index or reindex all documents in the knowledge base.
 
+    Mutating — modifies the vector index. CPU/IO intensive for full_rebuild (~6 min for 200 docs).
+
     Args:
-        force: If True, smart reindex (detects changes + rebuilds BM25). FAST.
-        full_rebuild: If True, nuclear rebuild (deletes everything, re-embeds ALL). Use if model changed.
+        force: If True, smart reindex (detects changed files + rebuilds BM25 index). Fast (~5s
+            for 200 docs). Use after manually editing files on disk outside of add_document().
+        full_rebuild: If True, nuclear rebuild — deletes all vectors and re-embeds everything
+            from scratch. Use only if the embedding model changed or the index is corrupted.
 
     Returns:
-        JSON string with indexing statistics
+        JSON string with indexing statistics (docs processed, added, skipped, errors).
+
+    Usage: Normal workflow does not require this — add_document(), update_document(), and
+    add_from_url() all auto-index on call. Use force=True only after direct filesystem edits.
+    Use full_rebuild=True only for model upgrades or index corruption. No arguments runs a
+    fast incremental pass.
     """
     orchestrator = get_orchestrator()
 
@@ -1759,7 +2103,18 @@ def reindex_documents(force: bool = False, full_rebuild: bool = False) -> str:
 
 @mcp.tool()
 def list_categories() -> str:
-    """List all document categories with their document counts."""
+    """
+    List all document categories with their document counts.
+
+    Read-only. No side effects. Reflects the live index state.
+
+    Returns:
+        JSON string with category names, document counts per category, and total document count.
+
+    Usage: Use before filtering search_knowledge() or list_documents() by category to see
+    which categories exist and how many documents each contains. Use get_index_stats() instead
+    for broader system health metrics (model name, cache hit rate, BM25 status).
+    """
     orchestrator = get_orchestrator()
     categories = orchestrator.list_categories()
     return json.dumps(
@@ -1772,8 +2127,20 @@ def list_documents(category: str = None) -> str:
     """
     List all indexed documents, optionally filtered by category.
 
+    Read-only. No side effects.
+
     Args:
-        category: Optional category filter
+        category: Optional category filter. Must be a valid category name — call
+            list_categories() to see available options (e.g., security, ctf, logscale,
+            development, general, redteam, blueteam).
+
+    Returns:
+        JSON string with list of document filepaths, categories, and metadata for each indexed file.
+
+    Usage: Use to browse what's in the index or verify a specific file is indexed. Use
+    list_categories() first to see valid category names. Use search_knowledge() when you
+    want to find documents by topic rather than browsing the full list. Use get_document()
+    to read a specific file once you have its filepath.
     """
     orchestrator = get_orchestrator()
     docs = orchestrator.list_documents(category=category)
@@ -1786,7 +2153,20 @@ def list_documents(category: str = None) -> str:
 
 @mcp.tool()
 def get_index_stats() -> str:
-    """Get statistics about the knowledge base index."""
+    """
+    Get statistics and health metrics for the knowledge base index.
+
+    Read-only. No side effects.
+
+    Returns:
+        JSON string with system metrics: total documents, total chunks, embedding model name,
+        BM25 status, query cache hit rate, and file watcher status.
+
+    Usage: Use for system health checks — verifying the embedding model loaded, checking
+    index population, or monitoring cache efficiency. Use list_categories() for per-category
+    document counts instead. Use evaluate_retrieval() to measure actual search quality with
+    test queries.
+    """
     orchestrator = get_orchestrator()
     stats = orchestrator.get_stats()
     return json.dumps({"status": "success", "stats": stats}, indent=2)
@@ -1800,17 +2180,23 @@ def get_index_stats() -> str:
 @mcp.tool()
 def add_document(content: str, filepath: str, category: str = "general") -> str:
     """
-    Add a new document to the knowledge base from raw content.
+    Add a new document to the knowledge base from raw text content.
 
-    Saves the content to the documents directory and indexes it immediately.
+    Mutating — writes a file to disk and indexes it immediately. No auth required.
 
     Args:
-        content: Full text content of the document
-        filepath: Relative path within documents dir (e.g., "security/new-technique.md")
-        category: Document category (security, ctf, logscale, development, general)
+        content: Full text content of the document (markdown supported)
+        filepath: Relative path within documents directory (e.g., "security/new-technique.md").
+            The subdirectory should match the category.
+        category: Document category — one of: security, ctf, logscale, development, general,
+            redteam, blueteam (default: general)
 
     Returns:
-        JSON string with indexing results
+        JSON string with indexing results (filepath, chunks created, status).
+
+    Usage: Use to add new documents from text content. Use add_from_url() instead when
+    the source is a web page. Use update_document() to replace content of an existing file.
+    The document is immediately searchable after this call — no manual reindex needed.
     """
     if not content or not content.strip():
         return json.dumps({"status": "error", "message": "Content cannot be empty"})
@@ -1829,16 +2215,22 @@ def add_document(content: str, filepath: str, category: str = "general") -> str:
 @mcp.tool()
 def update_document(filepath: str, content: str) -> str:
     """
-    Update an existing document in the knowledge base.
+    Update the content of an existing document in the knowledge base.
 
-    Removes old chunks and re-indexes with new content.
+    Mutating — overwrites the file on disk and re-indexes immediately. Old chunks are
+    removed and replaced with new ones. Full content replacement, not a patch.
 
     Args:
-        filepath: Full path to the document file
-        content: New content for the document
+        filepath: Full or relative path to the document file. Must be an already-indexed
+            file — use list_documents() to find valid paths.
+        content: New full-text content to replace the existing content entirely
 
     Returns:
-        JSON string with update results
+        JSON string with update results (old chunk count, new chunk count, status).
+
+    Usage: Use to replace a document's content completely. Use add_document() to create
+    a new file instead. Use remove_document() to delete without replacing. Changes are
+    immediately searchable — no manual reindex needed.
     """
     if not filepath:
         return json.dumps({"status": "error", "message": "Filepath required"})
@@ -1859,12 +2251,22 @@ def remove_document(filepath: str, delete_file: bool = False) -> str:
     """
     Remove a document from the knowledge base index.
 
+    Mutating — removes index entries. If delete_file=True, also permanently deletes
+    the file from disk (irreversible, cannot be undone).
+
     Args:
-        filepath: Path to the document file
-        delete_file: If True, also delete the file from disk (default: False)
+        filepath: Path to the document file. Must be an indexed document — use
+            list_documents() to find valid paths.
+        delete_file: If True, permanently deletes the file from disk in addition to
+            removing from the index (default: False).
 
     Returns:
-        JSON string with removal results
+        JSON string with removal results (filepath, status).
+
+    Usage: Use to unindex a document while keeping the file on disk (default). Set
+    delete_file=True only for permanent removal. Use update_document() to replace
+    content instead of removing. Use reindex_documents(force=True) if you deleted
+    the file manually on disk outside of this tool.
     """
     if not filepath:
         return json.dumps({"status": "error", "message": "Filepath required"})
@@ -1881,17 +2283,23 @@ def remove_document(filepath: str, delete_file: bool = False) -> str:
 @mcp.tool()
 def add_from_url(url: str, category: str = "general", title: str = None) -> str:
     """
-    Fetch content from a URL and add it to the knowledge base.
+    Fetch content from a URL, convert to markdown, and add to the knowledge base.
 
-    Fetches the page, strips HTML, converts to markdown, and indexes.
+    Mutating — makes an outbound HTTP request (requires internet access), strips HTML,
+    converts to markdown, saves to disk, and indexes immediately.
 
     Args:
-        url: URL to fetch content from
-        category: Document category (default: general)
-        title: Optional title for the document (auto-detected if not provided)
+        url: Full URL to fetch (https:// required). The page must be publicly accessible.
+        category: Document category — one of: security, ctf, logscale, development, general,
+            redteam, blueteam (default: general)
+        title: Optional document title. Auto-detected from the page's <title> tag if omitted.
 
     Returns:
-        JSON string with indexing results
+        JSON string with indexing results (detected title, filepath, chunks created, status).
+
+    Usage: Use to ingest web content (writeups, blog posts, documentation pages) directly
+    by URL. Use add_document() instead when you already have the text content. The document
+    is immediately searchable after this call — no manual reindex needed.
     """
     if not url or not url.strip():
         return json.dumps({"status": "error", "message": "URL cannot be empty"})
@@ -1908,16 +2316,22 @@ def add_from_url(url: str, category: str = "general", title: str = None) -> str:
 @mcp.tool()
 def search_similar(filepath: str, max_results: int = 5) -> str:
     """
-    Find documents similar to a given document.
+    Find documents semantically similar to a given reference document.
 
-    Uses the document's embedding to find semantically similar documents.
+    Read-only. No side effects. Uses the document's embedding for similarity comparison.
 
     Args:
-        filepath: Path to the reference document
-        max_results: Number of similar documents to return (default: 5)
+        filepath: Path to the reference document (must already be indexed — use
+            list_documents() to verify). E.g., "security/technique.md"
+        max_results: Number of similar documents to return (default: 5, max: 20)
 
     Returns:
-        JSON string with list of similar documents and similarity scores
+        JSON string with list of similar document filepaths and similarity scores (0.0–1.0).
+
+    Usage: Use when you have a specific document and want to discover thematically related
+    ones. Use search_knowledge() instead when you have a text query rather than a reference
+    document. The reference document must be indexed — call list_documents() to confirm
+    it exists before calling this tool.
     """
     if not filepath:
         return json.dumps({"status": "error", "message": "Filepath required"})
@@ -1940,13 +2354,22 @@ def search_similar(filepath: str, max_results: int = 5) -> str:
 @mcp.tool()
 def evaluate_retrieval(test_cases: str) -> str:
     """
-    Evaluate retrieval quality with test queries.
+    Evaluate search quality by testing whether search_knowledge() retrieves expected documents.
+
+    Read-only. Runs multiple search queries internally. No side effects on the index.
 
     Args:
-        test_cases: JSON string of test cases. Format: [{"query": "search term", "expected_filepath": "path/to/doc.md"}, ...]
+        test_cases: JSON string array of test cases. Each item requires "query" (search string)
+            and "expected_filepath" (path of the document that should appear in top-5 results).
+            Example: [{"query": "suid exploit", "expected_filepath": "security/suid.md"}]
 
     Returns:
-        JSON string with MRR@5, Recall@5, and per-query results
+        JSON string with MRR@5 (Mean Reciprocal Rank), Recall@5, and per-query hit/miss breakdown.
+        MRR@5 above 0.7 indicates good retrieval quality.
+
+    Usage: Use to audit search quality after bulk document ingestion or after tuning
+    hybrid_alpha. Use get_index_stats() for system health checks instead. Use
+    search_knowledge() for actual document retrieval — this tool is for quality measurement only.
     """
     try:
         cases = json.loads(test_cases) if isinstance(test_cases, str) else test_cases
@@ -2050,16 +2473,19 @@ def main():
                 print(f"[INFO] Indexed {stats['indexed']} documents with {stats['chunks_added']} chunks")
 
             # Start file watcher for auto-reindex on document changes
-            try:
-                watcher = DocumentWatcher(get_orchestrator, debounce_seconds=5.0)
-                observer = Observer()
-                observer.schedule(watcher, str(config.documents_dir), recursive=True)
-                observer.daemon = True
-                observer.start()
-                print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
-            except Exception as e:
-                print(f"[WARN] Failed to start file watcher: {e}")
-                print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
+            if os.environ.get("KNOWLEDGE_RAG_WATCHER_DISABLED", "").strip() == "1":
+                print("[WATCHER] Disabled via KNOWLEDGE_RAG_WATCHER_DISABLED=1")
+            else:
+                try:
+                    watcher = DocumentWatcher(get_orchestrator, debounce_seconds=10.0)
+                    observer = Observer()
+                    observer.schedule(watcher, str(config.documents_dir), recursive=True)
+                    observer.daemon = True
+                    observer.start()
+                    print(f"[WATCHER] Monitoring {config.documents_dir} for changes")
+                except Exception as e:
+                    print(f"[WARN] Failed to start file watcher: {e}")
+                    print("[WARN] Auto-reindexing disabled. Use reindex_documents tool manually.")
 
             # Restore real stdout for MCP JSON-RPC, keep print() going to stderr
             from . import _original_stdout

{knowledge_rag-3.9.0 → knowledge_rag-3.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "knowledge-rag"
-version = "3.9.0"
+version = "3.9.1"
 description = "Local RAG System for Claude Code — Hybrid search + Cross-encoder Reranking + 12 MCP Tools + 20 Format Parsers. Zero external servers."
 readme = "README.md"
 license = {text = "MIT"}