feat: implement SQLite FTS, improve config system, rename CLI to 'put', fix analyzer warnings (#1097)

## Summary

This PR implements SQLite Full-Text Search and includes several related
improvements to config system, CLI, and code quality:

### 1. SQLite FTS Implementation (~850 lines new code)
- **Core**: `SqliteFtsIndex` implementing FTS5 with stemming support
- **Interfaces**: `ISearchIndex`, `IFtsIndex`, `FtsMatch` for search
abstraction
- **Factory**: `SearchIndexFactory` to instantiate search indexes from
config
- **Integration**: Wired into CLI commands - content is automatically
indexed on upsert
- **Tests**: Comprehensive unit tests (310 lines) + integration tests
(264 lines)

**Usage:**
```bash
$ km put "Machine learning is a subset of AI" --id ml-001
$ km put "Natural language processing uses transformers" --id nlp-001
# Content is automatically indexed in SQLite FTS database
```

### 2. Config System Improvements
- **Specific discriminators**: `sqliteFTS`, `sqliteVector` (not generic
`"fts"`, `"vector"`)
- **Auto-creation**: Config file created automatically on first command
use
- **Config paths relative**: All paths in auto-created config are
relative to config file location
- **New command**: `km config --create` to persist default config to
disk
- **ConfigPathService**: DI-based config path access for commands

### 3. CLI Improvements
- **Rename command**: `upsert` → `put` (HTTP-style naming)
- **Remove premature features**: `embeddingsCache` removed from default
config (not yet implemented)
- **Help text updated**: All examples and documentation updated

### 4. Code Quality (Zero-Tolerance Build)
- Fixed CA1859: `SearchIndexFactory` return type optimization
- Fixed CA1031: Specific exception types in test cleanup
- Fixed CA1711: Test collection naming convention
- **All code passes `/warnaserror` build**

## Test Plan
- [x] All 301 tests passing (192 Main.Tests + 109 Core.Tests)
- [x] FTS indexing: Content indexed and searchable
- [x] Config auto-creation: Works with all CLI commands
- [x] Config discriminators: Validated in tests
- [x] "put" command: Works with all options
- [x] Zero-tolerance build: `build.sh` succeeds

## Files Changed (52 files, +2150/-265 lines)

**New FTS Implementation:**
- `src/Core/Search/SqliteFtsIndex.cs` (194 lines)
- `src/Core/Search/IFtsIndex.cs`, `ISearchIndex.cs`, `FtsMatch.cs`
- `src/Main/Services/SearchIndexFactory.cs` (60 lines)
- `tests/Core.Tests/Search/SqliteFtsIndexTests.cs` (310 lines)
- `tests/Core.Tests/Search/FtsIntegrationTests.cs` (264 lines)

**Config System:**
- `src/Core/Config/ConfigParser.cs` - Auto-creation logic
- `src/Core/Config/AppConfig.cs` - Remove embeddingsCache
- `src/Main/CLI/Infrastructure/ConfigPathService.cs` - DI service
- `src/Main/CLI/Commands/ConfigCommand.cs` - Add --create flag
- `tests/Core.Tests/Config/ConfigParserAutoCreateTests.cs` (203 lines)

**CLI Changes:**
- `src/Main/CLI/CliApplicationBuilder.cs` - Rename upsert → put
- `src/Main/CLI/Commands/GetCommand.cs`, `ListCommand.cs` - Help text
- 14 test files updated for "put" command

## Breaking Changes
- CLI command renamed from `upsert` to `put`
- Default config no longer includes `embeddingsCache`
- Config discriminators changed: `fts` → `sqliteFTS`, `vector` →
`sqliteVector`

Author: dluc

AGENTS.md

@@ -1,5 +1,6 @@
 - Follow @docs/AGENTS.md instructions without exceptions
 - Ignore the "archived" directory
+- During development don't EVER write to my personal ~/.km dir
 - For any task with multiple steps, create a todo list FIRST, then execute.
 - Avoid destructive operations like "get reset", "git clean", etc.
 

docs

@@ -57,24 +57,31 @@ public void Validate(string path = "")
 
     /// <summary>
     /// Creates a default configuration with a single "personal" node
-    /// using local SQLite storage
+    /// using local SQLite storage in the user's home directory
     /// </summary>
     public static AppConfig CreateDefault()
     {
         var homeDir = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
         var kmDir = Path.Combine(homeDir, ".km");
-        var personalNodeDir = Path.Combine(kmDir, "nodes", "personal");
+        return CreateDefault(kmDir);
+    }
+
+    /// <summary>
+    /// Creates a default configuration with a single "personal" node
+    /// using local SQLite storage in the specified base directory
+    /// </summary>
+    /// <param name="baseDir">Base directory for data storage</param>
+    public static AppConfig CreateDefault(string baseDir)
+    {
+        var personalNodeDir = Path.Combine(baseDir, "nodes", "personal");
 
         return new AppConfig
         {
             Nodes = new Dictionary<string, NodeConfig>
             {
                 ["personal"] = NodeConfig.CreateDefaultPersonalNode(personalNodeDir)
-            },
-            EmbeddingsCache = CacheConfig.CreateDefaultSqliteCache(
-                Path.Combine(kmDir, "embeddings-cache.db")
-            ),
-            LLMCache = null
+            }
+            // EmbeddingsCache and LLMCache intentionally omitted - add when features are implemented
         };
     }
 }

