🚀 MARIA v3.4.3

AI-Powered Development Platform with Enhanced /init Command - Enterprise-grade CLI tool featuring revolutionary project analysis, automatic documentation generation with 100% success rate, monorepo support, visual insights with Mermaid diagrams, and comprehensive AI provider integration. Build faster, smarter, and more efficiently with MARIA's enhanced initialization and deep technical documentation capabilities.

🌐 Homepage: https://bonginkan.ai/

🧠 Revolutionary Graph RAG Technology

MARIA v3.4.0 introduces cutting-edge Graph RAG (Retrieval Augmented Generation) capabilities and complete Business Operations suite that transform how AI understands and works with your codebase:

┌─────────────────────────────────────────────────────────────┐
│  🔍 AST PARSING    →   📊 KNOWLEDGE GRAPH   →   🤖 AI GUIDE  │
│                                                             │
│  TypeScript/JS     →   Neo4j Relationships  →   Dynamic     │
│  Code Analysis     →   Semantic Connections →   Guidelines  │
│  Dependencies      →   Vector Embeddings    →   Smart Recs  │
└─────────────────────────────────────────────────────────────┘

🎯 What's New in v3.4.3

• 🐛 Critical Bug Fixes: Fixed 8 major bugs in /init command for 100% success rate
• 🚀 Enhanced /init Command: Monorepo detection, visual insights, deep documentation
• 📊 Mermaid Diagrams: Automatic dependency graphs and architecture visualization
• 🏗️ Monorepo Support: Full support for pnpm, yarn, npm, lerna, nx workspaces
• 📚 Deep Technical Appendix: Automatic extraction of patterns, security, performance
• 🛡️ CI/CD Quality Gates: Automated MARIA.md validation with minimum standards
• ⚡ Atomic File Writes: Safe file operations with tmp→fsync→rename pattern
• 🎨 Visual Provider Matrix: AI provider capabilities in beautiful tables
• 📈 Adaptive Timeouts: Smart timeout adjustment for large projects
• 💯 100% Generation Guarantee: Fallback ensures MARIA.md is always created

🎨 Beautiful CLI Experience

When you run maria, you'll see:

╔══════════════════════════════════════════════════════════╗
║  ███╗   ███╗ █████╗ ██████╗ ██╗ █████╗                  ║
║  ████╗ ████║██╔══██╗██╔══██╗██║██╔══██╗                 ║
║  ██╔████╔██║███████║██████╔╝██║███████║                 ║
║  ██║╚██╔╝██║██╔══██║██╔══██╗██║██╔══██║                 ║
║  ██║ ╚═╝ ██║██║  ██║██║  ██║██║██║  ██║                 ║
║  ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝                 ║
║        AI-Powered Development Platform                   ║
║         (c) 2025 Bonginkan Inc.                          ║
╚══════════════════════════════════════════════════════════╝

MARIA CODE v3.4.3 — Enhanced /init with 100% Success Rate
/help for commands | Providers: 8/8 OK | Monorepo: Supported | Docs: Guaranteed

Available AI Providers:
☁️  Cloud AI: OpenAI, Anthropic, Google, Groq, xAI
💻 Local AI: Ollama, LM Studio, vLLM
🚀 Enhanced Init: Monorepo Support, Visual Insights, Deep Documentation
📊 Quality Assurance: CI/CD Gates, Atomic Writes, 100% Success Rate

📋 System Requirements

• Node.js: v20.10.0 or higher
• npm/pnpm: npm v10+ or pnpm v10.10.0
• Memory: 4GB RAM minimum (8GB recommended for Graph RAG)
• Disk Space: 500MB for installation + space for knowledge graphs
• OS: macOS, Linux, Windows (WSL2 recommended)

Optional Requirements

• Neo4j: For Graph RAG features (auto-installed if needed)
• Docker: For containerized deployments
• GPU: CUDA-compatible for local AI models (Ollama, vLLM)

⚡ Installation

# Global installation (recommended)
npm install -g @bonginkan/maria

# Or with pnpm (faster)
pnpm add -g @bonginkan/maria

# Or use npx without installation
npx @bonginkan/maria

# Verify installation
maria --version
# Output: MARIA v3.4.3

🔧 Configuration

# Initialize configuration on first run
maria --init

# Set up AI provider API keys
maria --setup-providers

# Configure Graph RAG (optional)
maria --setup-graph-rag

💼 Business Operations Quick Start

Battle Card Generation

# Generate competitive battle cards with PDF output
maria
/battlecard --competitor "CompetitorX" --customer "ABC Corp" --industry manufacturing

