feat: implement zero-config system with Node.js 22 compatibility

- Add comprehensive zero-config preset system (production, development, minimal)
- Implement intelligent auto-configuration for models and storage
- Add Node.js version enforcement for ONNX Runtime stability
- Force single-threaded ONNX operations to prevent V8 HandleScope crashes
- Create extensible configuration architecture
- Add 14 distributed system presets for enterprise deployments
- Include detailed documentation and migration guides

BREAKING CHANGE: Now requires Node.js 22.x LTS for optimal stability

src/utils/embedding.ts

@@ -17,9 +17,10 @@ import { pipeline, env } from '@huggingface/transformers'
 if (typeof process !== 'undefined' && process.env) {
   process.env.ORT_DISABLE_MEMORY_ARENA = '1'
   process.env.ORT_DISABLE_MEMORY_PATTERN = '1'
-  // Also limit ONNX thread count for more predictable memory usage
-  process.env.ORT_INTRA_OP_NUM_THREADS = '2'
-  process.env.ORT_INTER_OP_NUM_THREADS = '2'
+  // Force single-threaded operation for maximum stability (Node.js 24 compatibility)
+  process.env.ORT_INTRA_OP_NUM_THREADS = '1'    // Single thread for operators
+  process.env.ORT_INTER_OP_NUM_THREADS = '1'    // Single thread for sessions
+  process.env.ORT_NUM_THREADS = '1'             // Additional safety override
 }
 
 /**
@@ -111,7 +112,7 @@ export class TransformerEmbedding implements EmbeddingModel {
       // 1. Explicit option takes highest priority
       localFilesOnly = options.localFilesOnly
     } else if (process.env.BRAINY_ALLOW_REMOTE_MODELS === 'false') {
-      // 2. Environment variable explicitly disables remote models
+      // 2. Environment variable explicitly disables remote models (legacy support)
       localFilesOnly = true
     } else if (process.env.NODE_ENV === 'development') {
       // 3. Development mode allows remote models
@@ -313,9 +314,9 @@ export class TransformerEmbedding implements EmbeddingModel {
         session_options: {
           enableCpuMemArena: false,  // Disable pre-allocated memory arena
           enableMemPattern: false,   // Disable memory pattern optimization
-          interOpNumThreads: 2,      // Limit thread count
-          intraOpNumThreads: 2,      // Limit parallelism
-          graphOptimizationLevel: 'all'
+          interOpNumThreads: 1,      // Force single thread for V8 stability
+          intraOpNumThreads: 1,      // Force single thread for V8 stability
+          graphOptimizationLevel: 'disabled'  // Disable threading optimizations
         }
       }
       
@@ -367,8 +368,8 @@ export class TransformerEmbedding implements EmbeddingModel {
               // Both local and remote failed - throw comprehensive error
               const errorMsg = `Failed to load embedding model "${this.options.model}". ` +
                               `Local models not found and remote download failed. ` +
-                              `To fix: 1) Set BRAINY_ALLOW_REMOTE_MODELS=true, ` +
-                              `2) Run "npm run download-models", or ` +
+                              `To fix: 1) Run "npm run download-models", ` +
+                              `2) Check your internet connection, or ` +
                               `3) Use a custom embedding function.`
               throw new Error(errorMsg)
             }

src/utils/nodeVersionCheck.ts

@@ -0,0 +1,81 @@
+/**
+ * Node.js Version Compatibility Check
+ * 
+ * Brainy requires Node.js 22.x LTS for maximum stability with ONNX Runtime.
+ * This prevents V8 HandleScope locking issues in worker threads.
+ */
+
+export interface VersionInfo {
+  current: string
+  major: number
+  isSupported: boolean
+  recommendation: string
+}
+
+/**
+ * Check if the current Node.js version is supported
+ */
+export function checkNodeVersion(): VersionInfo {
+  const nodeVersion = process.version
+  const majorVersion = parseInt(nodeVersion.split('.')[0].substring(1))
+  
+  const versionInfo: VersionInfo = {
+    current: nodeVersion,
+    major: majorVersion,
+    isSupported: majorVersion === 22,
+    recommendation: 'Node.js 22.x LTS'
+  }
+  
+  return versionInfo
+}
+
+/**
+ * Enforce Node.js version requirement with helpful error messaging
+ */
+export function enforceNodeVersion(): void {
+  const versionInfo = checkNodeVersion()
+  
+  if (!versionInfo.isSupported) {
+    const errorMessage = [
+      '🚨 BRAINY COMPATIBILITY ERROR',
+      '━'.repeat(50),
+      `❌ Current Node.js: ${versionInfo.current}`,
+      `✅ Required: ${versionInfo.recommendation}`,
+      '',
+      '💡 Quick Fix:',
+      '  nvm install 22 && nvm use 22',
+      '  npm install',
+      '',
+      '📖 Why Node.js 22?',
+      '  • Maximum ONNX Runtime stability',
+      '  • Prevents V8 threading crashes',
+      '  • Optimal zero-config performance',
+      '',
+      '🔗 More info: https://github.com/soulcraftlabs/brainy#node-version',
+      '━'.repeat(50)
+    ].join('\n')
+    
+    throw new Error(errorMessage)
+  }
+}
+
+/**
+ * Soft warning for version issues (non-blocking)
+ */
+export function warnNodeVersion(): boolean {
+  const versionInfo = checkNodeVersion()
+  
+  if (!versionInfo.isSupported) {
+    console.warn([
+      '⚠️  BRAINY VERSION WARNING',
+      `   Current: ${versionInfo.current}`,
+      `   Recommended: ${versionInfo.recommendation}`,
+      '   Consider upgrading for best stability',
+      ''
+    ].join('\n'))
+    
+    return false
+  }
+  
+  return true
+}