@soulcraft/brainy 4.0.0 → 4.0.2

package/README.md

@@ -9,676 +9,619 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
-**🧠 Brainy - The Knowledge Operating System**
+## The Knowledge Operating System
 
-**The world's first Knowledge Operating System** where every piece of knowledge - files, concepts, entities, ideas - exists as living information that understands itself, evolves over time, and connects to everything related.
+**Every piece of knowledge in your application — living, connected, and intelligent.**
 
-**Why Brainy Changes Everything**: Traditional systems trap knowledge in files or database rows. Brainy liberates it. Your characters exist across stories. Your concepts span projects. Your APIs remember their evolution. Every piece of knowledge - whether it's code, prose, or pure ideas - lives, breathes, and connects in a unified intelligence layer where everything understands its meaning, remembers its history, and relates to everything else.
+Stop fighting with vector databases, graph databases, and document stores. Stop stitching together Pinecone + Neo4j + MongoDB. **Brainy does all three, in one elegant API, from prototype to planet-scale.**
 
-Built on revolutionary **Triple Intelligence™** that unifies vector similarity, graph relationships, and document filtering in one magical API. **Framework-first design.** Zero configuration. O(log n) performance, <10ms search latency. **Production-ready for billion-scale deployments.**
+```javascript
+const brain = new Brainy()
+await brain.init()
+
+// That's it. You now have semantic search, graph relationships,
+// and document filtering. Zero configuration. Just works.
+```
+
+**Built by developers who were tired of:**
+- Spending weeks configuring embeddings, indexes, and schemas
+- Choosing between vector similarity OR graph relationships OR metadata filtering
+- Rewriting everything when you need to scale from 1,000 to 1,000,000,000 entities
+
+**Brainy makes the impossible simple: All three paradigms. One API. Any scale.**
 
 ---
 
-## 🎉 NEW in v4.0.0 - Enterprise-Scale Cost Optimization
+## See It In Action
 
-**Major Release: Production cost optimization and enterprise-scale features**
+**30 seconds to understand why Brainy is different:**
 
-### 💰 **Up to 96% Storage Cost Savings**
+```javascript
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
 
-Automatic cloud storage lifecycle management for **AWS S3**, **Google Cloud Storage**, and **Azure Blob Storage**:
+const brain = new Brainy()
+await brain.init()
 
-- **GCS Autoclass**: Fully automatic tier optimization (94% savings!)
-- **AWS Intelligent-Tiering**: Smart archival with instant retrieval
-- **Azure Lifecycle Policies**: Automatic tier transitions
-- **Cost Impact**: $138,000/year → $5,940/year @ 500TB scale
+// Add knowledge with context
+const reactId = await brain.add({
+    data: "React is a JavaScript library for building user interfaces",
+    type: NounType.Concept,
+    metadata: { category: "frontend", year: 2013 }
+})
 
-### ⚡ **Performance at Billion-Scale**
+const nextId = await brain.add({
+    data: "Next.js framework for React with server-side rendering",
+    type: NounType.Concept,
+    metadata: { category: "framework", year: 2016 }
+})
 
-- **1000x faster batch deletions** (533 entities/sec vs 0.5/sec)
-- **60-80% FileSystem compression** with gzip
-- **OPFS quota monitoring** for browser storage
-- **Enhanced CLI** with 47 commands including 9 storage management tools
+// Create relationships
+await brain.relate({ from: nextId, to: reactId, type: VerbType.BuiltOn })
 
-### 🛡️ **Zero Breaking Changes**
+// NOW THE MAGIC: Query with natural language
+const results = await brain.find({
+    query: "modern frontend frameworks", // 🔍 Vector similarity
+    where: { year: { greaterThan: 2015 } },  // 📊 Document filtering
+    connected: { to: reactId, depth: 2 }  // 🕸️ Graph traversal
+})
 
-**100% backward compatible.** No migration required. All new features are opt-in.
+// ALL THREE PARADIGMS. ONE QUERY. 10ms response time.
+```
 
-**[📖 Read the full v4.0.0 Changelog →](CHANGELOG.md)** | **[Migration Guide →](docs/MIGRATION-V3-TO-V4.md)**
+**This is impossible with traditional databases.** Brainy makes it trivial.
 
 ---
 
-## 🎯 What Makes Brainy Revolutionary?
+## From Prototype to Planet Scale
 
-### 🧠 **Triple Intelligence™ - The Impossible Made Possible**
+**The same API. Zero rewrites. Any scale.**
 
-**The world's first to unify three database paradigms in ONE API:**
+### 👤 **Individual Developer** → Weekend Prototype
+
+```javascript
+// Zero configuration - starts in memory
+const brain = new Brainy()
+await brain.init()
+
+// Build your prototype in minutes
+// Change nothing when ready to scale
+```
+
+**Perfect for:** Hackathons, side projects, rapid prototyping, learning AI concepts
+
+### 👥 **Small Team** → Production MVP (Thousands of Entities)
 
-- **Vector Search** 🔍 Semantic similarity like Pinecone/Weaviate
-- **Graph Relationships** 🕸️ Navigate connections like Neo4j/ArangoDB
-- **Document Filtering** 📊 MongoDB-style queries with O(log n) performance
+```javascript
+// Add persistence - one line
+const brain = new Brainy({
+  storage: {
+    type: 'filesystem',
+    path: './brainy-data',
+    compression: true  // 60-80% space savings
+  }
+})
+```
 