src/Core/Config/AppConfig.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
 using KernelMemory.Core.Config.Cache;
 using KernelMemory.Core.Config.ContentIndex;
 using KernelMemory.Core.Config.SearchIndex;
@@ -19,28 +20,55 @@ public static class ConfigParser
     /// - Case insensitive property names
     /// - Comments allowed
     /// - Trailing commas allowed
+    /// - Supports polymorphic deserialization
     /// </summary>
     private static readonly JsonSerializerOptions s_jsonOptions = new()
     {
         PropertyNameCaseInsensitive = true,
         ReadCommentHandling = JsonCommentHandling.Skip,
         AllowTrailingCommas = true,
-        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        TypeInfoResolver = new DefaultJsonTypeInfoResolver()
     };
 
     /// <summary>
-    /// Loads configuration from a file, or returns default config if file doesn't exist
+    /// JSON serializer options for writing config files
+    /// - Indented formatting
+    /// - Camel case property names
+    /// - Omit null values
+    /// </summary>
+    private static readonly JsonSerializerOptions s_writeJsonOptions = new()
+    {
+        WriteIndented = true,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull
+    };
+
+    /// <summary>
+    /// Loads configuration from a file, or creates default config if file doesn't exist.
+    /// The config file is always ensured to exist on disk after loading.
     /// Performs tilde expansion on paths (~/ → home directory)
     /// </summary>
     /// <param name="filePath">Path to configuration file</param>
     /// <returns>Validated AppConfig instance</returns>
     /// <exception cref="ConfigException">Thrown when file exists but parsing or validation fails</exception>
     public static AppConfig LoadFromFile(string filePath)
     {
-        // If file doesn't exist, return default configuration
+        AppConfig config;
+
+        // If file doesn't exist, create default configuration relative to config file location
         if (!File.Exists(filePath))
         {
-            return AppConfig.CreateDefault();
+            var configDir = Path.GetDirectoryName(filePath);
+            var baseDir = string.IsNullOrEmpty(configDir) ? "." : configDir;
+
+            // Create default config relative to config file location
+            config = AppConfig.CreateDefault(baseDir);
+
+            // Write the config file
+            WriteConfigFile(filePath, config);
+
+            return config;
         }
 
         try
@@ -49,11 +77,14 @@ public static AppConfig LoadFromFile(string filePath)
             var json = File.ReadAllText(filePath);
 
             // Parse and validate
-            var config = ParseFromString(json);
+            config = ParseFromString(json);
 
             // Expand tilde paths
             ExpandTildePaths(config);
 
+            // Always ensure the config file exists (recreate if deleted between load and save)
+            WriteConfigFileIfMissing(filePath, config);
+
             return config;
         }
         catch (ConfigException)
@@ -251,4 +282,38 @@ private static string ExpandTilde(string path, string homeDir)
 
         return path;
     }
+    /// <summary>
+    /// Writes the config file to disk if it doesn't exist.
+    /// Used to ensure config file is always present after any operation.
+    /// </summary>
+    /// <param name="filePath">Path to configuration file</param>
+    /// <param name="config">Configuration to write</param>
+    private static void WriteConfigFileIfMissing(string filePath, AppConfig config)
+    {
+        if (File.Exists(filePath))
+        {
+            return;
+        }
+
+        WriteConfigFile(filePath, config);
+    }
+
+    /// <summary>
+    /// Writes the config file to disk, creating directories if needed.
+    /// </summary>
+    /// <param name="filePath">Path to configuration file</param>
+    /// <param name="config">Configuration to write</param>
+    private static void WriteConfigFile(string filePath, AppConfig config)
+    {
+        // Create the directory if needed
+        var configDir = Path.GetDirectoryName(filePath);
+        if (!string.IsNullOrEmpty(configDir) && !Directory.Exists(configDir))
+        {
+            Directory.CreateDirectory(configDir);
+        }
+
+        // Write the config file
+        var json = System.Text.Json.JsonSerializer.Serialize(config, s_writeJsonOptions);
+        File.WriteAllText(filePath, json);
+    }
 }

src/Core/Config/ConfigParser.cs

@@ -9,7 +9,7 @@ namespace KernelMemory.Core.Config.ContentIndex;
 /// Base class for content index configurations
 /// Content index is the source of truth, backed by Entity Framework
 /// </summary>
