fix: resolve PR #36 Copilot review comments (19/24 fixed)

Documentation fixes:
- README.md: Go version badge 1.25+ → 1.24.4+ to match go.mod
- internal/service/tools/README.md: corrected filenames in tool table
  and package tree (update_tools.go → updates.go, agent_skills.go → skills.go)
- internal/updater/README.md: sha256sums.txt → checksums.txt, removed
  non-existent info.UpdateAvailable field from example code
- docs/headless-usage.md: rewritten to match current implementation —
  SSE/session endpoints → stateless /mcp, --port → --http-port,
  ragcode-sse skill → ragcode-http

Code fixes:
- pkg/telemetry/metrics_reader.go: increased scanner buffer to 1MB for
  long JSONL lines, added explicit HybridSearches counter (was incorrectly
  counted as VectorSearches)
- smart_search_pipeline.go: normalizeInput now clamps min_score to
  [0.0, 1.0] range, buildFallbackNote no longer emits empty 'Progress: .'
  when all languages have TotalFiles==0, restored SessionMetrics population
  in buildResponseMeta via telemetry.ReadAggregatedMetrics

Deferred (4 items for separate PRs):
- existingCollections edge case in engine fan-out
- lazy embed optimization for unindexed workspaces
- reportLang/reportColl accuracy for polyglot workspaces
- score filter unit test coverage

Author: razvan

README.md