-**Others make you choose.** Vector OR graph OR document. **Brainy does ALL THREE together.** This is what enables The Knowledge Operating System.
+**Perfect for:** Startups, MVPs, internal tools, team knowledge bases
+**Scale:** Thousands to hundreds of thousands of entities
+**Performance:** <5ms queries, sub-second imports
 
-### 🚀 **Zero Configuration - Just Works™**
+### 🏢 **Growing Company** → Multi-Million Entity Scale
 
 ```javascript
-import { Brainy } from '@soulcraft/brainy'
+// Scale to cloud - same API
+const brain = new Brainy({
+  storage: {
+    type: 's3',
+    s3Storage: {
+      bucketName: 'my-knowledge-base',
+      region: 'us-east-1'
+    }
+  },
+  hnsw: { typeAware: true }  // 87% memory reduction
+})
+```
 
-const brain = new Brainy()
-await brain.init()
+**Perfect for:** SaaS products, e-commerce, content platforms, enterprise apps
+**Scale:** Millions of entities
+**Performance:** <10ms queries, 12GB memory @ 10M entities
+**Features:** Auto-scaling, distributed storage, cost optimization (96% savings)
+
+### 🌍 **Enterprise / Planet Scale** → Billion+ Entities
+
+```javascript
+// Billion-scale - STILL the same API
+const brain = new Brainy({
+  storage: {
+    type: 'gcs',
+    gcsStorage: { bucketName: 'global-knowledge' }
+  },
+  hnsw: {
+    typeAware: true,
+    M: 32,
+    efConstruction: 400
+  }
+})
 
-// That's it! Auto-detects storage, optimizes memory, configures everything.
+// Enable intelligent archival
+await brain.storage.enableAutoclass({
+  terminalStorageClass: 'ARCHIVE'
+})
 ```
 
-No configuration files. No environment variables. No complex setup. **It just works.**
+**Perfect for:** Fortune 500, global platforms, research institutions, government
+**Scale:** Billions of entities (tested at 1B+)
+**Performance:** 18ms queries @ 1B scale, 50GB memory (87% reduction)
+**Cost:** $138k/year → $6k/year with intelligent tiering (96% savings)
+**Features:** Sharding, replication, monitoring, enterprise SLAs
+
+### 🎯 **The Point**
+
+**Start simple. Scale infinitely. Never rewrite.**
+
+Most systems force you to choose:
+- Simple but doesn't scale (SQLite, Redis)
+- Scales but complex (Kubernetes + 7 databases)
+
+**Brainy gives you both:** Starts simple as SQLite. Scales like Google.
+
+---
+
+## Why Brainy Is Revolutionary
+
+### 🧠 **Triple Intelligence™** — The Impossible Made Possible
+
+**The world's first to unify three database paradigms in ONE API:**
+
+| What You Get | Like Having | But Unified |
+|-------------|-------------|-------------|
+| 🔍 **Vector Search** | Pinecone, Weaviate | Find by meaning |
+| 🕸️ **Graph Relationships** | Neo4j, ArangoDB | Navigate connections |
+| 📊 **Document Filtering** | MongoDB, Elasticsearch | Query metadata |
+
+**Every other system makes you choose.** Brainy does all three together.
 
-### ⚡ **Production Performance at Any Scale**
+**Why this matters:** Your data isn't just vectors or just documents or just graphs. It's all three at once. A research paper is semantically similar to other papers (vector), written by an author (graph), and published in 2023 (document). **Brainy is the only system that understands this.**
 
-- **<10ms search** across millions of entities
-- **87% memory reduction** @ billion scale (384GB → 50GB)
-- **10x faster queries** with type-aware indexing
-- **99% storage cost savings** with intelligent archival
-- **Container-aware** memory allocation (Docker/K8s)
+### 🎯 **31 Noun Types × 40 Verb Types = Universal Protocol**
 
-### 🎯 **31 Noun Types × 40 Verb Types = Infinite Expressiveness**
+Model **any domain** with mathematical completeness:
 
-Model **ANY domain** with 1,240 base type combinations + unlimited metadata:
+```
+31 Nouns × 40 Verbs × ∞ Metadata = 1,240+ base combinations
+```
 
-- Healthcare: Patient → diagnoses → Condition
-- Finance: Account → transfers → Transaction
-- Manufacturing: Product → assembles → Component
-- Education: Student → completes → Course
-- **Your domain**: Your types + Your relationships = Your knowledge graph
+**Real-world expressiveness:**
+- Healthcare: `Patient → diagnoses → Condition`
+- Finance: `Account → transfers → Transaction`
+- Manufacturing: `Product → assembles → Component`
+- Education: `Student → completes → Course`
+- **YOUR domain** → Your types + relationships = Your knowledge graph
 
 [→ See the Mathematical Proof](docs/architecture/noun-verb-taxonomy.md)
 
