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/FINAL-2.0-PUBLIC-API.md

@@ -0,0 +1,210 @@
+# 🧠 Brainy 2.0 Final Public API
+
+> **Clean, Specific, Beautiful** - Every method has ONE clear purpose.
+
+## 📚 NOUNS (Vectors with Metadata)
+
+```typescript
+// Single Operations
+addNoun(vector, metadata?)                  // Add one noun
+getNoun(id)                                 // Get one noun by ID
+updateNoun(id, vector?, metadata?)          // Update entire noun
+updateNounMetadata(id, metadata)            // Update metadata only  
+getNounMetadata(id)                         // Get metadata only
+getNounWithVerbs(id)                        // Get noun with all relationships
+deleteNoun(id)                              // Delete one noun
+hasNoun(id)                                 // Check if noun exists
+
+// Batch Operations  
+addNouns(items[])                          // Add multiple nouns
+getNouns(idsOrOptions)                     // Get multiple nouns (by IDs or query)
+  // getNouns(['id1', 'id2'])              // Get by specific IDs
+  // getNouns({ filter: {...} })           // Get with filters
+  // getNouns({ limit: 10, offset: 20 })   // Get with pagination
+deleteNouns(ids[])                         // Delete multiple nouns
+```
+
+## 🔗 VERBS (Relationships)
+
+```typescript
+// Single Operations
+addVerb(source, target, type, metadata?)    // Create relationship
+getVerb(id)                                 // Get one verb by ID
+deleteVerb(id)                              // Delete one verb
+
+// Batch Operations
+addVerbs(verbs[])                          // Add multiple relationships
+getVerbs(filter?)                          // Get filtered verbs
+getVerbsBySource(sourceId)                 // Get outgoing relationships
+getVerbsByTarget(targetId)                 // Get incoming relationships
+getVerbsByType(type)                       // Get by relationship type
+deleteVerbs(ids[])                         // Delete multiple verbs
+```
+
+## 🔍 SEARCH
+
+```typescript
+// Core Search
+search(query, k?, options?)                 // Primary vector search
+searchText(text, k?, options?)              // Natural language search
+find(query)                                 // Triple Intelligence (Vector+Graph+Field) 🧠
+findSimilar(id, k?, options?)              // Find similar to existing noun
+
+// Advanced Search
+searchByNounTypes(types[], query, k?)      // Filter by noun types
+searchWithinItems(query, ids[], k?)        // Search within specific nouns
+searchWithCursor(query, cursor)            // Paginated search
+searchByStandardField(field, value, k?)    // Field-based search
+
+// Graph Search
+searchVerbs(query, options?)               // Search relationships
+searchNounsByVerbs(conditions)             // Find nouns by relationships
+
+// Distributed Search
+searchLocal(query, k?)                     // Search local instance only
+searchRemote(query, k?)                    // Search remote instance only
+searchCombined(query, k?)                  // Search both local and remote
+```
+
+## 📊 METADATA & FILTERING
+
+```typescript
+getFilterFields()                          // Get all indexed fields
+getFilterValues(field)                     // Get unique values for a field
+getAvailableFieldNames()                   // Get available field names
+getStandardFieldMappings()                 // Get standard field mappings
+```
+
+## 🚀 PERFORMANCE & MONITORING
+
+```typescript
+// Cache
+getCacheStats()                            // Get cache statistics
+clearCache()                               // Clear search cache
+
+// Statistics
+size()                                     // Total noun count
+getStatistics(options?)                    // Comprehensive statistics
+getServiceStatistics(service)              // Per-service statistics
+listServices()                             // List all services
+flushStatistics()                          // Persist statistics to storage
+
+// Health
+getHealthStatus()                          // System health check
+status()                                   // Full status report
+```
+
+## ⚙️ CONFIGURATION
+
+```typescript
+// Operational Modes
+isReadOnly() / setReadOnly(bool)          // Read-only mode
+isWriteOnly() / setWriteOnly(bool)        // Write-only mode  
+isFrozen() / setFrozen(bool)              // Freeze all modifications
+
+// Real-time Sync
+enableRealtimeUpdates(config)              // Enable live synchronization
+disableRealtimeUpdates()                   // Disable synchronization
+getRealtimeUpdateConfig()                  // Get current config
+checkForUpdatesNow()                       // Manual sync trigger
+
+// Remote Connection
+connectToRemoteServer(url, options?)       // Connect to remote instance
+disconnectFromRemoteServer()               // Disconnect from remote
+isConnectedToRemoteServer()               // Check connection status
+```
+
+## 🧠 INTELLIGENCE
+
+```typescript
+// Verb Scoring
+provideFeedbackForVerbScoring(feedback)    // Train relationship scoring
+getVerbScoringStats()                      // Get scoring statistics
+exportVerbScoringLearningData()           // Export training data
+importVerbScoringLearningData(data)       // Import training data
+
+// Embeddings
+embed(text)                                // Generate embedding vector
+calculateSimilarity(a, b, metric?)         // Calculate vector similarity
+```
+
+## 💾 DATA MANAGEMENT
+
+```typescript
+// Clear Operations
+clear(options?)                           // Clear all data
+clearNouns(options?)                      // Clear all nouns only
+clearVerbs(options?)                      // Clear all verbs only
+
+// Backup & Restore
+backup()                                   // Create full backup
+restore(backup)                           // Restore from backup
+
+// Import/Export
+import(data, format)                      // Import external data
+importSparseData(data)                    // Import sparse format
+
+// Index Management
+rebuildMetadataIndex()                    // Rebuild metadata index
+```
+
+## 🔒 SECURITY
+
+```typescript
+encryptData(data)                         // Encrypt data
+decryptData(data)                         // Decrypt data
+```
+
+## 🎲 UTILITIES
+
+```typescript
+generateRandomGraph(nodes, edges)         // Generate test graph data
+```
+
+## 🚀 LIFECYCLE
+
+```typescript
+// Instance Methods
+new BrainyData(config?)                   // Create instance
+init()                                     // Initialize (REQUIRED!)
+shutDown()                                // Graceful shutdown
+cleanup()                                  // Clean up resources
+
+// Static Methods
+BrainyData.preloadModel(options?)         // Preload ML model
+BrainyData.warmup(options?)              // Warmup system
+```
+
+## 📐 PROPERTIES (Read-only)
+
+```typescript
+dimensions                                // Vector dimensions
+maxConnections                           // HNSW max connections
+efConstruction                           // HNSW ef construction
+initialized                              // Is initialized?
+```
+
+---
+
+## 📝 Key Changes in 2.0
+
+### ✅ Simplified & Unified
+- `getNouns()` now handles ALL plural queries (by IDs, filters, or pagination)
+- No more `getNounsByIds()`, `queryNouns()`, `getBatch()` - just `getNouns()`
+- Clear singular vs plural: `getNoun()` for one, `getNouns()` for many
+
+### ✅ Specific Naming
+- Always specify noun/verb: `addNoun()` not `add()`
+- No aliases or duplicates
+- One method, one purpose
+
+### ✅ Private Legacy Methods
+These are now private (use new methods above):
+- `add()`, `get()`, `delete()`, `update()`
+- `relate()`, `connect()`, `has()`, `exists()`
+- `getMetadata()`, `updateMetadata()`
+- `addItem()`, `addToBoth()`, `addBatch()`, `getBatch()`
+
+### ✅ Triple Intelligence
+- New `find()` method unifies Vector + Graph + Field search
+- Most powerful search capability in one simple method