npm - @defai.digital/automatosx - Versions diffs - 9.2.0 → 9.2.3 - Mend

@defai.digital/automatosx 9.2.0 → 9.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,8 @@
 <h1><img src=".github/assets/axlogo.png" alt="AutomatosX Logo" width="36" /> <span style="font-size: 1.5em;">AutomatosX</span></h1>
-*From Idea to Production in Minutes: The AI Workforce Platform with Persistent Memory*
+*The Invisible Power Addon for Claude Code & OpenAI Codex*
-AutomatosX is a pure CLI orchestration platform for AI agents. It wraps around `claude`, `gemini`, `grok`, and `codex` commands to provide multi-agent orchestration, persistent memory, and workflow automation. Simple, focused, and easy to integrate with your existing AI workflow.
+**AutomatosX transforms your AI coding assistant into a multi-agent enterprise platform** - with 20+ specialized agents, persistent memory, and 80% cost savings through intelligent multi-provider routing. **You keep using Claude Code or Codex exactly as before**, but now with superpowers.
 [![npm version](https://img.shields.io/npm/v/@defai.digital/automatosx.svg)](https://www.npmjs.com/package/@defai.digital/automatosx)
 [![License](https://img.shields.io/badge/license-Apache--2.0-yellow.svg)](LICENSE)
@@ -13,1116 +13,591 @@ AutomatosX is a pure CLI orchestration platform for AI agents. It wraps around `
 [![Windows](https://img.shields.io/badge/Windows-10+-blue.svg)](https://www.microsoft.com/windows)
 [![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-blue.svg)](https://ubuntu.com)
-**Status**: ✅ **Production Ready** | v9.2.0 | 20 Specialized Agents | Pure CLI Orchestration | Enterprise MCP Support
+**Status**: ✅ **Production Ready** | v9.2.3 | Enterprise MCP Support | Multi-Provider Orchestration
-> 🎉 **NEW in v8.5.3**: **Phase 4 MCP Complete!** Production-ready Model Context Protocol (MCP) server management with lifecycle logging, auto-installation, configuration hot-reload, performance monitoring, and resource enforcement. Transform your AI workflow with enterprise-grade server orchestration.
+> 🎯 **What AutomatosX Does**: Adds 20+ specialized agents, persistent memory, workflow automation, and 80% cost savings to Claude Code/Codex - **without changing how you work**.
-> 🔥 **NEW in v8.3.0**: Major simplification! Removed ~36,000 lines of code including policy routing, free-tier management, and SDK providers. AutomatosX is now a pure CLI orchestration wrapper around `claude`, `gemini`, `grok`, and `codex` commands. Simpler, faster, easier to maintain.
+> 💡 **No Learning Curve**: Keep using Claude Code naturally. AutomatosX runs invisibly in the background, giving you enterprise capabilities automatically.
 ---
-## ⚡ New to AutomatosX? [Start Here: 3-Minute Quickstart](docs/getting-started/quickstart-3min.md)
+## ⚡ The Problem (Before AutomatosX)
-Get productive in under 3 minutes with our fast-track guide! Install, run your first agent, try multi-agent collaboration, and learn pro tips. **Perfect for first-time users.**
+**Claude Code is amazing, but...**
----
-## 🚀 The Complete AI Workflow Platform
-AutomatosX is **the only AI platform** that gives you:
+```
+❌ Expensive: $150-300/mo API costs for heavy users
+❌ No Memory: Loses context between sessions (wasted tokens)
+❌ Single Agent: No specialized experts (backend, security, etc.)
+❌ No Multi-Provider: Locked into one provider (no cost optimization)
+❌ No Observability: Can't track what AI is doing (compliance issue)
+❌ No Workflows: Manual coordination for complex tasks
+```
-| Feature | What It Does | Value |
-|---------|--------------|-------|
-| 📋 **Spec-Kit Integration** | Define workflows in YAML. Generate plans, DAGs, scaffolding, and tests automatically. | Ship projects 10x faster |
-| 🧠 **Persistent Memory** | Every conversation is remembered. Agents get perfect context automatically. | Never repeat yourself again |
-| 🤝 **Multi-Agent Orchestration** | 20 specialized agents delegate tasks to each other. You manage the project, not the details. | Focus on strategy, not micromanagement |
-| 🔧 **Pure CLI Wrapper** | Works with your existing `claude`, `gemini`, `grok`, `codex` CLIs. No API keys needed for CLI mode. | Simple integration |
-| 🔍 **Complete Observability** | Trace every execution and decision. Debug with confidence. | Production-grade reliability |
-| 🎯 **Enterprise MCP** | Production-ready MCP server management: lifecycle logging, auto-install, hot-reload, metrics, resource limits. | Mission-critical reliability |
+**Total Monthly Cost**: $170-320/mo (Claude Pro + API usage)
 ---
-## ⚡ Quick Summary
-```bash
-# Install
-npm i -g @defai.digital/automatosx
+## ✨ The Solution (After AutomatosX)
-# Initialize (REQUIRED - sets up agents and config)
-cd your-project && ax setup
+**Same Claude Code experience, but with superpowers:**
-# Create workflow from natural language
-ax spec create "Build auth system with API, tests, security audit"
+```
+✅ 80% Cost Savings: $60/mo total (multi-provider routing)
+✅ Perfect Memory: Remembers everything forever (SQLite FTS5)
+✅ 20+ Specialized Agents: Backend, security, DevOps experts
+✅ Multi-Provider: Auto-routes to Claude/Gemini/OpenAI optimally
+✅ Complete Observability: JSONL trace logs for every decision
+✅ Workflow Automation: YAML specs for complex multi-step tasks
+```
-# Execute workflow
-ax run workflow.ax.yaml
+**Total Monthly Cost**: $60/mo (same unlimited usage)
-# Debug with trace logs
-ax providers trace --follow
+**💰 Savings**: $110-260/mo per developer | $1,320-3,120/year per developer
-# Result: Production-ready auth system in minutes
-```
+---
-**AutomatosX**: The only AI platform with declarative workflows, persistent memory, and multi-agent orchestration wrapped around existing AI CLI tools.
+## 🎨 How It Works (The Magic)
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    You (Developer)                              │
+│        "Build user authentication with security audit"          │
+└────────────────────────────────────────────────────────────────┘
+                              ↓
+                      [Claude Code]
+                   (Your familiar interface)
+                              ↓
+┌────────────────────────────────────────────────────────────────┐
+│                       AutomatosX                                │
+│              (Invisible Power Layer)                            │
+│                                                                  │
+│  • Routes to optimal provider (cost + performance)              │
+│  • Delegates to specialized agents (backend → security)         │
+│  • Saves everything to persistent memory (zero repetition)      │
+│  • Logs all decisions (complete observability)                  │
+└────────────────────────────────────────────────────────────────┘
+                              ↓
+        ┌─────────────────────┼─────────────────────┐
+        ↓                     ↓                     ↓
+  ┌──────────┐          ┌──────────┐          ┌──────────┐
+  │  Claude  │          │  Gemini  │          │ OpenAI   │
+  │ (Reason) │          │  (Code)  │          │  (Speed) │
+  └──────────┘          └──────────┘          └──────────┘
+        ↓                     ↓                     ↓
+                      [MCP Servers]
+              Filesystem • Git • Database
+```
+**You**: Talk to Claude Code naturally (no new commands!)
+**AutomatosX**: Invisibly orchestrates multi-agent execution, optimizes costs, saves to memory
+**You Get**: Better results, 80% lower costs, perfect context - automatically
 ---
-## ⚡ Quick Start: 60 Seconds to Your First Workflow
+## 🚀 Quick Start (60 Seconds)
+### Step 1: Install AutomatosX
 ```bash
-# 1. Install AutomatosX
 npm install -g @defai.digital/automatosx
+```
-# 2. Change to your project folder
-cd your-project
+### Step 2: Initialize in Your Project
-# 3. Set up AutomatosX (REQUIRED - sets up agents and configuration)
+```bash
+cd your-project
 ax setup
-# Or force reinitialize: ax setup -f
-# ⚠️ IMPORTANT: You MUST run 'ax setup' before using AutomatosX
-# This command:
-#   - Creates .automatosx/ directory with all 20 specialized agents
-#   - Sets up configuration files (ax.config.json)
-#   - Initializes memory database and session management
-#   - Configures the CLI environment for optimal performance
-# 4. Create a workflow spec in natural language
-ax spec create "Build user authentication with database, API, JWT, security audit, and tests"
-# AutomatosX automatically:
-#   ✅ Generates a complete project spec (.specify/)
-#   ✅ Creates execution plan
-#   ✅ Generates DAG for parallel execution
-#   ✅ Scaffolds project structure
-#   ✅ Generates comprehensive tests
-#   ✅ Executes with configured provider
-#   ✅ Tracks all decisions with trace logging
-# 5. View the generated plan
-ax gen plan workflow.ax.yaml
-# 6. Execute the workflow
-ax run workflow.ax.yaml
 ```
-**Result**: Complete authentication system with database, API, security audit, and tests—generated and executed in minutes, not days.
----
-## 🗣️ **Recommended**: Natural Language Interface
-AutomatosX is designed to work seamlessly with AI assistants using natural language commands. This is the **recommended way** to use AutomatosX:
-**✨ Key Feature**: AutomatosX **automatically selects the best agent(s)** for your task. You don't need to specify which agent to use - just describe what you want!
-### Use with Claude Code, Gemini CLI, Grok CLI, or OpenAI Codex
+**That's it!** AutomatosX is now running invisibly. Keep using Claude Code/Codex naturally.
-**Natural Task Descriptions** (ax auto-selects agents for you):
+### Step 3: Use Claude Code Naturally (No New Commands!)
-```
-# In Claude Code
-"Please use ax to implement user authentication"
-"Use ax to audit this code for vulnerabilities"
-"Have ax write comprehensive tests for this feature"
-"Use ax to design a microservices architecture"
-```
-```
-# In Gemini CLI
-"Use ax to find and fix bugs in the authentication system"
-"Work with ax to optimize the database queries"
-"Use ax to build the login UI"
-```
-```
-# In Grok CLI
-"Use ax to analyze and refactor this codebase"
-"Work with ax to debug the performance bottleneck"
-"Use ax to review code quality and suggest improvements"
-"Have ax identify security vulnerabilities"
-```
+**Just talk to Claude Code like you always do:**
 ```
-# In OpenAI Codex
-"Use ax to build the user interface"
-"Work with ax to set up CI/CD pipeline"
-"Use ax to design the database schema"
+"Build user authentication with JWT. Save the design to memory for future reference."
 ```
-**What Happens Behind the Scenes**:
-- 🤖 `ax` analyzes your task description
-- 🎯 Automatically selects the best agent(s) (backend, security, quality, etc.)
-- 🔄 Coordinates multi-agent collaboration if needed
-- 📝 All decisions stored in memory for context
+**Behind the scenes, AutomatosX automatically**:
+- Routes to Gemini (cost-efficient for implementation)
+- Delegates security audit to Claude (best reasoning)
+- Saves everything to persistent memory (zero token waste)
+- Logs all decisions (complete audit trail)
-### Natural Language Interaction Examples
+**You see**: Natural Claude Code response, but better and cheaper!
-#### Workflow Creation and Execution
+---
-```
-# In Claude Code
-"Create an ax workflow spec for a REST API with authentication, database,
-and comprehensive tests. Then execute it."
+## 💬 Natural Language Examples (How You'll Use It)
-"Generate a spec for refactoring the payment module with security audit and
-backwards compatibility tests. Use the backend and security agents."
+### Example 1: Multi-Agent Collaboration
-"Build a complete microservices architecture spec with service mesh, monitoring,
-and deployment configs."
+**You say to Claude Code**:
 ```
+"Work with AutomatosX agents to build a payment system.
+Let the backend agent implement the API, security agent audit it,
+and quality agent write tests. Save everything to memory."
 ```
-# In Gemini CLI
-"Use ax to create and execute a workflow for migrating from MongoDB
-to PostgreSQL. Include data validation and rollback procedures."
-"Generate a spec for implementing rate limiting across all API endpoints.
-Include security review and load testing."
-"Create a workflow for adding GraphQL to our REST API. Include schema
-generation, resolver tests, and performance benchmarks."
-```
+**What AutomatosX does automatically**:
+1. Product agent designs architecture
+2. Backend agent implements API (routed to Gemini - cost-efficient)
+3. Security agent audits code (routed to Claude - best reasoning)
+4. Quality agent writes tests (routed to Gemini - fast)
+5. Everything saved to memory for future tasks
+6. Complete trace log for observability
-```
-# In OpenAI Codex
-"Work with ax to build a real-time notification system with WebSockets,
-Redis, and push notifications. Generate the full workflow spec."
+**Cost**: $0 additional (using CLI subscriptions)
+**Time**: 60% faster (parallel execution)
+**Quality**: 3 specialized agents vs 1 generalist
-"Create and execute a spec for implementing OAuth2 with Google, GitHub, and
-Facebook providers. Include security audit and integration tests."
+### Example 2: Persistent Memory
-"Generate a workflow for database migration with zero downtime. Include
-blue-green deployment strategy and rollback automation."
+**Day 1 - You say**:
 ```
+"Design a calculator app with add/subtract features.
+Save the architecture to AutomatosX memory."
 ```
-# In Grok CLI
-"Use ax to create a workflow for comprehensive code quality improvement.
-Include refactoring, performance optimization, and security hardening."
-"Generate and execute a spec for debugging and fixing production issues.
-Include root cause analysis, fix implementation, and regression tests."
-"Create a workflow for technical debt reduction with code analysis,
-refactoring strategy, and validation tests."
+**Day 7 - You say**:
 ```
-#### Multi-Agent Orchestration
+"Implement the calculator API we designed last week."
 ```
-# In Claude Code
-"Use ax to build a complete e-commerce platform with requirements,
-architecture, API, database, React UI, security audit, and comprehensive tests."
-"Work with ax to implement a data analytics pipeline with API,
-ETL, and data warehousing."
-```
+**AutomatosX automatically**:
+- Searches memory for "calculator" design
+- Injects full context into prompt (< 1ms search)
+- Zero token waste (no repetition)
+- Perfect continuity (like talking to same person)
-```
-# In Grok CLI
-"Use ax to analyze and optimize the entire codebase with quality checks,
-security audits, performance profiling, and comprehensive refactoring."
+**Savings**: 50-80% fewer tokens (no context repetition)
-"Work with ax to debug complex multi-service issues with distributed
-tracing, log analysis, and performance optimization."
-```
-#### Iterate Mode Tasks
+### Example 3: Cost Optimization
+**You say**:
 ```
-# In Claude Code - Autonomous Bug-Finding
-"Please use ax in iterate mode to find and fix bugs. Run 5 iterations."
-# In Gemini CLI - Comprehensive Code Analysis
-"Use ax in iterate mode to analyze the entire codebase for
-performance issues. Set 120 minute timeout with balanced strictness."
-# In OpenAI Codex - Security Hardening
-"Use ax to run a comprehensive security audit in iterate mode
-with strict level. This is for production deployment."
+"Review this 10,000-line codebase for bugs.
+Use cost-efficient routing - this is routine analysis."
 ```
-### Why Natural Language?
-- ✅ **Conversational**: Talk to AI assistants like teammates
-- ✅ **Context-aware**: AI assistants maintain full conversation context
-- ✅ **Flexible**: No need to remember exact command syntax
-- ✅ **Integrated**: Works directly in your AI assistant workflow
-- ✅ **Powerful**: Combines AI assistant capabilities with AutomatosX's memory and orchestration
-- ✅ **Production-Ready**: Full observability and trace logging for debugging
-### Behind the Scenes
-When you say "use ax to implement authentication", here's what happens:
-1. AI assistant calls `ax run "implement user authentication"`
-2. ax **automatically analyzes the task** and selects the best agent(s)
-3. Routes to the configured provider
-4. Persistent memory ensures perfect context across all interactions
-5. Results are returned to your AI assistant with full context
-6. The conversation continues naturally
+**AutomatosX automatically**:
+- Routes to Gemini (routine task = cost-efficient)
+- Uses Gemini Advanced unlimited plan ($20/mo)
+- Instead of Claude API ($150-300/mo for this volume)
+- Same quality, 80% cost savings
-**This natural language interface with auto-agent selection is how we expect users to work with AutomatosX daily.**
+**API Cost (without AutomatosX)**: ~$45 (10K lines × $15/1M tokens)
+**CLI Cost (with AutomatosX)**: $0 (already paying $20/mo Gemini Advanced)
-**Advanced: Direct Agent Specification** (Optional):
-If you need a specific agent, you can still specify it:
-- `ax run backend "task"` - Forces backend agent
-- `ax run security "task"` - Forces security agent
+---
-But in most cases, auto-selection works better!
+## 🎯 What You Get (Automatically)
-### CLI-Only Mode (No API Access Required)
+### 1. 20+ Specialized Agents
-If you only have CLI tools installed and **no API access** (no API keys or restricted network), you can force CLI-only mode:
+**No setup needed - just mention them in conversation:**
-```bash
-# Set environment variable to enforce CLI-only mode
-export AX_CLI_ONLY=true
+- **Backend Agent (Bob)**: Go/Rust systems, API design, databases
+- **Security Agent (Steve)**: Threat modeling, penetration testing, audits
+- **Frontend Agent (Frank)**: React/Next.js, UI/UX, responsive design
+- **DevOps Agent (Oliver)**: CI/CD, Kubernetes, infrastructure
+- **Quality Agent (Queenie)**: Test planning, QA automation
+- **Product Agent (Paris)**: Requirements, roadmaps, user stories
+- **Data Agent (Daisy)**: ETL pipelines, data warehouses
+- ... [13 more agents](docs/full-features.md#agents)
-# Now all providers will use CLI integration (subprocess), never API
-ax run backend "implement user authentication"
+**Example**:
+```
+"Security agent, please audit this authentication code."
+"Backend agent, optimize this database query."
+"DevOps agent, set up the CI/CD pipeline."
 ```
-**When to use CLI-only mode:**
-- ✅ You have `codex`, `gemini`, or `claude` CLI tools installed
-- ✅ You don't have API keys configured
-- ✅ You're behind a corporate firewall blocking API access
-- ✅ You want to avoid API connection attempts and retries
-**What it does:**
-- Forces `openai` provider to use CLI subprocess mode (`codex` command)
-- Prevents OpenAI SDK API calls even if configured for SDK mode
-- Eliminates "Unable to connect to API" errors and retry loops
-**Note**: This only affects OpenAI provider. Claude and Gemini providers always use CLI mode by default.
----
-### Direct CLI Usage
-**Note**: You can let AutomatosX auto-select agents, or specify a particular agent if needed.
-```bash
-# Auto-selection (recommended) - AutomatosX picks the best agent
-ax run "implement user authentication" --iterate
-# With agent specified (optional)
-ax run backend "implement user authentication" --iterate
-# With time limit and strictness control
-ax run "refactor codebase" --iterate --iterate-timeout 60 --iterate-strictness balanced
+### 2. Persistent Memory (Context That Never Expires)
-# For security-critical tasks
-ax run "audit entire codebase for security vulnerabilities" --iterate --iterate-strictness strict
+**Automatic - no configuration needed:**
-# Test execution plan without making changes (dry-run)
-ax run "plan database migration" --iterate --iterate-dry-run
+- ✅ **< 1ms Search**: SQLite FTS5 full-text search
+- ✅ **$0 Cost**: No embedding APIs (pure local)
+- ✅ **100% Private**: Data never leaves your machine
+- ✅ **Forever**: Infinite context window (not limited to session)
+- ✅ **Smart**: Auto-injects relevant context from past conversations
-# Verbosity control (v8.5.8+)
-ax run backend "task" --quiet              # Minimal output (perfect for AI assistants)
-ax run backend "task"                       # Normal output (default, shows progress)
-ax run backend "task" --verbose             # All details (for debugging)
+**Example**:
 ```
+Week 1: "Design microservices architecture"
+       → Saved to memory automatically
-### Key Features
+Week 2: "Implement user service"
+       → Memory auto-injects Week 1 architecture
+       → Zero manual context passing
+```
-| Feature | Description | Default |
-|---------|-------------|---------|
-| **Autonomous Execution** | Agents auto-respond to confirmation prompts | Enabled with `--iterate` |
-| **Time Limits** | Configure execution timeouts to prevent runaway tasks | 120 minutes |
-| **Safety Levels** | Choose from `paranoid`, `balanced`, `permissive` | `balanced` |
-| **Dangerous Operation Detection** | Automatic classification of risky operations | Always active |
-| **Dry Run Mode** | Test autonomous execution without making changes | Off |
-| **Context History** | Maintains classification context for smarter decisions | Max 100 entries |
-| **Workspace Protection** | Prevents access to files outside project directory | Always active |
+### 3. Multi-Provider Cost Optimization
-### Safety Guardrails
+**Intelligent routing - completely automatic:**
-Iterate Mode includes comprehensive safety protections:
+| Task Type | Routed To | Why | Cost |
+|-----------|-----------|-----|------|
+| Architecture design | Claude | Best reasoning | $20/mo unlimited |
+| Code implementation | Gemini | Cost-efficient | $20/mo unlimited |
+| Security audit | Claude | Critical accuracy | $20/mo unlimited |
+| Test generation | Gemini | Fast & reliable | $20/mo unlimited |
+| Quick questions | ChatGPT | Fastest response | $20/mo unlimited |
-- ✅ **Execution Timeout Protection**: Automatic shutdown after time limit
-- ✅ **Workspace Boundary Protection**: Cannot access files outside project directory
-- ✅ **Memory Leak Prevention**: Classification history bounded to prevent unbounded growth
-- ✅ **Dangerous Operation Detection**: Auto-blocks risky operations in paranoid mode
-- ✅ **Strictness Controls**: Three levels (paranoid/balanced/permissive) for risk tolerance
-- ✅ **Dry Run Preview**: Test automation logic before making actual changes
+**Total**: $60/mo for unlimited usage across all providers
-### Use Cases
+**vs API-only**: $150-300/mo with per-token billing
-**Perfect For:**
+**Savings**: 80% monthly cost reduction
-- ✅ Long-running refactoring tasks
-- ✅ Comprehensive code audits
-- ✅ Batch processing multiple files
-- ✅ Overnight automation jobs
-- ✅ Large-scale testing and validation
-- ✅ Multi-step workflow execution
+### 4. Complete Observability
-**Not Recommended For:**
+**Automatic trace logging - no setup:**
-- ❌ Tasks requiring frequent user input
-- ❌ Highly destructive operations without dry-run first
-- ❌ Tasks where intermediate decisions are critical
+- ✅ Who executed what task
+- ✅ Which provider was used
+- ✅ How much it cost (tokens)
+- ✅ Delegation chains (agent → agent)
+- ✅ Execution time and results
-### Configuration Options
+**Perfect for**: Compliance audits, debugging, optimization
-```bash
-# All iterate mode flags
-ax run agent "task" \
-  --iterate                           # Enable iterate mode
-  --iterate-max-tokens 1000000        # Max total tokens (default: 1,000,000) [v8.6.0+]
-  --iterate-max-tokens-per-iteration 100000  # Max per iteration (default: 100,000) [v8.6.0+]
-  --iterate-timeout 60                # Max duration in minutes (default: 120)
-  --iterate-strictness balanced       # Safety level: paranoid|balanced|permissive
-  --iterate-dry-run                   # Test mode - no actual changes
-```
+### 5. Workflow Automation
-### Performance
+**Define complex workflows once, reuse forever:**
-- **Classification Latency**: < 50ms per decision
-- **Memory Usage**: Bounded to 100 classification entries
-- **Context Cleanup**: Automatic expiration of old contexts
-- **Timeout Enforcement**: Real-time monitoring with automatic shutdown
-### Example Workflow
-**Natural Language (Recommended)**:
+```yaml
+# .automatosx/workflows/release.ax.yaml
+metadata:
+  name: Production Release Workflow
-```
-# In Claude Code or Gemini CLI
-"I need you to refactor the authentication module using ax backend agent.
-First, do a dry run in iterate mode to show me what you plan to do.
-Then if it looks good, run it in iterate mode with paranoid strictness
-and a 30 minute timeout."
+steps:
+  - Quality agent runs full test suite (Gemini - fast)
+  - Security agent audits for vulnerabilities (Claude - thorough)
+  - DevOps agent deploys to staging (Gemini - routine)
+  - Product agent validates requirements (Claude - critical)
+  - DevOps agent deploys to production (Gemini - routine)
 ```
-**More Natural Language Examples**:
+**You say to Claude Code**:
 ```
-# Comprehensive Bug Analysis (Long-running task)
-"Please ultrathink to work with ax in iterate mode to find and fix bug"
-# Large-Scale Refactoring
-"Use ax backend agent in iterate mode to refactor the entire payment system.
-Set timeout to 120 minutes and use balanced strictness."
-# Security Audit with High Safety
-"Work with ax security agent in iterate mode with paranoid strictness to audit
-the entire codebase. This is for production so be very thorough."
-# Performance Optimization
-"Ask ax quality agent to analyze and optimize all database queries in iterate mode.
-Use a 90 minute timeout with balanced strictness."
-# Multi-File Test Generation
-"Have ax quality agent run in iterate mode to generate tests for all untested
-functions across the codebase. Set 60 minute timeout."
+"Run the production release workflow"
 ```
-**Direct CLI Usage**:
-```bash
-# 1. Dry run to preview actions
-ax run backend "refactor authentication module" \
-  --iterate --iterate-dry-run
-# 2. Run with tight safety controls
-ax run backend "refactor authentication module" \
-  --iterate \
-  --iterate-strictness paranoid \
-  --iterate-timeout 30
-# 3. Monitor progress
-tail -f .automatosx/logs/router-trace-*.jsonl
-```
+**AutomatosX executes everything automatically**, with optimal provider routing.
 ---
-## 🎯 What Makes AutomatosX Different?
-### Traditional AI Workflows
-```bash
-# ❌ Manual coordination
-codex "Design auth system"
-# → Copy/paste output
-codex "Implement API from this design: [paste design]"
-# → Repeat context, pay for duplicate tokens
+## 💰 Cost Comparison (Real Numbers)
-codex "Write tests for this code: [paste code]"
-# → Lost context, higher costs, manual orchestration
+### Heavy User (100K tokens/day)
-# Result: Slow, expensive, repetitive
+**Before AutomatosX** (Claude API only):
 ```
-### AutomatosX Workflows
-```bash
-# ✅ Declarative, automated, optimized
-ax spec create "Build auth system with API, tests, and security audit"
-# Result: Complete system generated and executed automatically
-#   - Persistent memory eliminates context repetition
-#   - Pure CLI orchestration - simple and reliable
-#   - Parallel execution completes 3-5x faster
-#   - Auto-generated tests provide 60%+ baseline coverage
+100K tokens/day × 30 days = 3M tokens/month
+3M input × $3/1M = $9/mo
+3M output × $15/1M = $45/mo
+Claude Code Pro: $20/mo
+Total: $74/mo (likely $150-300/mo in reality)
 ```
----
-## 📋 **NEW**: Spec-Kit Integration (v6.0+)
-The game-changing feature that makes AutomatosX the most powerful AI workflow platform.
-### Natural Language Spec Creation (Recommended)
-Most users interact with AutomatosX through AI assistants (Claude Code, Gemini CLI, OpenAI Codex) using natural language. Here are practical examples:
+**After AutomatosX** (Multi-provider CLI):
 ```
-# In Claude Code
-"Create an ax workflow spec for building a complete authentication system
-with JWT, OAuth2, database integration, security audit, and comprehensive tests.
-Optimize for cost and generate the full project structure."
-"I need a spec for a microservices architecture with user service, payment service,
-API gateway, and Redis caching. Include deployment configs and monitoring."
+Claude Code Pro: $20/mo (20% of tasks)
+Gemini Advanced: $20/mo (70% of tasks)
+ChatGPT Plus: $20/mo (10% of tasks)
+Total: $60/mo (unlimited usage)
-"Generate a workflow spec for refactoring our legacy authentication code.
-Include security review, performance optimization, and backwards compatibility tests."
+Savings: $90-240/mo (60-80% reduction)
 ```
-```
-# In Gemini CLI
-"Use ax to create a spec for an e-commerce checkout flow with Stripe,
-inventory management, fraud detection, and integration tests."
+### Team of 5 Developers
-"Build me a spec for a data pipeline that ingests CSV files, transforms them,
-loads to PostgreSQL, and includes data validation tests."
+**Before**: 5 × $200/mo average = **$1,000/mo**
-"Create a workflow spec for API versioning migration from v1 to v2 with
-backwards compatibility and comprehensive test coverage."
-```
+**After**: 5 × $60/mo = **$300/mo**
-```
-# In OpenAI Codex
-"Work with ax to generate a spec for a real-time chat application
-with WebSocket support, message persistence, and E2E tests."
-"Create a spec for migrating from REST to GraphQL with schema generation,
-resolver implementation, and query performance tests."
+**Savings**: **$700/mo** | **$8,400/year**
-"Generate an ax workflow for implementing RBAC (role-based access control)
-with permissions management, audit logging, and security tests."
-```
+### Enterprise (50 Developers)
-**What happens behind the scenes:**
+**Before**: 50 × $200/mo = **$10,000/mo**
-When you ask an AI assistant to create a spec, it uses `ax spec create "your description"` which:
+**After**: 50 × $60/mo + $500/mo Enterprise = **$3,500/mo**
-1. Generates a complete YAML workflow spec in `.specify/`
-2. Creates execution plan
-3. Generates dependency DAG for parallel execution
-4. Scaffolds project structure
-5. Generates comprehensive test suite
-6. Ready to execute with your configured provider
+**Savings**: **$6,500/mo** | **$78,000/year**
-### 1. Define Your Workflow in YAML
+---
-```yaml
-# workflow.ax.yaml
-metadata:
-  id: user-auth-system
-  name: User Authentication System
+## 🏢 Enterprise Features (Invisible, Automatic)
-actors:
-  - id: backend
-    agent: backend
-    description: Implement JWT authentication API
+### Offline-Friendly & Compliance-Ready
-  - id: security
-    agent: security
-    description: Audit authentication implementation
+Unlike cloud-dependent tools, AutomatosX works in **air-gapped environments**:
-  - id: quality
-    agent: quality
-    description: Generate comprehensive test suite
-```
+- ✅ **100% Local**: All data stays on your machine
+- ✅ **Offline Mode**: Works without internet (with Ollama)
+- ✅ **Audit Trails**: Complete JSONL trace logging
+- ✅ **Data Sovereignty**: No data leaves your infrastructure
+- ✅ **GDPR/HIPAA Ready**: Built for regulated industries
-### 2. Generate Everything Automatically
+**Perfect for**: Government, finance, healthcare
-```bash
-# Generate execution plan with cost estimates
-ax gen plan workflow.ax.yaml
-# Output: Execution plan with phases, costs ($0.003-$0.008), risks
+### Secure & Sandboxed
-# Generate DAG for parallel execution
-ax gen dag workflow.ax.yaml --format mermaid
-# Output: Dependency graph with change detection hash
+Enterprise security controls (automatic):
-# Scaffold complete project structure
-ax gen scaffold workflow.ax.yaml
-# Output: Full directory structure, configs, READMEs
+- ✅ **Filesystem Sandboxing**: Agents can't access outside project directory
+- ✅ **Resource Limits**: CPU/memory caps per agent
+- ✅ **Network Restrictions**: Control API access
+- ✅ **Dangerous Operation Detection**: Auto-blocks risky commands
+- ✅ **Audit Logging**: Every file access, API call logged
-# Generate comprehensive test suite
-ax gen tests workflow.ax.yaml
-# Output: Unit, integration, E2E tests with policy assertions
-```
+### Complete Observability
-### 3. Execute Workflow
+Transform AI agents into **governable workforce**:
-```bash
-# Run workflow
-ax run workflow.ax.yaml
-# AutomatosX automatically:
-#   1. Executes actors with configured provider
-#   2. Executes actors in optimal order
-#   3. Logs all executions to trace file
-#   4. Stores results in persistent memory
-```
+- ✅ Real-time execution traces (JSONL)
+- ✅ Token usage tracking (prevent budget overruns)
+- ✅ Provider performance metrics
+- ✅ Resource monitoring (CPU, memory)
+- ✅ Delegation chains (full transparency)
+- ✅ Cost attribution (per-agent, per-task)
-### 4. Debug with Complete Visibility
+---
-```bash
-# View all executions
-ax providers trace --follow
+## 📦 AutomatosX Editions
-# Output (real-time):
-# 18:26:49  EXECUTION    gemini-cli      Starting task...
-# 18:26:50  EXECUTION    gemini-cli      Processing...
-# 18:26:51  EXECUTION    gemini-cli      ✓ 1234ms, completed
-```
+### Edition Positioning
-**The Complete Workflow**:
+**Pro** – For teams that want priority support & stable releases
-```bash
-# From idea to production in one command
-ax spec create "Build e-commerce checkout with Stripe, inventory, and fraud detection" \
-  && ax run workflow.ax.yaml
-# AutomatosX handles:
-#   ✅ Pure CLI orchestration (simple and reliable)
-#   ✅ Parallel execution (3-5x faster)
-#   ✅ Persistent memory (zero context repetition)
-#   ✅ Auto-generated tests (60%+ coverage)
-#   ✅ Complete observability (trace every execution)
-```
+**Enterprise** – For organizations needing compliance, control, and confidence at scale
 ---
-## 🔌 Provider Configuration
+### 🔷 AutomatosX Pro
-AutomatosX is a pure CLI orchestration wrapper. It works with your existing AI CLI tools without requiring API keys (though API access is supported for some providers).
+**For startups, SMEs, and teams that want stability and support.**
-### Supported Providers
+#### Feature Highlights
-| Provider | CLI Command | API Support | Notes |
-|----------|-------------|-------------|-------|
-| **Claude Code** | `claude` | ✅ Yes | Official Anthropic CLI |
-| **Gemini CLI** | `gemini` | ✅ Yes | Google's AI CLI |
-| **Grok CLI** | `grok` | ✅ Yes | X.AI or Z.AI GLM 4.6 |
-| **OpenAI Codex** | `codex` | ✅ Yes | OpenAI's development CLI |
+**Core Platform**:
+- ✅ **Priority email support & maintenance** - Dedicated support with SLA
+- ✅ **Stable LTS releases** - Long-term support for production
+- ✅ **Commercial use licensing** - Clear licensing for business use
-### Configuration
+**Advanced Workflows**:
+- ✅ **Advanced workflow templates** - SaaS, RAG, API orchestration, CI/CD
+- ✅ **Multi-project management** - Switch contexts, reuse workflows
+- ✅ **Custom agent packs** - Team-specific expertise
-```bash
-# Configure default provider in ax.config.json
-{
-  "providers": {
-    "default": "gemini",  # or claude, grok, codex
-    "claude": { "enabled": true },
-    "gemini": { "enabled": true },
-    "grok": { "enabled": true },
-    "codex": { "enabled": true }
-  }
-}
-# Use specific provider for a task
-ax run backend "task" --provider gemini
-ax run security "audit" --provider claude
-# Check provider status
-ax doctor          # Check all providers
-ax doctor grok     # Check specific provider
-ax providers list  # List available providers
-```
+**Provider & Configuration**:
+- ✅ **Per-project provider profiles** - Different Claude/Gemini configs per project
+- ✅ **Local memory encryption** - Secure persistent memory
+- ✅ **Backup & restore** - Export/import workflows and memory
-**Learn More**:
+**Observability**:
+- ✅ **Run history & usage dashboard** - Track execution history
+- ✅ **MCP auto-install & hot-reload** - Automatic server management
-- [Gemini Integration Guide](docs/providers/gemini.md) - Gemini CLI setup
-- [ax-cli Integration Guide](.ax-cli/README.md) - Multi-provider CLI (GLM, xAI, OpenAI, Anthropic, Ollama)
-- [Provider Comparison](docs/providers/overview.md) - Provider comparison
+**Perfect for**: Startups, consultancies, product teams
 ---
-## 🧠 Persistent Memory: Context That Never Expires
+### 🏢 AutomatosX Enterprise
-AutomatosX **never forgets**. Every conversation, decision, and piece of code is automatically indexed in a local SQLite database with full-text search. Future tasks get perfect context automatically.
+**For organizations where "Enterprises pay for compliance, convenience, and confidence - not just security."**
-### The Problem with Traditional AI
+#### Compliance & Governance
-```bash
-# Day 1: Design a calculator
-codex "Design a calculator with add/subtract"
-# → Response: [Calculator design]
-# Day 2: Implement it (context lost!)
-codex "Implement the calculator"
-# → Error: "What calculator? Please provide context."
-# → You waste time and money re-explaining
-```
+**Audit & Control**:
+- ✅ **Centralized control plane (self-hosted)** - Org-wide management
+- ✅ **Org-wide workflow catalog with approvals** - Governed library
+- ✅ **SSO (SAML/OIDC) & granular RBAC** - Enterprise auth
+- ✅ **Audit-grade logs** - Complete trail of who ran what
+- ✅ **Data retention & deletion policies** - Lifecycle management
-### AutomatosX Solution
+**Data Protection**:
+- ✅ **PII masking / DLP hooks** - Data loss prevention
+- ✅ **Compliance-ready architecture** - GDPR, HIPAA, SOC2
-```bash
-# Day 1: Design
-ax run product "Design a calculator with add/subtract"
-# → Automatically saved to memory
-# Day 2: Implement (context auto-injected!)
-ax run backend "Implement the calculator"
-# → Memory finds "calculator" design from Day 1
-# → Backend agent gets full context automatically
-# → Zero context repetition, zero wasted tokens
-```
+#### Convenience & Control
-### Memory Features
+**Infrastructure Management**:
+- ✅ **Multi-node agent management** - Manage across dev/CI/prod
+- ✅ **Central provider routing & failover** - Org-wide policies
+- ✅ **Quota & rate limits** - Control usage by team/project
+- ✅ **Central MCP registry** - Health monitoring, versioning
-- **Speed**: < 1ms search with SQLite FTS5
-- **Cost**: $0 (no embedding APIs)
-- **Privacy**: 100% local (data never leaves your machine)
-- **Search**: `ax memory search "calculator"`
-- **Export**: `ax memory export > backup.json`
+**Observability at Scale**:
+- ✅ **Org dashboards** - Real-time visibility (runs, success, latency, tokens)
+- ✅ **OpenTelemetry / SIEM integration** - Prometheus, Splunk, Datadog
+- ✅ **Advanced analytics** - Cost attribution, performance trends
----
+#### Confidence & Support
-## 🤝 Multi-Agent Orchestration
+**Enterprise Infrastructure**:
+- ✅ **Hardened, self-hosted deployment** - Docker/Helm for air-gapped
+- ✅ **HA / backup & disaster recovery** - Automated failover
+- ✅ **Multi-region support** - Data sovereignty
-Stop micromanaging AI. Give a high-level goal to one agent, and AutomatosX creates a plan, delegates tasks, and orchestrates a team of specialists.
+**Premium Support**:
+- ✅ **Enterprise SLA & named technical contact** - Guaranteed response times
+- ✅ **Onboarding workshops & playbooks** - Expert guidance
+- ✅ **Optional design partnership** - Influence roadmap
-### How It Works
-```bash
-# 1. Give a high-level goal
-ax run product "Build complete user authentication"
-# 2. Product agent analyzes and delegates
-# Output:
-# "I'll design auth with JWT and OAuth2.
-#
-#  @backend Please implement the JWT authentication API.
-#  @security Please audit the implementation for vulnerabilities.
-#  @quality Please write integration tests."
-# 3. AutomatosX executes automatically
-#    - Backend implements API
-#    - Security audits code
-#    - Quality writes tests
-#    - All in parallel, all with full context
-```
-### 20 Specialized Agents
-Each agent is an expert in their domain:
-| Agent | Role | Use Cases |
-|-------|------|-----------|
-| **Bob** | Backend Engineer | API design, databases, Go/Rust systems |
-| **Frank** | Frontend Engineer | React/Next.js, UI components, state management |
-| **Avery** | Software Architect | System architecture, ADR management, architecture runway |
-| **Steve** | Security Specialist | Threat modeling, vulnerability assessment, penetration testing |
-| **Queenie** | QA Engineer | Test planning, E2E testing, quality assurance |
-| **Oliver** | DevOps Engineer | CI/CD, Kubernetes, infrastructure automation |
-| **Paris** | Product Manager | Requirements, roadmaps, stakeholder alignment |
-| **Daisy** | Data Engineer | ETL pipelines, data warehouses, Spark |
-| **Dana** | Data Scientist | ML models, statistical analysis, Python |
-| **Tony** | CTO | Technical strategy, architecture, scaling |
-| **Eric** | CEO | Business strategy, vision, leadership |
-| **Wendy** | Technical Writer | Documentation, API docs, tutorials |
-| **Stan** | Standards Expert | Best practices, design patterns, code review |
-[See all 20 agents](docs/guides/agents.md) | [Create custom agents](docs/guides/agent-templates.md)
+**Perfect for**: Regulated industries (finance, healthcare, government), enterprises with compliance requirements
 ---
-## 🏗️ Architecture: How It All Fits Together
-```
-┌─────────────────────────────────────────────────────────────┐
-│  1. YAML Spec (workflow.ax.yaml)                           │
-│     • Define actors and workflow steps                      │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│  2. Spec-Kit Generation (ax gen)                           │
-│     • Plan: Execution plan with resource requirements       │
-│     • DAG: Dependency graph with change detection hash      │
-│     • Scaffold: Complete project structure                  │
-│     • Tests: Unit, integration, E2E test suites            │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│  3. CLI Orchestration (Router)                             │
-│     • Execute with configured provider                      │
-│     • Wrap claude/gemini/grok/codex CLI calls              │
-│     • Fallback on failure                                   │
-│     • Log all executions to trace file                      │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│  4. Memory & Context (MemoryManager)                        │
-│     • Index: Save response to SQLite FTS5                   │
-│     • Retrieve: Search < 1ms for future tasks               │
-│     • Inject: Auto-add context to prompts                   │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-┌─────────────────────────────────────────────────────────────┐
-│  5. Observability (RouterTraceLogger)                       │
-│     • Log: JSONL trace to .automatosx/logs/                │
-│     • View: ax providers trace --follow                     │
-│     • Debug: Complete visibility into all executions        │
-└─────────────────────────────────────────────────────────────┘
-```
+### 🆚 Edition Comparison
+| Feature | Open Source | Pro | Enterprise |
+|---------|-------------|-----|------------|
+| **Core Orchestration** | ✅ Full | ✅ Full | ✅ Full |
+| **Multi-Provider Support** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Persistent Memory** | ✅ Yes | ✅ Encrypted | ✅ Encrypted + DLP |
+| **MCP Management** | ✅ Local | ✅ Auto-install | ✅ Central registry |
+| **Support** | Community | Priority email | Enterprise SLA |
+| **LTS Releases** | ❌ No | ✅ Yes | ✅ Yes + backports |
+| **Multi-Project** | Manual | ✅ Managed | ✅ Org catalog |
+| **Custom Agents** | DIY | ✅ Agent packs | ✅ Org library |
+| **Observability** | Local logs | ✅ Dashboard | ✅ SIEM integration |
+| **Deployment** | Local only | Local only | ✅ Self-hosted cluster |
+| **SSO / RBAC** | ❌ No | ❌ No | ✅ Yes |
+| **Audit Logs** | Basic | Basic | ✅ Compliance-grade |
+| **Data Governance** | ❌ No | ❌ No | ✅ Full DLP + policies |
+| **Pricing** | Free (OSS) | Contact sales | Contact sales |
 ---
-## 📚 Real-World Examples
-### Example 1: E-Commerce Checkout System
-```yaml
-# checkout.ax.yaml
-metadata:
-  id: ecommerce-checkout
-  name: E-Commerce Checkout System
-actors:
-  - id: backend
-    agent: backend
-    description: Implement Stripe integration and inventory management
-  - id: security
-    agent: security
-    description: Implement fraud detection and PCI compliance checks
+### 📞 Get Started with Pro or Enterprise
-  - id: quality
-    agent: quality
-    description: E2E tests for checkout flow with Stripe test mode
-```
+**AutomatosX Pro**: Perfect for commercial teams needing stability and support
+- Email: sales@defai.digital
+- Subject: "AutomatosX Pro - Pricing Inquiry"
-```bash
-# Generate and execute
-ax gen plan checkout.ax.yaml     # Generate execution plan
-ax gen scaffold checkout.ax.yaml # Create project structure
-ax gen tests checkout.ax.yaml    # Generate test suite
-ax run checkout.ax.yaml          # Execute workflow
-# Result:
-#   - Complete Stripe integration
-#   - Fraud detection system
-#   - PCI compliant
-#   - 60%+ test coverage
-```
+**AutomatosX Enterprise**: For organizations requiring compliance at scale
+- Email: sales@defai.digital
+- Subject: "AutomatosX Enterprise - Compliance Discussion"
-### Example 2: Microservices API
-```bash
-# Natural language workflow
-ax spec create "Build microservices API with user service, auth service, API gateway, and Docker deployment"
-# AutomatosX generates:
-#   - Service architecture design
-#   - Three microservices in parallel
-#   - API gateway with rate limiting
-#   - Docker compose configuration
-#   - Integration tests
-#   - Documentation
-# Execute workflow
-ax run workflow.ax.yaml
-# Monitor executions
-ax providers trace --follow
-```
+**Questions about licensing?** See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)
 ---
-## 🎨 Advanced Features
-### Parallel Execution
-```bash
-# Execute tasks in parallel for 3-5x speedup
-ax spec run --parallel
-# AutomatosX automatically:
-#   - Builds dependency graph
-#   - Runs independent tasks concurrently
-#   - Waits for dependencies before starting
-#   - Aggregates results
-```
+## 🏆 Why AutomatosX Wins
-### Checkpoints & Resume
+| Capability | AutomatosX | Claude Code | Gemini CLI | Cursor |
+|------------|------------|-------------|------------|--------|
+| **Role** | **Power addon** | AI assistant | AI assistant | AI editor |
+| **Learning Curve** | **Zero** (use naturally) | Low | Low | Medium |
+| **Multi-Provider** | ✅ Auto-routing | ⚠️ Claude only | ⚠️ Gemini only | ⚠️ Limited |
+| **Cost Savings** | ✅ 80% via routing | ❌ Pay-as-you-go | ❌ Pay-as-you-go | ❌ Pay-as-you-go |
+| **Persistent Memory** | ✅ Forever | ❌ Session-only | ❌ Session-only | ❌ Session-only |
+| **Multi-Agent Teams** | ✅ 20 specialists | ❌ Single agent | ❌ Single agent | ❌ Single agent |
+| **Workflow Automation** | ✅ YAML specs | ❌ | ❌ | ❌ |
+| **Observability** | ✅ Complete traces | ⚠️ Basic | ⚠️ Basic | ⚠️ Basic |
+| **Offline-Friendly** | ✅ 100% local | ⚠️ Hybrid | ⚠️ Hybrid | ⚠️ Cloud |
+| **Compliance** | ✅ GDPR-ready | ❌ | ❌ | ❌ |
+**Bottom Line**: AutomatosX is the **only power addon** that gives you enterprise capabilities **without changing your workflow**.
-```bash
-# Long-running workflows save checkpoints
-ax spec run --resumable
+---
-# Interrupt anytime (Ctrl+C)
-# Resume from last checkpoint
-ax resume <run-id>
+## 📚 Real-World Use Cases
-# List all runs
-ax runs list
-```
+### 1. Startup Reducing AI Costs by 80%
-### Change Detection
+**Scenario**: Small team, limited budget
-```bash
-# Generate DAG with hash
-ax gen dag workflow.ax.yaml -o dag.json
-# DAG stores spec hash for change detection
-# If spec changes, AutomatosX warns you before execution
-ax run dag.json
-# → Warning: Spec has changed. Regenerate DAG? (Y/n)
 ```
-### 🎯 Enterprise MCP Server Management (Phase 4)
-**NEW in v8.5.3**: Production-ready Model Context Protocol (MCP) server orchestration with comprehensive lifecycle management, auto-installation, and enterprise-grade monitoring.
-#### **Phase 4A: Lifecycle Management**
-```bash
-# Start AutomatosX as MCP server for Claude Code
-ax mcp server
-# Monitor server status
-ax mcp status
-# View lifecycle events
-ax mcp logs --follow
-# All server events are logged to:
-# .automatosx/logs/mcp/lifecycle-events.jsonl
+"Build user authentication with security audit and tests.
+Use cost-efficient routing - this is a standard feature."
 ```
-**Features**:
-- ✅ Comprehensive event logging (start/stop/restart/crash/health)
-- ✅ Automatic log rotation when file exceeds size limit
-- ✅ Event history retrieval for debugging
-- ✅ JSONL format for machine-readable logs
+**What AutomatosX does**:
+- Routes implementation to Gemini ($20/mo unlimited)
+- Routes security audit to Claude (critical accuracy)
+- Generates tests with Gemini (fast)
+- Saves design to memory (zero token waste in future)
-#### **Phase 4B: Auto-Installation**
-```bash
-# Discover available MCP servers
-ax mcp discover
+**Cost**: $40/mo total (Claude Pro + Gemini Advanced)
+**vs API-only**: $200-300/mo
+**Savings**: $160-260/mo (80% reduction)
-# Install MCP server packages
-ax mcp install @modelcontextprotocol/server-filesystem
-ax mcp install @modelcontextprotocol/server-github
-ax mcp install @modelcontextprotocol/server-git
+### 2. Enterprise Ensuring Compliance
-# Install multiple packages in parallel
-ax mcp install --batch filesystem github git
+**Scenario**: Finance company with GDPR requirements
-# Update installed servers
-ax mcp update @modelcontextprotocol/server-filesystem
 ```
-**Features**:
-- ✅ NPM registry search and package discovery
-- ✅ One-command installation for MCP servers
-- ✅ Support for npm, yarn, and pnpm package managers
-- ✅ Batch installation for faster setup
-- ✅ Version management (update, uninstall)
-- ✅ Dry-run mode for testing installations
-#### **Phase 4C: Configuration Hot-Reload**
-```bash
-# Edit MCP configuration (changes apply automatically)
-vim ax.config.json
-# Configuration changes are detected and applied without restart!
-# - Server configurations updated
-# - Security limits adjusted
-# - Health check settings modified
+"Review this payment processing code for vulnerabilities.
+Log everything for compliance audit."
 ```
-**Features**:
-- ✅ Configuration hot-reload without server restart
-- ✅ File watching with debounced change detection (1 second)
-- ✅ Comprehensive validation with error and warning reporting
-- ✅ Change event notifications for dynamic updates
-- ✅ Default configuration fallback
-#### **Phase 4D: Performance Monitoring**
-```bash
-# View real-time metrics for all servers
-ax mcp metrics
-# Show detailed metrics for specific server
-ax mcp metrics filesystem-server
+**What AutomatosX does**:
+- Executes entirely offline (no data leaves company)
+- Generates complete JSONL audit trail
+- Uses local models via Ollama (air-gapped)
+- Saves to encrypted local memory
-# View metrics summary
-ax mcp metrics --summary
+**Compliance**: ✅ GDPR-ready, complete audit trail
+**Security**: ✅ Zero data exfiltration
+**Cost**: ✅ No cloud API costs
-# Export metrics history
-ax mcp metrics --export > metrics.json
-```
+### 3. Team Coordinating Multi-Agent Workflows
-**Metrics Collected**:
-- ✅ CPU usage percentage per server
-- ✅ Memory usage (MB) per server
-- ✅ Server uptime (seconds)
-- ✅ Total requests handled
-- ✅ Failed requests count
-- ✅ Average/min/max response times
-- ✅ Restart count
-- ✅ Time-series data with configurable retention (default: 24 hours)
-#### **Phase 4E: Resource Limits & Security**
-```bash
-# View current resource limits
-ax mcp limits
+**Scenario**: 5 developers building microservices
-# Set custom limits for specific server
-ax mcp limits filesystem-server --memory 1024 --cpu 75
-# Configure enforcement mode (warn/throttle/kill)
-ax config set mcp.security.enforcementMode throttle
 ```
-**Security Features**:
-- ✅ Resource limit enforcement (CPU, memory)
-- ✅ Configurable enforcement modes:
-  - `warn` - Log violations only
-  - `throttle` - Temporarily pause violating processes (SIGSTOP/SIGCONT)
-  - `kill` - Terminate violating processes (SIGKILL)
-- ✅ Grace period before enforcement (default: 10 seconds)
-- ✅ Per-server limit overrides
-- ✅ Violation event logging and alerting
-- ✅ Filesystem and network restrictions
-#### **Configuration Example**
-```json
-{
-  "mcp": {
-    "enabled": true,
-    "servers": [
-      {
-        "name": "filesystem",
-        "command": "npx",
-        "args": ["@modelcontextprotocol/server-filesystem", "/allowed/path"],
-        "enabled": true
-      }
-    ],
-    "discovery": {
-      "enabled": true,
-      "packagePrefixes": ["@modelcontextprotocol/server-"]
-    },
-    "security": {
-      "limits": {
-        "maxServers": 10,
-        "maxMemoryPerServer": 512,
-        "maxCpuPerServer": 50
-      },
-      "filesystem": {
-        "allowedPaths": ["/home/user/data"],
-        "deniedPaths": ["/home/user/.ssh"]
-      }
-    },
-    "healthCheck": {
-      "enabled": true,
-      "intervalMs": 60000,
-      "restartOnFailure": true
-    },
-    "logging": {
-      "logServerOutput": true,
-      "logLevel": "info"
-    }
-  }
-}
+"Product agent, design payment service.
+Backend agent, implement it.
+Security agent, audit it.
+Quality agent, write tests.
+Save everything to shared memory."
 ```
-#### **Performance Impact**
-- Memory overhead: ~8-10 MB (with 24h metrics retention)
-- CPU overhead: ~3-5% (periodic monitoring tasks)
-- Startup time: +50ms for Phase 4 initialization
+**What AutomatosX does**:
+- Product → Backend → Security → Quality (automatic delegation)
+- Routes to optimal providers (cost + performance)
+- Shared memory across team (perfect context)
+- Parallel execution (3-5x faster)
-**Production-Ready**: All Phase 4 features are fully backward compatible and opt-in. Enable what you need, when you need it.
+**Result**: 5x productivity, 80% cost savings, zero manual coordination
 ---
-## 📖 Documentation
-### Getting Started
+## 🎓 Documentation
-- **[3-Minute Quickstart](docs/getting-started/quickstart-3min.md)** ⚡ **[NEW]** - Get productive in under 3 minutes
-- [Quick Start Guide](docs/getting-started/quick-start.md) - Get running in 5 minutes
-- [Installation](docs/getting-started/installation.md) - Detailed installation instructions
-- [Configuration](docs/guides/configuration.md) - Configure providers and settings
+### Getting Started (5 Minutes)
+- **[Quick Start Guide](docs/getting-started/quickstart-3min.md)** - Get productive fast
+- [Installation](docs/getting-started/installation.md) - Detailed setup
-### Core Features
+### Natural Language Usage (Recommended)
+- **[Using with Claude Code](docs/guides/claude-code-integration.md)** - Best practices
+- [Using with OpenAI Codex](docs/guides/codex-integration.md) - Natural language examples
+- [Agent Collaboration](docs/guides/agent-communication.md) - Multi-agent workflows
-- **[Spec-Kit Usage Guide](docs/guides/spec-kit-guide.md)** 📋 **[NEW]** - Complete YAML workflow guide with examples
-- **[Iteration Mode Guide](docs/guides/iteration-mode-guide.md)** 🔄 **[NEW]** - Multi-iteration autonomous analysis
-- [Provider Configuration](docs/providers/overview.md) - Multi-provider CLI orchestration
-- [Persistent Memory](docs/guides/agent-communication.md) - Context management
-- [Multi-Agent Orchestration](docs/guides/multi-agent-orchestration.md) - Team coordination
+### Advanced Features
+- [Cost Optimization Strategies](docs/advanced/cost-optimization.md) - Save 80%
+- [Persistent Memory Guide](docs/guides/memory.md) - Context management
+- [Workflow Automation](docs/guides/spec-kit-guide.md) - YAML workflows
+- [Observability](docs/advanced/observability.md) - Trace logging
-### Advanced
+### For Advanced Users (5% Who Need CLI)
+- **[Full Features List](docs/full-features.md)** - All CLI commands and capabilities
+- [CLI Command Reference](docs/reference/cli-commands.md) - Complete CLI docs
+- [API Reference](docs/reference/api.md) - Programmatic usage
-- [Custom Agents](docs/guides/agent-templates.md) - Create your own specialists
-- [Provider Configuration](docs/providers/overview.md) - Add AI providers
-- [Performance & Caching](docs/advanced/performance.md) - Optimization techniques
-- [Parallel Execution](docs/advanced/parallel-execution.md) - Scale your workflows
-### Reference
-- [Agent Directory](docs/guides/agents.md) - All 20 agents
-- [CLI Reference](docs/reference/cli-commands.md) - All commands
-- [Provider Comparison](docs/providers/overview.md) - Provider features and costs
-- [Troubleshooting](TROUBLESHOOTING.md) - Common issues and solutions
----
-## 🏆 Why AutomatosX Wins
-| Capability | AutomatosX | Claude Code | Cursor | GitHub Copilot |
-|------------|------------|-------------|--------|----------------|
-| **Declarative Workflows** | ✅ YAML specs | ❌ | ❌ | ❌ |
-| **Auto-Generation** | ✅ Plans, DAGs, scaffolds, tests | ❌ | ❌ | ❌ |
-| **CLI Orchestration** | ✅ Pure wrapper around AI CLIs | ❌ | ❌ | ❌ |
-| **Persistent Memory** | ✅ SQLite FTS5 < 1ms | ❌ | ❌ | ❌ |
-| **Multi-Agent Teams** | ✅ 20 specialists | ❌ | ❌ | ❌ |
-| **Multi-Provider Support** | ✅ Claude, Gemini, Grok, Codex | ⚠️ Claude only | ⚠️ Limited | ⚠️ Limited |
-| **MCP Server Management** | ✅ Enterprise-grade (Phase 4) | ⚠️ Basic | ❌ | ❌ |
-| **Complete Observability** | ✅ Trace logging + metrics | ❌ | ❌ | ❌ |
-| **Parallel Execution** | ✅ DAG-based | ❌ | ❌ | ❌ |
-| **Local-First** | ✅ 100% private | ⚠️ Hybrid | ⚠️ Cloud | ⚠️ Cloud |
-**Bottom Line**: AutomatosX is the **only platform** that combines declarative workflows, persistent memory, multi-agent orchestration, enterprise MCP management, and pure CLI orchestration in one tool.
----
-## 🚦 Production Readiness
-✅ **v8.5.3 Released** - Enterprise MCP Phase 4 complete
-✅ **v7.0.0 Released** - Natural language-first design, unified setup
-✅ **100% Complete** - Spec-Kit integration + MCP management fully implemented
-✅ **2,512+ Tests Passing** - Comprehensive test coverage
-✅ **TypeScript Strict Mode** - Type-safe codebase
-✅ **Enterprise MCP** - Production-ready server lifecycle, metrics, security
-✅ **Zero Resource Leaks** - Clean shutdown guaranteed
-✅ **Cross-Platform** - macOS, Windows, Ubuntu
-✅ **Local-First** - No cloud dependencies, 100% private
+### Enterprise
+- [Security & Compliance](docs/advanced/security.md) - GDPR, HIPAA, SOC2
+- [Offline Deployment](docs/advanced/offline-deployment.md) - Air-gapped environments
+- [Multi-Region Setup](docs/advanced/multi-region.md) - Data sovereignty
 ---
@@ -1132,207 +607,61 @@ ax config set mcp.security.enforcementMode throttle
 ```bash
 npm install -g @defai.digital/automatosx
-ax --version  # v7.0.0
+ax --version  # v9.2.3
 ```
-### ⚠️ REQUIRED: Initialize Your Project
-**After installing, you MUST run `ax setup` in your project directory to initialize the AutomatosX workspace:**
+### Initialize Your Project
 ```bash
-# Navigate to your project directory
 cd your-project
-# Set up AutomatosX (creates .automatosx/ with agents and config)
 ax setup
-# Or force reinitialize if you already have a .automatosx/ directory
-ax setup -f
 ```
 **What `ax setup` does:**
+- ✅ Creates `.automatosx/` directory
+- ✅ Installs all 20 specialized agents
+- ✅ Generates optimal configuration
+- ✅ Initializes persistent memory database
+- ✅ Sets up trace logging
-- ✅ Creates `.automatosx/` directory structure
-- ✅ Installs all 20 specialized agents (backend, frontend, security, etc.)
-- ✅ Generates `ax.config.json` with optimal defaults
-- ✅ Initializes SQLite memory database
-- ✅ Sets up session management
-- ✅ Configures trace logging
-**Without running `ax setup`, AutomatosX commands will not work properly!**
-### ✨ Optional: AI-Powered Setup (v7.1.2+)
-For a more advanced, AI-driven setup, you can use the `ax init` command. It analyzes your project to create a tailored integration guide (`ax.md`) for AI assistants.
-```bash
-# Run the interactive, AI-powered initialization
-ax init
-```
-Use `ax setup` for the standard, essential setup. Use `ax init` for an enhanced AI integration experience.**
+**That's it!** Now just use Claude Code/Codex naturally - AutomatosX runs invisibly.
 ### Requirements
 - **Node.js**: >= 24.0.0
-- **AI Providers**: At least one:
-  - [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) (recommended - cheapest)
-  - [OpenAI Codex](https://platform.openai.com/docs/guides/code) (fastest)
-  - [Claude Code](https://claude.ai/code) (most capable)
-  - [ax-cli](.ax-cli/README.md) (multi-provider: GLM, xAI, OpenAI, Anthropic, Ollama)
+- **At least one AI CLI** (you probably already have):
+  - [Claude Code](https://claude.ai/code) - **Recommended** (best reasoning)
+  - [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) - Cost-efficient
+  - [OpenAI Codex](https://platform.openai.com/docs/guides/code) - Fastest
-[➡️ Full Installation Guide](docs/getting-started/installation.md)
+**Optional**:
+- [ax-cli](.ax-cli/README.md) - GLM-first native CLI for Chinese models
 ---
-## 🗺️ Roadmap
-### Completed (v6.0.0 - v7.0.0)
-- ✅ **v7.0.0 - Natural Language First** (Latest)
-  - ✅ Unified setup command (init→setup)
-  - ✅ Natural language-only interaction
-  - ✅ Enhanced force mode with complete cleanup
-  - ✅ Removed slash command dependencies
-- ✅ **v8.3.0 - Major Simplification** (Latest)
-  - ✅ Removed policy routing, free-tier management (~36,000 lines)
-  - ✅ Pure CLI orchestration wrapper
-  - ✅ Streamlined architecture
-  - ✅ Focus on core features
-- ✅ Spec-Kit Integration (100%)
-  - ✅ Plan generation
-  - ✅ DAG generation
-  - ✅ Scaffold generation
-  - ✅ Test generation
-  - ✅ Regeneration Detector (v6.5.6)
-- ✅ CLI Orchestration
-  - ✅ Multi-provider support (Claude, Gemini, Grok, Codex)
-  - ✅ Pure CLI wrapper (no API key required for CLI mode)
-  - ✅ Fallback and retry logic
-- ✅ Router Trace Logging
-  - ✅ JSONL format
-  - ✅ Real-time following
-  - ✅ Color-coded CLI
-### Coming Soon (v8.5.3+)
-- ⏳ Enhanced Spec Features
-  - Advanced DAG visualization
-  - Workflow templates library
-  - Interactive spec builder
-- ⏳ Enhanced Parallel Execution
-  - Resource-aware scheduling
-  - Priority-based execution
-[View Full Roadmap](#roadmap)
----
-## 🔄 Migration from v6.x
-**v7.0.0 introduces breaking changes. Follow this guide to upgrade:**
-### Breaking Changes
-1. **Command Rename**: `ax init` → `ax setup`
-   ```bash
-   # ❌ v6.x (deprecated)
-   ax init
-   # ✅ v7.0.0 (new)
-   ax setup
-   ```
-2. **Slash Commands Removed**: Natural language only
-   - ❌ No more `.claude/commands/ax-*.md` files
-   - ❌ No more `.gemini/commands/ax-*.toml` files
-   - ✅ Use natural language with AI assistants instead
-   ```
-   # ✅ v7.0.0 - Natural language (recommended)
-   "Please use ax to implement user authentication"
-   "Work with ax to audit this code for security issues"
-   "Have ax write tests for this feature"
-   ```
-3. **Enhanced Force Mode**: Complete cleanup on `ax setup --force`
-   - Now removes `.automatosx/` directory completely
-   - Removes all `.claude/commands/ax-*` files
-   - Removes all `.gemini/commands/ax-*` files
-   - Ensures clean reinstall with no leftover files
-### Migration Steps
-1. **Update AutomatosX**:
-   ```bash
-   npm update -g @defai.digital/automatosx
-   ax --version  # Should show v7.0.0
-   ```
-2. **Clean Install** (Recommended):
-   ```bash
-   cd your-project
-   ax setup --force  # Complete cleanup and reinstall
-   ```
-3. **Update Scripts**: Change any scripts using `ax init` to `ax setup`
-   ```bash
-   # Update in package.json, shell scripts, CI/CD configs
-   sed -i '' 's/ax init/ax setup/g' package.json
-   ```
-4. **Remove Custom Slash Commands** (if you had any):
-   ```bash
-   # These are no longer needed
-   rm -rf .claude/commands/ax-*
-   rm -rf .gemini/commands/ax-*
-   ```
-5. **Update Documentation**: Search your docs for `ax init` references
-### What Stays the Same
-- ✅ All agent functionality unchanged
-- ✅ Memory system works the same
-- ✅ Spec-Kit features unchanged
-- ✅ CLI orchestration works the same
-- ✅ Multi-provider support unchanged
-- ✅ CLI command syntax (except init→setup)
-### Need Help?
-- [GitHub Releases (https://github.com/defai-digital/automatosx/releases)](GitHub Releases (https://github.com/defai-digital/automatosx/releases)) - Full v7.0.0 changes
-- [GitHub Issues](https://github.com/defai-digital/automatosx/issues) - Report migration issues
-- [Troubleshooting Guide](TROUBLESHOOTING.md) - Common problems
+## 🚦 Production Readiness
-[View Full Roadmap](#roadmap)
+✅ **v9.2.3 Released** - ax-cli SDK Phase 2 complete
+✅ **2,512+ Tests Passing** - Comprehensive coverage
+✅ **TypeScript Strict Mode** - Type-safe codebase
+✅ **Zero Resource Leaks** - Clean shutdown guaranteed
+✅ **Cross-Platform** - macOS, Windows, Ubuntu
+✅ **100% Local-First** - No cloud dependencies
+✅ **Enterprise-Ready** - Observability, governance, compliance
 ---
 ## 🤝 Contributing
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md)
 ### Development Setup
 ```bash
-# Clone the repo
 git clone https://github.com/defai-digital/automatosx.git
 cd automatosx
-# Install dependencies
 npm install
-# Run in dev mode
-npm run dev -- run backend "test task"
-# Run tests
 npm test
-# Run type checking
-npm run typecheck
-# Build
-npm run build
 ```
 ---
@@ -1341,25 +670,16 @@ npm run build
 AutomatosX is dual-licensed:
-- **Apache License 2.0** - See [LICENSE](LICENSE) for code licensing
-- **Commercial License with OpenRAIL-M** - See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) for commercial use and model restrictions
-### TL;DR - When Do You Need a Commercial License?
+- **Apache License 2.0** - See [LICENSE](LICENSE)
+- **Commercial License with OpenRAIL-M** - See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)
-**✅ FREE for**:
-- Research and academic use
-- Personal projects
-- Startups with < $2M revenue AND < $2M funding
+**TL;DR**:
+- ✅ FREE for research, academic, personal projects, startups < $2M revenue
+- ❌ Commercial license required for companies ≥ $2M revenue/funding
-**❌ Commercial License Required for**:
-- Companies with ≥ $2M annual revenue OR ≥ $2M total funding
-- Competitive products against DEFAI's offerings
-- SaaS or managed services built on AutomatosX
-- Commercial redistribution or embedding
-**Learn more**: See [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) for full details.
-**Get a commercial license**: https://license.defai.digital/automatox
+**Need a commercial license?**
+- Email: <sales@defai.digital>
+- Subject: "AutomatosX Commercial License Inquiry"
 Copyright 2025 DEFAI Private Limited
@@ -1367,7 +687,7 @@ Copyright 2025 DEFAI Private Limited
 ## 🌟 Star Us on GitHub
-If AutomatosX saves you time and money, give us a star! ⭐
+If AutomatosX saves you 80% on AI costs **without changing your workflow**, give us a star! ⭐
 [⭐ Star on GitHub](https://github.com/defai-digital/automatosx)
@@ -1377,10 +697,10 @@ If AutomatosX saves you time and money, give us a star! ⭐
 - **Issues**: [GitHub Issues](https://github.com/defai-digital/automatosx/issues)
 - **Email**: <support@defai.digital>
+- **Commercial Licenses**: <sales@defai.digital>
 ---
 <p align="center">
   Made with ❤️ by <a href="https://defai.digital">DEFAI Digital</a>
 </p>