+### ⚡ **Zero Configuration Philosophy**
+
+**We hate configuration files. So we eliminated them.**
+
+```javascript
+const brain = new Brainy()  // Auto-detects everything
+await brain.init()          // Optimizes for your environment
+```
+
+Brainy automatically:
+- Detects optimal storage (memory/filesystem/cloud)
+- Configures memory based on available RAM
+- Optimizes for containers (Docker/K8s)
+- Tunes indexes for your data patterns
+- Manages embedding models and caching
+
+**You write business logic. Brainy handles infrastructure.**
+
+---
+
+## What Can You Build?
+
+**If your app needs to remember, understand, or connect information — Brainy makes it trivial.**
+
+### 🤖 **AI Agents with Perfect Memory**
+Give your AI unlimited context that persists forever. Not just chat history — true understanding of relationships, evolution, and meaning over time.
+
+**Examples:** Personal assistants, code assistants, conversational AI, research agents
+
+### 📚 **Living Documentation & Knowledge Bases**
+Documentation that understands itself. Auto-links related concepts, detects outdated information, finds connections across your entire knowledge base.
+
+**Examples:** Internal wikis, research platforms, smart documentation, learning systems
+
+### 🔍 **Semantic Search at Any Scale**
+Find by meaning, not keywords. Search codebases, research papers, customer data, or media libraries with natural language.
+
+**Examples:** Code search, research platforms, content discovery, recommendation engines
+
+### 🏢 **Enterprise Knowledge Management**
+Corporate memory that never forgets. Track every customer interaction, product evolution, and business relationship.
+
+**Examples:** CRM systems, product catalogs, customer intelligence, institutional knowledge
+
+### 🎮 **Rich Interactive Experiences**
+NPCs that remember. Characters that persist across stories. Worlds that evolve based on real relationships.
+
+**Examples:** Game worlds, interactive fiction, educational platforms, creative tools
+
+### 🎨 **Content & Media Platforms**
+Every asset knows its relationships. Intelligent tagging, similarity-based discovery, and relationship-aware management.
+
+**Examples:** DAM systems, media libraries, writing assistants, content management
+
+**The pattern:** Knowledge that needs to live, connect, and evolve. That's what Brainy was built for.
+
 ---
 
-## ⚡ Quick Start - Zero Configuration
+## Quick Start
 
 ```bash
 npm install @soulcraft/brainy
 ```
 
-### 🎯 **Your First Knowledge Graph in 30 Seconds**
+### Your First Knowledge Graph (60 seconds)
 
 ```javascript
-import { Brainy, NounType } from '@soulcraft/brainy'
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
 
-// Just this - auto-detects everything!
 const brain = new Brainy()
 await brain.init()
 
-// Add entities with automatic embedding
+// Add knowledge
 const jsId = await brain.add({
     data: "JavaScript is a programming language",
-    nounType: NounType.Concept,
-    metadata: {
-        type: "language",
-        year: 1995,
-        paradigm: "multi-paradigm"
-    }
+    type: NounType.Concept,
+    metadata: { category: "language", year: 1995 }
 })
 
 const nodeId = await brain.add({
     data: "Node.js runtime environment",
-    nounType: NounType.Concept,
-    metadata: {
-        type: "runtime",
-        year: 2009,
-        platform: "server-side"
-    }
+    type: NounType.Concept,
+    metadata: { category: "runtime", year: 2009 }
 })
 
-// Create relationships between entities
-await brain.relate({
-    from: nodeId,
-    to: jsId,
-    type: "executes",
-    metadata: {
-        since: 2009,
-        performance: "high"
-    }
-})
+// Create relationships
+await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes })
 
-// Natural language search with graph relationships
+// Query with Triple Intelligence
 const results = await brain.find({
-    query: "programming languages used by server runtimes"
-})
-
-// Triple Intelligence: vector + metadata + relationships
-const filtered = await brain.find({
-    query: "JavaScript",                  // Vector similarity
-    where: {type: "language"},           // Metadata filtering
-    connected: {from: nodeId, depth: 1}  // Graph relationships
+    query: "JavaScript",                     // 🔍 Vector
+    where: { category: "language" },         // 📊 Document
+    connected: { from: nodeId, depth: 1 }    // 🕸️ Graph
 })
 ```
 
-**That's it!** You just created a knowledge graph with semantic search, relationship traversal, and metadata filtering. **No configuration. No complexity. Just works.**
+**Done.** No configuration. No complexity. Production-ready from day one.
 
 ---
 
-## 🌟 Core Features
+## Core Features
 
-### 🧠 **Natural Language Understanding**
+### 🧠 **Natural Language Queries**
 
 ```javascript
-// Ask questions naturally - Brainy understands
-await brain.find("Show me recent React components with tests")
-await brain.find("Popular JavaScript libraries similar to Vue")
-await brain.find("Documentation about authentication from last month")
+// Ask naturally - Brainy understands
+await brain.find("recent React components with tests")
+await brain.find("JavaScript libraries similar to Vue")
 
-// Structured queries with Triple Intelligence
+// Or use structured Triple Intelligence queries
 await brain.find({
-    like: "React",                       // Vector similarity
-    where: {                             // Document filtering
-        type: "library",
-        year: {greaterThan: 2020}
-    },
-    connected: {to: "JavaScript", depth: 2}  // Graph relationships
+    query: "React",
+    where: { type: "library", year: { greaterThan: 2020 } },
+    connected: { to: "JavaScript", depth: 2 }
 })
 ```
 
-### 🌐 **Virtual Filesystem - Intelligent File Management**
+### 🌐 **Virtual Filesystem** — Intelligent File Management
 