# Output:
# 🎯 Analyzing competitor strategy...
# 📊 Generating battle card content...
# 💼 Creating presentation-ready output...
# ✨ Battle card saved to battlecard_CompetitorX_ABC.html

Real-time Sales Dashboard

# Launch interactive TUI dashboard
/sales-dashboard

# With specific profile and theme
/sales-dashboard --profile executive --theme business

AI Behavior Tuning

# Natural language AI adjustment
/tune "Focus on increasing sales conversion rate while maintaining quality"

# With intensity and scope control
/tune "Prioritize cost reduction" --intensity high --scope team

Pilot Team Management

# Setup 5-person sales team pilot
/pilot-setup template
/pilot-setup setup --config ./pilot-config.json
/pilot-setup start --pilot-id team_alpha_2025

🧬 Graph RAG Quick Start

Initialize Your Project with Graph RAG

# Full codebase analysis with knowledge graph construction
maria
/init

# Output:
# 🧠 Initializing Graph RAG analysis...
# 📁 Scanning project files (TypeScript, JavaScript, Python, Go, Rust)...
# 🔍 Parsing AST structures with @babel/traverse...
# 📊 Building Neo4j knowledge graph with relationships...
# 🔄 Creating vector embeddings for semantic search...
# ✨ Generating MARIA.md and CLAUDE.md guidelines...
# 📈 Graph contains: 1,247 nodes, 3,892 relationships

Incremental Updates

# Smart incremental updates with delta detection
/update

# With specific change detection methods
/update --since git:HEAD~3      # Git-based changes
/update --since 2025-08-20      # Time-based changes
/update --since state            # State-based changes
/update --full                   # Force full rebuild

Advanced Graph RAG Commands

# Query the knowledge graph
/query "Show all React components that use authentication"

# Visualize graph relationships
/graph --visualize --depth 3 --node "UserService"

# Export graph data
/export --format neo4j --output ./graph-data.json

🎯 Core Features

🧠 Graph RAG Intelligence

• AST Parsing: Deep TypeScript/JavaScript code analysis
• Knowledge Graphs: Neo4j-powered semantic relationships
• Vector Search: Hybrid search with RRF ranking
• Delta Detection: Three methods (git, time, state-based)
• Provenance: Full explanation of AI recommendations

💼 Business Operations Suite

• Battle Cards: Automated competitive analysis and PDF generation
• Sales Dashboards: Real-time TUI dashboards with blessed.js
• AI Tuning: Natural language behavior adjustment for teams
• Pilot Management: 5-person team onboarding and monitoring
• Salesforce Integration: OAuth2.0 API with failover to CSV
• RBAC Security: Role-based access control with audit logging

🤖 AI Provider Support

8 AI Providers with automatic failover:

🎨 Advanced CLI Features

# Core Commands (Enhanced in v3.4.1)
/init          # Full project analysis with 100% success rate
/init --scan   # Enhanced monorepo detection and visual insights
/update        # Incremental updates with delta detection
/memory        # View dual-memory system statistics
/status        # System health with Graph RAG metrics
/help          # Enhanced help with visual diagrams

# AI Provider Management
/provider list               # Show all available providers
/provider switch anthropic   # Switch to specific provider
/provider test              # Test all configured providers
/provider failover          # Configure automatic failover

# Advanced Analysis
/analyze --deep             # Deep codebase analysis with recommendations
/security-scan              # RBAC and security vulnerability scan
/performance-profile        # Performance bottleneck detection
/dependency-audit           # Check for outdated/vulnerable dependencies

# Workflow Automation
/workflow create "Deploy to production"
/workflow run deploy-prod
/schedule "Daily standup report" --cron "0 9 * * *"
/automate code-review --on "pull_request"

📊 Graph RAG Visualization

Knowledge Graph Structure:
├── 📁 Project Root
│   ├── 🔗 Dependencies
│   │   ├── External Packages
│   │   └── Internal Modules  
│   ├── 🧩 Components
│   │   ├── React Components
│   │   └── Utility Functions
│   ├── 🎯 Types & Interfaces
│   │   ├── API Contracts
│   │   └── Domain Models
│   └── 🔄 Data Flow
│       ├── State Management
│       └── Event Handlers

🚀 Advanced Usage

Custom Delta Detection

# Git-based changes
/update --since git:HEAD~5

# Time-based changes  
/update --since 2025-08-20T10:00:00Z

# State-based changes (SHA-256)
/update --since state

Output Modes

# TTY mode (interactive)
maria

# JSON mode (CI/CD)
MARIA_OUTPUT=json maria

Budget Control

// Budget-aware processing
{
  "budget": {
    "maxFiles": 1000,
    "maxTimeMs": 300000,
    "maxTokens": 100000
  }
}

🏗️ Architecture

