fix: enable searching for literal reserved words (AND, OR, NOT) (#1103)

## Summary

- Fix issue 4 from KNOWN-ISSUES.md: users could not search for literal
words "AND", "OR", "NOT" even with quotes
- FTS5 reserved words are now properly escaped when generating FTS
queries
- Added examples to `km examples` showing how to search for literal
reserved words

## Changes

- **`src/Core/Search/NodeSearchService.cs`**: Added FTS5 reserved word
detection and escaping in `FtsQueryExtractor`
- **`src/Main/CLI/Commands/ExamplesCommand.cs`**: Added examples for
searching literal reserved words
- **`KNOWN-ISSUES.md`**: Removed resolved issue 4
- **`tests/Core.Tests/Search/FtsQueryExtractionTest.cs`**: Added 5 E2E
tests
- **`tests/Core.Tests/Search/Query/InfixQueryParserTests.cs`**: Added 12
parser tests

## Test plan

- [x] All 520 tests pass (306 Core + 214 Main)
- [x] Zero skipped tests
- [x] Code coverage at 83.82% (above 80% threshold)
- [x] `build.sh` passes with 0 warnings
- [x] `format.sh` passes
- [x] `coverage.sh` passes

## Usage examples (now working)

```bash
km search '"NOT"'              # Search for literal "NOT"
km search '"AND"'              # Search for literal "AND"
km search '"Alice AND Bob"'    # Search for phrase containing AND
```

Author: dluc

KNOWN-ISSUES.md

@@ -84,33 +84,6 @@ km search 'content:"user:password"'
 
 ---
 
-### 4. Reserved Words Cannot Be Searched
-
-**Status:** Known limitation
-
-**Issue:** Cannot search for the literal words "AND", "OR", "NOT" even with quotes.
-
-**Example:**
-```bash
-km put "this is NOT important"
-km search "NOT"
-# Expected: Find the document
-# Actual: Parser error "Unexpected end of query"
-```
-
-**Root Cause:**
-- Tokenizer treats AND/OR/NOT as reserved keywords (case-insensitive)
-- Even quoted, they're tokenized as operators
-- Parser expects operands after NOT
-
-**Workaround:** None. These words cannot be searched.
-
-**Fix Required:**
-- Tokenizer must recognize quotes and treat content literally
-- Major parser refactoring needed
-
----
-
 ## Testing Gaps
 
 These bugs were discovered through comprehensive E2E testing. Previous tests only verified:
@@ -127,16 +100,3 @@ But did NOT test:
 
 ---
 
-## Resolved Issues
-
-### BM25 Score Normalization (FIXED)
-- **Issue:** All searches returned 0 results despite FTS finding matches
-- **Cause:** BM25 scores (~0.000001) filtered by MinRelevance=0.3
-- **Fix:** Exponential normalization maps [-10, 0] → [0.37, 1.0]
-- **Commit:** 4cb283e
-
-### Field-Specific Equal Operator (FIXED)
-- **Issue:** `content:summaries` failed with SQLite error
-- **Cause:** Equal operator didn't extract FTS queries
-- **Fix:** ExtractComparison now handles both Contains and Equal
-- **Commit:** 59bf3f2

src/Core/Search/NodeSearchService.cs

@@ -127,6 +127,15 @@ private string ExtractFtsQuery(QueryNode queryNode)
     /// </summary>
     private sealed class FtsQueryExtractor
     {
+        /// <summary>
+        /// SQLite FTS5 reserved words that must be quoted when used as search terms.
+        /// These keywords have special meaning in FTS5 query syntax.
+        /// </summary>
+        private static readonly HashSet<string> s_fts5ReservedWords = new(StringComparer.OrdinalIgnoreCase)
+        {
+            "AND", "OR", "NOT", "NEAR"
+        };
+
         public string Extract(QueryNode node)
         {
             var terms = this.ExtractTerms(node);
@@ -153,22 +162,31 @@ private string ExtractTextSearch(TextSearchNode node)
             {
                 // Phrase searches: use quotes and no field prefix
                 // FTS5 doesn't support field:phrase syntax well, so just search all fields
-                var escapedPhrase = node.SearchText.Replace("\"", "\"\"", StringComparison.Ordinal);
+                var escapedPhrase = this.EscapeFtsPhrase(node.SearchText);
                 return $"\"{escapedPhrase}\"";
             }
 
+            // Check if the term is a reserved word that needs quoting
+            if (this.IsFts5ReservedWord(node.SearchText))
+            {
+                // Reserved words must be quoted to be treated as literal search terms
+                // We cannot use field prefix with quoted terms in FTS5, so search all fields
+                var escapedTerm = this.EscapeFtsPhrase(node.SearchText);
+                return $"\"{escapedTerm}\"";
+            }
+
             // Single word searches: use field prefix WITHOUT quotes
-            var escapedTerm = this.EscapeFtsSingleTerm(node.SearchText);
+            var escaped = this.EscapeFtsSingleTerm(node.SearchText);
 
             // If specific field, prefix with field name (SQLite FTS5 syntax)
             if (node.Field != null && this.IsFtsField(node.Field.FieldPath))
             {
-                return $"{node.Field.FieldPath}:{escapedTerm}";
+                return $"{node.Field.FieldPath}:{escaped}";
             }
 
             // Default field: search all FTS fields (title, description, content)
             // FTS5 syntax: {title description content}:term
-            return $"{{title description content}}:{escapedTerm}";
+            return $"{{title description content}}:{escaped}";
         }
 
         private string ExtractLogical(LogicalNode node)
@@ -208,13 +226,22 @@ private string ExtractComparison(ComparisonNode node)
                 if (isPhrase)
                 {
                     // Phrase search: use quotes without field prefix
-                    var escapedPhrase = searchText.Replace("\"", "\"\"", StringComparison.Ordinal);
+                    var escapedPhrase = this.EscapeFtsPhrase(searchText);
                     return $"\"{escapedPhrase}\"";
                 }
 
+                // Check if the term is a reserved word that needs quoting
+                if (this.IsFts5ReservedWord(searchText))
+                {
+                    // Reserved words must be quoted to be treated as literal search terms
+                    // We cannot use field prefix with quoted terms in FTS5
+                    var escapedTerm = this.EscapeFtsPhrase(searchText);
+                    return $"\"{escapedTerm}\"";
+                }
+
                 // Single word: use field prefix without quotes
-                var escapedTerm = this.EscapeFtsSingleTerm(searchText);
-                return $"{node.Field.FieldPath}:{escapedTerm}";
+                var escaped = this.EscapeFtsSingleTerm(searchText);
+                return $"{node.Field.FieldPath}:{escaped}";
             }
 
             // Other comparison operators (!=, >=, <, etc.) are handled by LINQ filtering
@@ -233,13 +260,31 @@ private bool IsFtsField(string? fieldPath)
             return normalized == "title" || normalized == "description" || normalized == "content";
         }
 