-Build file explorers, IDEs, and knowledge systems that **never crash**:
+Build file explorers and IDEs that never crash:
 
 ```javascript
 const vfs = brain.vfs()
-await vfs.init()
-
-// ✅ Safe file operations
-await vfs.writeFile('/projects/app/index.js', 'console.log("Hello")')
-await vfs.mkdir('/docs')
 
-// ✅ NEVER crashes: Tree-aware directory listing
-const children = await vfs.getDirectChildren('/projects')
+// Tree-aware operations prevent infinite recursion
+const tree = await vfs.getTreeStructure('/projects', { maxDepth: 3 })
 
-// ✅ Build file explorers safely
-const tree = await vfs.getTreeStructure('/projects', {
-  maxDepth: 3,          // Prevent deep recursion
-  sort: 'name'
-})
-
-// ✅ Semantic file search
+// Semantic file search
 const reactFiles = await vfs.search('React components with hooks')
 ```
 
-**Prevents infinite recursion** that crashes traditional file systems. Tree-aware operations ensure your file explorer never hangs.
-
-**[📖 VFS Quick Start →](docs/vfs/QUICK_START.md)** | **[🎯 Common Patterns →](docs/vfs/COMMON_PATTERNS.md)**
+**[📖 VFS Quick Start →](docs/vfs/QUICK_START.md)** | **[Common Patterns →](docs/vfs/COMMON_PATTERNS.md)** | **[Neural Extraction →](docs/vfs/NEURAL_EXTRACTION.md)**
 
-### 🚀 **Import Anything - CSV, Excel, PDF, URLs**
+### 🚀 **Import Anything** — CSV, Excel, PDF, URLs
 
 ```javascript
-// Import CSV with auto-detection
-await brain.import('customers.csv')
-// ✨ Auto-detects: encoding, delimiter, types, creates entities!
-
-// Import Excel workbooks with multi-sheet support
-await brain.import('sales-data.xlsx', {
-  excelSheets: ['Q1', 'Q2']
-})
-
-// Import PDF documents with table extraction
-await brain.import('research-paper.pdf', {
-  pdfExtractTables: true
-})
-
-// Import from URLs (auto-fetched)
+await brain.import('customers.csv')  // Auto-detects everything
+await brain.import('sales-data.xlsx', { excelSheets: ['Q1', 'Q2'] })
+await brain.import('research-paper.pdf', { pdfExtractTables: true })
 await brain.import('https://api.example.com/data.json')
 ```
 
 **[📖 Complete Import Guide →](docs/guides/import-anything.md)**
 
-### 🧠 **Neural API - Advanced Semantic Analysis**
+### 🧠 **Neural API** — Advanced Semantic Analysis
 
 ```javascript
-const neural = brain.neural
-
-// Automatic semantic clustering
-const clusters = await neural.clusters({
-    algorithm: 'kmeans',
-    maxClusters: 5,
-    threshold: 0.8
-})
-
-// Calculate similarity between any items
-const similarity = await neural.similar('item1', 'item2')
-
-// Find nearest neighbors
-const neighbors = await neural.neighbors('item-id', 10)
-
-// Detect outliers
-const outliers = await neural.outliers(0.3)
-
-// Generate visualization data for D3/Cytoscape
-const vizData = await neural.visualize({
-    maxNodes: 100,
-    dimensions: 3,
-    algorithm: 'force'
-})
+// Clustering, similarity, outlier detection, visualization
+const clusters = await brain.neural.clusters({ algorithm: 'kmeans' })
+const similarity = await brain.neural.similar('item1', 'item2')
+const outliers = await brain.neural.outliers(0.3)
+const vizData = await brain.neural.visualize({ maxNodes: 100 })
 ```
 
 ---
 
-## 🌐 Framework Integration
+## Framework Integration
 
-**Brainy is framework-first!** Works with **any** modern framework:
+**Works with any modern framework.** React, Vue, Angular, Svelte, Solid.js — your choice.
 
-### ⚛️ React & Next.js
 ```javascript
-function SearchComponent() {
-  const [brain] = useState(() => new Brainy())
-  useEffect(() => { brain.init() }, [])
+// React
+const [brain] = useState(() => new Brainy())
+useEffect(() => { brain.init() }, [])
 
-  const handleSearch = async (query) => {
-    const results = await brain.find(query)
-    setResults(results)
-  }
-}
-```
+// Vue
+async mounted() { this.brain = await new Brainy().init() }
 
-### 🟢 Vue.js & Nuxt.js
-```javascript
-export default {
-  async mounted() {
-    this.brain = new Brainy()
-    await this.brain.init()
-  },
-  methods: {
-    async search(query) {
-      return await this.brain.find(query)
-    }
-  }
-}
+// Angular
+@Injectable() export class BrainyService { brain = new Brainy() }
 ```
 
-### 🅰️ Angular
-```typescript
-@Injectable({ providedIn: 'root' })
-export class BrainyService {
-  private brain = new Brainy()
-  async search(query: string) {
-    return await this.brain.find(query)
-  }
-}
-```
+**Supports:** All bundlers (Webpack, Vite, Rollup) • SSR/SSG • Edge runtimes • Browser/Node.js
 