-[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
 [JsonDerivedType(typeof(SqliteContentIndexConfig), typeDiscriminator: "sqlite")]
 [JsonDerivedType(typeof(PostgresContentIndexConfig), typeDiscriminator: "postgres")]
 public abstract class ContentIndexConfig : IValidatable

src/Core/Config/ContentIndex/ContentIndexConfig.cs

@@ -8,7 +8,7 @@ namespace KernelMemory.Core.Config.Embeddings;
 /// <summary>
 /// Base class for embeddings provider configurations
 /// </summary>
-[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
 [JsonDerivedType(typeof(OllamaEmbeddingsConfig), typeDiscriminator: "ollama")]
 [JsonDerivedType(typeof(OpenAIEmbeddingsConfig), typeDiscriminator: "openai")]
 [JsonDerivedType(typeof(AzureOpenAIEmbeddingsConfig), typeDiscriminator: "azureOpenAI")]

src/Core/Config/Embeddings/EmbeddingsConfig.cs

@@ -71,10 +71,24 @@ public void Validate(string path)
         this.FileStorage?.Validate($"{path}.FileStorage");
         this.RepoStorage?.Validate($"{path}.RepoStorage");
 
+        // Validate search indexes
         for (int i = 0; i < this.SearchIndexes.Count; i++)
         {
             this.SearchIndexes[i].Validate($"{path}.SearchIndexes[{i}]");
         }
+
+        // Ensure all search index IDs are unique within this node
+        var duplicateIds = this.SearchIndexes
+            .GroupBy(idx => idx.Id)
+            .Where(g => g.Count() > 1)
+            .Select(g => g.Key)
+            .ToList();
+
+        if (duplicateIds.Count > 0)
+        {
+            throw new ConfigException($"{path}.SearchIndexes",
+                $"Duplicate search index IDs found: {string.Join(", ", duplicateIds)}. Each search index must have a unique ID within a node.");
+        }
     }
 
     /// <summary>
@@ -97,16 +111,10 @@ internal static NodeConfig CreateDefaultPersonalNode(string nodeDir)
             {
                 new FtsSearchIndexConfig
                 {
+                    Id = "sqlite-fts",
                     Type = SearchIndexTypes.SqliteFTS,
                     Path = Path.Combine(nodeDir, "fts.db"),
                     EnableStemming = true
-                },
-                new VectorSearchIndexConfig
-                {
-                    Type = SearchIndexTypes.SqliteVector,
-                    Path = Path.Combine(nodeDir, "vectors.db"),
-                    Dimensions = 768,
-                    Metric = VectorMetrics.Cosine
                 }
             }
         };

src/Core/Config/NodeConfig.cs

@@ -33,6 +33,12 @@ public sealed class FtsSearchIndexConfig : SearchIndexConfig
     /// <inheritdoc />
     public override void Validate(string path)
     {
+        // Validate ID is provided
+        if (string.IsNullOrWhiteSpace(this.Id))
+        {
+            throw new ConfigException($"{path}.Id", "Search index ID is required");
+        }
+
         this.Embeddings?.Validate($"{path}.Embeddings");
 
         var isSqlite = this.Type == SearchIndexTypes.SqliteFTS;

src/Core/Config/SearchIndex/FtsSearchIndexConfig.cs

@@ -27,6 +27,12 @@ public sealed class GraphSearchIndexConfig : SearchIndexConfig
     /// <inheritdoc />
     public override void Validate(string path)
     {
+        // Validate ID is provided
+        if (string.IsNullOrWhiteSpace(this.Id))
+        {
+            throw new ConfigException($"{path}.Id", "Search index ID is required");
+        }
+
         this.Embeddings?.Validate($"{path}.Embeddings");
 
         var hasPath = !string.IsNullOrWhiteSpace(this.Path);

src/Core/Config/SearchIndex/GraphSearchIndexConfig.cs

@@ -9,12 +9,20 @@ namespace KernelMemory.Core.Config.SearchIndex;
 /// <summary>
 /// Base class for search index configurations
 /// </summary>
-[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
-[JsonDerivedType(typeof(FtsSearchIndexConfig), typeDiscriminator: "fts")]
-[JsonDerivedType(typeof(VectorSearchIndexConfig), typeDiscriminator: "vector")]
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "type")]
+[JsonDerivedType(typeof(FtsSearchIndexConfig), typeDiscriminator: "sqliteFTS")]
+[JsonDerivedType(typeof(VectorSearchIndexConfig), typeDiscriminator: "sqliteVector")]
 [JsonDerivedType(typeof(GraphSearchIndexConfig), typeDiscriminator: "graph")]
 public abstract class SearchIndexConfig : IValidatable
 {
+    /// <summary>
+    /// Unique identifier for this search index instance.
+    /// Must be unique within a node's SearchIndexes array.
+    /// Used to identify index instances in operations pipeline (stable across config changes).
+    /// </summary>
+    [JsonPropertyName("id")]
+    public string Id { get; set; } = string.Empty;
+
     /// <summary>
     /// Type of search index
     /// </summary>