+        /// <summary>
+        /// Check if a term is an FTS5 reserved word.
+        /// Reserved words need special escaping to be searched as literals.
+        /// </summary>
+        private bool IsFts5ReservedWord(string term)
+        {
+            return s_fts5ReservedWords.Contains(term);
+        }
+
+        /// <summary>
+        /// Escape a phrase for FTS5 quoted string search.
+        /// Doubles any internal quotes (FTS5 escape syntax).
+        /// </summary>
+        private string EscapeFtsPhrase(string phrase)
+        {
+            return phrase.Replace("\"", "\"\"", StringComparison.Ordinal);
+        }
+
         private string EscapeFtsSingleTerm(string term)
         {
             // For single-word searches with field prefix (e.g., content:call)
             // FTS5 does NOT support quotes after the colon: content:"call" is INVALID
             // We must use: content:call
-            // 
-            // Escape FTS5 special characters: " * 
+            //
+            // Escape FTS5 special characters: " *
             // For now, keep it simple: just remove quotes and wildcards that could break syntax
             return term.Replace("\"", string.Empty, StringComparison.Ordinal)
                       .Replace("*", string.Empty, StringComparison.Ordinal);

src/Main/CLI/Commands/ExamplesCommand.cs

@@ -139,6 +139,13 @@ private void ShowSearchExamples()
         AnsiConsole.MarkupLine("[dim]Find documents with either python or javascript[/]");
         AnsiConsole.WriteLine();
 
+        AnsiConsole.MarkupLine("[bold]Search for literal reserved words[/]");
+        AnsiConsole.MarkupLine("[cyan]km search '\"NOT\"'[/]");
+        AnsiConsole.MarkupLine("[dim]Use quotes to search for literal AND, OR, NOT as words[/]");
+        AnsiConsole.MarkupLine("[cyan]km search '\"Alice AND Bob\"'[/]");
+        AnsiConsole.MarkupLine("[dim]Search for a phrase containing reserved words literally[/]");
+        AnsiConsole.WriteLine();
+
         AnsiConsole.MarkupLine("[bold]Complex queries with parentheses[/]");
         AnsiConsole.MarkupLine("[cyan]km search \"vacation AND (beach OR mountain)\"[/]");
         AnsiConsole.MarkupLine("[dim]Find vacation plans for beach or mountain trips[/]");