-**Works with:** Svelte, Solid.js, Qwik, Fresh, and more! All bundlers (Webpack, Vite, Rollup). SSR/SSG. Edge runtimes.
+**[📖 Framework Integration Guide →](docs/guides/framework-integration.md)** | **[Next.js →](docs/guides/nextjs-integration.md)** | **[Vue →](docs/guides/vue-integration.md)**
 
 ---
 
-## 💾 Storage - From Development to Production
+## Storage — From Memory to Planet-Scale
 
-### 🚀 **Development: Just Works**
+### Development → Just Works
 ```javascript
-const brain = new Brainy()  // Memory storage, auto-configured
+const brain = new Brainy()  // Memory storage, zero config
 ```
 
-### ⚡ **Production: FileSystem with Compression**
+### Production → Persistence with Compression
 ```javascript
 const brain = new Brainy({
-  storage: {
-    type: 'filesystem',
-    path: './brainy-data',
-    compression: true  // 60-80% space savings!
-  }
+  storage: { type: 'filesystem', path: './data', compression: true }
 })
+// 60-80% space savings with gzip
 ```
 
-### ☁️ **Production: Cloud Storage** (NEW in v4.0.0)
-
-Choose your cloud provider - all support **automatic cost optimization:**
-
-#### **AWS S3 / Cloudflare R2 / DigitalOcean Spaces**
+### Cloud → AWS, GCS, Azure, Cloudflare R2
 ```javascript
+// AWS S3 / Cloudflare R2
 const brain = new Brainy({
   storage: {
     type: 's3',
     s3Storage: {
       bucketName: 'my-knowledge-base',
-      region: 'us-east-1',
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+      region: 'us-east-1'
     }
   }
 })
 
-// Enable Intelligent-Tiering for automatic 96% cost savings
-await brain.storage.enableIntelligentTiering('entities/', 'brainy-auto-tier')
+// Enable Intelligent-Tiering: 96% cost savings
+await brain.storage.enableIntelligentTiering('entities/', 'auto-tier')
 ```
 
-#### **Google Cloud Storage**
-```javascript
-const brain = new Brainy({
-  storage: {
-    type: 'gcs',
-    gcsStorage: {
-      bucketName: 'my-knowledge-base',
-      keyFilename: '/path/to/service-account.json'
-    }
-  }
-})
+**Cost optimization at scale:**
 
-// Enable Autoclass for automatic 94% cost savings
-await brain.storage.enableAutoclass({ terminalStorageClass: 'ARCHIVE' })
-```
+| Scale | Standard | With Intelligent Tiering | Annual Savings |
+|-------|----------|--------------------------|----------------|
+| 5TB | $1,380 | $59 | $1,321 (96%) |
+| 50TB | $13,800 | $594 | $13,206 (96%) |
+| 500TB | $138,000 | $5,940 | $132,060 (96%) |
 
