docs: Document planned architectural refactor and tool consolidation.

docs/ToolConsolidation.md

@@ -0,0 +1,112 @@
+# Tool Consolidation Ideas
+
+This document outlines opportunities to merge similar tools to simplify the API.
+
+## 1. File Write Operations
+
+**Current tools:** `CreateFile`, `InsertAfter`, `AppendToFile`
+
+**Proposed merge:** `WriteToFile`
+
+```csharp
+public static string WriteToFile(
+    string path,
+    string[] content,
+    string? mode = "create",
+    string? anchor = null)
+```
+
+**Behavior:**
+- `mode="create"` - Creates new file (error if exists)
+- `mode="append"` - Appends to EOF (creates if missing)
+- `mode="insert"` - Inserts after anchor (requires existing file)
+
+**Benefits:**
+- Reduces 3 tools to 1
+- Cleaner API for LLM
+- Unified error handling
+
+## 2. File Move Operations
+
+**Current tools:** `RenameFile`, `CopyFile`
+
+**Proposed merge:** `MoveFile`
+
+```csharp
+public static string MoveFile(
+    string sourcePath,
+    string destinationPath,
+    bool copy = false)
+```
+
+**Behavior:**
+- `copy=false` - Moves file (current RenameFile behavior)
+- `copy=true` - Copies file (current CopyFile behavior)
+
+**Benefits:**
+- 90% identical logic
+- Only difference is File.Move vs File.Copy
+- Both create parent directories
+- Similar error handling patterns
+
+## 3. Grep Operations
+
+**Current tools:** `GrepFile`, `GrepRecursive`
+
+**Proposed merge:** `Grep`
+
+```csharp
+public static string Grep(
+    string path,
+    string pattern,
+    bool recursive = false,
+    string? filePattern = null)
+```
+
+**Behavior:**
+- `recursive=false` - Searches single file (current GrepFile)
+- `recursive=true` - Searches directory recursively (current GrepRecursive)
+- `filePattern` - Optional glob to filter files when recursive
+
+**Benefits:**
+- Very similar logic
+- Reduces 2 tools to 1
+- Cleaner API for LLM
+
+## 4. Delete Operations
+
+**Current tools:** `DeleteFile`, `DeleteDir`
+
+**Proposed merge:** `Delete`
+
+```csharp
+public static string Delete(
+    string path,
+    bool recursive = true)
+```
+
+**Behavior:**
+- Auto-detects if path is file or directory
+- `recursive=true` - Delete directory and all contents
+- `recursive=false` - Only matters for directories (error if not empty)
+
+**Benefits:**
+- Auto-detects file vs directory
+- Similar error handling patterns
+- Reduces 2 tools to 1
+
+## Summary
+
+These consolidations would reduce the tool count from 17 to 13 tools, making the API simpler and easier for the LLM to use effectively.
+
+**High priority merges:**
+1. ✅ File Write Operations (3 → 1)
+2. ✅ File Move Operations (2 → 1)
+3. ✅ Grep Operations (2 → 1)
+4. ✅ Delete Operations (2 → 1)
+
+**Kept separate:**
+- `ReadFile` - distinct read-only operation
+- `ListDir`, `FindFiles`, `GetFileInfo` - different purposes
+- `CreateDir` - simple enough to keep standalone
+- `ReplaceLines`, `InsertAfter`, `DeleteRange` - too complex to merge without confusing LLM