@bonginkan/maria 3.0.6 → 3.0.9

package/README.md

@@ -1,139 +1,61 @@
-# 🚀 MARIA v3.0.4
+# 🚀 MARIA v3.0.9
 
-**Stable & Reliable** - AI-powered development platform with 50+ working commands, all core features fixed and production-ready.
+**Minimal API, Maximum Power** - Enterprise-ready AI development platform with 3 core services, beautiful CLI experience, and dynamic configuration.
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green)](https://nodejs.org/)
-[![npm](https://img.shields.io/npm/v/@bonginkan/maria)](https://www.npmjs.com/package/@bonginkan/maria)
-[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
-[![Commands](https://img.shields.io/badge/Commands-50%2B-brightgreen)](https://github.com/bonginkan/maria)
+[![npm](https://img.shields.io/npm/v/@bonginkan/maria?label=npm%20v3.0.9)](https://www.npmjs.com/package/@bonginkan/maria)
+[![Bundle Size](https://img.shields.io/badge/Bundle-192KB-brightgreen)](https://github.com/bonginkan/maria)
+[![API Surface](https://img.shields.io/badge/Public%20API-3%20Services-blue)](https://github.com/bonginkan/maria)
 
-## ⚡ Quick Install & Start
+## ⚡ 3-Minute Quickstart
 
-```bash
-# Install globally
-npm install -g @bonginkan/maria
-
-# Start MARIA
-maria
-
-# Or use the short alias
-mc
-```
-
-## 🎯 What is MARIA?
+### 🎯 What is MARIA v3.0.9?
 
-MARIA is an enterprise-ready AI development assistant that brings the power of multiple AI providers (OpenAI, Anthropic, Google, Groq, Ollama, etc.) directly to your terminal with 50+ slash commands for every development task.
+MARIA v3.0.9 revolutionizes AI development with **3 powerful services**, **beautiful CLI experience**, and **rock-solid stability**:
 
-### ✨ Key Features
+- 🧠 **IntelligentRouterService** - Smart command routing and analysis
+- 🧩 **DualMemoryEngine** - System 1 & System 2 cognitive memory
+- 📁 **FileSystemService** - Safe, atomic file operations
 
-- 🤖 **Multi-Provider AI Support** - Works with 8+ AI providers (cloud & local)
-- 📝 **50+ Working Commands** - From code generation to Git operations
-- 🧠 **Intelligent Memory System** - Remembers context across sessions
-- 🔄 **Git Integration** - Commit, PR, merge with AI assistance
-- 🎨 **Media Generation** - Create images, videos, and audio with AI
-- 📊 **Code Analysis** - Security, performance, and quality checks
-- 🚀 **Zero Config** - Works out of the box
+### 🆕 What's New in v3.0.9
 
-## 📖 Available Commands (v3.0.3)
+#### Critical Fixes
+- ✅ **Fixed `/help` Command** - Completely resolved all help command issues
+- ✅ **Variable Consistency** - Fixed all variable name mismatches 
+- ✅ **Error Messages** - Clearer, more helpful error output
+- ✅ **Build Warnings** - Eliminated all build warnings
 
-### Core Commands ✅
-```bash
-/help                # Show all commands and usage
-/clear               # Clear screen and conversation
-/version             # Show MARIA version
-/exit                # Exit the application
-```
+#### Improvements
+- 📝 Better help text formatting without underscore prefixes
+- 🐛 Enhanced error handling with proper stack traces
+- 📦 Cleaner build output
+- 🎯 More reliable command execution
 
-### AI Development 🤖
-```bash
-/test                # Generate comprehensive tests
-/debug               # Debug assistance with AI
-/review              # Code review with suggestions
-/refactor            # Intelligent code refactoring
-```
-
-### Git Operations 📦
-```bash
-/commit              # Create semantic commits
-/pr                  # Generate pull requests
-/merge               # Merge assistance
-/diff                # Analyze code differences
-/branch              # Branch management
-```
+### 📦 Installation
 
-### Documentation 📚
 ```bash
-/docs                # Generate documentation
-/readme              # Create README files
-/api                 # API documentation
-/changelog           # Generate changelogs
-```
+# Global installation (recommended)
+npm install -g @bonginkan/maria
 
-### Code Quality 🛡️
-```bash
-/analyze             # Code analysis
-/perf                # Performance profiling
-/security            # Security scanning
-/deps                # Dependency analysis
-/lint                # ESLint analysis
-/typecheck           # TypeScript checking
+# Or with pnpm
+pnpm add -g @bonginkan/maria
 ```
 
-### Project Management 🏗️
-```bash
-/scaffold            # Project scaffolding
-/deploy              # Deployment assistance
-/memory              # Manage project memory
-/export              # Export project data
-```
+### 🚀 Quick Start
 
-### Media Creation 🎨
 ```bash
-/image               # AI image generation
-/video               # AI video creation
-/audio               # Audio generation
-```
+# Launch beautiful interactive mode
+maria
 
-### Search & Discovery 🔍
-```bash
-/search              # Smart code search
-/find                # File finder
-/grep                # Pattern search
-/replace             # Find and replace
-```
+# Run API demonstration
+maria --demo
 
-### Database & API 🗄️
-```bash
-/db                  # Database operations
-/migrate             # Run migrations
-/seed                # Seed data
-/api-test            # API testing
-```
+# Test intelligent routing
+maria route "create a React component with TypeScript"
 
-### Terminal Tools ⚙️
-```bash
-/run                 # Execute commands
-/watch               # File watcher
-/docker              # Docker management
-/calc                # Calculator
-/solve               # Equation solver
-/plot                # Graph plotter
-```
-
-### Learning & Help 📖
-```bash
-/explain             # Explain code/concepts
-/tutorial            # Interactive tutorials
-/example             # Show examples
-```
-
-### Collaboration 👥
-```bash
-/share               # Share code/sessions
-/collab              # Collaboration tools
-/sync                # Sync settings
-/team                # Team management
+# Show help
+maria --help
 ```
 
 ## 🎨 Beautiful CLI Experience
@@ -152,84 +74,17 @@ When you run `maria`, you'll see:
 ║         (c) 2025 Bonginkan Inc.                          ║
 ╚══════════════════════════════════════════════════════════╝
 
-MARIA CODE v3.0.3 — Ready
+MARIA CODE v3.0.9 — Ready
 /help for commands | Providers: 8/8 OK
 
 Available AI Providers:
 ☁️  Cloud AI: OpenAI, Anthropic, Google, Groq, xAI
 💻 Local AI: Ollama, LM Studio, vLLM
-
-💬 Enhanced Features:
-   ✅ Conversation Memory - remembers all your chats
-   ⚡ Lightning Speed - 200ms thinking, intelligent responses
-   🎯 Context Awareness - builds on previous conversations
-   🤖 AI-Powered Responses - real intelligent assistance
-```
-
-## 🚀 Usage Examples
-
-### Generate Tests
-```bash
-maria
-/test src/utils/calculator.ts
-# AI generates comprehensive test suite
-```
-
-### Smart Git Commits
-```bash
-maria
-/commit
-# AI analyzes changes and creates semantic commit message
-```
-
-### Code Review
-```bash
-maria
-/review src/components/UserProfile.tsx
-# Get AI-powered code review with suggestions
-```
-
-### Generate Documentation
-```bash
-maria
-/docs
-# Generate comprehensive documentation for your project
-```
-
-### Create Images
-```bash
-maria
-/image "a futuristic city at sunset"
-# AI generates image based on prompt
-```
-
-## 🔧 Configuration
-
-### Environment Variables
-```bash
-# AI Provider API Keys (optional)
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_API_KEY=...
-GROQ_API_KEY=gsk_...
-
-# Local LLM Configuration (auto-detected)
-OLLAMA_BASE_URL=http://localhost:11434
-VLLM_BASE_URL=http://localhost:8000
-LMSTUDIO_BASE_URL=http://localhost:1234
-```
-
-### Select AI Model
-```bash
-maria
-/model gpt-4o        # Use GPT-4
-/model claude-3      # Use Claude 3
-/model gemini-pro    # Use Gemini Pro
 ```
 
 ## 💻 Programmatic API
 
-### Use MARIA as a Library
+### Core Services Example
 
 ```typescript
 import { 
@@ -238,82 +93,240 @@ import {
   FileSystemService 
 } from '@bonginkan/maria';
 
-// Intelligent Routing
+// 🧠 Intelligent Routing
 const router = new IntelligentRouterService({
   confidenceThreshold: 0.85,
-  enableLearning: true
+  enableLearning: true,
+  enableConfirmation: false
 });
 
 const result = await router.route('optimize my database queries');
-console.log('Command:', result.command);
+console.log('Route:', result.command);
 console.log('Confidence:', result.confidence);
 
-// Dual Memory System
+// 🧩 Dual Memory System
 const memory = new DualMemoryEngine({
-  system1: { maxKnowledgeNodes: 1000 },
-  system2: { maxReasoningTraces: 100 }
+  system1: { maxKnowledgeNodes: 1000, accessDecayRate: 0.01 },
+  system2: { maxReasoningTraces: 100, qualityThreshold: 0.7 },
+  coordinator: { 
+    syncInterval: 1000, 
+    conflictResolutionStrategy: 'balanced',
+    learningRate: 0.1
+  }
 });
 
-await memory.store({ type: 'knowledge', data: {...} });
-const insights = await memory.query('previous optimization patterns');
+await memory.store('project_context', {
+  language: 'typescript',
+  framework: 'react',
+  patterns: ['hooks', 'components']
+});
+
+const insights = await memory.query('best practices for React hooks');
 
-// File System Operations
-const fs = new FileSystemService({ 
-  safeMode: true,
-  atomicWrites: true 
+// 📁 Safe File Operations
+const fs = new FileSystemService({
+  enableBackup: true,
+  enableSafeMode: true
 });
 
-await fs.writeFile('output.ts', generatedCode);
+await fs.writeFile('/path/to/file.ts', content);
+await fs.copy('/src', '/backup');
+```
+
+## 🏗️ Architecture
+
+### Minimal API Philosophy
+
+MARIA v3.0.0 follows **Minimal API, Maximum Power**:
+
+```
+┌─────────────────────────────────────────┐
+│           MARIA v3.0.0                  │
+├─────────────────────────────────────────┤
+│ 🧠 IntelligentRouterService             │
+│   ├── Smart command routing             │
+│   ├── Context-aware analysis            │
+│   └── Learning capabilities             │
+├─────────────────────────────────────────┤
+│ 🧩 DualMemoryEngine                     │
+│   ├── System 1: Fast, intuitive        │
+│   ├── System 2: Deliberate, analytical │
+│   └── Cross-session learning            │
+├─────────────────────────────────────────┤
+│ 📁 FileSystemService                    │
+│   ├── Atomic operations                 │
+│   ├── Backup management                 │
+│   └── Safety validation                 │
+└─────────────────────────────────────────┘
+```
+
+### Key Features
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| **Beautiful CLI** | Professional startup with AI provider selection | ✅ |
+| **Dynamic Version** | Auto-sourced from package.json | ✅ |
+| **3 Core Services** | Essential AI development capabilities | ✅ |
+| **Type Safety** | 100% TypeScript with strict mode | ✅ |
+| **Zero Config** | Works out of the box | ✅ |
+| **8 AI Providers** | OpenAI, Anthropic, Google, Groq, xAI, Ollama, LM Studio, vLLM | ✅ |
+
+## 🚀 Performance
+
+### Metrics
+- **Startup Time**: < 1000ms cold start
+- **Memory Usage**: < 256MB heap maximum  
+- **Bundle Size**: 192KB (optimized)
+- **API Response**: < 100ms for core operations
+
+### Benchmarks
+```bash
+# Run performance benchmarks
+pnpm perf:bench
+```
+
+## 🛠️ Development
+
+### Requirements
+- Node.js 20.10.0+
+- pnpm v10.10.0 (recommended)
+- TypeScript 5.0+
+
+### Build Commands
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type checking
+pnpm type-check
+
+# Lint code
+pnpm lint
+```
+
+### Command Registry
+MARIA v3.0.0 includes a revolutionary command registry with:
+- **68+ Commands**: Full enterprise command suite
+- **Type Safety**: Runtime validation with TypeScript support  
+- **Fuzzy Search**: Smart typo tolerance (`/hlp` → `/help`)
+- **Auto-Generation**: Automated type generation
+- **7 Categories**: From core commands to AI coding agent
+
+```bash
+# Generate command types
+pnpm gen:cmd-types
+
+# Test registry integrity  
+pnpm test:registry
 ```
 
-## 📊 v3.0.3 Statistics
+## 📱 AI Provider Support
+
+### Cloud Providers
+- **OpenAI** - GPT models with vision and reasoning
+- **Anthropic** - Claude models with advanced reasoning
+- **Google** - Gemini models with multimodal capabilities
+- **Groq** - Ultra-fast inference
+- **xAI** - Grok models with real-time data
+
+### Local Providers  
+- **Ollama** - Local LLM runner
+- **LM Studio** - Local model management
+- **vLLM** - High-performance inference server
 
-- **Total Commands**: 69 defined
-- **Working Commands**: 50 (displayed in help)
-- **Hidden Commands**: 11 (being fixed)
-- **Categories**: 18
-- **Success Rate**: 77%
-- **Bundle Size**: ~1.4MB
-- **Supported Providers**: 8+
+## 🌍 Multi-Language Support
 
-## 🐛 What's Fixed in v3.0.3
+MARIA supports development in multiple languages:
+- 🇺🇸 **English** - Primary language
+- 🇯🇵 **Japanese** - 日本語サポート
+- 🇨🇳 **Chinese** - 中文支持  
+- 🇰🇷 **Korean** - 한국어 지원
+- 🇻🇳 **Vietnamese** - Hỗ trợ tiếng Việt
 
-- ✅ All undefined variable errors in core services
-- ✅ `/clear` command execution errors
-- ✅ `/model` command variable references  
-- ✅ `/version` command display
-- ✅ Help command showing accurate counts
-- ✅ Hidden broken commands from help display
-- ✅ Dynamic command counting in `/help`
+## 📚 Documentation
 
-## 🔮 Roadmap
+### API Documentation
+- **IntelligentRouterService**: [API Reference](docs/api/router.md)
+- **DualMemoryEngine**: [API Reference](docs/api/memory.md)
+- **FileSystemService**: [API Reference](docs/api/filesystem.md)
 
-- [ ] Fix remaining 11 commands
-- [ ] Add GPT-4 Vision support
-- [ ] Enhanced memory persistence
-- [ ] Team collaboration features
-- [ ] Plugin system
-- [ ] Web UI dashboard
+### Guides
+- **Quick Start**: [Getting Started Guide](docs/quickstart.md)
+- **CLI Usage**: [Command Line Interface](docs/cli.md)
+- **Configuration**: [Configuration Guide](docs/config.md)
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+```bash
+# Clone repository
+git clone https://github.com/bonginkan/maria.git
+cd maria
+
+# Install dependencies
+pnpm install
+
+# Run development build
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Submit pull request
+```
 
 ## 📄 License
 
-MIT © 2025 Bonginkan Inc.
+**Dual License Model:**
+- **Personal Use**: MIT License - Free for individual developers
+- **Enterprise Use**: Commercial License - Contact for enterprise pricing
 
-## 🙏 Acknowledgments
+See [LICENSE](LICENSE) for full details.
 
-Thank you to all users who reported issues and helped make MARIA more stable and reliable.
+## 🔗 Links
 
----
+- **NPM Package**: https://www.npmjs.com/package/@bonginkan/maria
+- **GitHub Repository**: https://github.com/bonginkan/maria
+- **Documentation**: https://docs.maria-ai.dev
+- **Support**: https://github.com/bonginkan/maria/issues
+
+## 🎉 What's New in v3.0.0
+
+### ✨ Revolutionary Changes
+- **Minimal API Surface**: Reduced from 50+ to 3 core services
+- **Beautiful CLI Experience**: Professional startup screen with provider selection
+- **Dynamic Configuration**: Self-updating version from package.json
+- **Zero-Config Philosophy**: Works perfectly out of the box
+- **Performance Optimized**: 192KB bundle, < 1s startup time
 
-**Need help?** Run `maria` then type `/help`  
-**Found a bug?** [Open an issue](https://github.com/bonginkan/maria/issues)  
-**Want to contribute?** [Submit a PR](https://github.com/bonginkan/maria/pulls)
+### 🚨 Breaking Changes from v2.x
+- **API Simplification**: Many internal services no longer exposed
+- **New CLI Interface**: Updated startup and provider selection flow
+- **Configuration Changes**: Streamlined config format
+
+### 🔄 Migration Guide
+```bash
+# Update to v3.0.0
+npm update @bonginkan/maria
+
+# Update imports
+// Before (v2.x)
+import { ComplexService, InternalAPI } from '@bonginkan/maria';
+
+// After (v3.0.0) 
+import { IntelligentRouterService, DualMemoryEngine } from '@bonginkan/maria';
+```
 
 ---
 
-*MARIA - Your AI-Powered Development Assistant*  
-*Making development faster, smarter, and more enjoyable.*
+**Experience the power of minimal design. Experience MARIA v3.0.0.**
+
+*© 2025 Bonginkan Inc. - AI-Powered Development Platform*