-#### **Azure Blob Storage**
-```javascript
-const brain = new Brainy({
-  storage: {
-    type: 'azure',
-    azureStorage: {
-      containerName: 'knowledge-base',
-      connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING
-    }
-  }
-})
-
-// Batch tier changes for 99% cost savings
-await brain.storage.setBlobTierBatch(
-  oldBlobs.map(name => ({ blobName: name, tier: 'Archive' }))
-)
-```
-
-### 💰 **Cost Optimization Impact**
-
-| Scale | Before | After (Archive) | Savings/Year |
-|-------|--------|-----------------|--------------|
-| 5TB | $1,380/year | $59/year | **$1,321 (96%)** |
-| 50TB | $13,800/year | $594/year | **$13,206 (96%)** |
-| 500TB | $138,000/year | $5,940/year | **$132,060 (96%)** |
-
-**[📖 AWS S3 Cost Guide →](docs/operations/cost-optimization-aws-s3.md)** | **[GCS →](docs/operations/cost-optimization-gcs.md)** | **[Azure →](docs/operations/cost-optimization-azure.md)** | **[R2 →](docs/operations/cost-optimization-cloudflare-r2.md)**
+**[📖 Cloud Storage Guide →](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** | **[AWS Cost Optimization →](docs/operations/cost-optimization-aws-s3.md)** | **[GCS →](docs/operations/cost-optimization-gcs.md)** | **[Azure →](docs/operations/cost-optimization-azure.md)**
 
 ---
 
-## 🚀 Production Scale Features (NEW in v4.0.0)
+## Production Features
 
-### 🎯 **Type-Aware HNSW - 87% Memory Reduction**
+### 🎯 Type-Aware HNSW Indexing — 87% Memory Reduction
 
-**Billion-scale deployments made affordable:**
+Scale to billions affordably:
 
-- **Memory @ 1B entities**: 384GB → 50GB (-87%)
-- **Single-type queries**: 10x faster (search 100M instead of 1B)
-- **Multi-type queries**: 5-8x faster
-- **Optimized rebuilds**: 31x faster with type filtering
+- **1B entities:** 384GB → 50GB memory (-87%)
+- **Single-type queries:** 10x faster
+- **Multi-type queries:** 5-8x faster
 
 ```javascript
-const brain = new Brainy({
-  hnsw: {
-    typeAware: true  // Enable type-aware indexing
-  }
-})
+const brain = new Brainy({ hnsw: { typeAware: true } })
 ```
 
-### ⚡ **Production-Ready Storage**
+**[📖 How Type-Aware Indexing Works →](docs/architecture/data-storage-architecture.md)**
 
-**NEW v4.0.0 enterprise features:**
+### ⚡ Enterprise-Ready Operations (v4.0.0)
 
-- **🗑️ Batch Operations**: Delete thousands of entities with retry logic
-- **📦 Gzip Compression**: 60-80% space savings (FileSystem)
-- **💽 OPFS Quota Monitoring**: Real-time quota tracking (Browser)
-- **🔄 Metadata/Vector Separation**: Billion-entity scalability
-- **🛡️ Enterprise Reliability**: Backpressure, circuit breakers, retries
+- **Batch operations** with retry logic (1000x faster deletes)
+- **Gzip compression** (60-80% space savings)
+- **OPFS quota monitoring** (browser storage)
+- **Metadata/Vector separation** (billion-entity scalability)
+- **Circuit breakers & backpressure** (enterprise reliability)
 
 ```javascript
-// Batch delete with retry logic
-await brain.storage.batchDelete(keys, {
-  maxRetries: 3,
-  continueOnError: true
-})
+// Batch operations
+await brain.storage.batchDelete(keys, { maxRetries: 3 })
 
-// Get storage status
+// Monitor storage
 const status = await brain.storage.getStorageStatus()
-console.log(`Used: ${status.used}, Quota: ${status.quota}`)
 ```
 
-### 📊 **Adaptive Memory Management**
+### 📊 Adaptive Memory Management
 
-**Auto-scales from 2GB to 128GB+ based on resources:**
+Auto-scales 2GB → 128GB+ based on environment:
 
-- Container-aware (Docker/K8s cgroups v1/v2)
-- Environment-smart (25% dev, 40% container, 50% production)
-- Model memory accounting (150MB Q8, 250MB FP32)
-- Built-in cache monitoring with recommendations
+- Container-aware (Docker/K8s cgroups)
+- Environment-optimized (dev/staging/production)
+- Built-in cache monitoring with tuning recommendations
 
 ```javascript
-// Get cache statistics and recommendations
-const stats = brain.getCacheStats()
-console.log(`Hit rate: ${stats.hitRate * 100}%`)
-// Actionable tuning recommendations included
+const stats = brain.getCacheStats()  // Performance insights
 ```
 
 **[📖 Capacity Planning Guide →](docs/operations/capacity-planning.md)**
 
 ---
 
-## 🏢 Enterprise Features - No Paywalls
+## Benchmarks
 
-Brainy includes **enterprise-grade capabilities at no extra cost**:
-
-- ✅ **Scales to billions of entities** with 18ms search latency @ 1B scale
-- ✅ **Distributed architecture** with sharding and replication
-- ✅ **Read/write separation** for horizontal scaling
-- ✅ **Connection pooling** and request deduplication
-- ✅ **Built-in monitoring** with metrics and health checks
-- ✅ **Production ready** with circuit breakers and backpressure
-
-**No premium tiers. No feature gates. Everyone gets the same powerful system.**
+| Operation | Performance | Memory |
+|-----------|-------------|--------|
+| Initialize | 450ms | 24MB |
+| Add entity | 12ms | +0.1MB |
+| Vector search (1K) | 3ms | - |
+| Metadata filter (10K) | 0.8ms | - |
+| Bulk import (1K) | 2.3s | +8MB |
+| **10M entities** | **5.8ms** | **12GB** |
+| **1B entities** | **18ms** | **50GB** |
 
 ---
 
-## 📊 Benchmarks
-
-| Operation                        | Performance | Memory   |
-|----------------------------------|-------------|----------|
-| Initialize                       | 450ms       | 24MB     |
-| Add Item                         | 12ms        | +0.1MB   |
-| Vector Search (1k items)         | 3ms         | -        |
-| Metadata Filter (10k items)      | 0.8ms       | -        |
-| Natural Language Query           | 15ms        | -        |
-| Bulk Import (1000 items)         | 2.3s        | +8MB     |
-| **Production Scale (10M items)** | **5.8ms**   | **12GB** |
-| **Billion Scale (1B items)**     | **18ms**    | **50GB** |
+## 🧠 Deep Dive: How Brainy Actually Works
 
----
-
-## 🎯 Use Cases
+**Want to understand the magic under the hood?**
 
-### Knowledge Management
-```javascript
-// Create knowledge graph with relationships
-const apiGuide = await brain.add("REST API Guide", {
-    nounType: NounType.Document,
-    category: "documentation"
-})
+### 🔍 Triple Intelligence & find() API
+Understand how vector search, graph relationships, and document filtering work together in one unified query:
 
-const author = await brain.add("Jane Developer", {
-    nounType: NounType.Person,
-    role: "tech-lead"
-})
+**[📖 Triple Intelligence Architecture →](docs/architecture/triple-intelligence.md)**
+**[📖 Natural Language Guide →](docs/guides/natural-language.md)**
+**[📖 API Reference: find() →](docs/api/README.md)**
 
-await brain.relate(author, apiGuide, "authored")
+### 🗂️ Type-Aware Indexing & HNSW
+Learn how we achieve 87% memory reduction and 10x query speedups at billion-scale:
 
-// Query naturally
-const docs = await brain.find(
-  "documentation authored by tech leads for active projects"
-)
-```
+**[📖 Data Storage Architecture →](docs/architecture/data-storage-architecture.md)**
+**[📖 Architecture Overview →](docs/architecture/overview.md)**
 
-### AI Memory Layer
-```javascript
-// Store conversation context with relationships
-const userId = await brain.add("User 123", {
-    nounType: NounType.User,
-    tier: "premium"
-})
+### 📈 Scaling: Individual → Planet
+Understand how the same code scales from prototype to billions of entities:
 
-const messageId = await brain.add(userMessage, {
-    nounType: NounType.Message,
-    timestamp: Date.now()
-})
+**[📖 Capacity Planning →](docs/operations/capacity-planning.md)**
+**[📖 Cloud Deployment Guide →](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)**
 
-await brain.relate(userId, messageId, "sent")
+### 🎯 The Universal Type System
+Explore the mathematical foundation: 31 nouns × 40 verbs = any domain:
 
-// Retrieve context
-const context = await brain.find({
-    where: {type: "message"},
-    connected: {from: userId, type: "sent"},
-    like: "previous product issues"
-})
-```
-
-### Semantic Search
-```javascript
-// Find similar content
-const similar = await brain.search(existingContent, {
-    limit: 5,
-    threshold: 0.8
-})
-```
+**[📖 Noun-Verb Taxonomy →](docs/architecture/noun-verb-taxonomy.md)**
 
 ---
 
-## 🛠️ CLI
+## CLI Tools
 
 ```bash
 npm install -g brainy
 
-# Add data
 brainy add "JavaScript is awesome" --metadata '{"type":"opinion"}'
-
-# Search
-brainy search "programming"
-
-# Natural language find
 brainy find "awesome programming languages"
-
-# Interactive mode
-brainy chat
+brainy search "programming"
 ```
 
----
-
-## 📖 Documentation
+47 commands available, including storage management, imports, and neural operations.
 
-### Getting Started
-- [Getting Started Guide](docs/guides/getting-started.md)
-- [v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md) **← NEW**
-- [AWS S3 Cost Guide](docs/operations/cost-optimization-aws-s3.md) | [GCS](docs/operations/cost-optimization-gcs.md) | [Azure](docs/operations/cost-optimization-azure.md) | [R2](docs/operations/cost-optimization-cloudflare-r2.md) **← NEW**
+---
 
-### Framework Integration
-- [Framework Integration Guide](docs/guides/framework-integration.md)
-- [Next.js Integration](docs/guides/nextjs-integration.md)
-- [Vue.js Integration](docs/guides/vue-integration.md)
+## Documentation
 
-### Virtual Filesystem
-- [VFS Core Documentation](docs/vfs/VFS_CORE.md)
-- [Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)
-- [Neural Extraction API](docs/vfs/NEURAL_EXTRACTION.md)
+### 🚀 Getting Started
+- **[Getting Started Guide](docs/guides/getting-started.md)** — Your first steps with Brainy
+- **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)** — Upgrade from v3 (backward compatible)
 
