refactor: conditionally register update tools, fix documentation

- Register rag_check_update and rag_apply_update only when auto_update=false
- Rewrite doc_updates.md: fix SHA256 'Future Hook' (already implemented),
  replace 'binary swap' with installer handoff, add daemon auto-update
  and adapter version upgrade sections
- README: remove non-existent --update CLI flag, document auto-update
  as default, update tool count to 9
- engine: add workspace detection debug logging

Author: razvan

README.md

@@ -21,7 +21,7 @@
 
 RagCode is a **Model Context Protocol (MCP) server** that instantly makes your project **AI-ready**. It enables AI assistants like **GitHub Copilot**, **Cursor**, **Windsurf**, and **Claude** to understand your entire codebase through **semantic vector search**, bridging the gap between your code and Large Language Models (LLMs).
 
-Built with the official [Model Context Protocol Go SDK](https://github.com/modelcontextprotocol/go-sdk), RagCode provides **11 powerful tools** to index, search, and analyze code — including **Markdown documentation search** — making it the ultimate solution for **AI-ready software development**.
+Built with the official [Model Context Protocol Go SDK](https://github.com/modelcontextprotocol/go-sdk), RagCode provides **9 powerful MCP tools** to index, search, and analyze code — including **Markdown documentation search** — making it the ultimate solution for **AI-ready software development**.
 
 ## ⚡ One-Command Installation
 
@@ -55,23 +55,20 @@ Invoke-WebRequest -Uri "https://github.com/doITmagic/rag-code-mcp/releases/lates
 
 ### 🔄 Keep Updated
 
-The auto-update feature is available starting with **v1.1.18**.
+**Auto-update is enabled by default.** The daemon checks for new versions on startup and applies them automatically. No action needed.
 
 **How to Upgrade:**
 
 1.  **If you are on an older version (< v1.1.18):**
-    Your version **does not know** the update command.
     You must **re-run the installation command** (the curl command above) one last time.
-    *(Don't worry, your indexes and configuration will be preserved).*
+    *(Don't worry, your indexes and configuration will be preserved.)*
 
 2.  **If you are on v1.1.18 or newer:**
-    Simply run:
-    ```bash
-    rag-code-mcp --update
-    ```
+    Updates happen automatically. You can also trigger a manual update:
+    - Ask your AI assistant to run `rag_check_update` (check) or `rag_apply_update` (install)
+    - Or re-run the installer: `rag-code-install --upgrade -y`
 
-**For new installations:**
-The update system is built-in. Use the installer once, then simply run `rag-code-mcp --update` anytime to get the latest features.
+**To disable auto-update:** Set `auto_update: false` in `~/.ragcode/bin/config.yaml`.
 
 📖 **[Full Installation Guide →](./QUICKSTART.md)** | **[Windows WSL Setup →](./QUICKSTART.md#windows-with-wsl-alternative)**
 
@@ -161,7 +158,7 @@ First query triggers background indexing. Subsequent queries are instant.
 
 ---
 
-## 🛠️ 11 Powerful MCP Tools
+## 🛠️ MCP Tools
 
 ### 🔍 Search & Navigation (Core)
 
@@ -186,8 +183,11 @@ First query triggers background indexing. Subsequent queries are instant.
 | Tool | Description | Use When |
 |------|-------------|----------|
 | `rag_evaluate` | AI-to-Developer feedback on RagCode performance | Provide feedback |
-| `rag_check_update` | Check for available RagCode updates | Staying current |
-| `rag_apply_update` | Download and install latest RagCode version | Upgrading |
+| `rag_check_update` | Check for available RagCode updates | Only when `auto_update: false` |
+| `rag_apply_update` | Download and install latest RagCode version | Only when `auto_update: false` |
+
+> [!NOTE]
+> Update tools are only registered when `auto_update: false` in config. By default, the daemon auto-updates on startup, so these tools are hidden to keep the AI context lean.
 
 > [!TIP]
 > **`rag_search` is all you need for most queries.** It automatically combines semantic and exact search, adapts output format based on confidence, and with `include_docs: true` also searches project documentation (README, guides, Markdown files).

internal/daemon/run.go

@@ -161,8 +161,11 @@ func Run(rcfg RunConfig) error {
 	tools.NewListSkillsTool(eng, cfg.Skills).Register(mcpServer)
 	tools.NewInstallSkillTool(eng, cfg.Skills).Register(mcpServer)
 	tools.NewEvaluateRagCodeTool(eng, cfg).Register(mcpServer)
-	tools.NewCheckUpdateTool(rcfg.Version, cfg).Register(mcpServer)
-	tools.NewApplyUpdateTool(rcfg.Version).Register(mcpServer)
+	if !cfg.AutoUpdate {
+		tools.NewCheckUpdateTool(rcfg.Version, cfg).Register(mcpServer)
+		tools.NewApplyUpdateTool(rcfg.Version).Register(mcpServer)
+		logger.Instance.Info("Update tools registered (auto_update=false)")
+	}
 
 	logger.Instance.Info("MCP RagCode Daemon initialized (version=%s)", rcfg.Version)
 
@@ -209,8 +212,12 @@ func Run(rcfg RunConfig) error {
 	// Middleware: extract X-Workspace-Hint header from adapter and inject into request context.
 	// This makes the IDE's CWD available to all tools via transport.GetWorkspaceHint(ctx).
 	mcpHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if hint := r.Header.Get("X-Workspace-Hint"); hint != "" {
+		hint := r.Header.Get("X-Workspace-Hint")
+		if hint != "" {
+			logger.Instance.Debug("[DAEMON] Request received with X-Workspace-Hint=%s", hint)
 			r = r.WithContext(transport.WithWorkspaceHint(r.Context(), hint))
+		} else {
+			logger.Instance.Debug("[DAEMON] Request received WITHOUT X-Workspace-Hint header")
 		}
 		mcpMux.ServeHTTP(w, r)
 	})

internal/service/engine/engine.go

@@ -180,13 +180,18 @@ func (e *Engine) DetectFromParams(ctx context.Context, params map[string]interfa
 // If path is empty, it falls back to the last active workspace from the registry.
 // Results are cached with a 5s TTL to avoid redundant resolver invocations.
 func (e *Engine) DetectContext(ctx context.Context, path string) (*WorkspaceContext, error) {
+	// Log incoming detection request for debugging workspace resolution
+	hintFromCtx := transport.GetWorkspaceHint(ctx)
+	logger.Instance.Info("[WS-DETECT] ▶ DetectContext called: path=%q, X-Workspace-Hint=%q", path, hintFromCtx)
+
 	// Normalize cache key
 	cacheKey := strings.TrimSpace(path)
 	if entry, ok := e.detectionCache.LoadAndDelete(cacheKey); ok {
 		ce := entry.(*detectionCacheEntry)
 		if time.Now().Before(ce.expiry) {
 			// Re-store valid entry atomically before returning
 			e.detectionCache.Store(cacheKey, ce)
+			logger.Instance.Debug("[WS-DETECT] ◀ Cache hit: root=%s, source=%s", ce.wctx.Root, ce.wctx.DetectionSource)
 			return ce.wctx, nil
 		}
 	}
@@ -195,8 +200,10 @@ func (e *Engine) DetectContext(ctx context.Context, path string) (*WorkspaceCont
 	source := "explicit_file_path"
 
 	if strings.TrimSpace(path) == "" {
+		logger.Instance.Info("[WS-DETECT] Tier 1 skipped: no explicit path in request params")
+
 		// Tier 2: Try workspace hint from adapter (IDE's CWD injected via X-Workspace-Hint header)
-		if hint := strings.TrimSpace(transport.GetWorkspaceHint(ctx)); hint != "" {
+		if hint := strings.TrimSpace(hintFromCtx); hint != "" {
 			abs, err := filepath.Abs(hint)
 			if err == nil {
 				// Validate the path actually exists on disk before using it
@@ -205,25 +212,35 @@ func (e *Engine) DetectContext(ctx context.Context, path string) (*WorkspaceCont
 					source = "hint_fallback"
 					// Use hint as cache key so different IDEs don't share the same empty-string entry
 					cacheKey = abs
+					logger.Instance.Info("[WS-DETECT] ✅ Tier 2 matched: using X-Workspace-Hint=%s", abs)
+				} else {
+					logger.Instance.Warn("[WS-DETECT] Tier 2 skipped: hint path does not exist on disk: %s (err: %v)", abs, statErr)
 				}
+			} else {
+				logger.Instance.Warn("[WS-DETECT] Tier 2 skipped: could not resolve hint to abs path: %v", err)
 			}
+		} else {
+			logger.Instance.Info("[WS-DETECT] Tier 2 skipped: no X-Workspace-Hint header in request")
 		}
 
 		// Tier 3: Fall back to last active workspace from registry
 		if req.FilePath == "" {
 			active, err := e.GetActiveWorkspace()
 			if err != nil || active == "" {
+				logger.Instance.Warn("[WS-DETECT] ❌ All tiers exhausted — no workspace detected")
 				return nil, fmt.Errorf("❌ No workspace detected. Please provide the 'file_path' of the file you are currently working on to help detect the project context.")
 			}
 			req.WorkspaceRoot = active
 			source = "registry_fallback"
+			logger.Instance.Info("[WS-DETECT] ✅ Tier 3 matched: using registry fallback=%s", active)
 		}
 	} else {
 		abs, err := filepath.Abs(path)
 		if err != nil {
 			return nil, fmt.Errorf("failed to resolve path: %w", err)
 		}
 		req.FilePath = abs
+		logger.Instance.Info("[WS-DETECT] ✅ Tier 1 matched: using explicit path=%s", abs)
 	}
 
 	resp, wsErr := e.resolver.Resolve(ctx, req)
@@ -242,6 +259,9 @@ func (e *Engine) DetectContext(ctx context.Context, path string) (*WorkspaceCont
 		HeadSHA:         resp.HeadSHA,
 	}
 
+	logger.Instance.Info("[WS-DETECT] ◀ Resolved: root=%s, id=%s, branch=%s, source=%s, risk=%s",
+		wctx.Root, wctx.ID, wctx.Branch, source, wctx.MismatchRisk)
+
 	// Don't cache entries that require reindex or are high-risk — let next call re-evaluate
 	if !wctx.ReindexRequired && wctx.MismatchRisk != "high" {
 		e.detectionCache.Store(cacheKey, &detectionCacheEntry{

internal/service/tools/doc_updates.md

@@ -2,26 +2,47 @@
 
 **Source File**: `updates.go`
 
-These two companion tools provide self-maintaining capabilities to the RagCode MCP server, allowing the AI assistant to detect when a newer version exists on GitHub and gracefully trigger an in-place upgrade.
+These two companion tools provide self-maintaining capabilities to the RagCode MCP server, allowing the AI assistant to detect when a newer version exists on GitHub and gracefully trigger an upgrade.
+
+> **Note:** These tools are only registered when `auto_update: false` in config. By default, the daemon handles updates automatically on startup, so these tools are hidden to reduce AI context overhead.
 
 ## 1. `rag_check_update`
 
 ### Query Mechanisms
 - **External API Query**: Hooks into the public GitHub Releases API (`api.github.com/repos/doITmagic/rag-code-mcp/releases/latest`) to check the newest tagged version.
-- **Cache Mechanism**: By default, checks are cached to avoid API rate limiting. This can be overridden by passing `"force": true`.
-- **Version Comparison**: Compares the natively injected build version (`t.version` passed via `LDFLAGS`) against the Semantic Version tag discovered remotely.
+- **Cache Mechanism**: Results are cached for 24 hours in `~/.ragcode/update_cache.json` (written atomically via temp-file + rename, permissions `0600`). Pass `"force": true` to bypass the cache.
+- **Version Comparison**: Compares the natively injected build version (`t.version` passed via `LDFLAGS`) against the Semantic Version tag discovered remotely using `Masterminds/semver`.
+- **Remote Stable Model Check**: Fetches `config.yaml` from the `main` branch on GitHub to detect if the recommended embedding model has changed. Displays a warning if the local model differs from the remote stable model.
 
 ### Features
-- **Deterministic**: Provides the exact changelog and download URLs in the structured `ToolResponse.Data` response so the AI can summarize new features for the user.
+- **Deterministic**: Provides the exact download URLs, tag, and version details in the structured `ToolResponse.Data` response so the AI can summarize what's new for the user.
+- **Structured Response**: Returns a `ToolResponse` JSON with `status`, `message`, `error`, `context` (current version), and `data` (full `UpdateInfo` object) fields.
 
 ---
 
 ## 2. `rag_apply_update`
 
 ### Query Mechanisms
-- **Artifact Download**: Performs an HTTP streaming download of the release artifact (ZIP or TAR.GZ) aligned with the host's operating system and architecture (`GOOS`/`GOARCH`).
-- **Cryptographic Verification**: *(Future Hook)* Validates the BLAKE3/SHA256 checksum associated with the release to ensure binary integrity before executing a swap.
+- **Artifact Download**: Performs an HTTP streaming download of the release artifact (`.tar.gz` or `.zip`) aligned with the host's operating system and architecture (`GOOS`/`GOARCH`).
+- **SHA256 Verification**: Downloads `checksums.txt` from the release, locates the hash for the platform-specific archive, computes the SHA256 of the downloaded file, and compares them. Fails if the hashes don't match.
 
 ### Features
-- **In-place Binary Swap**: Downloads the artifact to a securely generated `os.CreateTemp` path. Unpacks the new `rag-code-mcp` executable and aggressively swaps it with the current running binary (using standard POSIX rename/replace syscalls depending on OS).
-- **Graceful Handoff**: Once the new binary is placed on disk, it prompts the AI to notify the user to restart their IDE or MCP client so the new process takes over.
+- **Installer Handoff**: Downloads the artifact to a securely generated `os.CreateTemp` path, extracts it to a temp directory, then spawns `rag-code-install --upgrade -y` from the extracted directory. The current process exits via `os.Exit(0)` to hand control to the installer. The installer handles process stopping (via PID file) and file copying to `~/.ragcode/bin/`.
+- **Cleanup**: On error paths, the temp directory is automatically cleaned up. On successful handoff, the installer takes ownership.
+- **Graceful Restart**: Once the installer completes, the AI prompts the user to restart their IDE or MCP client so the new version takes over.
+
+---
+
+## 3. Daemon Auto-Update
+
+### Mechanism
+- **Automatic by Default**: The `auto_update: true` setting in `config.yaml` (default) enables automatic update checking on daemon startup.
+- **Background Worker**: 10 seconds after the daemon starts, a background goroutine calls `updater.CheckForUpdates()` (using the 24h cache), and if a new version is found, calls `updater.DownloadVerifyAndApply()` — which downloads, verifies SHA256, and spawns the installer.
+- **Shared Helper**: `DownloadVerifyAndApply()` is the unified code path used by both the daemon auto-update worker and the `rag_apply_update` MCP tool.
+- **Disable**: Set `auto_update: false` in `~/.ragcode/bin/config.yaml` to disable automatic updates.
+
+---
+
+## 4. Adapter Version Upgrade
+
+When the adapter (stdio bridge) starts, it checks if the running daemon is on an older version. If so, it stops the old daemon and restarts with the current binary version. This ensures that after a manual update, the daemon is always running the latest installed version.