Add reranking, RRF fusion, bench harness, tag contexts, and data ingestion

Implements five of the six enhancements from docs/kb-enhancements-proposal.htm,
closing the retrieval-quality gap identified in the qmd review.

- Cross-encoder reranking: new kb/reranker.py loads an optional reranking
  model at startup (KB_RERANK_ENABLED, KB_RERANKER_MODEL,
  KB_RERANK_CANDIDATES). Search degrades gracefully to plain hybrid
  retrieval when the model is absent. Exposed via a "rerank" block in
  /status, a rerank flag on search, and --no-rerank in the CLI.
- RRF rank fusion: FTS and vector lists now merge by reciprocal rank
  fusion with a top-rank bonus, replacing the old score blend. Scores are
  comparable across queries.
- Bench harness and explain traces: kb bench runs a query fixture against
  each backend and reports precision@k, recall and MRR. --explain returns a
  per-result score breakdown.
- Tag context descriptions: tags carry an optional one-line description
  (kb tag-describe), returned as tag_contexts with search results. Adds a
  tags.description column migration.
- Structured data ingestion: .json/.yaml/.toml files ingest as text via the
  new "data" doc type, pretty-printing minified JSON before chunking.

Query expansion (proposal item 5) is deliberately left out pending bench
results. Requires engine v3.3.0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

client/cmd/search.go

@@ -23,6 +23,8 @@ func init() {
 	searchCmd.Flags().Bool("fts-only", false, "use full-text search only")
 	searchCmd.Flags().Bool("vec-only", false, "use vector search only")
 	searchCmd.Flags().Float64("threshold", 0, "minimum score threshold")
+	searchCmd.Flags().Bool("explain", false, "include per-result score breakdown")
+	searchCmd.Flags().Bool("no-rerank", false, "skip cross-encoder reranking (lower latency)")
 	rootCmd.AddCommand(searchCmd)
 }
 
@@ -33,16 +35,18 @@ func runSearch(cmd *cobra.Command, args []string) error {
 	ftsOnly, _ := cmd.Flags().GetBool("fts-only")
 	vecOnly, _ := cmd.Flags().GetBool("vec-only")
 	threshold, _ := cmd.Flags().GetFloat64("threshold")
+	explain, _ := cmd.Flags().GetBool("explain")
+	noRerank, _ := cmd.Flags().GetBool("no-rerank")
 
 	body := map[string]interface{}{
 		"query": args[0],
 		"top":   top,
 	}
 	if tags != "" {
-		body["tags"] = tags
+		body["tags"] = splitTags(tags)
 	}
 	if docType != "" {
-		body["type"] = docType
+		body["doc_type"] = docType
 	}
 	if ftsOnly {
 		body["fts_only"] = true
@@ -53,6 +57,12 @@ func runSearch(cmd *cobra.Command, args []string) error {
 	if threshold > 0 {
 		body["threshold"] = threshold
 	}
+	if explain {
+		body["explain"] = true
+	}
+	if noRerank {
+		body["rerank"] = false
+	}
 
 	client := api.NewClient()
 	resp, err := client.Post("/api/v1/search", body)
@@ -66,13 +76,17 @@ func runSearch(cmd *cobra.Command, args []string) error {
 	}
 
 	var result struct {
-		Results []struct {
+		Reranked bool `json:"reranked"`
+		Results  []struct {
 			Score         float64                `json:"score"`
+			DocumentID    int64                  `json:"document_id"`
 			Title         string                 `json:"title"`
 			DocType       string                 `json:"doc_type"`
 			Tags          []string               `json:"tags"`
+			TagContexts   map[string]string      `json:"tag_contexts"`
 			ChunkMetadata map[string]interface{} `json:"chunk_metadata"`
 			Text          string                 `json:"text"`
+			Explain       map[string]interface{} `json:"explain"`
 		} `json:"results"`
 	}
 
@@ -94,13 +108,17 @@ func runSearch(cmd *cobra.Command, args []string) error {
 		return nil
 	}
 
+	if result.Reranked {
+		fmt.Println("(reranked)")
+	}
+
 	for i, r := range result.Results {
 		snippet := r.Text
 		if len(snippet) > 200 {
 			snippet = snippet[:200] + "..."
 		}
 
-		fmt.Printf("\n%d. [%.4f] %s\n", i+1, r.Score, r.Title)
+		fmt.Printf("\n%d. [%.4f] %s (doc:%d)\n", i+1, r.Score, r.Title, r.DocumentID)
 
 		location := ""
 		if page, ok := r.ChunkMetadata["page"]; ok && page != nil {
@@ -123,12 +141,63 @@ func runSearch(cmd *cobra.Command, args []string) error {
 		if len(r.Tags) > 0 {
 			fmt.Printf("   Tags: %s\n", joinStrings(r.Tags))
 		}
+		for _, tag := range r.Tags {
+			if desc, ok := r.TagContexts[tag]; ok && desc != "" {
+				fmt.Printf("   Context: %s — %s\n", tag, desc)
+			}
+		}
+		if r.Explain != nil {
+			fmt.Printf("   Score: %s\n", formatExplain(r.Explain))
+		}
 		fmt.Printf("   %s\n", snippet)
 	}
 	fmt.Println()
 	return nil
 }
 
+// formatExplain renders the engine's explain breakdown as one line, e.g.
+// "fts score=4.213 rank=2 (rrf 0.016129) | vec score=0.512 rank=1 (rrf 0.016393) | bonus 0.05 | final 0.082522"
+func formatExplain(e map[string]interface{}) string {
+	num := func(key string) (float64, bool) {
+		v, ok := e[key].(float64)
+		return v, ok
+	}
+	var parts []string
+	for _, arm := range []string{"fts", "vec"} {
+		score, hasScore := num(arm + "_score")
+		if !hasScore {
+			continue
+		}
+		part := fmt.Sprintf("%s score=%.4f", arm, score)
+		if rank, ok := num(arm + "_rank"); ok {
+			part += fmt.Sprintf(" rank=%d", int(rank))
+		}
+		if rrf, ok := num("rrf_" + arm); ok {
+			part += fmt.Sprintf(" (rrf %.6f)", rrf)
+		}
+		parts = append(parts, part)
+	}
+	if bonus, ok := num("bonus"); ok && bonus > 0 {
+		parts = append(parts, fmt.Sprintf("bonus %.2f", bonus))
+	}
+	for _, key := range []string{"pre_rerank_rank", "rerank_score", "blend_weight"} {
+		if v, ok := num(key); ok {
+			parts = append(parts, fmt.Sprintf("%s %.4f", key, v))
+		}
+	}
+	if final, ok := num("final_score"); ok {
+		parts = append(parts, fmt.Sprintf("final %.6f", final))
+	}
+	result := ""
+	for i, p := range parts {
+		if i > 0 {
+			result += " | "
+		}
+		result += p
+	}
+	return result
+}
+
 func joinStrings(ss []string) string {
 	result := ""
 	for i, s := range ss {