-### Core Documentation
-- [API Reference](docs/api/README.md)
-- [Architecture Overview](docs/architecture/overview.md)
-- [Data Storage Architecture](docs/architecture/data-storage-architecture.md)
-- [Natural Language Guide](docs/guides/natural-language.md)
-- [Triple Intelligence](docs/architecture/triple-intelligence.md)
-- [Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)
+### 🧠 Core Concepts
+- **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** — How vector + graph + document work together
+- **[Natural Language Queries](docs/guides/natural-language.md)** — Using find() effectively
+- **[API Reference](docs/api/README.md)** — Complete API documentation
+- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** — The universal type system
 
-### Operations & Production
-- [Capacity Planning](docs/operations/capacity-planning.md)
-- [Cloud Deployment Guide](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md) **← NEW**
-- [AWS S3 Cost Guide](docs/operations/cost-optimization-aws-s3.md) | [GCS](docs/operations/cost-optimization-gcs.md) | [Azure](docs/operations/cost-optimization-azure.md) | [R2](docs/operations/cost-optimization-cloudflare-r2.md) **← NEW**
+### 🏗️ Architecture & Scaling
+- **[Architecture Overview](docs/architecture/overview.md)** — System design and components
+- **[Data Storage Architecture](docs/architecture/data-storage-architecture.md)** — Type-aware indexing and HNSW
+- **[Capacity Planning](docs/operations/capacity-planning.md)** — Memory, storage, and scaling guidelines
 
----
+### ☁️ Production & Operations
+- **[Cloud Deployment Guide](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** — Deploy to AWS, GCS, Azure
+- **[AWS Cost Optimization](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)**
 
-## 💖 Support Brainy
+### 🌐 Framework Integration
+- **[Framework Integration Guide](docs/guides/framework-integration.md)** — React, Vue, Angular, Svelte
+- **[Next.js Integration](docs/guides/nextjs-integration.md)**
+- **[Vue.js Integration](docs/guides/vue-integration.md)**
 
-Brainy is **free and open source** - no paywalls, no premium tiers, no feature gates. If Brainy helps your project, consider supporting development:
+### 🌳 Virtual Filesystem
+- **[VFS Quick Start](docs/vfs/QUICK_START.md)** — Build file explorers that never crash
+- **[VFS Core Documentation](docs/vfs/VFS_CORE.md)**
+- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)**
+- **[Neural Extraction API](docs/vfs/NEURAL_EXTRACTION.md)**
 
