feat(docs): add comprehensive user guides and installation instructions for Brainy

docs/getting-started/installation.md

@@ -0,0 +1,321 @@
+# Installation Guide
+
+This guide covers installing Brainy and setting up your development environment.
+
+## 📦 Package Installation
+
+### Core Package
+
+```bash
+npm install @soulcraft/brainy
+```
+
+The core package includes everything you need:
+- ✅ Vector database with HNSW indexing
+- ✅ Auto-configuration and optimization
+- ✅ All storage adapters (Memory, FileSystem, OPFS, S3)
+- ✅ TensorFlow.js integration
+- ✅ Cross-environment compatibility
+
+### Optional Packages
+
+#### CLI Tools
+
+```bash
+npm install -g @soulcraft/brainy-cli
+```
+
+Command-line interface for:
+- Database management
+- Bulk operations  
+- Performance testing
+- Data visualization
+
+#### Web Service
+
+```bash
+npm install @soulcraft/brainy-web-service
+```
+
+REST API wrapper for:
+- HTTP endpoints
+- Remote database access
+- Microservice integration
+
+## 🌐 Environment Requirements
+
+### Node.js
+
+- **Minimum**: Node.js 24.4.0+
+- **Recommended**: Node.js 20+ or latest LTS
+- **Package Manager**: npm, yarn, or pnpm
+
+```bash
+node --version  # Should be 24.4.0+
+npm --version   # Any recent version
+```
+
+### Browser
+
+Modern browsers with ES Modules support:
+- **Chrome**: 86+
+- **Edge**: 86+
+- **Opera**: 72+
+- **Firefox**: 78+
+- **Safari**: 14+
+
+#### Optional Browser Features
+
+- **OPFS Support**: For persistent storage (Chrome 86+, Edge 86+)
+- **Web Workers**: For parallel processing (all modern browsers)
+- **WebGL**: For GPU acceleration (most modern browsers)
+
+### Memory Requirements
+
+| Use Case | Minimum RAM | Recommended RAM |
+|----------|-------------|-----------------|
+| Development | 512MB | 2GB |
+| Small datasets (<10k vectors) | 1GB | 4GB |
+| Medium datasets (<100k vectors) | 2GB | 8GB |
+| Large datasets (1M+ vectors) | 4GB | 16GB+ |
+
+### Storage Requirements
+
+| Dataset Size | Minimum Storage | Recommended Storage |
+|-------------|-----------------|-------------------|
+| <10k vectors | 100MB | 500MB |
+| <100k vectors | 1GB | 5GB |
+| <1M vectors | 10GB | 50GB |
+| 1M+ vectors | 50GB+ | Dataset size × 3 |
+
+## ✅ Installation Verification
+
+### Basic Verification
+
+```typescript
+import { BrainyData } from '@soulcraft/brainy'
+
+console.log('Brainy installed successfully!')
+
+// Test auto-configuration
+import { createAutoBrainy } from '@soulcraft/brainy'
+const brainy = createAutoBrainy()
+console.log('Auto-configuration works!')
+```
+
+### Environment Detection Test
+
+```typescript
+import { environment } from '@soulcraft/brainy'
+
+console.log(`Environment: ${
+  environment.isBrowser ? 'Browser' :
+  environment.isNode ? 'Node.js' :
+  'Unknown'
+}`)
+
+console.log(`Threading available: ${environment.isThreadingAvailable()}`)
+```
+
+### Storage Test
+
+```typescript
+import { createAutoBrainy } from '@soulcraft/brainy'
+
+const brainy = createAutoBrainy()
+
+// Add a test vector
+await brainy.addVector({ 
+  id: 'test-1', 
+  vector: [0.1, 0.2, 0.3], 
+  text: 'Installation test' 
+})
+
+// Search for it
+const results = await brainy.search([0.1, 0.2, 0.3], 1)
+console.log('Storage test passed:', results.length > 0)
+```
+
+## 🔧 Development Setup
+
+### TypeScript Configuration
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "lib": ["ES2022", "DOM", "WebWorker"],
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+### Bundler Configuration
+
+#### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  optimizeDeps: {
+    include: ['@soulcraft/brainy']
+  },
+  define: {
+    global: 'globalThis'
+  }
+})
+```
+
+#### Webpack
+
+```javascript
+// webpack.config.js
+module.exports = {
+  resolve: {
+    fallback: {
+      "buffer": require.resolve("buffer"),
+      "util": require.resolve("util")
+    }
+  },
+  plugins: [
+    new webpack.ProvidePlugin({
+      Buffer: ['buffer', 'Buffer'],
+      process: 'process/browser'
+    })
+  ]
+}
+```
+
+#### Rollup
+
+```javascript
+// rollup.config.js
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+import { nodePolyfills } from 'rollup-plugin-polyfill-node'
+
+export default {
+  plugins: [
+    nodePolyfills(),
+    nodeResolve({ browser: true, preferBuiltins: false })
+  ]
+}
+```
+
+## 🚀 Production Setup
+
+### Environment Variables
+
+For S3 storage in production:
+
+```bash
+# AWS Configuration
+AWS_ACCESS_KEY_ID=your_access_key
+AWS_SECRET_ACCESS_KEY=your_secret_key
+AWS_REGION=us-east-1
+
+# Optional S3 Configuration
+S3_BUCKET_NAME=your-vector-storage
+S3_ENDPOINT=https://s3.amazonaws.com
+```
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+EXPOSE 3000
+
+# Set memory limit for large datasets
+ENV NODE_OPTIONS="--max-old-space-size=8192"
+
+CMD ["node", "index.js"]
+```
+
+### Performance Optimizations
+
+```typescript
+// Production configuration
+import { createAutoBrainy } from '@soulcraft/brainy'
+
+const brainy = createAutoBrainy({
+  // S3 storage for persistence
+  bucketName: process.env.S3_BUCKET_NAME,
+  region: process.env.AWS_REGION
+})
+
+// System auto-configures based on:
+// - Available memory
+// - CPU cores  
+// - Dataset size
+// - Environment type
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+#### "Module not found" errors
+
+**Solution**: Ensure your bundler is configured for ES modules:
+
+```json
+{
+  "type": "module"
+}
+```
+
+#### Out of memory errors
+
+**Solution**: Increase Node.js memory limit:
+
+```bash
+node --max-old-space-size=8192 your-script.js
+```
+
+#### TensorFlow.js loading issues
+
+**Solution**: The auto-patcher handles this, but if needed:
+
+```typescript
+import '@soulcraft/brainy/setup'  // Import before other modules
+import { BrainyData } from '@soulcraft/brainy'
+```
+
+#### Browser compatibility issues
+
+**Solution**: Check browser requirements and enable feature detection:
+
+```typescript
+import { environment } from '@soulcraft/brainy'
+
+if (!environment.isBrowser) {
+  console.error('This app requires a modern browser')
+}
+```
+
+### Getting Help
+
+- 📚 [Troubleshooting Guide](../troubleshooting/)
+- 🐛 [GitHub Issues](https://github.com/soulcraft-research/brainy/issues)
+- 💬 [GitHub Discussions](https://github.com/soulcraft-research/brainy/discussions)
+
+## ✅ Next Steps
+
+Once installation is complete:
+
+1. **[Quick Start Guide](quick-start.md)** - Your first Brainy app
+2. **[Environment Setup](environment-setup.md)** - Optimize your environment  
+3. **[First Steps](first-steps.md)** - Learn core concepts