@@ -5,7 +5,7 @@
 <div align="center">
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Go Version](https://img.shields.io/badge/Go-1.25%2B-blue)](https://go.dev/)
+[![Go Version](https://img.shields.io/badge/Go-1.24.4%2B-blue)](https://go.dev/)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io)
 ![AI Ready](https://img.shields.io/badge/Codebase-AI%20Ready-blueviolet)
 

docs/headless-usage.md

@@ -1,37 +1,29 @@
-# Headless Usage (HTTP & SSE)
+# Headless Usage (Streamable HTTP)
 
 RagCode MCP is primarily an MCP Server designed to be invoked via `stdio` by conforming clients (like Cursor, Windsurf, Claude Desktop). However, the architecture is **Protocol Agnostic**, allowing it to be used "headlessly" without IDE integration.
 
 This is especially useful for purely autonomous AI agents (like Antigravity scripts, custom Python bots, or CI/CD integrations) that need to issue JSON-RPC queries to the engine over TCP instead of standard I/O pipes.
 
-## SSE (Server-Sent Events) Mode
+## Streamable HTTP Mode
 
-RagCode features a subpackage `internal/daemon/` which can spawn an SSE HTTP server that perfectly conforms to the MCP standard over HTTP GET/POST.
+RagCode features a subpackage `internal/daemon/` which spawns a stateless Streamable HTTP handler that conforms to the MCP standard.
 
 To start the daemon:
 
 ```bash
-rag-code-mcp --port 8080
+rag-code-mcp --http-port 8080
 ```
 
 When the server starts successfully, it will print:
-`[INFO] SSE MCP server listening on :8080`
+`[INFO] HTTP MCP server listening on :8080`
 
 ### Example Integration (Using cURL or HTTP Agents)
 
-Once the daemon is active, your AI Script can connect to it using standard MCP-over-SSE endpoints:
+Once the daemon is active, your AI Script can send standard MCP JSON-RPC requests directly to the `/mcp` endpoint:
 
-**1. Establish an SSE Session (GET)**
+**Send an MCP Command (POST)**
 ```bash
-curl -N http://localhost:8080/sse
-```
-*This endpoint yields events and is intended to be kept alive. It will return a URI specifying the exact Session ID endpoint where you must send queries.*
-
-**2. Send an MCP Command (POST)**
-Suppose the SSE terminal returned `Endpoint: /message?sessionId=123`.
-
-```bash
-curl -X POST http://localhost:8080/message?sessionId=123 \
+curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
   -d '{
     "jsonrpc": "2.0",
@@ -47,16 +39,16 @@ curl -X POST http://localhost:8080/message?sessionId=123 \
   }'
 ```
 
-The response will be sent via JSON-RPC 2.0 back on the open `/sse` channel you hold.
+The response will be returned as a standard JSON-RPC 2.0 response in the HTTP body.
 
-## "The `ragcode-sse` Skill" Integration
+## "The `ragcode-http` Skill" Integration
 
-For agents that do not inherently support SSE/MCP natively in their prompt cycle, developers can push the officially provided `ragcode-sse` agent skill. 
+For agents that do not inherently support MCP natively in their prompt cycle, developers can push the officially provided `ragcode-http` agent skill. 
 
-This skill injects bash commands that wrap `curl` payloads, allowing the agent to perform raw POST/GET queries seamlessly, extracting context from large workspaces directly into standard markdown without installing a Desktop IDE.
+This skill injects bash commands that wrap `curl` payloads, allowing the agent to perform raw POST queries seamlessly, extracting context from large workspaces directly into standard markdown without installing a Desktop IDE.
 
 1. Agent discovers skill via `rag_list_skills`.
-2. Agent runs `rag_install_skill {"skill_id": "ragcode-sse", "target": "agent"}`.
+2. Agent runs `rag_install_skill {"skill_id": "ragcode-http", "target": "agent"}`.
 3. The agent reads `SKILL.md` to learn how to frame HTTP POST queries toward port `8080`.
 
 **Note on Workspace Context:** Always ensure the script explicitly sends `"file_path": "/absolute/path/to/project/file.ext"` inside the arguments payload. Without an IDE, RagCode completely relies on `file_path` to map the workspace identity correctly.

internal/service/tools/README.md

@@ -17,10 +17,10 @@ Implementation of the MCP tools exposed by the RagCode AI assistants server.
 | `rag_read_file_context` | `read_file_context.go` | [doc_read_file_context.md](/docs/tools/doc_read_file_context.md) |
 | `rag_index_workspace` | `index_workspace.go` | [doc_index_workspace.md](/docs/tools/doc_index_workspace.md) |
 | `rag_evaluate` | `evaluate_ragcode.go` | [doc_evaluate_ragcode.md](/docs/tools/doc_evaluate_ragcode.md) |
-| `rag_check_update` | `update_tools.go` | [doc_updates.md](/docs/tools/doc_updates.md) |
-| `rag_apply_update` | `update_tools.go` | [doc_updates.md](/docs/tools/doc_updates.md) |
-| `rag_list_skills` | `agent_skills.go` | (none) |
-| `rag_install_skill` | `agent_skills.go` | (none) |
+| `rag_check_update` | `updates.go` | [doc_updates.md](/docs/tools/doc_updates.md) |
+| `rag_apply_update` | `updates.go` | [doc_updates.md](/docs/tools/doc_updates.md) |
+| `rag_list_skills` | `skills.go` | (none) |
+| `rag_install_skill` | `skills.go` | (none) |
 
 ---
 
@@ -39,8 +39,8 @@ internal/service/tools/
 ├── read_file_context.go
 ├── index_workspace.go
 ├── evaluate_ragcode.go
-├── update_tools.go                 # Check and apply updates tools
-├── agent_skills.go                 # List and install skills tools
+├── updates.go                      # Check and apply updates tools
+├── skills.go                       # List and install skills tools
 ├── healthcheck.go
 ├── response.go                     # ToolResponse, ContextMetadata, JSON helpers
 └── README.md

internal/service/tools/smart_search_pipeline.go

@@ -29,6 +29,12 @@ func normalizeInput(input SmartSearchInput, defaultLimit int) (string, int, Smar
 	if input.Mode == "strict_docs" {
 		input.IncludeDocs = true
 	}
+	// Clamp min_score to valid range [0.0, 1.0]
+	if input.MinScore < 0 {
+		input.MinScore = 0
+	} else if input.MinScore > 1.0 {
+		input.MinScore = 1.0
+	}
 	return query, limit, input, nil
 }
 
@@ -212,6 +218,7 @@ func (t *SmartSearchTool) buildResponseMeta(meta searchMetadata) ToolResponse {
 			Language:         meta.language,
 			Collection:       meta.collection,
 			IndexingProgress: idxProgress,
+			SessionMetrics:   telemetry.ReadAggregatedMetrics(meta.workspaceRoot),
 		},
 	}
 
@@ -257,23 +264,23 @@ func buildFallbackNote(progress *IndexingProgressSummary) string {
 	// Report per-language progress and collect fully-indexed langs
 	var readyLangs []string
 	if progress != nil && len(progress.Languages) > 0 {
-		sb.WriteString("Progress: ")
-		first := true
+		var langParts []string
 		for lang, lp := range progress.Languages {
 			if lp.TotalFiles == 0 {
 				continue
 			}
-			if !first {
-				sb.WriteString(" · ")
-			}
-			sb.WriteString(fmt.Sprintf("%s %d%%", lang, lp.Percent))
+			entry := fmt.Sprintf("%s %d%%", lang, lp.Percent)
 			if lp.Percent == 100 {
-				sb.WriteString(" ✓")
+				entry += " ✓"
 				readyLangs = append(readyLangs, lang)
 			}
-			first = false
+			langParts = append(langParts, entry)
+		}
+		if len(langParts) > 0 {
+			sb.WriteString("Progress: ")
+			sb.WriteString(strings.Join(langParts, " · "))
+			sb.WriteString(". ")
 		}
-		sb.WriteString(". ")
 	}
 
 	// Actionable hint: tell agent which langs can use vector search now

internal/updater/README.md

@@ -22,8 +22,8 @@ if err != nil {
     // Handle error
 }
 
-if info != nil && info.UpdateAvailable {
-    // Perform update and verification
+if info != nil {
+    // Non-nil info means an update is available
     err := updater.DownloadVerifyAndApply(ctx, info)
     if err != nil {
         // Handle error
@@ -33,5 +33,5 @@ if info != nil && info.UpdateAvailable {
 
 ## Safety Considerations
 
-- **Verification**: Updates are cryptographically verified using `sha256sums.txt` included in releases.
+- **Verification**: Updates are cryptographically verified using `checksums.txt` included in releases.
 - **Rollback**: Updates happen via binary replacement; if the process fails mid-way, the original executable is restored from a temporary backup.

pkg/telemetry/metrics_reader.go

@@ -9,18 +9,19 @@ import (
 
 // AggregatedMetrics holds cumulative statistics from search_metrics.jsonl.
 type AggregatedMetrics struct {
-	TotalSearches      int     `json:"total_searches"`
-	SearchesWithResults int    `json:"searches_with_results"`
-	FallbackSearches   int     `json:"fallback_searches"`
-	VectorSearches     int     `json:"vector_searches"`
-	AvgTopScore        float32 `json:"avg_top_score"`
-	TotalBytesSaved    int64   `json:"total_bytes_saved"`
-	TotalTokensSaved   int64   `json:"total_tokens_saved"`
-	AvgResponseMs      int64   `json:"avg_response_ms"`
+	TotalSearches       int     `json:"total_searches"`
+	SearchesWithResults int     `json:"searches_with_results"`
+	FallbackSearches    int     `json:"fallback_searches"`
+	VectorSearches      int     `json:"vector_searches"`
+	HybridSearches      int     `json:"hybrid_searches"`
+	AvgTopScore         float32 `json:"avg_top_score"`
+	TotalBytesSaved     int64   `json:"total_bytes_saved"`
+	TotalTokensSaved    int64   `json:"total_tokens_saved"`
+	AvgResponseMs       int64   `json:"avg_response_ms"`
 }
 
 // ReadAggregatedMetrics reads and aggregates all metrics from the JSONL file.
-// Returns nil if no metrics file exists.
+// Returns nil if no metrics file exists or on read errors.
 func ReadAggregatedMetrics(workspaceRoot string) *AggregatedMetrics {
 	if workspaceRoot == "" {
 		return nil
@@ -37,6 +38,9 @@ func ReadAggregatedMetrics(workspaceRoot string) *AggregatedMetrics {
 	var msSum int64
 
 	scanner := bufio.NewScanner(f)
+	// Increase buffer to 1MB to handle long JSONL lines (large query strings, etc.)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+
 	for scanner.Scan() {
 		var m SearchMetric
 		if json.Unmarshal(scanner.Bytes(), &m) != nil {
@@ -46,9 +50,12 @@ func ReadAggregatedMetrics(workspaceRoot string) *AggregatedMetrics {
 		if m.ResultCount > 0 {
 			agg.SearchesWithResults++
 		}
-		if m.Source == "fallback" {
+		switch m.Source {
+		case "fallback":
 			agg.FallbackSearches++
-		} else {
+		case "hybrid":
+			agg.HybridSearches++
+		default:
 			agg.VectorSearches++
 		}
 		scoreSum += m.TopScore