-- ⭐ **Star us on [GitHub](https://github.com/soulcraftlabs/brainy)**
-- 💝 **Sponsor via [GitHub Sponsors](https://github.com/sponsors/soulcraftlabs)**
-- 🐛 **Report issues** and contribute code
-- 📣 **Share** with your team and community
-
-Your support keeps Brainy free for everyone and enables continued development of enterprise features at no cost.
+### 📦 Data Import
+- **[Import Anything Guide](docs/guides/import-anything.md)** — CSV, Excel, PDF, URLs
 
 ---
 
-## 📋 System Requirements
+## What's New in v4.0.0
 
-**Node.js Version:** 22 LTS (recommended)
+**Enterprise-scale cost optimization and performance improvements:**
 
-- ✅ **Node.js 22 LTS** - Fully supported (recommended for production)
-- ✅ **Node.js 20 LTS** - Compatible (maintenance mode)
-- ❌ **Node.js 24** - Not supported (ONNX compatibility issues)
+- 🎯 **96% cloud storage cost savings** with intelligent tiering (AWS, GCS, Azure)
+- ⚡ **1000x faster batch deletions** (533 entities/sec vs 0.5/sec)
+- 📦 **60-80% compression** with gzip (FileSystem storage)
+- 🔄 **Enhanced metadata/vector separation** for billion-scale deployments
 
-If using nvm: `nvm use` (we provide a `.nvmrc` file)
+**[📖 Full v4.0.0 Changelog →](CHANGELOG.md)** | **[Migration Guide →](docs/MIGRATION-V3-TO-V4.md)** (100% backward compatible)
 
 ---
 
-## 🧠 The Knowledge Operating System Explained
-
-### How We Achieved The Impossible
-
-**Triple Intelligence™** unifies three database paradigms that were previously incompatible:
+## Requirements
 
-1. **Vector databases** (Pinecone, Weaviate) - semantic similarity
-2. **Graph databases** (Neo4j, ArangoDB) - relationships
-3. **Document databases** (MongoDB, Elasticsearch) - metadata filtering
+**Node.js 22 LTS** (recommended) or **Node.js 20 LTS**
 
-**Others make you choose. Brainy does all three together.**
-
-### The Math of Infinite Expressiveness
-
-```
-31 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol
+```bash
+nvm use  # We provide .nvmrc
 ```
 
-- **1,240 base combinations** from standardized types
-- **∞ domain specificity** via unlimited metadata
-- **∞ relationship depth** via graph traversal
-- **= Model ANYTHING**: From quantum physics to social networks
-
-### Why This Changes Everything
+---
 
-**Like HTTP for the web, Brainy for knowledge:**
+## Why Brainy Exists
 
-- All augmentations compose perfectly - same noun-verb language
-- All AI models share knowledge - GPT, Claude, Llama all understand
-- All tools integrate seamlessly - no translation layers
-- All data flows freely - perfect portability
+**The Vision:** Traditional systems force you to choose between vector databases, graph databases, and document stores. You need all three, but combining them is complex and fragile.
 
-**The Vision**: One protocol. All knowledge. Every tool. Any AI.
+**Brainy solved the impossible:** One API. All three paradigms. Any scale.
 
-**Proven across industries**: Healthcare, Finance, Manufacturing, Education, Legal, Retail, Government, and beyond.
+Like HTTP standardized web communication, **Brainy standardizes knowledge representation.** One protocol that any AI model understands. One system that scales from prototype to planet.
 
-[→ See the Mathematical Proof & Full Taxonomy](docs/architecture/noun-verb-taxonomy.md)
+**[📖 Read the Mathematical Proof →](docs/architecture/noun-verb-taxonomy.md)**
 
 ---
 
-## 🏢 Enterprise & Cloud
+## Enterprise & Support
 
-**Brain Cloud** - Managed Brainy with team sync, persistent memory, and enterprise connectors.
+**🏢 Brain Cloud** — Managed Brainy with team sync, persistent memory, and enterprise connectors.
+Visit **[soulcraft.com](https://soulcraft.com)** for more information.
 
-```bash
-brainy cloud setup
-```
+**💖 Support Development:**
+- ⭐ Star us on **[GitHub](https://github.com/soulcraftlabs/brainy)**
+- 💝 Sponsor via **[GitHub Sponsors](https://github.com/sponsors/soulcraftlabs)**
+- 🐛 Report issues and contribute code
+- 📣 Share with your team and community
 
-Visit [soulcraft.com](https://soulcraft.com) for more information.
+**Brainy is 100% free and open source.** No paywalls, no premium tiers, no feature gates.
 
 ---
 
-## 🤝 Contributing
+## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
 
 ---
 
-## 📄 License
+## License
 
 MIT © Brainy Contributors
 
@@ -686,6 +629,6 @@ MIT © Brainy Contributors
 
 <p align="center">
   <strong>Built with ❤️ by the Brainy community</strong><br>
-  <em>Zero-Configuration AI Database with Triple Intelligence™</em><br>
-  <em>v4.0.0 - Production-Scale Storage with 99% Cost Savings</em>
+  <em>The Knowledge Operating System</em><br>
+  <em>From prototype to planet-scale • Zero configuration • Triple Intelligence™</em>
 </p>