Minimal API, Maximum Power Philosophy

MARIA v3.4.2 follows a strict architectural principle: expose only what's necessary, hide the complexity. With just 7 public exports, we maintain a clean API while providing 50+ internal services.

// Only 7 public exports - minimal surface area, maximum stability
import {
  IntelligentRouterService,  // Smart command routing with Graph RAG
  System1MemoryManager,      // Fast, intuitive memory
  System2MemoryManager,      // Analytical, deliberate memory
  DualMemoryEngine,          // Coordinates both memory systems
  FileSystemService,         // Safe, atomic file operations
  GraphRAGService,           // Knowledge graph management (v3.3+)
  BusinessOpsService         // Enterprise operations (v3.4+)
} from '@bonginkan/maria';

Graph RAG Pipeline

Input → AST Parser → Knowledge Graph → Vector Store → AI Analysis → Guidelines
  ↓         ↓             ↓               ↓            ↓           ↓
Files → Structures → Relationships → Embeddings → Insights → MARIA.md

Memory Systems

• System 1: Fast pattern recognition, code snippets (< 100ms)
• System 2: Deep reasoning, architectural analysis (1-5s)
• Graph Store: Neo4j persistent knowledge relationships
• Vector Store: Semantic similarity search with embeddings

Safety & Privacy

• Local Processing: AST parsing runs locally
• Gradual Degradation: Works without external services
• Budget Controls: Prevents resource exhaustion
• Safe Defaults: Non-destructive operations
• Audit Trail: Complete operation logging for compliance

📚 Graph RAG Configuration

Neo4j Integration

{
  "graphRAG": {
    "neo4j": {
      "uri": "bolt://localhost:7687",
      "user": "neo4j",
      "password": "your-password"
    },
    "vectorDB": {
      "provider": "qdrant",
      "collection": "maria-knowledge"
    }
  }
}

AST Analysis Settings

{
  "astParser": {
    "languages": ["typescript", "javascript"],
    "includePatterns": ["src/**/*.ts", "src/**/*.tsx"],
    "excludePatterns": ["node_modules/**", "dist/**"],
    "maxDepth": 10
  }
}

🏢 Enterprise Features

🔒 Security & Compliance

• RBAC System: Fine-grained role-based access control
• Audit Logging: Complete audit trail for compliance
• Encryption: End-to-end encryption for sensitive data
• SSO Integration: SAML/OAuth2.0 single sign-on support
• Data Residency: Configurable data location controls

📊 Analytics & Monitoring

• Real-time Dashboards: Business metrics visualization
• Performance Metrics: Latency, throughput, error rates
• Usage Analytics: Team productivity insights
• Cost Tracking: AI provider usage and costs
• Custom Reports: Exportable PDF/CSV reports

🤝 Team Collaboration

• Shared Knowledge Base: Team-wide Graph RAG
• Code Review Automation: AI-powered PR reviews
• Documentation Generation: Auto-generated docs
• Team Templates: Shareable workflow templates
• Version Control Integration: Git/GitHub/GitLab support

🎯 Use Cases

🏢 Enterprise Development

• Code Review: AI-powered analysis with Graph RAG insights
• Architecture Planning: Relationship mapping and dependency analysis
• Knowledge Transfer: Dynamic guideline generation for teams
• Legacy Migration: Deep codebase understanding for modernization

👨‍💻 Individual Developers

• Project Onboarding: Instant understanding of new codebases
• Code Quality: Intelligent suggestions based on project patterns
• Documentation: Auto-generated guidelines that evolve with code
• Learning: Explore code relationships through knowledge graphs

📖 API Reference

Core Services

import { 
  IntelligentRouterService,    // Graph RAG routing
  DualMemoryEngine,           // System 1 & 2 memory
  FileSystemService           // Safe file operations
} from '@bonginkan/maria';

Graph RAG Services

import {
  GraphRAGService,            // Main Graph RAG orchestrator
  ASTAnalyzer,               // Code structure analysis
  KnowledgeGraphService,     // Neo4j graph management
  DeltaDetectorService       // Change detection
} from '@bonginkan/maria/graph-rag';

📚 Version History

🚀 v3.4.2 (Current) - December 2024

• Gemini 2.5 Flash Integration: Latest Google AI model with vision capabilities
• NPM Registry Restoration: Fixed package publication and README display
• UI Enhancements: Cleaner CLI display with reduced noise
• Bug Fixes: Critical stability improvements

🎯 v3.4.0 - December 2024

💼 Business Operations Suite

