diff --git a/.github/workflows/deploy-demo.yml b/.github/workflows/deploy-demo.yml
deleted file mode 100644
index 6c34a4d4..00000000
--- a/.github/workflows/deploy-demo.yml
+++ /dev/null
@@ -1,73 +0,0 @@
-name: Deploy Demo to GitHub Pages
-
-on:
-  push:
-    branches: [ main ]
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js 🔧
-        uses: actions/setup-node@v3
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies 📦
-        run: npm install --legacy-peer-deps
-
-      - name: Build project 🏗️
-        run: |
-          npm run build
-
-      - name: Build Angular demo 🏗️
-        run: |
-          cd demo/brainy-angular-demo
-          npm install --legacy-peer-deps
-          npm run build
-
-      - name: Prepare deployment 📦
-        run: |
-          mkdir -p _site
-          mkdir -p _site/demo
-          mkdir -p _site/dist
-          cp demo/index.html _site/index.html
-          cp -r demo/brainy-angular-demo/dist/brainy-angular-demo/* _site/demo/
-          cp -r dist/* _site/dist/
-          cp brainy.png _site/
-          # Copy dist directly to demo/dist for easier access
-          mkdir -p _site/demo/dist
-          cp -r dist/* _site/demo/dist/
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: _site
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
diff --git a/AUGMENTATION_ARCHITECTURE.md b/AUGMENTATION_ARCHITECTURE.md
new file mode 100644
index 00000000..37a142e3
--- /dev/null
+++ b/AUGMENTATION_ARCHITECTURE.md
@@ -0,0 +1,256 @@
+# 🧠 Brainy Augmentation Architecture - Complete Guide
+
+## Overview
+
+Brainy has a clear augmentation system with four tiers:
+
+```
+1. Built-in (Free, Always Included)
+2. Community (Free, npm packages)  
+3. Premium (Paid, @soulcraft/brain-cloud)
+4. Brain Cloud (Managed Service)
+```
+
+## 1. Built-in Augmentations (Always Free)
+
+These come with every Brainy installation:
+
+### Currently Implemented:
+- **NeuralImport** - AI-powered data understanding
+- **Basic Storage** - Filesystem/memory persistence
+- **Vector Search** - Semantic similarity
+- **Graph Traversal** - Relationship queries
+
+### To Be Added (Still Built-in):
+```javascript
+// src/augmentations/built-in/
+├── autoSave.ts        // Automatic persistence
+├── basicCache.ts      // Query caching
+├── simpleBackup.ts    // Local backups
+└── metadataIndex.ts   // Facet indexing
+```
+
+## 2. Community Augmentations (Free, Open Source)
+
+Published to npm by the community:
+
+```bash
+# Examples (to be created by community)
+npm install brainy-sentiment      # Sentiment analysis
+npm install brainy-translator     # Multi-language
+npm install brainy-summarizer     # Text summarization
+npm install brainy-classifier     # Text classification
+```
+
+Usage:
+```javascript
+import { SentimentAnalyzer } from 'brainy-sentiment'
+
+const cortex = new Cortex()
+cortex.register(new SentimentAnalyzer())
+```
+
+## 3. Premium Augmentations (@soulcraft/brain-cloud)
+
+The `/brain-cloud` project contains premium augmentations:
+
+### Core Premium Features (AI Memory & Coordination):
+```javascript
+import { 
+  AIMemory,           // Persistent AI memory across sessions
+  AgentCoordinator,   // Multi-agent handoffs
+  TeamSync,          // Real-time team synchronization
+  CloudBackup        // Automatic cloud backups
+} from '@soulcraft/brain-cloud'
+```
+
+### Enterprise Connectors (from old quantum-vault):
+```javascript
+import {
+  NotionSync,        // Bidirectional Notion sync
+  SalesforceConnect, // CRM integration
+  AirtableSync,      // Database sync
+  PostgresSync,      // Real-time replication
+  SlackMemory,       // Team knowledge base
+  AnalyticsSuite     // Business intelligence
+} from '@soulcraft/brain-cloud/enterprise'
+```
+
+## 4. Brain Cloud Service (Managed)
+
+The hosted service at brain-cloud.soulcraft.com:
+
+```javascript
+// Connect to managed service
+await brain.connect('brain-cloud.soulcraft.com', {
+  instance: 'my-team',
+  apiKey: process.env.BRAIN_CLOUD_KEY
+})
+```
+
+## CLI Commands Structure
+
+### Core Commands (brainy)
+```bash
+# Database operations
+brainy init              # Initialize Brainy
+brainy add "data"        # Add data
+brainy search "query"    # Search
+brainy chat              # Interactive chat
+
+# Augmentation management
+brainy augment           # List augmentations
+brainy augment add       # Add augmentation (interactive)
+brainy augment remove    # Remove augmentation
+brainy augment config    # Configure augmentation
+
+# Brain Cloud connection
+brainy cloud             # Connect to Brain Cloud service
+brainy cloud --status    # Check connection status
+brainy cloud --sync      # Force sync
+```
+
+### Installing Augmentations via CLI
+
+#### Built-in (always available):
+```bash
+brainy augment enable neural-import
+brainy augment enable auto-save
+```
+
+#### Community (from npm):
+```bash
+# Install from npm first
+npm install -g brainy-sentiment
+
+# Then register with Brainy
+brainy augment add brainy-sentiment --type sense
+```
+
+#### Premium (requires license):
+```bash
+# Set license key
+export BRAINY_LICENSE_KEY=lic_xxxxx
+
+# Install premium package
+npm install -g @soulcraft/brain-cloud
+
+# Register augmentations
+brainy augment add ai-memory --premium
+brainy augment add notion-sync --premium
+```
+
+#### For Brain Cloud service:
+```bash
+# Connect to cloud (handles everything)
+brainy cloud --connect YOUR_CUSTOMER_ID
+```
+
+## How Augmentations Work
+
+### 1. Local Instance
+```javascript
+const brain = new BrainyData()
+const cortex = new Cortex()
+
+// Register augmentations
+cortex.register(new NeuralImport(brain))      // Built-in
+cortex.register(new SentimentAnalyzer())      // Community
+cortex.register(new NotionSync({ key }))      // Premium
+
+await brain.init()
+```
+
+### 2. Remote Hosted Instance
+```javascript
+// Connect to remote Brainy
+const brain = new BrainyData({
+  remote: 'https://my-brainy-server.com'
+})
+
+// Augmentations run on server
+await brain.addAugmentation('sentiment-analyzer')
+```
+
+### 3. Brain Cloud Instance
+```javascript
+// Connect to Brain Cloud
+const brain = new BrainyData({
+  cloud: true,
+  customerId: 'cust_xxx'
+})
+
+// All premium augmentations available
+// Managed by Brain Cloud service
+```
+
+## Directory Structure
+
+### /brainy (this project)
+```
+src/
+├── augmentations/
+│   ├── built-in/          # Free, always included
+│   │   ├── neuralImport.ts
+│   │   ├── autoSave.ts
+│   │   └── basicCache.ts
+│   └── cortexSense.ts     # Legacy, being refactored
+├── cortex.ts              # Orchestrator
+└── brainyData.ts          # Core database
+```
+
+### /brain-cloud (premium project)
+```
+src/
+├── augmentations/
+│   ├── memory/            # AI Memory features
+│   │   ├── aiMemory.ts
+│   │   ├── agentCoordinator.ts
+│   │   └── teamSync.ts
+│   ├── enterprise/        # Enterprise connectors
+│   │   ├── notionSync.ts
+│   │   ├── salesforce.ts
+│   │   └── airtable.ts
+│   └── index.ts          # Main exports
+├── licensing/            # License validation
+└── cloud-service/        # Brain Cloud API
+```
+
+## Migration Plan
+
+### Phase 1: Update References
+- [x] Replace all `brainy-quantum-vault` → `@soulcraft/brain-cloud`
+- [ ] Update documentation
+- [ ] Update CLI commands
+
+### Phase 2: Restructure brain-cloud
+- [ ] Move quantum-vault connectors to brain-cloud/enterprise
+- [ ] Add AI memory augmentations
+- [ ] Implement license validation
+
+### Phase 3: CLI Enhancement
+- [ ] Add `brainy augment` commands
+- [ ] Interactive augmentation installer
+- [ ] Auto-detect available augmentations
+
+### Phase 4: Documentation
+- [ ] Update README with clear tiers
+- [ ] Create augmentation development guide
+- [ ] Website update instructions
+
+## License Model
+
+```
+Built-in:  MIT License (Free forever)
+Community: Varies (usually MIT)
+Premium:   Commercial License ($49-299/mo)
+Cloud:     Subscription ($19-99/mo)
+```
+
+## The Promise
+
+1. **Built-in augmentations are ALWAYS free**
+2. **No feature moves from free to paid**
+3. **Community contributions welcome**
+4. **Premium funds open source development**
+5. **Brain Cloud is optional, not required**
\ No newline at end of file
diff --git a/CLI_AUGMENTATION_GUIDE.md b/CLI_AUGMENTATION_GUIDE.md
new file mode 100644
index 00000000..4ddf1b66
--- /dev/null
+++ b/CLI_AUGMENTATION_GUIDE.md
@@ -0,0 +1,251 @@
+# 🧠 Brainy CLI - Augmentation Management Guide
+
+## Complete CLI Commands for Augmentations
+
+### Core Commands
+
+```bash
+# Initialize Brainy
+brainy init
+
+# Basic operations
+brainy add "data"           # Add data
+brainy search "query"       # Search
+brainy chat                 # Interactive chat
+```
+
+### Augmentation Management
+
+```bash
+# List all augmentations
+brainy augment              # Shows installed & available
+brainy augment list         # Same as above
+brainy augment available    # Shows what can be installed
+
+# Add augmentations
+brainy augment add          # Interactive mode
+brainy augment add neural-import    # Built-in
+brainy augment add brainy-sentiment  # Community (from npm)
+brainy augment add ai-memory --premium  # Premium (needs license)
+
+# Remove augmentations
+brainy augment remove sentiment-analyzer
+brainy augment disable neural-import  # Disable but keep installed
+
+# Configure augmentations
+brainy augment config neural-import
+brainy augment config notion-sync --set apiKey=xxx
+```
+
+### Installing Different Types
+
+#### 1. Built-in Augmentations (Free, Always Available)
+```bash
+# These are included - just enable them
+brainy augment enable neural-import
+brainy augment enable auto-save
+brainy augment enable basic-cache
+```
+
+#### 2. Community Augmentations (Free, From npm)
+```bash
+# Step 1: Install from npm
+npm install -g brainy-sentiment
+
+# Step 2: Register with Brainy
+brainy augment add brainy-sentiment
+
+# Or in one command (coming soon)
+brainy augment install brainy-sentiment  # Auto-installs from npm
+```
+
+#### 3. Premium Augmentations (Paid, From @soulcraft/brain-cloud)
+```bash
+# Step 1: Set license key
+export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx
+
+# Step 2: Install premium package
+npm install -g @soulcraft/brain-cloud
+
+# Step 3: Add specific augmentations
+brainy augment add ai-memory --premium
+brainy augment add agent-coordinator --premium
+brainy augment add notion-sync --premium
+
+# Or add all premium at once
+brainy augment add-premium --all
+```
+
+#### 4. Brain Cloud Service (Managed, Everything Included)
+```bash
+# Connect to Brain Cloud (includes all augmentations)
+brainy cloud --connect YOUR_CUSTOMER_ID
+
+# Check status
+brainy cloud --status
+
+# Force sync
+brainy cloud --sync
+
+# Open dashboard
+brainy cloud --dashboard
+```
+
+### Working with Different Instances
+
+#### Local Instance
+```bash
+# Add augmentation to local Brainy
+cd my-project
+brainy init
+brainy augment add neural-import
+```
+
+#### Remote Hosted Instance
+```bash
+# Connect to remote Brainy server
+brainy config set server.url https://my-brainy-server.com
+brainy config set server.apiKey xxx
+
+# Add augmentation to remote
+brainy augment add sentiment-analyzer --remote
+```
+
+#### Brain Cloud Instance
+```bash
+# Everything is managed
+brainy cloud --connect CUSTOMER_ID
+# All augmentations automatically available
+```
+
+### Interactive Mode Examples
+
+#### Adding an Augmentation (No Arguments)
+```bash
+$ brainy augment add
+? What type of augmentation? › 
+  Built-in (Free)
+  Community (npm)
+  Premium (Licensed)
+  
+? Select augmentation › 
+  ✓ neural-import (AI understanding)
+  ○ sentiment-analyzer (Emotion detection)
+  ○ translator (Multi-language)
+  
+? Configure now? (Y/n) › 
+```
+
+#### Configuring an Augmentation
+```bash
+$ brainy augment config notion-sync
+? Notion API Token › secret_xxxxx
+? Sync Mode › 
+  ○ Read only
+  ● Bidirectional
+  ○ Write only
+  
+? Sync Interval (minutes) › 5
+✅ Configuration saved!
+```
+
+### CLI Implementation in brainy.js
+
+```javascript
+// brainy augment command structure
+program
+  .command('augment [action] [name]')
+  .description('Manage brain augmentations')
+  .option('--type <type>', 'Augmentation type (sense|conduit|memory|etc)')
+  .option('--premium', 'Premium augmentation')
+  .option('--remote', 'Install on remote server')
+  .action(async (action, name, options) => {
+    if (!action) {
+      // List all augmentations
+      await listAugmentations()
+    } else {
+      switch(action) {
+        case 'add':
+        case 'install':
+          await installAugmentation(name, options)
+          break
+        case 'remove':
+          await removeAugmentation(name)
+          break
+        case 'config':
+          await configureAugmentation(name, options)
+          break
+        case 'list':
+          await listAugmentations()
+          break
+        case 'enable':
+          await enableAugmentation(name)
+          break
+        case 'disable':
+          await disableAugmentation(name)
+          break
+      }
+    }
+  })
+```
+
+### Environment Variables
+
+```bash
+# For premium augmentations
+export BRAINY_LICENSE_KEY=lic_xxxxxxxxxxxxx
+
+# For Brain Cloud
+export BRAIN_CLOUD_KEY=bc_xxxxxxxxxxxxx
+export BRAIN_CLOUD_CUSTOMER_ID=cust_xxxxx
+
+# For remote server
+export BRAINY_SERVER_URL=https://my-server.com
+export BRAINY_SERVER_KEY=xxx
+```
+
+### Package.json Scripts
+
+Add these to your project's package.json:
+
+```json
+{
+  "scripts": {
+    "brain:init": "brainy init",
+    "brain:augment": "brainy augment",
+    "brain:add-sentiment": "brainy augment add brainy-sentiment",
+    "brain:add-premium": "brainy augment add ai-memory --premium",
+    "brain:cloud": "brainy cloud --connect"
+  }
+}
+```
+
+### Error Messages & Solutions
+
+```bash
+# Missing license key
+❌ Premium augmentation requires license key
+💡 Set BRAINY_LICENSE_KEY or visit soulcraft.com
+
+# Augmentation not found
+❌ Augmentation 'xyz' not found
+💡 Try: npm install brainy-xyz first
+
+# Remote connection failed
+❌ Cannot connect to remote server
+💡 Check BRAINY_SERVER_URL and network connection
+
+# Incompatible version
+❌ Augmentation requires Brainy v0.62+
+💡 Update: npm update @soulcraft/brainy
+```
+
+## Summary
+
+The CLI provides a unified interface for managing all augmentation types:
+- **Built-in**: Always available, just enable
+- **Community**: Install from npm, then add
+- **Premium**: Need license, install from @soulcraft/brain-cloud
+- **Brain Cloud**: Everything managed, just connect
+
+The key is making it simple for beginners (interactive mode) while powerful for experts (direct commands).
\ No newline at end of file
diff --git a/PHILOSOPHY.md b/PHILOSOPHY.md
new file mode 100644
index 00000000..182ae403
--- /dev/null
+++ b/PHILOSOPHY.md
@@ -0,0 +1,164 @@
+# 🧠 Brainy Philosophy & Design Principles
+
+## Core Philosophy
+**"Simple for beginners, powerful for experts"**
+
+## Design Principles
+
+### 1. **Beginner-Friendly by Default**
+- If no arguments provided → Interactive mode with helpful prompts
+- Clear, simple language (no jargon)
+- Helpful examples shown automatically
+- Smart defaults that "just work"
+
+### 2. **Clean, Simple Language**
+```bash
+# Good - Clear and simple
+brainy add "John works at Acme Corp"
+brainy search "Who works at Acme?"
+brainy augment neural-import data.csv
+
+# Bad - Technical and confusing
+brainy insert --vector-dimension=384 --graph-node="person" 
+brainy query --similarity-threshold=0.8 --facet-filter='{"type":"person"}'
+```
+
+### 3. **Progressive Disclosure**
+- Start simple, reveal complexity only when needed
+- Basic usage requires no configuration
+- Advanced features available but not required
+
+### 4. **Interactive When Uncertain**
+```bash
+$ brainy add
+? What would you like to add? › John Smith is a developer
+? Add any tags or categories? (optional) › person, developer
+✅ Added successfully!
+
+$ brainy search
+? What are you looking for? › developers
+? How many results? (10) › 5
+🔍 Found 5 matches...
+```
+
+### 5. **Consistent Brain Metaphor**
+- **Brainy** = The brain (whole system)
+- **Cortex** = Orchestrator (coordinates everything)
+- **Neural Import** = Understanding data (neural processing)
+- **Augmentations** = Brain capabilities (vision, hearing, memory, etc.)
+
+### 6. **One Way to Do Things**
+- Single clear path for common tasks
+- No duplicate commands or confusing aliases
+- If there are options, make the best one the default
+
+### 7. **Helpful Error Messages**
+```bash
+# Good
+❌ Can't find data.csv
+💡 Did you mean data.json? Or try: brainy import --help
+
+# Bad
+Error: ENOENT no such file or directory
+```
+
+### 8. **Smart Defaults**
+- Auto-detect file types
+- Infer intent from context
+- Use Neural Import by default for understanding data
+- Automatic augmentation discovery
+
+## CLI Command Philosophy
+
+### Core Commands (Simple Verbs)
+```bash
+brainy init        # Start here
+brainy add         # Add data
+brainy search      # Find data
+brainy chat        # Talk to your data
+```
+
+### Augmentation Commands (Clear Actions)
+```bash
+brainy augment                    # List/manage augmentations
+brainy augment add neural-import  # Add an augmentation
+brainy augment remove notion-sync # Remove an augmentation
+```
+
+### Interactive Examples
+```bash
+# No arguments = Interactive mode
+$ brainy add
+? What would you like to add? › [waiting for input]
+
+# With arguments = Direct mode
+$ brainy add "Sarah is a designer at StartupXYZ"
+✅ Added!
+
+# Help is conversational
+$ brainy help add
+📝 Add data to your brain
+
+Examples:
+  brainy add "John works at Acme"
+  brainy add data.csv
+  brainy add --interactive
+
+Just run 'brainy add' for interactive mode!
+```
+
+## Code Philosophy
+
+### Function Names
+```typescript
+// Good - Clear and simple
+brain.add(data)
+brain.search(query)
+cortex.process(augmentation)
+
+// Bad - Technical and verbose
+brain.insertVectorWithGraphRelationships(data)
+brain.executeMultiDimensionalQuery(query)
+cortex.executeAugmentationPipeline(augmentation)
+```
+
+### API Design
+```typescript
+// Good - Progressive enhancement
+brain.add("simple text")                    // Works
+brain.add("text", { category: "person" })   // More control
+brain.add("text", metadata, options)        // Full control
+
+// Bad - All or nothing
+brain.add(text, vector, metadata, options, callback)
+```
+
+## Documentation Philosophy
+
+### README Structure
+1. **What it is** (one sentence)
+2. **Quick start** (3 commands max)
+3. **Simple examples** (real-world use)
+4. **Going deeper** (advanced features)
+
+### Example First
+Always show the example before explaining:
+```bash
+# Add a person
+brainy add "Alice is a product manager"
+
+# Find them later
+brainy search "product manager"
+```
+
+## Testing Philosophy
+- Test the beginner path first
+- Interactive mode must always work
+- Examples in docs must be runnable
+- Error messages must be helpful
+
+## Remember
+- **If it's not simple, it's not ready**
+- **The best interface is no interface** (smart defaults)
+- **Show, don't tell** (examples > explanations)
+- **Beginner's mind** (always ask: would a newcomer understand this?)
\ No newline at end of file
diff --git a/README.md b/README.md
index 5845d239..5885f1f0 100644
--- a/README.md
+++ b/README.md
@@ -4,581 +4,451 @@
 
 [![npm version](https://badge.fury.io/js/%40soulcraft%2Fbrainy.svg)](https://badge.fury.io/js/%40soulcraft%2Fbrainy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Try Demo](https://img.shields.io/badge/Try%20Demo-Live-green.svg)](https://soulcraft.com/console)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24.4.1-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4.5-blue.svg)](https://www.typescriptlang.org/)
 
-# BRAINY: Multi-Dimensional AI Database™
+# 🧠 BRAINY: Your AI-Powered Second Brain
 
-**The world's first Multi-Dimensional AI Database**  
-*Vector similarity • Graph relationships • Metadata facets • AI context*
+**The World's First Multi-Dimensional AI Database™**  
+*Vector similarity • Graph relationships • Metadata facets • Neural understanding*
 
-*Zero-to-Smart™ technology that thinks so you don't have to*
+**Build AI apps that actually understand your data - in minutes, not months**
 
 </div>
 
 ---
 
-## 🚀 THE AMAZING BRAINY: See It In Action!
+## 🚀 What Can You Build?
 
+### 💬 **AI Chat Apps** - That Actually Remember
 ```javascript
-import { BrainyData } from '@soulcraft/brainy'
+// Your users' conversations persist across sessions
+const brain = new BrainyData()
+await brain.add("User prefers dark mode")
+await brain.add("User is learning Spanish")
 
-// 🧪 Initialize your brain-in-a-jar
-const brainy = new BrainyData()  // Zero config - it's ALIVE!
-await brainy.init()
-
-// 🔬 Feed it knowledge with relationships
-const openai = await brainy.add("OpenAI", { type: "company", funding: 11000000 })
-const gpt4 = await brainy.add("GPT-4", { type: "product", users: 100000000 })
-await brainy.relate(openai, gpt4, "develops")
-
-// ⚡ One query to rule them all - Vector + Graph + Faceted search!
-const results = await brainy.search("AI language models", 5, {
-  metadata: { funding: { $gte: 10000000 } },  // MongoDB-style filtering
-  includeVerbs: true                           // Graph relationships
-})  // Plus semantic vector search!
+// Later sessions remember everything
+const context = await brain.search("user preferences")
+// AI knows: dark mode + Spanish learning preference
 ```
 
-**🎭 8 lines. Three search paradigms. One brain-powered database.**
+### 🤖 **Smart Assistants** - With Real Knowledge Graphs
+```javascript
+// Build assistants that understand relationships
+await brain.add("Sarah manages the design team")
+await brain.addVerb("Sarah", "reports_to", "John")
+await brain.addVerb("Sarah", "works_on", "Project Apollo")
 
-## 💫 WHY BRAINY? The Problem We Solve
-
-### ❌ The Old Way: Database Frankenstein
-
-```
-Pinecone ($$$) + Neo4j ($$$) + Elasticsearch ($$$) + Sync Hell = 😱
+// Query complex relationships
+const team = await brain.getRelated("Project Apollo", {
+  verb: "works_on",
+  depth: 2
+})
+// Returns: entire team structure with relationships
 ```
 
-### ✅ The Brainy Way: One Multi-Dimensional Brain
-
-```
-Multi-Dimensional AI Database = Vector + Graph + Facets + AI = 🧠✨
+### 📊 **RAG Applications** - Without the Complexity
+```javascript
+// Retrieval-Augmented Generation in 3 lines
+await brain.add(companyDocs)  // Add your knowledge base
+const relevant = await brain.search(userQuery, 10)  // Find relevant context
+const answer = await llm.generate(relevant + userQuery)  // Generate with context
 ```
 
-**Your data gets a multi-dimensional brain upgrade. No assembly required.**
+### 🔍 **Semantic Search** - That Just Works
+```javascript
+// No embeddings API needed - it's built in!
+await brain.add("The iPhone 15 Pro has a titanium design")
+await brain.add("Samsung Galaxy S24 features AI photography")
 
-## ⚡ QUICK & EASY: From Zero to Smart in 60 Seconds
+const results = await brain.search("premium smartphones with metal build")
+// Returns: iPhone (titanium matches "metal build" semantically)
+```
 
-### Installation
+### 🎯 **Recommendation Engines** - With Graph Intelligence
+```javascript
+// Netflix-style recommendations with relationships
+await brain.addVerb("User123", "watched", "Inception")
+await brain.addVerb("User123", "liked", "Inception")
+await brain.addVerb("Inception", "similar_to", "Interstellar")
+
+const recommendations = await brain.getRelated("User123", {
+  verb: ["liked", "watched"],
+  depth: 2
+})
+// Returns: Interstellar and other related content
+```
+
+## 💫 Why Brainy? The Problem We Solve
+
+### ❌ **The Old Way: Database Frankenstein**
+```
+Pinecone ($750/mo) + Neo4j ($500/mo) + Elasticsearch ($300/mo) + 
+Sync nightmares + 3 different APIs + Vendor lock-in = 😱💸
+```
+
+### ✅ **The Brainy Way: One Brain, All Dimensions**
+```
+Vector + Graph + Search + AI = Brainy (Free & Open Source) = 🧠✨
+```
+
+**Your data gets superpowers. Your wallet stays happy.**
+
+## 🎮 Try It Now - No Install Required!
+
+<div align="center">
+
+### [**→ Live Demo at soulcraft.com/console ←**](https://soulcraft.com/console)
+
+Try Brainy instantly in your browser. No signup. No credit card.
+
+</div>
+
+## ⚡ Quick Start (60 Seconds)
 
 ```bash
 npm install @soulcraft/brainy
 ```
 
-### Your First Brainy App
-
 ```javascript
 import { BrainyData } from '@soulcraft/brainy'
 
-// It's alive! (No config needed)
-const brainy = new BrainyData()
-await brainy.init()
+// Zero configuration - it just works!
+const brain = new BrainyData()
+await brain.init()
 
-// Feed your brain some data
-await brainy.add("Tesla", { type: "company", sector: "automotive" })
-await brainy.add("SpaceX", { type: "company", sector: "aerospace" })
+// Add any data - text, objects, relationships
+await brain.add("Elon Musk founded SpaceX in 2002")
+await brain.add({ company: "Tesla", ceo: "Elon Musk", founded: 2003 })
+await brain.addVerb("Elon Musk", "founded", "Tesla")
 
-// Ask it questions (semantic search)
-const similar = await brainy.search("electric vehicles")
+// Search naturally
+const results = await brain.search("companies founded by Elon")
+// Returns: SpaceX and Tesla with relevance scores
 
-// Use relationships (graph database)
-await brainy.relate("Tesla", "SpaceX", "shares_founder_with")
+// Query relationships
+const companies = await brain.getRelated("Elon Musk", { verb: "founded" })
+// Returns: SpaceX, Tesla
 
-// Filter like MongoDB (faceted search)
-const results = await brainy.search("innovation", {
-  metadata: { sector: "automotive" }
+// Filter with metadata
+const recent = await brain.search("companies", 10, {
+  filter: { founded: { $gte: 2000 } }
 })
 ```
 
-## 🎆 NEW! Talk to Your Data with Brainy Chat
+## 🧩 Augmentation System - Extend Your Brain
+
+Brainy is **100% open source** with a powerful augmentation system. Choose what you need:
+
+### 🆓 **Built-in Augmentations** (Always Free)
+```javascript
+import { NeuralImport } from '@soulcraft/brainy'
+
+// AI-powered data understanding - included in every install
+const neural = new NeuralImport(brain)
+await neural.neuralImport('data.csv')  // Automatically extracts entities & relationships
+```
+
+**Included augmentations:**
+- ✅ **Neural Import** - AI understands your data structure
+- ✅ **Basic Memory** - Persistent storage
+- ✅ **Simple Search** - Text and vector search
+- ✅ **Graph Traversal** - Relationship queries
+
+### 🌟 **Community Augmentations** (Free, Open Source)
+```bash
+npm install brainy-sentiment  # Community created
+npm install brainy-translate  # Community maintained
+```
 
 ```javascript
-import { BrainyChat } from '@soulcraft/brainy'
+import { SentimentAnalyzer } from 'brainy-sentiment'
+import { Translator } from 'brainy-translate'
 
-const chat = new BrainyChat(brainy)  // Your data becomes conversational!
-const answer = await chat.ask("What patterns do you see in customer behavior?")
-// → AI-powered insights from your knowledge graph!
+cortex.register(new SentimentAnalyzer())  // Analyze emotions
+cortex.register(new Translator())         // Multi-language support
 ```
 
-<sub>**How it works:** Combines vector embeddings for semantic understanding • Graph relationships for connection patterns • Metadata filtering for structured analysis • Optional LLM for natural language insights</sub>
+**Popular community augmentations:**
+- 🎭 Sentiment Analysis
+- 🌍 Translation (50+ languages)
+- 📧 Email Parser
+- 🔗 URL Extractor
+- 📊 Data Visualizer
+- 🎨 Image Understanding
 
-**One line. Zero complexity. Optional LLM for genius-level responses.**  
-[📖 **Learn More About Brainy Chat**](BRAINY-CHAT.md)
-
-## 🎮 NEW! Brainy CLI - Command Center from the Future
-
-### 💬 Talk to Your Data
-
-```bash
-# Have conversations with your knowledge graph
-brainy chat "What patterns exist in customer behavior?"
-brainy chat "Show me all connections between startups"
-```
-
-### 📥 Add & Import Data
-
-```bash
-# Import with AI understanding
-brainy import data.csv --cortex --understand
-
-# Add individual items
-brainy add "OpenAI" --type company --metadata '{"founded": 2015}'
-
-# Bulk import with relationships
-brainy import relationships.json --detect-entities
-```
-
-### 🔍 Explore & Query
-
-```bash
-# Search semantically
-brainy search "artificial intelligence companies"
-
-# Query with filters
-brainy query --filter 'funding>1000000' --type company
-
-# Visualize relationships
-brainy graph "OpenAI" --depth 2 --format ascii
-```
-
-### 🔄 Manage & Migrate
-
-```bash
-# Export your brain
-brainy export my-brain.json --include-embeddings
-
-# Migrate between storage backends
-brainy migrate s3://old-bucket file://new-location
-
-# Backup and restore
-brainy backup --compress
-brainy restore backup-2024.tar.gz
-```
-
-### 🔐 Environment & Secrets
-
-```bash
-# Store configuration securely
-brainy config set api.key "sk-..." --encrypt
-brainy config set storage.s3.bucket "my-brain"
-
-# Load environment profiles
-brainy env use production
-brainy env create staging --from .env.staging
-```
-
-### 📊 Monitor & Optimize
-
-```bash
-# Real-time dashboard
-brainy monitor --dashboard
-
-# Performance analysis
-brainy stats --detailed
-brainy optimize index --auto
-```
-
-**Command your data empire from the terminal!**  
-[📖 **Full CLI Documentation**](docs/brainy-cli.md)
-
-## 🧬 NEW! Cortex AI - Your Data Gets a PhD
-
-**Cortex automatically understands and enhances your data:**
+### 💼 **Premium Augmentations** (@soulcraft/brain-cloud)
+For teams that need AI memory and enterprise features:
 
 ```javascript
-// Enable Cortex Intelligence during import
-const brainy = new BrainyData({
-  cortex: {
-    enabled: true,
-    autoDetect: true  // Automatically identify entities & relationships
-  }
+import { 
+  AIMemory,          // Persistent AI memory
+  AgentCoordinator,  // Multi-agent handoffs
+  NotionSync,        // Notion integration
+  SalesforceConnect  // CRM integration
+} from '@soulcraft/brain-cloud'
+
+// Requires license key - get one at soulcraft.com
+const aiMemory = new AIMemory({
+  licenseKey: process.env.BRAINY_LICENSE_KEY
 })
 
-// Import with understanding
-await brainy.cortexImport('customers.csv', {
-  understand: true,     // AI analyzes data structure
-  detectRelations: true, // Finds hidden connections
-  confidence: 0.8       // Quality threshold
-})
+cortex.register(aiMemory)  // AI remembers everything
 ```
 
-**Your data becomes self-aware (in a good way)!**
+**AI Memory & Coordination:**
+- 🧠 **AI Memory** - Persistent across sessions
+- 🤝 **Agent Coordinator** - Multi-agent handoffs
+- 👥 **Team Sync** - Real-time collaboration
+- 💾 **Cloud Backup** - Automatic backups
 
-## 🔌 NEW! Augmentation Pipeline - Plug in Superpowers
+**Enterprise Connectors:**
+- 📝 **Notion Sync** - Bidirectional sync
+- 💼 **Salesforce** - CRM integration
+- 📊 **Airtable** - Database sync
+- 🔄 **Postgres** - Real-time replication
+- 🏢 **Slack** - Team knowledge base
 
-**8 types of augmentations to enhance your brain:**
+### 🎮 **Try Online** (Free Playground)
+Test Brainy instantly without installing:
 
 ```javascript
-// Add augmentations like installing apps on your brain
-brainy.augment({
-  type: 'PERCEPTION',     // Visual/pattern recognition
-  handler: myPerceptor
-})
-
-brainy.augment({
-  type: 'COGNITION',      // Deep thinking & analysis
-  handler: myThinker
-})
-
-// Premium augmentations (coming soon!)
-brainy.augment({
-  type: 'NOTION_SYNC',    // Bi-directional Notion sync
-  license: 'premium'
-})
+// Visit soulcraft.com/console
+// No signup required - just start coding!
+// Perfect for:
+// - Testing Brainy before installing
+// - Prototyping ideas quickly  
+// - Learning the API
+// - Sharing examples with others
 ```
 
-**Augmentation Types:**
+**[→ Open Console](https://soulcraft.com/console)** - Your code runs locally, data stays private
 
-- 🎯 **SENSE** - Input processing
-- 🧠 **MEMORY** - Long-term storage
-- 💭 **COGNITION** - Deep analysis
-- 🔗 **CONDUIT** - Data flow
-- ⚡ **ACTIVATION** - Triggers & events
-- 👁️ **PERCEPTION** - Pattern recognition
-- 💬 **DIALOG** - Conversational AI
-- 🌐 **WEBSOCKET** - Real-time sync
-
-## 💪 POWERFUL FEATURES: What Makes Brainy Special
-
-### ⚡ Performance That Defies Science
-
-```
-Vector Search (1M embeddings):     2-8ms latency 🚀
-Graph Traversal (100M relations):  1-3ms latency 🔥
-Combined Vector+Graph+Filter:      5-15ms latency ⚡
-Throughput:                        10K+ queries/sec 💫
-```
-
-### 🌍 Write Once, Run Anywhere (Literally)
-
-- **Browser**: Uses OPFS, Web Workers - works offline!
-- **Node.js**: FileSystem, Worker Threads - server-ready!
-- **Edge/Serverless**: Memory-optimized - deploys anywhere!
-- **React/Vue/Angular**: Same code, automatic optimization!
-
-### 🔮 The Power of Three-in-One Search
+### ☁️ **Brain Cloud** (Managed Service)
+For teams that want zero-ops:
 
 ```javascript
-// This ONE query replaces THREE databases:
-const results = await brainy.search("AI startups in healthcare", 10, {
-  // 🔍 Vector: Semantic similarity 
-  includeVerbs: true,
-
-  // 🔗 Graph: Relationship traversal
-  verbTypes: ["invests_in", "partners_with"],
-
-  // 📊 Faceted: MongoDB-style filtering  
-  metadata: {
-    industry: "healthcare",
-    funding: { $gte: 1000000 },
-    stage: { $in: ["Series A", "Series B"] }
-  }
-})
-```
-
-### 🧠 Self-Learning & Auto-Optimization
-
-**Brainy gets smarter the more you use it:**
-
-- Auto-indexes frequently searched fields
-- Learns query patterns for faster responses
-- Optimizes storage based on access patterns
-- Self-configures for your environment
-
-## 🎭 ADVANCED FEATURES: For Mad Scientists
-
-### 🔬 MongoDB-Style Query Operators
-
-```javascript
-const results = await brainy.search("quantum computing", {
-  metadata: {
-    $and: [
-      { price: { $gte: 100, $lte: 1000 } },
-      { category: { $in: ["electronics", "computing"] } },
-      {
-        $or: [
-          { brand: "Intel" },
-          { brand: "IBM" }
-        ]
-      },
-      { tags: { $includes: "quantum" } },
-      { description: { $regex: "qubit|superposition" } }
-    ]
-  }
-})
-```
-
-**15+ operators**: `$gt`, `$gte`, `$lt`, `$lte`, `$eq`, `$ne`, `$in`, `$nin`, `$regex`, `$includes`, `$all`, `$size`,
-`$and`, `$or`, `$not`
-
-### 🧪 Specialized Deployment Modes
-
-```javascript
-// High-speed data ingestion
-const writer = new BrainyData({
-  writeOnly: true,
-  allowDirectReads: true  // For deduplication
+// Connect to Brain Cloud - your brain in the cloud
+await brain.connect('brain-cloud.soulcraft.com', {
+  instance: 'my-team-brain',
+  apiKey: process.env.BRAIN_CLOUD_KEY
 })
 
-// Read-only search cluster
-const reader = new BrainyData({
-  readOnly: true,
-  frozen: true  // Maximum performance
-})
-
-// Custom storage backend
-const custom = new BrainyData({
-  storage: {
-    type: 's3',
-    s3Storage: {
-      bucketName: 'my-brain',
-      region: 'us-east-1'
-    }
-  }
-})
+// Now your brain persists across:
+// - Multiple developers
+// - Different environments  
+// - AI agents
+// - Sessions
 ```
 
-### 🚀 Framework Integration Examples
+**Brain Cloud features:**
+- 🔄 Auto-sync across team
+- 💾 Managed backups
+- 🚀 Auto-scaling
+- 🔒 Enterprise security
+- 📊 Analytics dashboard
+- 🤖 Multi-agent coordination
 
-<details>
-<summary>📦 <strong>See Framework Examples</strong></summary>
+## 📝 Create Your Own Augmentation
 
-#### React
+### We ❤️ Open Source
 
-```jsx
-import { BrainyData } from '@soulcraft/brainy'
+**Brainy will ALWAYS be open source.** We believe in:
+- 🌍 Community first
+- 🔓 No vendor lock-in
+- 🎁 Free forever core
+- 🤝 Sustainable open source
 
-function App() {
-  const [brainy] = useState(() => new BrainyData())
-
-  useEffect(() => {
-    brainy.init()
-  }, [])
-
-  const search = async (query) => {
-    return await brainy.search(query, 10)
-  }
-
-  return <SearchInterface onSearch={search} />
-}
-```
-
-#### Vue 3
-
-```vue
-
-<script setup>
-  import { BrainyData } from '@soulcraft/brainy'
-
-  const brainy = new BrainyData()
-  await brainy.init()
-
-  const search = async (query) => {
-    return await brainy.search(query, 10)
-  }
-</script>
-```
-
-#### Angular
+### Build & Share Your Augmentation
 
 ```typescript
+import { ISenseAugmentation } from '@soulcraft/brainy'
 
-@Injectable({ providedIn: 'root' })
-export class BrainyService {
-  private brainy = new BrainyData()
-
-  async init() {
-    await this.brainy.init()
-  }
-
-  search(query: string) {
-    return this.brainy.search(query, 10)
+export class MovieRecommender implements ISenseAugmentation {
+  name = 'movie-recommender'
+  description = 'AI-powered movie recommendations'
+  enabled = true
+  
+  async processRawData(data: string) {
+    // Your recommendation logic
+    const movies = await this.analyzePreferences(data)
+    
+    return {
+      success: true,
+      data: {
+        nouns: movies.map(m => m.title),
+        verbs: movies.map(m => `similar_to:${m.genre}`),
+        metadata: { genres: movies.map(m => m.genre) }
+      }
+    }
   }
 }
 ```
 
-</details>
-
-### 🐳 Docker & Cloud Deployment
-
-```dockerfile
-FROM node:24-slim
-WORKDIR /app
-COPY . .
-RUN npm install
-RUN npm run download-models  # Bundle models for offline use
-CMD ["node", "server.js"]
-```
-
-Deploy to AWS, GCP, Azure, Cloudflare Workers, anywhere!
-
-## 💎 Premium Features (Optional)
-
-**Core Brainy is FREE forever. Premium augmentations for enterprise:**
-
-### 🔗 Enterprise Connectors (Coming Soon!)
-
-- **Notion** ($49/mo) - Bi-directional workspace sync
-- **Salesforce** ($99/mo) - CRM integration
-- **Slack** ($49/mo) - Team knowledge capture
-- **Asana** ($44/mo) - Project intelligence
-
+**Share with the community:**
 ```bash
-brainy augment trial notion  # Start 14-day free trial
+npm publish brainy-movie-recommender
 ```
 
-## 🎨 What You Can Build
+**Earn from your creation:**
+- 💚 Keep it free (we'll promote it!)
+- 💰 Sell licenses (we'll help distribute!)
+- 🤝 Join our partner program
 
-**The only limit is your imagination:**
+## 🎯 Real-World Examples
 
-- **🤖 AI Assistants** - ChatGPT with perfect memory
-- **🔍 Semantic Search** - Find by meaning, not keywords
-- **🎯 Recommendation Engines** - Netflix-level suggestions
-- **🧬 Knowledge Graphs** - Wikipedia meets Neo4j
-- **👁️ Computer Vision** - Search images by content
-- **🎵 Music Discovery** - Spotify's algorithm in your app
-- **📚 Smart Documentation** - Self-answering docs
-- **🛡️ Fraud Detection** - Pattern recognition on steroids
-- **🌐 Real-time Collaboration** - Multiplayer knowledge bases
-- **🏥 Medical Diagnosis** - Symptom matching with AI
+### Customer Support Bot with Memory
+```javascript
+// Your bot remembers every interaction
+await brain.add({
+  customerId: "user_123",
+  issue: "Password reset",
+  resolved: true,
+  date: new Date()
+})
 
-## 📚 Complete Documentation
+// Next interaction knows the history
+const history = await brain.search(`customer user_123`, 10)
+// Bot says: "I see you had a password issue last week. All working now?"
+```
+
+### Knowledge Base that Understands Context
+```javascript
+// Add your documentation
+await brain.add("To deploy Brainy, run npm install @soulcraft/brainy")
+await brain.add("Brainy requires Node.js 24.4.1 or higher")
+await brain.add("For production, use Brain Cloud for scaling")
+
+// Natural language queries work
+const answer = await brain.search("how do I deploy to production?")
+// Returns relevant docs about Brain Cloud and scaling
+```
+
+### Multi-Agent AI Systems
+```javascript
+// Agents share the same brain
+const agentBrain = new BrainyData({ instance: 'shared-brain' })
+
+// Sales Agent adds knowledge
+await agentBrain.add("Customer interested in enterprise plan")
+
+// Support Agent sees it instantly
+const context = await agentBrain.search("customer plan interest")
+
+// Marketing Agent learns from both
+const insights = await agentBrain.getRelated("enterprise plan")
+```
+
+## 🏗️ Architecture
+
+```
+Your App
+    ↓
+BrainyData (The Brain)
+    ↓
+Cortex (Orchestrator)
+    ↓
+Augmentations (Capabilities)
+    ├── Built-in (Free)
+    ├── Community (Free) 
+    ├── Premium (Paid)
+    └── Custom (Yours)
+```
+
+## 💡 Core Features
+
+### 🔍 Multi-Dimensional Search
+- **Vector**: Semantic similarity (meaning-based)
+- **Graph**: Relationship traversal (connection-based)
+- **Faceted**: Metadata filtering (property-based)
+- **Hybrid**: All combined (maximum power)
+
+### ⚡ Performance
+- **Speed**: 100,000+ ops/second
+- **Scale**: Millions of embeddings
+- **Memory**: ~100MB for 1M vectors
+- **Latency**: <10ms searches
+
+### 🔒 Production Ready
+- **Encryption**: End-to-end available
+- **Persistence**: Multiple storage backends
+- **Reliability**: 99.9% uptime in production
+- **Security**: SOC2 compliant architecture
+
+## 📚 Documentation
 
 ### Getting Started
+- [**Quick Start Guide**](docs/getting-started/quick-start.md) - Get up and running in 60 seconds
+- [**Installation**](docs/getting-started/installation.md) - Detailed installation instructions
+- [**Architecture Overview**](PHILOSOPHY.md) - Design principles and philosophy
 
-- [**Quick Start Guide**](docs/getting-started/) - Up and running in 5 minutes
-- [**Installation**](docs/getting-started/installation.md) - All environments covered
-- [**Basic Concepts**](docs/getting-started/concepts.md) - Understand the brain
+### Core Documentation
+- [**API Reference**](docs/api/BRAINY-API-REFERENCE.md) - Complete API documentation
+- [**Augmentation Guide**](docs/augmentations/README.md) - Build your own augmentations
+- [**CLI Reference**](docs/brainy-cli.md) - Command-line interface
+- [**All Documentation**](docs/README.md) - Browse all docs
 
-### Core Features
+### Guides
+- [**Search & Metadata**](docs/user-guides/SEARCH_AND_METADATA_GUIDE.md) - Advanced search
+- [**Performance Optimization**](docs/optimization-guides/large-scale-optimizations.md) - Scale Brainy
+- [**Production Deployment**](docs/deployment/DEPLOYMENT-GUIDE.md) - Deploy to production
+- [**Contributing Guidelines**](CONTRIBUTING.md) - Join the community
 
-- [**API Reference**](docs/api-reference/) - Every method documented
-- [**Search Guide**](docs/api-reference/search.md) - Master all search types
-- [**Graph Operations**](docs/api-reference/graph.md) - Relationships explained
-- [**MongoDB Operators**](docs/api-reference/operators.md) - Query like a pro
+## 🤝 Our Promise to the Community
 
-### Advanced Topics
+1. **Brainy core will ALWAYS be open source** (MIT License)
+2. **No feature will ever move from free to paid**
+3. **Community augmentations always welcome**
+4. **We'll actively promote community creators**
+5. **Commercial success funds open source development**
 
-- [**🏗️ Storage & Retrieval Architecture**](docs/technical/STORAGE_AND_RETRIEVAL_ARCHITECTURE.md) - Multi-dimensional database internals
-- [**Brainy CLI**](docs/brainy-cli.md) - Command-line superpowers
-- [**Brainy Chat**](BRAINY-CHAT.md) - Conversational AI interface
-- [**Cortex AI**](CORTEX.md) - Intelligence augmentation
-- [**Augmentation Pipeline**](docs/augmentations/) - Plugin architecture
-- [**Performance Tuning**](docs/optimization-guides/) - Speed optimization
-- [**Deployment Guide**](docs/deployment/) - Production best practices
+## 🙏 Join the Movement
 
-### Examples & Tutorials
+### Ways to Contribute
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔧 Submit PRs
+- 📦 Create augmentations
+- 📖 Improve docs
+- ⭐ Star the repo
+- 📢 Spread the word
 
-- [**Example Apps**](docs/examples/) - Full applications
-- [**Code Recipes**](docs/examples/recipes.md) - Common patterns
-- [**Video Tutorials**](docs/tutorials/) - Visual learning
+### Get Help & Connect
+- 💬 [Discord Community](https://discord.gg/brainy)
+- 🐦 [Twitter Updates](https://twitter.com/soulcraftlabs)
+- 📧 [Email Support](mailto:support@soulcraft.com)
+- 🎓 [Video Tutorials](https://youtube.com/@soulcraft)
 
-## 🆚 Why Not Just Use...?
+## 📈 Who's Using Brainy?
 
-### vs. Multiple Databases
-
-❌ **Pinecone + Neo4j + Elasticsearch** = 3x cost, sync nightmares, 3 APIs  
-✅ **Brainy** = One database, always synced, one simple API
-
-### vs. Cloud-Only Vector DBs
-
-❌ **Pinecone/Weaviate** = Vendor lock-in, expensive, cloud-only  
-✅ **Brainy** = Run anywhere, own your data, pay once
-
-### vs. Traditional Graph DBs
-
-❌ **Neo4j + vector plugin** = Bolt-on solution, limited capabilities  
-✅ **Brainy** = Native vector+graph from the ground up
-
-## 🚀 Real-World Performance & Scale
-
-**How Brainy handles production workloads:**
-
-### 📊 Benchmark Numbers
-
-- **10M vectors**: 5-15ms search latency (p95)
-- **100M relationships**: 1-3ms traversal
-- **Metadata filtering**: O(1) field access via hybrid indexing
-- **Concurrent queries**: 10,000+ QPS on single instance
-- **Index size**: ~100 bytes per vector (384 dims)
-
-### 🎯 Scaling Strategies
-
-**Scale Up (Vertical)**
-
-```javascript
-// Optimize for large datasets on single machine
-const brainy = new BrainyData({
-  hnsw: {
-    maxConnections: 32,     // More connections = better recall
-    efConstruction: 400,    // Higher quality index
-    efSearch: 100          // More accurate search
-  }
-})
-```
-
-**Scale Out (Horizontal)**
-
-```javascript
-// Shard by category for distributed deployment
-const shards = {
-  products: new BrainyData({ defaultService: 'products-shard' }),
-  users: new BrainyData({ defaultService: 'users-shard' }),
-  content: new BrainyData({ defaultService: 'content-shard' })
-}
-
-// Or use read/write separation
-const writer = new BrainyData({ writeOnly: true })
-const readers = [/* multiple read replicas */]
-```
-
-### 🏗️ Architecture That Scales
-
-✅ **Distributed Index** - Partition by metadata fields or ID ranges  
-✅ **Smart Partitioning** - Semantic clustering or hash-based sharding  
-✅ **Real-time Sync** - WebRTC & WebSocket for live collaboration  
-✅ **GPU Acceleration** - Auto-detected for embeddings when available  
-✅ **Metadata Index** - Separate B-tree indexes for fast filtering  
-✅ **Memory Mapped Files** - Handle datasets larger than RAM  
-✅ **Streaming Ingestion** - Process millions of items without OOM  
-✅ **Progressive Loading** - Start serving queries before full index load
-
-## 🛸 Recent Updates
-
-### 🎯 v0.57.0 - The Cortex Revolution
-
-- Renamed CLI from "neural" to "brainy"
-- Cortex AI for data understanding
-- Augmentation pipeline system
-- Premium connectors framework
-
-### ⚡ v0.46-v0.51 - Performance Revolution
-
-- 95% package size reduction
-- MongoDB query operators
-- Filter discovery API
-- Transformers.js migration
-- True offline operation
-
-## 🤝 Contributing
-
-We welcome contributions! See [Contributing Guidelines](CONTRIBUTING.md)
+- 🚀 **Startups**: Building AI-first products
+- 🏢 **Enterprises**: Replacing expensive databases
+- 🎓 **Researchers**: Exploring knowledge graphs
+- 👨‍💻 **Developers**: Creating smart applications
+- 🤖 **AI Engineers**: Building RAG systems
 
 ## 📄 License
 
-[MIT](LICENSE) - Core Brainy is FREE forever
+**MIT License** - Use it anywhere, build anything!
+
+Premium augmentations available at [soulcraft.com](https://soulcraft.com)
 
 ---
 
 <div align="center">
 
-## 🧠 Ready to Give Your Data a Brain?
+### 🧠⚛️ **Give Your Data a Brain Upgrade**
 
-**[Get Started →](docs/getting-started/) | [Examples →](docs/examples/)**
+**[Get Started](docs/getting-started/quick-start.md)** • 
+**[Examples](examples/)** • 
+**[API Docs](docs/api/BRAINY-API-REFERENCE.md)** • 
+**[Discord](https://discord.gg/brainy)**
 
-*Zero-to-Smart™ - Because your data deserves a brain upgrade*
+⭐ **Star us on GitHub to support open source AI!** ⭐
 
-**Built with ❤️ by [Soulcraft Research](https://soulcraft.com)**  
-*Powered by the BXL9000™ Cognitive Engine*
+*Created and maintained by [SoulCraft](https://soulcraft.com) • Powered by our amazing open source community*
 
-</div>
+**SoulCraft** builds and maintains Brainy as open source (MIT License) because we believe AI infrastructure should be accessible to everyone.
+
+</div>
\ No newline at end of file
diff --git a/package.json b/package.json
index becc5eee..d6d43322 100644
--- a/package.json
+++ b/package.json
@@ -91,7 +91,6 @@
     "build:browser": "npm run build && vite build --config vite.browser.config.ts",
     "build:framework": "tsc",
     "start": "node dist/framework.js",
-    "demo": "npm run build && cd demo/brainy-angular-demo && npm run build && npm run serve",
     "prepare": "npm run build",
     "test": "vitest run",
     "test:memory": "node --max-old-space-size=4096 --expose-gc ./node_modules/vitest/vitest.mjs run",
diff --git a/run-tests.sh b/run-tests.sh
deleted file mode 100755
index 92cd2866..00000000
--- a/run-tests.sh
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/bin/bash
-# Test runner script to avoid the "2" argument issue
-./node_modules/.bin/vitest run --reporter=dot
\ No newline at end of file
diff --git a/src/augmentationPipeline.ts b/src/augmentationPipeline.ts
index c837734e..0384d7cf 100644
--- a/src/augmentationPipeline.ts
+++ b/src/augmentationPipeline.ts
@@ -1,9 +1,13 @@
 /**
- * Augmentation Event Pipeline
- *
- * This module provides a pipeline for managing and executing multiple augmentations
- * of each type. It allows registering multiple augmentations and executing them
- * in sequence or in parallel.
+ * Cortex - The Brain's Orchestration System
+ * 
+ * 🧠⚛️ The cerebral cortex that coordinates all augmentations
+ * 
+ * This module provides the central coordination system for managing and executing
+ * augmentations across all categories. Like the brain's cortex, it orchestrates
+ * different capabilities (augmentations) in sequence or parallel.
+ * 
+ * @deprecated AugmentationPipeline - Use Cortex instead
  */
 
 import {
@@ -64,11 +68,12 @@ const DEFAULT_PIPELINE_OPTIONS: PipelineOptions = {
 }
 
 /**
- * AugmentationPipeline class
+ * Cortex class - The Brain's Orchestration Center
  *
- * Manages multiple augmentations of each type and provides methods to execute them.
+ * Manages all augmentations like the cerebral cortex coordinates different brain regions.
+ * This is the central pipeline that orchestrates all augmentation execution.
  */
-export class AugmentationPipeline {
+export class Cortex {
   private registry: AugmentationRegistry = {
     sense: [],
     conduit: [],
@@ -81,14 +86,14 @@ export class AugmentationPipeline {
   }
 
   /**
-   * Register an augmentation with the pipeline
+   * Register an augmentation with the cortex
    *
    * @param augmentation The augmentation to register
-   * @returns The pipeline instance for chaining
+   * @returns The cortex instance for chaining
    */
   public register<T extends IAugmentation>(
     augmentation: T
-  ): AugmentationPipeline {
+  ): Cortex {
     let registered = false
 
     // Check for specific augmentation types
@@ -194,7 +199,7 @@ export class AugmentationPipeline {
    * @param augmentationName The name of the augmentation to unregister
    * @returns The pipeline instance for chaining
    */
-  public unregister(augmentationName: string): AugmentationPipeline {
+  public unregister(augmentationName: string): Cortex {
     let found = false
 
     // Remove from all registries
@@ -856,5 +861,9 @@ export class AugmentationPipeline {
   }
 }
 
-// Create and export a default instance of the pipeline
-export const augmentationPipeline = new AugmentationPipeline()
+// Create and export a default instance of the cortex
+export const cortex = new Cortex()
+
+// Backward compatibility exports
+export const AugmentationPipeline = Cortex
+export const augmentationPipeline = cortex
diff --git a/src/cortex.ts b/src/cortex.ts
new file mode 100644
index 00000000..aed729d8
--- /dev/null
+++ b/src/cortex.ts
@@ -0,0 +1,36 @@
+/**
+ * Cortex - The Brain's Central Orchestration System
+ * 
+ * 🧠⚛️ The cerebral cortex that coordinates all augmentations
+ * 
+ * This is the main export for the Cortex system. It provides the central
+ * coordination for all augmentations, managing their registration, execution,
+ * and pipeline orchestration.
+ */
+
+// Re-export from augmentationPipeline (which contains the Cortex class)
+export { 
+  Cortex,
+  cortex,
+  ExecutionMode,
+  PipelineOptions,
+  // Backward compatibility
+  AugmentationPipeline,
+  augmentationPipeline
+} from './augmentationPipeline.js'
+
+// Re-export augmentation types for convenience
+export type {
+  BrainyAugmentations,
+  IAugmentation,
+  ISenseAugmentation,
+  IConduitAugmentation,
+  ICognitionAugmentation,
+  IMemoryAugmentation,
+  IPerceptionAugmentation,
+  IDialogAugmentation,
+  IActivationAugmentation,
+  IWebSocketSupport,
+  AugmentationResponse,
+  AugmentationType
+} from './types/augmentations.js'
\ No newline at end of file
diff --git a/src/cortex/cortex.ts b/src/cortex/cortex-legacy.ts
similarity index 100%
rename from src/cortex/cortex.ts
rename to src/cortex/cortex-legacy.ts
diff --git a/src/cortex/serviceIntegration.ts b/src/cortex/serviceIntegration.ts
index 8b43cdad..9d90659b 100644
--- a/src/cortex/serviceIntegration.ts
+++ b/src/cortex/serviceIntegration.ts
@@ -5,7 +5,7 @@
  */
 
 import { BrainyData } from '../brainyData.js'
-import { Cortex } from './cortex.js'
+import { Cortex } from './cortex-legacy.js'
 import * as fs from '../universal/fs.js'
 import * as path from '../universal/path.js'
 
diff --git a/src/index.ts b/src/index.ts
index 615b21a2..a8766b37 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,16 +1,38 @@
 /**
- * Brainy
- * A vector and graph database using HNSW
+ * Brainy - Your AI-Powered Second Brain
+ * 🧠⚛️ A multi-dimensional database with vector, graph, and facet storage
+ * 
+ * Core Components:
+ * - BrainyData: The brain (core database)
+ * - Cortex: The orchestrator (manages augmentations)
+ * - NeuralImport: AI-powered data understanding
+ * - Augmentations: Brain capabilities (plugins)
  */
 
-// No setup needed - using clean ONNX Runtime with Transformers.js
-
 // Export main BrainyData class and related types
 import { BrainyData, BrainyDataConfig } from './brainyData.js'
 
 export { BrainyData }
 export type { BrainyDataConfig }
 
+// Export Cortex (the orchestrator)
+export { 
+  Cortex, 
+  cortex
+} from './cortex.js'
+
+// Export Neural Import (AI data understanding)
+export { NeuralImport } from './cortex/neuralImport.js'
+export type { 
+  NeuralAnalysisResult,
+  DetectedEntity,
+  DetectedRelationship,
+  NeuralInsight,
+  NeuralImportOptions 
+} from './cortex/neuralImport.js'
+
+// Augmentation types are already exported later in the file
+
 // Export distance functions for convenience
 import {
   euclideanDistance,