V2/token optimization (#11)

* v2.0: token-optimization overhaul

Additive (backward-compatible flags):
- file_read: skeleton mode, strip (imports/license/block_comments),
  compact_line_numbers, 8-char etag with prefix-match compat
- ast_query: format=verbose|compact|location, pagination cursor
- file_search: cluster mode, pagination cursor
- lsp_query (references): compact output

Breaking (v2):
- Preambles removed; opt-in verbose=true restores
- edit_apply: response=count|diff|none, default count
- ping tool removed
- symbol_at/find_definition/find_references merged into lsp_query
- Tool descriptions trimmed -83%, help moved to filepuff://help/<tool>
- Batch file_read dedups by etag

Protocol:
- ResourceLink returned for file_read >64 KiB (force_inline override)
- OnAfterInitialize hook reads capabilities.experimental.filepuff
  for session defaults (default_format, default_max_results,
  default_cluster, compact_refs, line_numbers,
  resource_link_threshold)

* fix: drop --max-total-count from ripgrep args

The flag does not exist in stable ripgrep (confirmed up to 15.1.0 --
"unrecognized flag --max-total-count, similar flags that are
available: --max-count"). Every file_search call failed on hosts with
stock rg. --max-count is per-file, not a drop-in replacement, so rely
on the in-process truncation in parseOutput that was already the
documented safety net.

internal/query/query.go

@@ -451,62 +451,121 @@ func passesFilters(node *sitter.Node, filters QueryFilters, content []byte) bool
 	return true
 }
 
-// FormatResults formats match results for display.
+// FormatResults formats match results for display (backward-compat wrapper, verbose mode).
 func FormatResults(results []MatchResult, maxResults int) string {
+	return FormatResultsWithOptions(results, maxResults, "verbose", 0)
+}
+
+// FormatResultsWithOptions formats match results with configurable output format.
+// format: "verbose" (default) | "compact" | "location"
+// offset: skip this many results before rendering (used for cursor pagination).
+// verbose: opt-in variadic — pass true to restore "Found N match(es):" preamble (v1 behaviour).
+func FormatResultsWithOptions(results []MatchResult, maxResults int, format string, offset int, verbose ...bool) string {
 	if len(results) == 0 {
 		return "No matches found."
 	}
 
-	var sb strings.Builder
-	sb.WriteString(fmt.Sprintf("Found %d match(es):\n\n", len(results)))
-
-	displayCount := len(results)
-	truncated := false
-	if maxResults > 0 && displayCount > maxResults {
-		displayCount = maxResults
-		truncated = true
+	// Apply offset (pagination skip).
+	if offset > 0 {
+		if offset >= len(results) {
+			return "No matches found."
+		}
+		results = results[offset:]
 	}
 
-	for i := 0; i < displayCount; i++ {
-		r := results[i]
-		nodeType := "unknown"
-		if r.Node != nil {
-			nodeType = r.Node.Type()
-		}
-		sb.WriteString(fmt.Sprintf("**%s:%d** (%s)\n", r.File, r.Location.Line, nodeType))
+	// Determine how many to render and whether more remain.
+	renderCount := len(results)
+	remaining := 0
+	if maxResults > 0 && renderCount > maxResults {
+		remaining = renderCount - maxResults
+		renderCount = maxResults
+	}
 
-		// Truncate very long text
-		text := r.Text
-		if len(text) > 500 {
-			text = text[:500] + "..."
-		}
-		sb.WriteString("```\n")
-		sb.WriteString(text)
-		sb.WriteString("\n```\n")
+	var sb strings.Builder
 
-		// Show captures
-		if len(r.Captures) > 0 {
-			sb.WriteString("Captures: ")
-			first := true
-			for name, cap := range r.Captures {
-				if !first {
-					sb.WriteString(", ")
+	// Emit preamble only when verbose=true is explicitly passed (opt-in, default off).
+	wantVerbose := len(verbose) > 0 && verbose[0]
+	if wantVerbose {
+		sb.WriteString(fmt.Sprintf("Found %d match(es):\n", renderCount))
+	}
+
+	switch format {
+	case "compact":
+		for i := 0; i < renderCount; i++ {
+			r := results[i]
+			nodeType := "unknown"
+			if r.Node != nil {
+				nodeType = r.Node.Type()
+			}
+			firstLine := firstLineOf(r.Text, 80)
+			sb.WriteString(fmt.Sprintf("%s:%d (%s) %s\n", r.File, r.Location.Line, nodeType, firstLine))
+		}
+
+	case "location":
+		for i := 0; i < renderCount; i++ {
+			r := results[i]
+			sb.WriteString(fmt.Sprintf("%s:%d\n", r.File, r.Location.Line))
+		}
+
+	default: // "verbose"
+		for i := 0; i < renderCount; i++ {
+			r := results[i]
+			nodeType := "unknown"
+			if r.Node != nil {
+				nodeType = r.Node.Type()
+			}
+			sb.WriteString(fmt.Sprintf("**%s:%d** (%s)\n", r.File, r.Location.Line, nodeType))
+
+			// Truncate very long text
+			text := r.Text
+			if len(text) > 500 {
+				text = text[:500] + "..."
+			}
+			sb.WriteString("```\n")
+			sb.WriteString(text)
+			sb.WriteString("\n```\n")
+
+			// Show captures
+			if len(r.Captures) > 0 {
+				sb.WriteString("Captures: ")
+				first := true
+				for name, cap := range r.Captures {
+					if !first {
+						sb.WriteString(", ")
+					}
+					first = false
+					capText := cap.Text
+					if len(capText) > 50 {
+						capText = capText[:50] + "..."
+					}
+					sb.WriteString(fmt.Sprintf("$%s=%s", name, capText))
 				}
-				first = false
-				capText := cap.Text
-				if len(capText) > 50 {
-					capText = capText[:50] + "..."
-				}
-				sb.WriteString(fmt.Sprintf("$%s=%s", name, capText))
+				sb.WriteString("\n")
 			}
 			sb.WriteString("\n")
 		}
-		sb.WriteString("\n")
 	}
 
-	if truncated {
-		sb.WriteString(fmt.Sprintf("... and %d more matches (truncated)\n", len(results)-maxResults))
+	if remaining > 0 {
+		// Caller must embed the cursor token; we just append the remaining count hint.
+		// The actual [cursor: ...] line is written by the handler after calling MakeCursor.
+		sb.WriteString(fmt.Sprintf("[remaining: %d]\n", remaining))
 	}
 
 	return sb.String()
 }
+
+// firstLineOf returns the first non-empty line of s, trimmed and capped at maxLen chars.
+func firstLineOf(s string, maxLen int) string {
+	for _, line := range strings.Split(s, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		if len(line) > maxLen {
+			return line[:maxLen-1] + "…"
+		}
+		return line
+	}
+	return ""
+}