• Battle Card Generator: Automated competitive analysis with PDF/HTML output
• Sales Dashboard: Real-time TUI dashboards with blessed.js integration
• AI Behavior Tuning: Natural language adjustment for business strategy
• Pilot Management: 5-person team automated onboarding and monitoring
• Salesforce Integration: Full OAuth2.0 API with CSV failover
• RBAC Security: Enterprise role-based access control with audit logging

🧠 Graph RAG Enhancements

• Complete Graph RAG Engine: Neo4j-powered knowledge graph analysis
• Enhanced /init Command: Deep AST parsing with relationship mapping
• Smart /update Command: Three delta detection methods (git/time/state)
• Vector Search: Hybrid search with RRF ranking algorithm
• Provenance Tracking: Full transparency in AI recommendations

🎯 Developer Experience

• Dynamic Version Display: Real-time version reading from package.json
• Autocomplete for Commands: 2-character trigger with keyboard navigation
• Advanced CLI UX: Progress bars, spinners, TTY/JSON output modes
• Enhanced Memory System: Dual-layer System 1 & 2 cognitive architecture

🔧 Performance & Quality

• TypeScript Improvements: Reduced errors from 870+ to 751
• ESLint Compliance: Decreased violations from 3539 to 561
• Build Optimization: 192KB bundle size with tree-shaking
• Memory Efficiency: Optimized AST parsing and graph operations
• Test Coverage: Comprehensive test suite with smoke, integration, and security tests

🧠 v3.3.x Series - November 2024

v3.3.2

• Critical Bug Fixes: Stability improvements and error resolution
• Command Type Updates: Regenerated command types for better type safety

v3.3.1

• Gemini 2.5 Flash Preview: Early integration of Google's latest AI model
• Vision Capabilities: Image analysis and understanding features

v3.3.0

• Revolutionary Graph RAG Engine: Complete knowledge graph implementation
• Enhanced /init Command: Deep codebase analysis with AST parsing
• Vector Embeddings: Semantic search capabilities

🎨 v3.1.x Series - October 2024

v3.1.9

• AI Orchestration Documentation: Comprehensive provider integration guides
• Reference Architecture: Best practices and patterns documentation

v3.1.8

• Zero Hardcoding Architecture: Dynamic configuration system
• Simplified Environment Setup: Streamlined configuration management

v3.1.5

• Advanced Telemetry System: ML-powered monitoring and predictive analytics
• Performance Monitoring: Real-time system health tracking

v3.1.4

• NPM Package Optimization: Improved package structure for distribution
• README Restructuring: Enhanced documentation organization

v3.1.2

• Dynamic Theming: Customizable UI themes
• Template System Removal: Replaced hardcoded templates with dynamic generation

v3.1.1

• Bug Fixes: Resolved corrupted service files
• Stability Improvements: Enhanced error handling

🚀 v3.0.x Series - September 2024

v3.0.0

• Major Architecture Overhaul: Complete codebase restructuring
• Dual Memory Engine: System 1 & System 2 cognitive architecture
• Minimal API Philosophy: Reduced public API to 7 core exports
• 8 AI Provider Support: OpenAI, Anthropic, Google, Groq, xAI, Ollama, LM Studio, vLLM
• 68+ Slash Commands: Comprehensive command system with categories

📦 v2.x Series - Legacy Features

v2.9.x

• Multi-Provider Failover: Automatic provider switching on failure
• Context Management: Improved conversation state handling
• File Operations: Enhanced file system interactions

v2.8.x

• Local AI Support: Integration with Ollama and LM Studio
• Stream Processing: Real-time response streaming
• Error Recovery: Graceful error handling and recovery

v2.7.x

• Command System: Introduction of slash command architecture
• Memory Management: Basic conversation memory implementation
• UI Components: Initial terminal UI with blessed.js

v2.6.x

• Provider Abstraction: Unified interface for AI providers
• Configuration System: YAML-based configuration management
• Testing Framework: Initial test suite with Vitest

v2.5.x

• TypeScript Migration: Complete rewrite in TypeScript
• ESLint Integration: Code quality enforcement
• Build System: tsup-based build pipeline

v2.0.0

• Initial Public Release: Basic AI chat functionality
• OpenAI Integration: GPT-3.5 and GPT-4 support
• CLI Interface: Command-line interaction system

🤝 Contributing

We welcome contributions to MARIA's Graph RAG capabilities!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-graph-rag)
3. Commit your changes (git commit -m 'Add amazing Graph RAG feature')
4. Push to the branch (git push origin feature/amazing-graph-rag)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🌟 Support

• 📧 Email: support@bonginkan.ai
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📚 Documentation: docs.bonginkan.ai

MARIA v3.4.2 - Enterprise AI Development Platform with Graph RAG Intelligence 🚀

Built with ❤️ by Bonginkan Inc.