@bonginkan/maria 3.0.0 → 3.0.3

package/README.md

@@ -1,47 +1,139 @@
-# 🚀 MARIA v3.0.0
+# 🚀 MARIA v3.0.3
 
-**Minimal API, Maximum Power** - Enterprise-ready AI development platform with 3 core services, beautiful CLI experience, and dynamic configuration.
+**Stable & Reliable** - AI-powered development platform with 50+ working commands, all core features fixed and production-ready.
 
 [![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?label=npm%20v3.0.0)](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)
+[![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)
 
-## ⚡ 3-Minute Quickstart
+## ⚡ Quick Install & Start
 
-### 🎯 What is MARIA v3.0.0?
+```bash
+# Install globally
+npm install -g @bonginkan/maria
+
+# Start MARIA
+maria
+
+# Or use the short alias
+mc
+```
+
+## 🎯 What is MARIA?
 
-MARIA v3.0.0 revolutionizes AI development with **3 powerful services** and a **beautiful CLI experience**:
+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.
 
-- 🧠 **IntelligentRouterService** - Smart command routing and analysis
-- 🧩 **DualMemoryEngine** - System 1 & System 2 cognitive memory
-- 📁 **FileSystemService** - Safe, atomic file operations
+### ✨ Key Features
 
-### 📦 Installation
+- 🤖 **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
 
+## 📖 Available Commands (v3.0.3)
+
+### Core Commands ✅
 ```bash
-# Global installation (recommended)
-npm install -g @bonginkan/maria
+/help                # Show all commands and usage
+/clear               # Clear screen and conversation
+/version             # Show MARIA version
+/exit                # Exit the application
+```
 
-# Or with pnpm
-pnpm add -g @bonginkan/maria
+### AI Development 🤖
+```bash
+/test                # Generate comprehensive tests
+/debug               # Debug assistance with AI
+/review              # Code review with suggestions
+/refactor            # Intelligent code refactoring
 ```
 
-### 🚀 Quick Start
+### Git Operations 📦
+```bash
+/commit              # Create semantic commits
+/pr                  # Generate pull requests
+/merge               # Merge assistance
+/diff                # Analyze code differences
+/branch              # Branch management
+```
 
+### Documentation 📚
 ```bash
-# Launch beautiful interactive mode
-maria
+/docs                # Generate documentation
+/readme              # Create README files
+/api                 # API documentation
+/changelog           # Generate changelogs
+```
+
+### Code Quality 🛡️
+```bash
+/analyze             # Code analysis
+/perf                # Performance profiling
+/security            # Security scanning
+/deps                # Dependency analysis
+/lint                # ESLint analysis
+/typecheck           # TypeScript checking
+```
+
+### Project Management 🏗️
+```bash
+/scaffold            # Project scaffolding
+/deploy              # Deployment assistance
+/memory              # Manage project memory
+/export              # Export project data
+```
+
+### Media Creation 🎨
+```bash
+/image               # AI image generation
+/video               # AI video creation
+/audio               # Audio generation
+```
+
+### Search & Discovery 🔍
+```bash
+/search              # Smart code search
+/find                # File finder
+/grep                # Pattern search
+/replace             # Find and replace
+```
+
+### Database & API 🗄️
+```bash
+/db                  # Database operations
+/migrate             # Run migrations
+/seed                # Seed data
+/api-test            # API testing
+```
 
-# Run API demonstration
-maria --demo
+### Terminal Tools ⚙️
+```bash
+/run                 # Execute commands
+/watch               # File watcher
+/docker              # Docker management
+/calc                # Calculator
+/solve               # Equation solver
+/plot                # Graph plotter
+```
 
-# Test intelligent routing
-maria route "create a React component with TypeScript"
+### Learning & Help 📖
+```bash
+/explain             # Explain code/concepts
+/tutorial            # Interactive tutorials
+/example             # Show examples
+```
 
-# Show help
-maria --help
+### Collaboration 👥
+```bash
+/share               # Share code/sessions
+/collab              # Collaboration tools
+/sync                # Sync settings
+/team                # Team management
 ```
 
 ## 🎨 Beautiful CLI Experience
@@ -60,17 +152,84 @@ When you run `maria`, you'll see:
 ║         (c) 2025 Bonginkan Inc.                          ║
 ╚══════════════════════════════════════════════════════════╝
 
-MARIA CODE v3.0.0 — Ready
+MARIA CODE v3.0.3 — 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
 
-### Core Services Example
+### Use MARIA as a Library
 
 ```typescript
 import { 
@@ -79,240 +238,82 @@ import {
   FileSystemService 
 } from '@bonginkan/maria';
 
-// 🧠 Intelligent Routing
+// Intelligent Routing
 const router = new IntelligentRouterService({
   confidenceThreshold: 0.85,
-  enableLearning: true,
-  enableConfirmation: false
+  enableLearning: true
 });
 
 const result = await router.route('optimize my database queries');
-console.log('Route:', result.command);
+console.log('Command:', result.command);
 console.log('Confidence:', result.confidence);
 
-// 🧩 Dual Memory System
+// Dual Memory System
 const memory = new DualMemoryEngine({
-  system1: { maxKnowledgeNodes: 1000, accessDecayRate: 0.01 },
-  system2: { maxReasoningTraces: 100, qualityThreshold: 0.7 },
-  coordinator: { 
-    syncInterval: 1000, 
-    conflictResolutionStrategy: 'balanced',
-    learningRate: 0.1
-  }
-});
-
-await memory.store('project_context', {
-  language: 'typescript',
-  framework: 'react',
-  patterns: ['hooks', 'components']
+  system1: { maxKnowledgeNodes: 1000 },
+  system2: { maxReasoningTraces: 100 }
 });
 
-const insights = await memory.query('best practices for React hooks');
+await memory.store({ type: 'knowledge', data: {...} });
+const insights = await memory.query('previous optimization patterns');
 
-// 📁 Safe File Operations
-const fs = new FileSystemService({
-  enableBackup: true,
-  enableSafeMode: true
+// File System Operations
+const fs = new FileSystemService({ 
+  safeMode: true,
+  atomicWrites: true 
 });
 
-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
+await fs.writeFile('output.ts', generatedCode);
 ```
 
-## 📱 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
+## 📊 v3.0.3 Statistics
 
-### 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)
-
-### Guides
-- **Quick Start**: [Getting Started Guide](docs/quickstart.md)
-- **CLI Usage**: [Command Line Interface](docs/cli.md)
-- **Configuration**: [Configuration Guide](docs/config.md)
+- [ ] Fix remaining 11 commands
+- [ ] Add GPT-4 Vision support
+- [ ] Enhanced memory persistence
+- [ ] Team collaboration features
+- [ ] Plugin system
+- [ ] Web UI dashboard
 
 ## 🤝 Contributing
 
-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
-```
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## 📄 License
 
-**Dual License Model:**
-- **Personal Use**: MIT License - Free for individual developers
-- **Enterprise Use**: Commercial License - Contact for enterprise pricing
-
-See [LICENSE](LICENSE) for full details.
-
-## 🔗 Links
+MIT © 2025 Bonginkan Inc.
 
-- **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
+## 🙏 Acknowledgments
 
-## 🎉 What's New in v3.0.0
+Thank you to all users who reported issues and helped make MARIA more stable and reliable.
 
-### ✨ 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
-
-### 🚨 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';
-```
+**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)
 
 ---
 
-**Experience the power of minimal design. Experience MARIA v3.0.0.**
-
-*© 2025 Bonginkan Inc. - AI-Powered Development Platform*
+*MARIA - Your AI-Powered Development Assistant*  
+*Making development faster, smarter, and more enjoyable.*