@soulcraft/brainy 0.48.0 → 0.50.0

package/README.md

@@ -7,32 +7,60 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4.5-blue.svg)](https://www.typescriptlang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**A powerful graph & vector data platform for AI applications across any environment**
+**The world's only true Vector + Graph database - unified semantic search and knowledge graphs**
 
 </div>
 
-## 🔥 MAJOR UPDATE: TensorFlow.js → Transformers.js Migration (v0.46+)
+## 🔥 MAJOR UPDATES: What's New in v0.49, v0.48 & v0.46+
 
-**We've completely replaced TensorFlow.js with Transformers.js for better performance and true offline operation!**
+### 🎯 **v0.49: Filter Discovery & Performance Improvements**
 
-### Why We Made This Change
+**Discover available filters and scale to millions of items!**
 
-**The Honest Truth About TensorFlow.js:**
+```javascript
+// Discover what filters are available - O(1) field lookup
+const categories = await brainy.getFilterValues('category')
+// Returns: ['electronics', 'books', 'clothing', ...]
+
+const fields = await brainy.getFilterFields()  // O(1) operation
+// Returns: ['category', 'price', 'brand', 'rating', ...]
+```
+
+- ✅ **Filter Discovery API**: O(1) field discovery for instant filter UI generation
+- ✅ **Improved Performance**: Removed deprecated methods, now uses pagination everywhere
+- ✅ **Better Scalability**: Hybrid indexing with O(1) field access scales to millions
+- ✅ **Smart Caching**: LRU cache for frequently accessed filters
+- ✅ **Zero Configuration**: Everything auto-optimizes based on usage patterns
+
+### 🚀 **v0.48: MongoDB-Style Metadata Filtering**
 
-- 📦 **Massive Package Size**: 12.5MB+ packages with complex dependency trees
-- 🌐 **Hidden Network Calls**: Even "local" models triggered fetch() calls internally
-- 🐛 **Dependency Hell**: Constant `--legacy-peer-deps` issues with Node.js updates
-- 🔧 **Maintenance Burden**: 47+ dependencies to keep compatible across environments
-- 💾 **Huge Models**: 525MB Universal Sentence Encoder models
+**Powerful querying with familiar syntax - filter DURING search for maximum performance!**
 
-### What You Get Now
+```javascript
+const results = await brainy.search("wireless headphones", 10, {
+  metadata: {
+    category: { $in: ["electronics", "audio"] },
+    price: { $lte: 200 },
+    rating: { $gte: 4.0 },
+    brand: { $ne: "Generic" }
+  }
+})
+```
 
-- ✅ **95% Smaller Package**: 643 kB vs 12.5 MB (and it actually works better!)
-- ✅ **84% Smaller Models**: 87 MB vs 525 MB all-MiniLM-L6-v2 vs USE
-- ✅ **True Offline Operation**: Zero network calls after initial model download
-- ✅ **5x Fewer Dependencies**: Clean dependency tree, no more peer dep issues
-- ✅ **Same API**: Drop-in replacement - your existing code just works
-- ✅ **Better Performance**: ONNX Runtime is faster than TensorFlow.js in most cases
+- ✅ **15+ MongoDB Operators**: `$gt`, `$in`, `$regex`, `$and`, `$or`, `$includes`, etc.
+- ✅ **Automatic Indexing**: Zero configuration, maximum performance
+- ✅ **Nested Fields**: Use dot notation for complex objects
+- ✅ **100% Backward Compatible**: Your existing code works unchanged
+
+### ⚡ **v0.46: Transformers.js Migration**
+
+**Replaced TensorFlow.js for better performance and true offline operation!**
+
+- ✅ **95% Smaller Package**: 643 kB vs 12.5 MB
+- ✅ **84% Smaller Models**: 87 MB vs 525 MB models
+- ✅ **True Offline**: Zero network calls after initial download
+- ✅ **5x Fewer Dependencies**: Clean tree, no peer dependency issues
+- ✅ **Same API**: Drop-in replacement, existing code works unchanged
 
 ### Migration (It's Automatic!)
 
@@ -56,11 +84,52 @@ RUN npm run download-models  # Download during build for offline production
 
 ---
 
+## 🏆 Industry First: True Vector + Graph Database
+
+**Brainy is the only database that natively combines vector search and graph relationships in a single, unified system.**
+
+Unlike other solutions that bolt vector search onto traditional databases or require multiple systems:
+
+✅ **Native Vector + Graph Architecture** - Purpose-built for both semantic search AND knowledge graphs  
+✅ **Single API, Dual Power** - Vector similarity search AND graph traversal in one database  
+✅ **True Semantic Relationships** - Not just "similar vectors" but meaningful connections like "develops", "owns", "causes"  
+✅ **Zero Integration Complexity** - No need to sync between Pinecone + Neo4j or pgvector + graph databases
+
+**Why This Matters:**
+```javascript
+// Other solutions: Manage 2+ databases
+const vectors = await pinecone.search(query)        // Vector search
+const graph = await neo4j.run("MATCH (a)-[r]->(b)") // Graph traversal
+// How do you keep them in sync? 😢
+
+// Brainy: One database, both capabilities
+const results = await brainy.search("AI models", 10, {
+  includeVerbs: true,     // Include relationships
+  verbTypes: ["develops"] // Filter by relationship type
+})
+// Everything stays perfectly synchronized! 🎉
+```
+
+This revolutionary architecture enables entirely new classes of AI applications that were previously impossible or prohibitively complex.
+
 ## ✨ What is Brainy?
 
-Imagine a database that thinks like you do - connecting ideas, finding patterns, and getting smarter over time. Brainy
-is the **AI-native database** that brings vector search and knowledge graphs together in one powerful, ridiculously
-easy-to-use package.
+**One API. Every environment. Zero configuration.**
+
+Brainy is the **AI-native database** that combines vector search and knowledge graphs in one unified API. Write your
+code once, and it runs everywhere - browsers, Node.js, serverless, edge workers - with automatic optimization for each
+environment.
+
+```javascript
+// This same code works EVERYWHERE
+const brainy = new BrainyData()
+await brainy.init()
+
+// Vector search (like Pinecone) + Graph database (like Neo4j)
+await brainy.add("OpenAI", { type: "company" })  // Nouns
+await brainy.relate(openai, gpt4, "develops")    // Verbs
+const results = await brainy.search("AI", 10)    // Semantic search
+```
 
 ### 🆕 NEW: Distributed Mode (v0.38+)
 
@@ -78,7 +147,8 @@ easy-to-use package.
   environment and optimizes itself
 - **🌍 True Write-Once, Run-Anywhere** - Same code runs in Angular, React, Vue, Node.js, Deno, Bun, serverless, edge
   workers, and web workers with automatic environment detection
-- **⚡ Scary Fast** - Handles millions of vectors with sub-millisecond search. GPU acceleration for embeddings, optimized CPU for distance calculations
+- **⚡ Scary Fast** - Handles millions of vectors with sub-millisecond search. GPU acceleration for embeddings, optimized
+  CPU for distance calculations
 - **🎯 Self-Learning** - Like having a database that goes to the gym. Gets faster and smarter the more you use it
 - **🔮 AI-First Design** - Built for the age of embeddings, RAG, and semantic search. Your LLMs will thank you
 - **🎮 Actually Fun to Use** - Clean API, great DX, and it does the heavy lifting so you can build cool stuff
@@ -103,41 +173,51 @@ npm install @soulcraft/brainy
 ```javascript
 import { BrainyData } from '@soulcraft/brainy'
 
+// Same code works EVERYWHERE - browser, Node.js, cloud, edge
 const brainy = new BrainyData()
 await brainy.init() // Auto-detects your environment
 
-// Add some data
-await brainy.add("The quick brown fox jumps over the lazy dog")
-await brainy.add("A fast fox leaps over a sleeping dog")
-await brainy.add("Cats are independent and mysterious animals")
+// 1️⃣ Simple vector search (like Pinecone)
+await brainy.add("The quick brown fox jumps over the lazy dog", { type: "sentence" })
+await brainy.add("Cats are independent and mysterious animals", { type: "sentence" })
 
-// Vector search finds similar content
-const results = await brainy.search("speedy animals jumping", 2)
-console.log(results) // Finds the fox sentences!
-```
-
-**🎯 That's it!** You just built semantic search in 4 lines. Works in Angular, React, Vue, Node.js, browsers,
-serverless - everywhere.
+const results = await brainy.search("fast animals", 5)
+// Finds similar content by meaning, not keywords!
 
-## 🚀 The Magic: Vector + Graph Database
+// 2️⃣ Graph relationships (like Neo4j)
+const openai = await brainy.add("OpenAI", { type: "company", founded: 2015 })
+const gpt4 = await brainy.add("GPT-4", { type: "product", released: 2023 })
+const sam = await brainy.add("Sam Altman", { type: "person", role: "CEO" })
 
-**Most databases do one thing.** Brainy does both vector similarity AND graph relationships:
+// Create relationships between entities
+await brainy.relate(openai, gpt4, "develops")
+await brainy.relate(sam, openai, "leads")
+await brainy.relate(gpt4, sam, "created_by")
 
-```javascript
-// Add entities with relationships
-const companyId = await brainy.addNoun("OpenAI creates powerful AI models", "company")
-const productId = await brainy.addNoun("GPT-4 is a large language model", "product")
+// 3️⃣ Combined power: Vector search + Graph traversal
+const similar = await brainy.search("AI language models", 10)  // Find by meaning
+const products = await brainy.getVerbsBySource(openai)         // Get relationships
+const graph = await brainy.findSimilar(gpt4, { relationType: "develops" })
 
-// Connect them with relationships  
-await brainy.addVerb(companyId, productId, undefined, { type: "develops" })
+// 4️⃣ Advanced: Search with context
+const contextual = await brainy.search("Who leads AI companies?", 5, {
+  includeVerbs: true,     // Include relationships in results
+  nounTypes: ["person"],  // Filter to specific entity types
+})
 
-// Now you can do BOTH:
-const similar = await brainy.search("AI language models")  // Vector similarity
-const products = await brainy.getVerbsByType("develops")   // Graph traversal
+// 5️⃣ NEW! MongoDB-style metadata filtering
+const filtered = await brainy.search("AI research", 10, {
+  metadata: {
+    type: "academic",
+    year: { $gte: 2020 },
+    status: { $in: ["published", "peer-reviewed"] },
+    impact: { $gt: 100 }
+  }
+})
+// Filters DURING search for maximum performance!
 ```
 
-**Why this matters:** Find content by meaning AND follow relationships. It's like having PostgreSQL and Pinecone working
-together seamlessly.
+**🎯 That's it!** Vector search + graph database + works everywhere. No config needed.
 
 ### 🔍 Want More Power?
 
@@ -162,335 +242,148 @@ returns "tiger"
 **🌐 Real-Time Collaboration** - Sync vector data across devices. Figma for AI data  
 **🏥 Medical Diagnosis Tools** - Match symptoms to conditions using embedding similarity
 
-## 🚀 Write-Once, Run-Anywhere Quick Start
+## 🚀 Works Everywhere - Same Code
 
-Brainy uses the same code across all environments with automatic detection. **Framework-optimized** for the best
-developer experience. Choose your environment:
+**Write once, run anywhere.** Brainy auto-detects your environment and optimizes automatically:
 
-### 🅰️ Angular (Latest)
+### 🌐 Browser Frameworks (React, Angular, Vue)
 
-```bash
-npm install @soulcraft/brainy
+```javascript
+import { BrainyData } from '@soulcraft/brainy'
+
+// SAME CODE in React, Angular, Vue, Svelte, etc.
+const brainy = new BrainyData()
+await brainy.init()  // Auto-uses OPFS in browsers
+
+// Add entities and relationships
+const john = await brainy.add("John is a software engineer", { type: "person" })
+const jane = await brainy.add("Jane is a data scientist", { type: "person" })
+const ai = await brainy.add("AI Project", { type: "project" })
+
+await brainy.relate(john, ai, "works_on")
+await brainy.relate(jane, ai, "leads")
+
+// Search by meaning
+const engineers = await brainy.search("software developers", 5)
+
+// Traverse relationships
+const team = await brainy.getVerbsByTarget(ai)  // Who works on AI Project?
 ```
 
+<details>
+<summary>📦 Full Angular Component Example</summary>
+
 ```typescript
 import { Component, signal, OnInit } from '@angular/core'
 import { BrainyData } from '@soulcraft/brainy'
 
 @Component({
   selector: 'app-search',
-  template: `
-    <div class="search-container">
-      <input [(ngModel)]="query" 
-             (input)="search($event.target.value)" 
-             placeholder="Search by meaning (try 'pets' or 'food')..."
-             class="search-input">
-      
-      <div class="results">
-        @for (result of results(); track result.id) {
-          <div class="result-item">
-            <strong>{{result.metadata?.category}}</strong>: {{result.metadata?.originalData}}
-            <small>Similarity: {{result.score | number:'1.2-2'}}</small>
-          </div>
-        }
-      </div>
-    </div>
-  `
+  template: `<input (input)="search($event.target.value)" placeholder="Search...">`
 })
 export class SearchComponent implements OnInit {
-  private brainy: BrainyData | null = null
-  results = signal<any[]>([])
-  query = ''
+  brainy = new BrainyData()
 
   async ngOnInit() {
-    // Auto-detects environment and uses OPFS storage in browsers
-    this.brainy = new BrainyData({
-      defaultService: 'my-app'
-    })
     await this.brainy.init()
-
-    // Add sample data
-    await this.brainy.add("Cats are amazing pets", { category: "animals" })
-    await this.brainy.add("Dogs love to play fetch", { category: "animals" })
-    await this.brainy.add("Pizza is delicious food", { category: "food" })
+    // Add your data...
   }
 
   async search(query: string) {
-    if (!query.trim() || !this.brainy) {
-      this.results.set([])
-      return
-    }
-
-    const searchResults = await this.brainy.search(query, 5)
-    this.results.set(searchResults)
+    const results = await this.brainy.search(query, 5)
+    // Display results...
   }
 }
 ```
 
-### ⚛️ React
+</details>
 
-```bash
-npm install @soulcraft/brainy
-```
+<details>
+<summary>📦 Full React Example</summary>
 
 ```jsx
 import { BrainyData } from '@soulcraft/brainy'
 import { useEffect, useState } from 'react'
 
-function SemanticSearch() {
+function Search() {
   const [brainy, setBrainy] = useState(null)
   const [results, setResults] = useState([])
-  const [query, setQuery] = useState('')
-  const [loading, setLoading] = useState(true)
 
   useEffect(() => {
-    async function initBrainy() {
-      // Auto-detects environment and uses OPFS storage in browsers
-      const db = new BrainyData({
-        defaultService: 'my-app'
-      })
+    const init = async () => {
+      const db = new BrainyData()
       await db.init()
-
-      // Add sample data
-      await db.add("Cats are amazing pets", { category: "animals" })
-      await db.add("Dogs love to play fetch", { category: "animals" })
-      await db.add("Pizza is delicious food", { category: "food" })
-
+      // Add your data...
       setBrainy(db)
-      setLoading(false)
     }
-
-    initBrainy()
+    init()
   }, [])
 
-  const search = async (searchQuery) => {
-    if (!searchQuery.trim() || !brainy) return setResults([])
-
-    const searchResults = await brainy.search(searchQuery, 5)
-    setResults(searchResults)
+  const search = async (query) => {
+    const results = await brainy?.search(query, 5) || []
+    setResults(results)
   }
 
-  if (loading) return <div>Initializing Brainy...</div>
-
-  return (
-    <div className="search-container">
-      <input
-        value={query}
-        onChange={(e) => {
-          setQuery(e.target.value)
-          search(e.target.value)
-        }}
-        placeholder="Search by meaning (try 'pets' or 'food')..."
-        className="search-input"
-      />
-
-      <div className="results">
-        {results.map((result, i) => (
-          <div key={result.id} className="result-item">
-            <strong>{result.metadata?.category}</strong>: {result.metadata?.originalData}
-            <small>Similarity: {result.score.toFixed(2)}</small>
-          </div>
-        ))}
-      </div>
-    </div>
-  )
+  return <input onChange={(e) => search(e.target.value)} placeholder="Search..." />
 }
-
-export default SemanticSearch
 ```
 
-### 🌟 Vue 3
+</details>
 
-```bash
-npm install @soulcraft/brainy
-```
+<details>
+<summary>📦 Full Vue Example</summary>
 
 ```vue
 
-<template>
-  <div class="search-container">
-    <input
-      v-model="query"
-      @input="search"
-      placeholder="Search by meaning (try 'pets' or 'food')..."
-      class="search-input"
-    />
-
-    <div v-if="loading" class="loading">
-      Initializing Brainy...
-    </div>
-
-    <div v-else class="results">
-      <div
-        v-for="result in results"
-        :key="result.id"
-        class="result-item"
-      >
-        <strong>{{ result.metadata?.category }}</strong>: {{ result.metadata?.originalData }}
-        <small>Similarity: {{ result.score.toFixed(2) }}</small>
-      </div>
-    </div>
-  </div>
-</template>
-
 <script setup>
   import { BrainyData } from '@soulcraft/brainy'
   import { ref, onMounted } from 'vue'
 
   const brainy = ref(null)
   const results = ref([])
-  const query = ref('')
-  const loading = ref(true)
 
   onMounted(async () => {
-    // Auto-detects environment and uses OPFS storage in browsers
-    const db = new BrainyData({
-      defaultService: 'my-app'
-    })
+    const db = new BrainyData()
     await db.init()
-
-    // Add sample data
-    await db.add("Cats are amazing pets", { category: "animals" })
-    await db.add("Dogs love to play fetch", { category: "animals" })
-    await db.add("Pizza is delicious food", { category: "food" })
-
+    // Add your data...
     brainy.value = db
-    loading.value = false
   })
 
-  const search = async () => {
-    if (!query.value.trim() || !brainy.value) {
-      results.value = []
-      return
-    }
-
-    const searchResults = await brainy.value.search(query.value, 5)
-    results.value = searchResults
+  const search = async (query) => {
+    const results = await brainy.value?.search(query, 5) || []
+    setResults(results)
   }
 </script>
 
-<style scoped>
-  .search-container {
-    max-width: 600px;
-    margin: 0 auto;
-    padding: 20px;
-  }
-
-  .search-input {
-    width: 100%;
-    padding: 12px;
-    margin-bottom: 20px;
-    border: 2px solid #ddd;
-    border-radius: 8px;
-  }
-
-  .result-item {
-    padding: 12px;
-    border: 1px solid #eee;
-    margin-bottom: 8px;
-    border-radius: 6px;
-  }
-
-  .loading {
-    text-align: center;
-    color: #666;
-  }
-</style>
-```
-
-### 🟢 Node.js Server
-
-```bash
-npm install @soulcraft/brainy
+<template>
+  <input @input="search($event.target.value)" placeholder="Search..." />
+</template>
 ```
 
-```javascript
-import { BrainyData } from '@soulcraft/brainy'
-
-// Auto-detects Node.js → FileSystem (local) or S3 (production), Worker threads
-const brainy = new BrainyData({
-  defaultService: 'my-app',
-  // Optional: Production S3 storage
-  storage: {
-    s3Storage: {
-      bucketName: process.env.S3_BUCKET,
-      region: process.env.AWS_REGION,
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
-    }
-  }
-})
-await brainy.init()
-
-// Same API everywhere
-await brainy.add("Cats are amazing pets", { category: "animals" })
-const results = await brainy.search("pets", 5)
-console.log('Search results:', results)
-```
+</details>
 
-### ⚡ Serverless (Vercel/Netlify)
+### 🟢 Node.js / Serverless / Edge
 
 ```javascript
 import { BrainyData } from '@soulcraft/brainy'
 
-export default async function handler(req, res) {
-  // Auto-detects serverless → S3/R2 storage for persistence, or Memory for temp
-  const brainy = new BrainyData({
-    defaultService: 'my-app',
-    // Optional: Explicit S3-compatible storage
-    storage: {
-      r2Storage: {
-        bucketName: process.env.R2_BUCKET,
-        accessKeyId: process.env.R2_ACCESS_KEY_ID,
-        secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
-        accountId: process.env.R2_ACCOUNT_ID
-      }
-    }
-  })
-  await brainy.init()
-
-  // Same API everywhere  
-  const results = await brainy.search(req.query.q, 5)
-  res.json({ results })
-}
-```
-
-### 🔥 Cloudflare Workers
+// SAME CODE works in Node.js, Vercel, Netlify, Cloudflare Workers, Deno, Bun
+const brainy = new BrainyData()
+await brainy.init()  // Auto-detects environment and optimizes
 
-```javascript
-import { BrainyData } from '@soulcraft/brainy'
+// Add entities and relationships
+await brainy.add("Python is great for data science", { type: "fact" })
+await brainy.add("JavaScript rules the web", { type: "fact" })
 
-export default {
-  async fetch(request) {
-    // Auto-detects edge → Minimal footprint, KV storage
-    const brainy = new BrainyData({
-      defaultService: 'edge-app'
-    })
-    await brainy.init()
+// Search by meaning
+const results = await brainy.search("programming languages", 5)
 
-    // Same API everywhere
-    const url = new URL(request.url)
-    const results = await brainy.search(url.searchParams.get('q'), 5)
-    return Response.json({ results })
+// Optional: Production with S3/R2 storage (auto-detected in cloud environments)
+const productionBrainy = new BrainyData({
+  storage: {
+    s3Storage: { bucketName: process.env.BUCKET_NAME }
   }
-}
-```
-
-### 🦕 Deno
-
-```typescript
-import { BrainyData } from 'https://esm.sh/@soulcraft/brainy'
-
-// Auto-detects Deno → Native compatibility, FileSystem storage
-const brainy = new BrainyData({
-  defaultService: 'deno-app'
 })
-await brainy.init()
-
-// Same API everywhere
-await brainy.add("Deno is awesome", { category: "tech" })
-const results = await brainy.search("technology", 5)
-console.log(results)
 ```
 
 **That's it! Same code, everywhere. Zero-to-Smart™**
@@ -510,7 +403,7 @@ Brainy automatically detects and optimizes for:
 
 ```dockerfile
 # One line extracts models automatically during build
-RUN npm run extract-models
+RUN npm run download-models
 
 # Deploy anywhere: Google Cloud, AWS, Azure, Cloudflare, etc.
 ```
@@ -577,6 +470,7 @@ console.log(`Instance ${health.instanceId}: ${health.status}`)
 ### Core Capabilities
 
 - **Vector Search** - Find semantically similar content using embeddings
+- **MongoDB-Style Metadata Filtering** 🆕 - Advanced filtering with `$gt`, `$in`, `$regex`, `$and`, `$or` operators
 - **Graph Relationships** - Connect data with meaningful relationships
 - **JSON Document Search** - Search within specific fields with prioritization
 - **Distributed Mode** - Scale horizontally with automatic coordination between instances
@@ -684,6 +578,7 @@ npm install @soulcraft/brainy @soulcraft/brainy-models
 - **🎯 Zero Configuration** - Automatic detection with graceful fallback
 - **🔐 Enhanced Security** - Complete air-gapping support for sensitive environments
 - **🏢 Enterprise Ready** - Works behind corporate firewalls and restricted networks
+- **⚖️ Compliance & Forensics** - Frozen mode for audit trails and legal discovery
 
 The offline models provide the **same functionality** with maximum reliability. Your existing code works unchanged -
 Brainy automatically detects and uses bundled models when available.
@@ -712,7 +607,7 @@ const brainy = createAutoBrainy({
 2. **Add to your Dockerfile:**
    ```dockerfile
    # Extract models during build (zero configuration!)
-   RUN npm run extract-models
+   RUN npm run download-models
    
    # Include models in final image
    COPY --from=builder /app/models ./models
@@ -730,15 +625,15 @@ const brainy = createAutoBrainy({
 ### Universal Dockerfile Template
 
 ```dockerfile
-FROM node:24-alpine AS builder
+FROM node:24-slim AS builder
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci
 COPY . .
-RUN npm run extract-models  # ← Automatic model extraction
+RUN npm run download-models  # ← Automatic model download
 RUN npm run build
 
-FROM node:24-alpine AS production  
+FROM node:24-slim AS production  
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --only=production --omit=optional
@@ -876,7 +771,8 @@ const writer = createAutoBrainy({
 
 const reader = createAutoBrainy({
   storage: { s3Storage: { bucketName: 'my-bucket' } },
-  readOnly: true,   // Automatically becomes 'reader' role
+  readOnly: true,   // Automatically becomes 'reader' role (allows optimizations)
+  // frozen: true,  // Optional: Complete immutability for compliance/forensics
   distributed: true
 })
 ```
@@ -938,6 +834,25 @@ const health = brainy.getHealthStatus()
 - **Writers**: Optimized write batching, minimal cache
 - **Hybrid**: Adaptive based on workload
 
+## ⚖️ Compliance & Forensics Mode
+
+For legal discovery, audit trails, and compliance requirements:
+
+```javascript
+// Create a completely immutable snapshot
+const auditDb = new BrainyData({
+  storage: { s3Storage: { bucketName: 'audit-snapshots' } },
+  readOnly: true,
+  frozen: true  // Complete immutability - no changes allowed
+})
+
+// Perfect for:
+// - Legal discovery (data cannot be modified)
+// - Compliance audits (guaranteed state)
+// - Forensic analysis (preserved evidence)
+// - Regulatory snapshots (unchanging records)
+```
+
 ### Deployment Examples
 
 **Docker Compose**
@@ -998,6 +913,13 @@ spec:
 ❌ **Neo4j** - Great for graphs, no vector support  
 ✅ **Brainy** - Vectors + graphs in one. Best of both worlds
 
+### vs. "Vector + Graph" Solutions
+
+❌ **Pinecone + Neo4j** - Two databases, sync nightmares, double the cost  
+❌ **pgvector + graph extension** - Hacked together, not native, performance issues  
+❌ **Weaviate "references"** - Limited graph capabilities, not true relationships  
+✅ **Brainy** - Purpose-built vector+graph architecture, single source of truth
+
 ### vs. DIY Solutions
 
 ❌ **Building your own** - Months of work, optimization nightmares  
@@ -1005,51 +927,41 @@ spec:
 
 ## 🚀 Getting Started in 30 Seconds
 
-### React
+**The same Brainy code works everywhere - React, Vue, Angular, Node.js, Serverless, Edge Workers.**
 
-```jsx
-import { createAutoBrainy } from 'brainy'
-import { useEffect, useState } from 'react'
+```javascript
+// This EXACT code works in ALL environments
+import { BrainyData } from '@soulcraft/brainy'
 
-function SemanticSearch() {
-  const [brainy] = useState(() => createAutoBrainy())
-  const [results, setResults] = useState([])
+const brainy = new BrainyData()
+await brainy.init()
 
-  const search = async (query) => {
-    const items = await brainy.searchText(query, 10)
-    setResults(items)
-  }
+// Add nouns (entities)
+const openai = await brainy.add("OpenAI", { type: "company" })
+const gpt4 = await brainy.add("GPT-4", { type: "product" })
 
-  return (
-    <input onChange={(e) => search(e.target.value)}
-           placeholder="Search by meaning..." />
-  )
-}
+// Add verbs (relationships)
+await brainy.relate(openai, gpt4, "develops")
+
+// Vector search + Graph traversal
+const similar = await brainy.search("AI companies", 5)
+const products = await brainy.getVerbsBySource(openai)
 ```
 
-### Angular
+<details>
+<summary>🔍 See Framework Examples</summary>
 
-```typescript
-import { Component, OnInit } from '@angular/core'
-import { createAutoBrainy } from 'brainy'
+### React
 
-@Component({
-  selector: 'app-search',
-  template: `
-    <input (input)="search($event.target.value)" 
-           placeholder="Semantic search...">
-    <div *ngFor="let result of results">
-      {{ result.text }}
-    </div>
-  `
-})
-export class SearchComponent implements OnInit {
-  brainy = createAutoBrainy()
-  results = []
+```jsx
+function App() {
+  const [brainy] = useState(() => new BrainyData())
+  useEffect(() => brainy.init(), [])
 
-  async search(query: string) {
-    this.results = await this.brainy.searchText(query, 10)
+  const search = async (query) => {
+    return await brainy.search(query, 10)
   }
+  // Same API as above
 }
 ```
 
@@ -1058,128 +970,66 @@ export class SearchComponent implements OnInit {
 ```vue
 
 <script setup>
-  import { createAutoBrainy } from 'brainy'
-  import { ref } from 'vue'
-
-  const brainy = createAutoBrainy()
-  const results = ref([])
-
-  const search = async (query) => {
-    results.value = await brainy.searchText(query, 10)
-  }
+  const brainy = new BrainyData()
+  await brainy.init()
+  // Same API as above
 </script>
-
-<template>
-  <input @input="search($event.target.value)"
-         placeholder="Find similar content...">
-  <div v-for="result in results" :key="result.id">
-    {{ result.text }}
-  </div>
-</template>
 ```
 
-### Svelte
-
-```svelte
-<script>
-  import { createAutoBrainy } from 'brainy'
-  
-  const brainy = createAutoBrainy()
-  let results = []
-  
-  async function search(e) {
-    results = await brainy.searchText(e.target.value, 10)
-  }
-</script>
+### Angular
 
-<input on:input={search} placeholder="AI-powered search...">
-{#each results as result}
-  <div>{result.text}</div>
-{/each}
-```
+```typescript
 
-### Next.js (App Router)
+@Component({})
+export class AppComponent {
+  brainy = new BrainyData()
 
-```jsx
-// app/search/page.js
-import { createAutoBrainy } from 'brainy'
-
-export default function SearchPage() {
-  async function search(formData) {
-    'use server'
-    const brainy = createAutoBrainy({ bucketName: 'vectors' })
-    const query = formData.get('query')
-    return await brainy.searchText(query, 10)
+  async ngOnInit() {
+    await this.brainy.init()
+    // Same API as above
   }
-
-  return (
-    <form action={search}>
-      <input name="query" placeholder="Search..." />
-      <button type="submit">Search</button>
-    </form>
-  )
 }
 ```
 
-### Node.js / Bun / Deno
+### Node.js / Deno / Bun
 
 ```javascript
-import { createAutoBrainy } from 'brainy'
-
-const brainy = createAutoBrainy()
-
-// Add some data
-await brainy.add("TypeScript is a typed superset of JavaScript", {
-  category: 'programming'
-})
-
-// Search for similar content
-const results = await brainy.searchText("JavaScript with types", 5)
-console.log(results)
+const brainy = new BrainyData()
+await brainy.init()
+// Same API as above
 ```
 
-### 🌍 Framework-First, Runs Everywhere
-
-**Brainy is designed for modern frameworks** with automatic environment detection and storage selection:
-
-**✨ Supported environments:**
+</details>
 
-- ⚛️ **React/Vue/Angular** - Framework-optimized builds with proper bundling
-- 🟢 **Node.js/Deno/Bun** - Full server-side capabilities
-- ⚡ **Serverless/Edge** - Optimized for cold starts and minimal footprint
-- 🧵 **Web/Worker threads** - Thread-safe, shared storage
-
-**🗄️ Auto-selected storage:**
+### 🌍 Framework-First, Runs Everywhere
 
-- 🌐 **OPFS** - Browser frameworks (persistent, fast)
-- 📁 **FileSystem** - Node.js servers (local development)
-- ☁️ **S3/R2/GCS** - Production, serverless, distributed deployments
-- 💾 **Memory** - Edge workers, testing, temporary data
+**Brainy automatically detects your environment and optimizes everything:**
 
-**🚀 Framework benefits:**
+| Environment     | Storage         | Optimization               |
+|-----------------|-----------------|----------------------------|
+| 🌐 Browser      | OPFS            | Web Workers, Memory Cache  |
+| 🟢 Node.js      | FileSystem / S3 | Worker Threads, Clustering |
+| ⚡ Serverless    | S3 / Memory     | Cold Start Optimization    |
+| 🔥 Edge Workers | Memory / KV     | Minimal Footprint          |
+| 🦕 Deno/Bun     | FileSystem / S3 | Native Performance         |
 
-- ✅ **Proper bundling** - Handles dynamic imports and dependencies correctly
-- ✅ **Type safety** - Full TypeScript integration and IntelliSense
-- ✅ **State management** - Reactive updates and component lifecycle
-- ✅ **Production ready** - Tree-shaking, optimization, error boundaries
+## 🌐 Deploy to Any Cloud
 
-**Note:** We focus on framework support for reliability. Vanilla JS had too many module resolution issues.
+<details>
+<summary>☁️ See Cloud Platform Examples</summary>
 
 ### Cloudflare Workers
 
 ```javascript
-import { createAutoBrainy } from 'brainy'
+import { BrainyData } from '@soulcraft/brainy'
 
 export default {
-  async fetch(request, env) {
-    const brainy = createAutoBrainy({
-      bucketName: env.R2_BUCKET
-    })
+  async fetch(request) {
+    const brainy = new BrainyData()
+    await brainy.init()
 
     const url = new URL(request.url)
-    const query = url.searchParams.get('q')
-
-    const results = await brainy.searchText(query, 10)
+    const results = await brainy.search(url.searchParams.get('q'), 10)
     return Response.json(results)
   }
 }
@@ -1188,156 +1038,54 @@ export default {
 ### AWS Lambda
 
 ```javascript
-import { createAutoBrainy } from 'brainy'
+import { BrainyData } from '@soulcraft/brainy'
 
 export const handler = async (event) => {
-  const brainy = createAutoBrainy({
-    bucketName: process.env.S3_BUCKET
-  })
-
-  const results = await brainy.searchText(event.query, 10)
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify(results)
-  }
-}
-```
-
-### Azure Functions
-
-```javascript
-import { createAutoBrainy } from 'brainy'
-
-module.exports = async function(context, req) {
-  const brainy = createAutoBrainy({
-    bucketName: process.env.AZURE_STORAGE_CONTAINER
-  })
-
-  const results = await brainy.searchText(req.query.q, 10)
+  const brainy = new BrainyData()
+  await brainy.init()
 
-  context.res = {
-    body: results
-  }
+  const results = await brainy.search(event.query, 10)
+  return { statusCode: 200, body: JSON.stringify(results) }
 }
 ```
 
 ### Google Cloud Functions
 
 ```javascript
-import { createAutoBrainy } from 'brainy'
+import { BrainyData } from '@soulcraft/brainy'
 
 export const searchHandler = async (req, res) => {
-  const brainy = createAutoBrainy({
-    bucketName: process.env.GCS_BUCKET
-  })
+  const brainy = new BrainyData()
+  await brainy.init()
 
-  const results = await brainy.searchText(req.query.q, 10)
+  const results = await brainy.search(req.query.q, 10)
   res.json(results)
 }
 ```
 
-### Google Cloud Run
-
-```dockerfile
-# Dockerfile
-FROM node:20-alpine
-USER node
-WORKDIR /app
-COPY package*.json ./
-RUN npm install brainy
-COPY . .
-CMD ["node", "server.js"]
-```
-
-```javascript
-// server.js
-import { createAutoBrainy } from 'brainy'
-import express from 'express'
-
-const app = express()
-const brainy = createAutoBrainy({
-  bucketName: process.env.GCS_BUCKET
-})
-
-app.get('/search', async (req, res) => {
-  const results = await brainy.searchText(req.query.q, 10)
-  res.json(results)
-})
-
-const port = process.env.PORT || 8080
-app.listen(port, () => console.log(`Brainy on Cloud Run: ${port}`))
-```
-
-```bash
-# Deploy to Cloud Run
-gcloud run deploy brainy-api \
-  --source . \
-  --platform managed \
-  --region us-central1 \
-  --allow-unauthenticated
-```
-
 ### Vercel Edge Functions
 
 ```javascript
-import { createAutoBrainy } from 'brainy'
+import { BrainyData } from '@soulcraft/brainy'
 
-export const config = {
-  runtime: 'edge'
-}
+export const config = { runtime: 'edge' }
 
 export default async function handler(request) {
-  const brainy = createAutoBrainy()
-  const { searchParams } = new URL(request.url)
-  const query = searchParams.get('q')
+  const brainy = new BrainyData()
+  await brainy.init()
 
-  const results = await brainy.searchText(query, 10)
+  const { searchParams } = new URL(request.url)
+  const results = await brainy.search(searchParams.get('q'), 10)
   return Response.json(results)
 }
 ```
 
-### Netlify Functions
-
-```javascript
-import { createAutoBrainy } from 'brainy'
-
-export async function handler(event, context) {
-  const brainy = createAutoBrainy()
-  const query = event.queryStringParameters.q
-
-  const results = await brainy.searchText(query, 10)
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify(results)
-  }
-}
-```
-
-### Supabase Edge Functions
-
-```typescript
-import { createAutoBrainy } from 'brainy'
-import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
-
-serve(async (req) => {
-  const brainy = createAutoBrainy()
-  const url = new URL(req.url)
-  const query = url.searchParams.get('q')
-
-  const results = await brainy.searchText(query, 10)
-
-  return new Response(JSON.stringify(results), {
-    headers: { 'Content-Type': 'application/json' }
-  })
-})
-```
+</details>
 
 ### Docker Container
 
 ```dockerfile
-FROM node:20-alpine
+FROM node:24-slim
 USER node
 WORKDIR /app
 COPY package*.json ./
@@ -1420,6 +1168,7 @@ services:
 
 - [**Search and Metadata**](docs/user-guides/) - Advanced search techniques
 - [**JSON Document Search**](docs/guides/json-document-search.md) - Field-based searching
+- [**Read-Only & Frozen Modes**](docs/guides/readonly-frozen-modes.md) - Immutability options for production
 - [**Production Migration**](docs/guides/production-migration-guide.md) - Deployment best practices
 
 ### API Reference