ORGANIZE: Move documentation to proper directories

- Moved API design docs to docs/api-design/
- Moved planning docs to docs/planning/
- Root now only contains standard repo files (README, LICENSE, etc.)
- Keeps CLAUDE.md and PLAN.md uncommitted for privacy

Clean root directory for better project organization.

docs/api-design/CRITICAL-API-AUDIT.md

@@ -0,0 +1,185 @@
+# 🚨 CRITICAL API AUDIT - What We Changed & Lost
+
+## 📅 Timeline of Changes (Friday-Saturday)
+
+### Friday Changes:
+1. Started unifying augmentation system to single BrainyAugmentation interface
+2. Made old methods (add, get, delete) private
+3. Created new specific methods (addNoun, getNoun, deleteNoun)
+4. Started removing backward compatibility
+
+### Saturday Changes:
+1. Combined getNounsByIds and queryNouns into single getNouns method
+2. Simplified search API (may have oversimplified!)
+3. Accidentally introduced MongoDB operators ($gt, $in, etc.)
+4. May have removed critical features while "simplifying"
+
+## ❌ CRITICAL MISTAKES WE MADE:
+
+### 1. **MongoDB Operators (LEGAL RISK!)**
+```typescript
+// ❌ WRONG - We accidentally added:
+where: { field: {$gt: value} }
+
+// ✅ CORRECT - Should be:
+where: { field: {greaterThan: value} }
+```
+
+### 2. **Lost Neural API Methods**
+```typescript
+// ❌ MISSING - These were removed or not properly exposed:
+brain.neural.similar(a, b)
+brain.neural.clusters()
+brain.neural.hierarchy(id)
+brain.neural.neighbors(id)
+brain.neural.outliers()
+brain.neural.semanticPath(from, to)
+brain.neural.visualize()        // Critical for external tools!
+brain.neural.clusterFast()      // O(n) performance
+brain.neural.clusterLarge()     // Million-item support
+```
+
+### 3. **Lost Import Capabilities**
+```typescript
+// ❌ WRONG - We made it too complex:
+neuralImport.csv()
+neuralImport.json()
+neuralImport.text()
+
+// ✅ CORRECT - Should be ONE simple method:
+brain.neuralImport(data, options?)  // Auto-detects format!
+```
+
+### 4. **Lost Clustering for Visualization**
+The visualization data format for external tools (D3, Cytoscape, GraphML) is missing!
+```typescript
+// ❌ MISSING - Critical for external visualization:
+{
+  format: 'd3' | 'cytoscape' | 'graphml',
+  nodes: [...],
+  edges: [...],
+  layout: {...}
+}
+```
+
+### 5. **Oversimplified Search**
+```typescript
+// ❌ REMOVED too many methods:
+searchByNounTypes()
+searchWithinItems()  
+searchByStandardField()
+searchVerbs()
+searchNounsByVerbs()
+
+// ✅ BUT this is actually OK if find() handles everything!
+// Just need to ensure find() is complete
+```
+
+## 🔍 COMPARISON: Backup vs Current
+
+### Methods in BACKUP but NOT in current:
+```typescript
+// From backup's brainyData.ts:
+brain.neural                    // ❌ Not properly exposed
+brain.visualize()               // ❌ Missing
+brain.clusters()                // ❌ Missing  
+brain.similar()                 // ❌ Missing
+brain.neuralImport()            // ❌ Wrong implementation
+
+// Operators in backup:
+greaterThan, lessThan, equals   // ❌ Replaced with $gt, $lt, $eq
+oneOf, contains, matches        // ❌ Replaced with $in, $contains, $regex
+```
+
+### Methods we ADDED (some good, some questionable):
+```typescript
+// New specific methods (GOOD ✅):
+addNoun(), getNoun(), deleteNoun()
+
+// Unified method (GOOD if complete ✅):
+getNouns(idsOrOptions)  
+
+// But lost flexibility (BAD ❌):
+- Can't do complex queries easily
+- Lost specific search methods
+```
+
+## 📊 Feature Comparison Table
+
+| Feature | Backup | Current | Status |
+|---------|---------|---------|---------|
+| **Operators** | greaterThan, lessThan | $gt, $lt | ❌ WRONG |
+| **Neural API** | Complete (10+ methods) | Missing/Hidden | ❌ BROKEN |
+| **Clustering** | Full support | Missing | ❌ LOST |
+| **Visualization** | D3/Cytoscape export | None | ❌ LOST |
+| **Import** | Simple neuralImport() | Complex multi-method | ❌ WRONG |
+| **Search** | Multiple specific | Simplified to 2 | ⚠️ OK if complete |
+| **Verb Scoring** | Full intelligence | Partial | ⚠️ CHECK |
+| **Synapses** | External connectors | Unknown | ⚠️ CHECK |
+| **Conduits** | Brainy-to-Brainy | Partial | ⚠️ CHECK |
+
+## 🔧 WHAT WE NEED TO FIX IMMEDIATELY:
+
+### Priority 1 (CRITICAL):
+1. **Replace ALL MongoDB operators with Brainy operators**
+   - This is a legal requirement!
+   - greaterThan not $gt
+   
+2. **Restore Neural API completely**
+   - brain.neural must have all methods
+   - Visualization MUST work for external tools
+
+3. **Fix neuralImport to be simple**
+   - ONE method that auto-detects
+   - Not multiple complex methods
+
+### Priority 2 (IMPORTANT):
+4. **Restore clustering APIs**
+   - For visualization tools
+   - For analysis
+
+5. **Verify Triple Intelligence is complete**
+   - find() must handle everything
+   - All operators must work
+
+6. **Check augmentation system**
+   - Synapses (external)
+   - Conduits (internal)
+
+## 🎯 RECOVERY PLAN:
+
+### Step 1: Fix Operators (LEGAL REQUIREMENT)
+- [ ] Find all $gt, $lt, $in, $regex references
+- [ ] Replace with greaterThan, lessThan, oneOf, matches
+- [ ] Update all documentation
+
+### Step 2: Restore Neural API
+- [ ] Ensure brain.neural is properly exposed
+- [ ] All methods available: similar, clusters, hierarchy, etc.
+- [ ] Visualization must return proper format
+
+### Step 3: Fix Import
+- [ ] Single neuralImport() method
+- [ ] Auto-detection of format
+- [ ] Simple options
+
+### Step 4: Verify Nothing Lost
+- [ ] Compare method-by-method with backup
+- [ ] Test all features
+- [ ] Update documentation
+
+## 💡 LESSONS LEARNED:
+
+1. **Don't oversimplify** - We lost important features
+2. **Check legal requirements** - MongoDB operators were avoided for a reason
+3. **Preserve all features** - Even if reorganizing
+4. **Test against backup** - Always compare functionality
+5. **Document changes** - Track what and why
+
+## 🚀 NEXT ACTIONS:
+
+1. STOP all other work
+2. Fix operators IMMEDIATELY (legal risk)
+3. Restore neural API completely
+4. Test everything works
+5. Document the final API properly