@defai.digital/ax-cli 1.1.3 → 1.1.4

package/README.md

@@ -1,6 +1,6 @@
 # AX CLI - Enterprise-Class AI CLI
 
-[![Tests](https://img.shields.io/badge/tests-124%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
+[![Tests](https://img.shields.io/badge/tests-306%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
 [![Coverage](https://img.shields.io/badge/coverage-98.29%25-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen?style=flat-square)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
@@ -14,1355 +14,182 @@
 
 ---
 
-## 🚀 Overview
+## 🚀 Quick Start
 
-**AX CLI** is an **enterprise-class AI command line interface** primarily designed for **GLM (General Language Model)** with support for multiple AI providers. Combining the power of offline-first local LLM execution with cloud-based AI services, AX CLI delivers production-ready quality with comprehensive testing, robust TypeScript architecture, and enterprise-grade reliability.
-
-Originally forked from [grok-cli](https://github.com/superagent-ai/grok-cli), AX CLI has been extensively upgraded using **AutomatosX** — a multi-agent AI orchestration platform — to achieve enterprise-class standards.
-
-### 🏆 Enterprise-Class Features
-
-- **🤖 Built with AutomatosX**: Developed using multi-agent collaboration for production-quality code
-- **✅ 98%+ Test Coverage**: Comprehensive test suite with 83+ tests covering critical paths
-- **🔒 Type-Safe Architecture**: Full TypeScript with Zod runtime validation
-- **🎯 Node.js 24+ Ready**: Modern JavaScript runtime support
-- **📊 Quality Assurance**: Automated testing, linting, and continuous integration
-- **🏗️ Enterprise Architecture**: Clean separation of concerns, modular design, extensible APIs
-
-### 💡 Why AX CLI?
-
-**GLM-Optimized**: Primary support for GLM (General Language Model) with optimized performance for local and cloud GLM deployments.
-
-**Production-Ready**: AX CLI is enterprise-grade with extensive testing, TypeScript safety, and proven reliability.
-
----
-
-## 🏗️ Enterprise Architecture
-
-### Single Source of Truth (SSOT) Type System
-
-AX CLI implements a **Single Source of Truth** design pattern through the `@ax-cli/schemas` package. This ensures that **API handlers, billing modules, and MCP adapters all consume the same schema**, drastically reducing future refactoring costs.
-
-#### The Problem: Before SSOT
-
-Without centralized schemas, each module maintained its own type definitions, leading to:
-
-```
-┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
-│   API Handler       │     │   MCP Adapter       │     │   Billing Module    │
-├─────────────────────┤     ├─────────────────────┤     ├─────────────────────┤
-│ type ModelId =      │     │ type ModelName =    │     │ type Model =        │
-│   string            │     │   string            │     │   string            │
-│                     │     │                     │     │                     │
-│ interface Message { │     │ interface Msg {     │     │ interface Request { │
-│   role: string      │     │   type: string      │     │   role: string      │
-│   content: string   │     │   text: string      │     │   content: string   │
-│ }                   │     │ }                   │     │ }                   │
-└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
-        ❌                          ❌                          ❌
-   Own schemas               Own schemas               Own schemas
-   Duplicated logic          Duplicated logic          Duplicated logic
-   Diverges over time        Diverges over time        Diverges over time
-```
-
-**Risks**:
-- ❌ **Type Mismatches**: API expects `role: string` but MCP sends `type: string`
-- ❌ **Duplicated Validation**: Same validation logic copied across 3 modules
-- ❌ **Silent Failures**: Changes in one module break others at runtime
-- ❌ **High Refactoring Cost**: Update model schema = touch 3+ files
-- ❌ **No Contract Enforcement**: No guarantee modules speak the same language
-
-#### The Solution: After SSOT
-
-With `@ax-cli/schemas`, all modules import from a single source:
-
-```
-                        ┌────────────────────────────────────┐
-                        │       @ax-cli/schemas              │
-                        │    (Single Source of Truth)        │
-                        ├────────────────────────────────────┤
-                        │                                    │
-                        │  • Brand Types (ModelId, etc.)     │
-                        │  • Centralized Enums (MessageRole) │
-                        │  • Zod Schemas (runtime validation)│
-                        │  • TypeScript Types (compile-time) │
-                        │                                    │
-                        └──────────────┬─────────────────────┘
-                                       │
-                         ┌─────────────┼─────────────┐
-                         │             │             │
-                         ▼             ▼             ▼
-              ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-              │ API Handler  │ │ MCP Adapter  │ │Billing Module│
-              ├──────────────┤ ├──────────────┤ ├──────────────┤
-              │ import {     │ │ import {     │ │ import {     │
-              │   ModelId,   │ │   ModelId,   │ │   ModelId,   │
-              │   Message    │ │   Message    │ │   Message    │
-              │ } from       │ │ } from       │ │ } from       │
-              │ '@ax-cli/    │ │ '@ax-cli/    │ │ '@ax-cli/    │
-              │  schemas'    │ │  schemas'    │ │  schemas'    │
-              └──────────────┘ └──────────────┘ └──────────────┘
-                    ✅               ✅               ✅
-               Same contract    Same contract    Same contract
-               Same validation  Same validation  Same validation
-```
-
-**Benefits**:
-- ✅ **Zero Divergence**: All modules consume identical type definitions
-- ✅ **Reduced Refactoring Cost**: Change once, propagate everywhere (1 file vs 3+ files)
-- ✅ **Compile-Time Safety**: TypeScript catches mismatches across module boundaries
-- ✅ **Runtime Validation**: Zod schemas ensure data validity at system boundaries
-- ✅ **Contract Enforcement**: Brand types prevent mixing incompatible IDs
-
-#### SSOT in Action
-
-**Example: Adding a new model**
-
-Before SSOT (3 files to update):
-```typescript
-// File 1: src/api/handler.ts
-type ModelId = string;  // Update here
-
-// File 2: src/mcp/adapter.ts
-type ModelName = string;  // Update here too
-
-// File 3: src/billing/tracker.ts
-type Model = string;  // And here
-```
-
-After SSOT (1 file to update):
-```typescript
-// File: packages/schemas/src/public/core/id-types.ts
-export const ModelIdSchema = z.string().brand<'ModelId'>();
-export type ModelId = z.infer<typeof ModelIdSchema>;
-
-// All consumers automatically get the update:
-// ✅ API handler
-// ✅ MCP adapter
-// ✅ Billing module
-```
-
-#### Quality Metrics
-
-| Metric | Before SSOT | After SSOT | Improvement |
-|--------|-------------|------------|-------------|
-| **Schema Duplication** | 3+ copies | 1 canonical | 67% reduction |
-| **Refactoring Cost** | 3+ files | 1 file | 67% faster |
-| **Type Mismatches** | Runtime errors | Compile-time catch | 100% safer |
-| **Validation Consistency** | Divergent | Unified | Enterprise-grade |
-| **Test Coverage** | Partial | 98.29% (124 tests) | Production-ready |
-
-### Technology Stack
-
-- **Language**: TypeScript 5.3+ (strict mode)
-- **Runtime**: Node.js 24+
-- **Validation**: Zod 3.x for runtime type safety
-- **Testing**: Vitest with 98%+ coverage
-- **UI**: Ink (React for CLI)
-- **AI Providers**: OpenAI-compatible APIs
-- **Package Manager**: npm / bun
-
-### Code Quality
-
-- **Linting**: ESLint with TypeScript rules
-- **Type Checking**: TypeScript strict mode enabled
-- **Runtime Validation**: Zod schemas for all inputs
-- **Testing**: Vitest with comprehensive test suite
-- **CI/CD**: GitHub Actions for automated testing
-
-### Test Suite
-
-**83 tests** covering critical functionality:
-
-```
-📊 Test Coverage Report
-─────────────────────────────────────
-Overall:          98.29%
-├─ Text Utils:    98.55% (36 tests)
-├─ Token Counter: 100%   (19 tests)
-└─ Schemas:       95.23% (28 tests)
-
-🎯 Coverage Breakdown
-─────────────────────────────────────
-Statements:  98.29%
-Branches:    95.06%
-Functions:   100%
-Lines:       98.19%
-```
-
-**What's Tested:**
-- ✅ Text manipulation (word navigation, deletion, Unicode)
-- ✅ Token counting (messages, streaming, formatting)
-- ✅ Schema validation (settings, MCP, API responses)
-- ✅ Edge cases (empty strings, null, surrogate pairs)
-- ✅ Error handling and validation
-
-**Run Tests:**
 ```bash
-npm test                  # Run all tests
-npm run test:watch        # Watch mode
-npm run test:coverage     # Coverage report
-npm run test:ui           # Interactive UI
-```
-
----
-
-## ✨ Key Features
-
-### 🔒 **GLM-First Architecture**
-- **Primary Support**: Optimized for GLM (General Language Model) deployments
-- **Local GLM**: Run GLM 4.6 and other GLM models locally via Ollama
-- **Cloud GLM**: Connect to cloud-hosted GLM services
-- **Zero internet dependency** for complete privacy with local models
-- **No API keys required** for local operation
-- Full conversational AI capabilities offline
+# Install globally
+npm install -g @defai.digital/ax-cli
 
-### 🚀 **Multi-Provider AI Support**
-- **Primary**: GLM 4.6 (200K context, reasoning mode) - Default model optimized for AX CLI
-- **Built-in GLM Models**: glm-4.6, grok-code-fast-1, glm-4-air, glm-4-airx
-- **Local Models**: Llama 3.1, Qwen 2.5, DeepSeek, and any Ollama-supported model
-- **Cloud Providers**: OpenAI (GPT-4), Anthropic (Claude), Google (Gemini), X.AI (Grok), OpenRouter, Groq
-- **Z.AI Platform**: Native support for z.ai GLM API server (cloud & local deployments)
-- **Flexible Configuration**: Switch between providers seamlessly
-- **OpenAI-Compatible API**: Works with ANY OpenAI-compatible endpoint
-- **Full Backward Compatibility**: All models from original grok-cli still supported
+# Initialize your project
+ax-cli init
 
-### 🤖 **Intelligent Automation**
-- **Smart File Operations**: AI automatically reads, creates, and edits files
-- **Bash Integration**: Execute shell commands through natural conversation
-- **Automatic Tool Selection**: AI chooses the right tools for your requests
-- **Multi-Step Task Execution**: Handle complex workflows with up to 400 tool rounds
-- **Intelligent Context Management**: Automatic pruning for infinite conversation length
-- **Project Analysis**: Auto-detect tech stack, conventions, and structure (`ax-cli init`)
+# Start interactive mode
+ax-cli
 
-### 🔌 **Extensibility**
-- **MCP Protocol Support**: Integrate Model Context Protocol servers
-- **Custom Instructions**: Project-specific AI behavior via `.ax-cli/CUSTOM.md`
-- **Plugin Architecture**: Extend with Linear, GitHub, and other MCP tools
-- **Morph Fast Apply**: Optional 4,500+ tokens/sec code editing
+# Run headless command
+ax-cli -p "list all TypeScript files"
+```
 
-### 💬 **Developer Experience**
-- **Interactive Mode**: Conversational AI assistant in your terminal
-- **Headless Mode**: Scriptable single-prompt execution for CI/CD
-- **Beautiful UI**: Ink-based terminal interface with syntax highlighting
-- **Global Installation**: Use anywhere with `npm install -g`
+## ✨ Features
 
-### 🏗️ **Enterprise Quality**
-- **98.29% Test Coverage**: Text utils, token counting, schema validation
-- **TypeScript + Zod**: Runtime type safety and validation
-- **Automated CI/CD**: Tests run on every commit and PR
-- **Comprehensive Documentation**: Detailed guides and API references
-- **Node.js 24+ Support**: Modern JavaScript runtime features
+- **🤖 Multi-Provider Support**: OpenAI, Anthropic, xAI, local models (Ollama)
+- **🧠 GLM 4.6 Optimized**: Primary support for General Language Model with advanced reasoning
+- **🔌 MCP Integration**: Model Context Protocol for extensible tool support
+- **✅ Production-Ready**: 98%+ test coverage, TypeScript strict mode, Zod validation
+- **🎯 Interactive & Headless**: Chat interface or one-shot commands
+- **📝 Smart Project Init**: Automatic project analysis and custom instructions
+- **🔄 Auto-Update**: Built-in update checker and installer
 
----
+[View all features →](docs/features.md)
 
 ## 📦 Installation
 
 ### Prerequisites
 
-#### **Node.js 24+** (Required)
-```bash
-# Check your Node.js version
-node --version  # Should be v24.0.0 or higher
-
-# Install Node.js 24+ from https://nodejs.org/
-```
-
-#### **For Offline Operation** (Recommended)
-- **Ollama** 0.1.0+ for local LLM inference
-- **GLM 4.6 Model** (9B parameters, ~5GB download)
-- **16GB RAM** minimum (32GB recommended for larger models)
-- **GPU** recommended but optional (CPU inference supported)
-
-#### **For Cloud Providers** (Optional)
-- API key from OpenAI, Anthropic, X.AI, or compatible provider
-- (Optional) Morph API key for Fast Apply editing
+- Node.js 24.0.0 or higher
+- npm or bun package manager
 
 ### Global Installation (Recommended)
 
 ```bash
-# Using npm
 npm install -g @defai.digital/ax-cli
-
-# Using bun (faster)
-bun add -g @defai.digital/ax-cli
-
-# Verify installation
-ax-cli --version
 ```
 
 ### Local Development
 
 ```bash
-# Clone the repository
-git clone https://github.com/defai-digital/ax-cli
+git clone https://github.com/defai-digital/ax-cli.git
 cd ax-cli
-
-# Install dependencies
 npm install
-
-# Build the project
 npm run build
-
-# Link globally
 npm link
-
-# Run tests
-npm test
-
-# Generate coverage report
-npm run test:coverage
 ```
 
----
-
-## ⚙️ Setup
-
-### Option 1: Offline Setup with GLM 4.6 (Privacy-First)
+[Installation Guide →](docs/installation.md)
 
-**Perfect for**: Developers who prioritize privacy, work with sensitive data, or need offline AI capabilities.
-
-#### Step 1: Install Ollama
-
-```bash
-# macOS / Linux
-curl -fsSL https://ollama.ai/install.sh | sh
+## ⚙️ Configuration
 
-# Windows
-# Download from https://ollama.ai/download
-
-# Verify installation
-ollama --version
-```
-
-#### Step 2: Download GLM 4.6 Model
+### Quick Setup
 
 ```bash
-# Pull the GLM-4-9B-Chat model (9B parameters, ~5GB download)
-ollama pull glm4:9b
-
-# Optional: Pull the vision-capable model
-ollama pull glm4v:9b
+# Set your API key (for cloud providers)
+export GROK_API_KEY=your_api_key_here
 
-# Verify models are available
-ollama list
+# Or configure in settings
+ax-cli  # Will prompt for API key on first run
 ```
 
-#### Step 3: Start Ollama Server
-
-```bash
-# Ollama runs as a background service by default
-# If needed, start it manually:
-ollama serve
-
-# Test the model
-ollama run glm4:9b "Hello, how are you?"
-```
+### Configuration Files
 
-#### Step 4: Configure AX CLI for Local Operation
+- **User Settings**: `~/.ax-cli/config.json`
+- **Project Settings**: `.ax-cli/settings.json`
+- **Custom Instructions**: `.ax-cli/CUSTOM.md`
 
-Create `~/.ax/user-settings.json`:
+[Configuration Guide →](docs/configuration.md)
 
-```json
-{
-  "baseURL": "http://localhost:11434/v1",
-  "defaultModel": "glm4:9b",
-  "models": [
-    "glm4:9b",
-    "glm4v:9b",
-    "llama3.1:8b",
-    "qwen2.5:7b"
-  ]
-}
-```
+## 🎯 Usage Examples
 
-#### Step 5: Test Your Setup
+### Interactive Mode
 
 ```bash
-# Interactive mode
+# Start interactive chat
 ax-cli
 
-# Headless mode
-ax-cli --prompt "Hello, please introduce yourself"
-
-# Specify working directory
-ax-cli --directory /path/to/project --prompt "List all TypeScript files"
-```
-
-**✅ You're now running completely offline!** No API keys, no internet, complete privacy.
-
----
-
-### Option 2: Cloud Provider Setup
-
-**Perfect for**: Teams using enterprise AI providers, developers who need the latest models, or hybrid offline/cloud workflows.
-
-#### Supported Providers
-
-**AX CLI supports ANY OpenAI-compatible API endpoint**, making it universally compatible with major AI providers.
-
-| Provider | Base URL | Supported Models | Best For |
-|----------|----------|------------------|----------|
-| **Z.AI** | `https://api.z.ai/v1` | GLM-4.6, GLM-4-Air, GLM-4-AirX | GLM models (cloud & local), 200K context, reasoning mode |
-| **X.AI (Grok)** | `https://api.x.ai/v1` | Grok, Grok Code Fast | Fast code generation, X.AI ecosystem |
-| **OpenAI** | `https://api.openai.com/v1` | GPT-4, GPT-4 Turbo, GPT-3.5 | General purpose, production-ready |
-| **Anthropic** | `https://api.anthropic.com/v1` | Claude 3.5 Sonnet, Claude 3 Opus | Long context, advanced reasoning |
-| **Google** | `https://openrouter.ai/api/v1` | Gemini Pro 1.5 (via OpenRouter) | Multi-modal, Google ecosystem |
-| **OpenRouter** | `https://openrouter.ai/api/v1` | 100+ models from all providers | Model routing, fallback strategies |
-| **Groq** | `https://api.groq.com/openai/v1` | Llama, Mistral, Gemma | Ultra-fast inference (500+ tokens/sec) |
-| **Ollama** | `http://localhost:11434/v1` | Llama, Qwen, DeepSeek, GLM, any | Complete privacy, offline operation |
-
-#### Built-in Models
-
-AX CLI includes 4 pre-configured GLM models optimized for different use cases:
-
-| Model | Context | Max Output | Thinking Mode | Best For |
-|-------|---------|-----------|---------------|----------|
-| **glm-4.6** ⭐ | 200K | 128K | ✅ Yes | Default - Long context, reasoning tasks |
-| **grok-code-fast-1** | 128K | 4K | ❌ No | Fast code generation, quick responses |
-| **glm-4-air** | 128K | 8K | ❌ No | Balanced performance, general tasks |
-| **glm-4-airx** | 8K | 8K | ❌ No | Lightweight, quick interactions |
-
-⭐ **Default Model**: glm-4.6 is the default model for AX CLI
-
-#### Step 1: Get API Key
-
-1. Sign up at your chosen provider:
-   - [Z.AI](https://docs.z.ai) - GLM models (recommended for GLM 4.6)
-   - [X.AI (Grok)](https://x.ai) - Fast code models
-   - [OpenAI](https://platform.openai.com) - GPT-4 and GPT-3.5
-   - [Anthropic](https://console.anthropic.com) - Claude 3.5 Sonnet
-   - [OpenRouter](https://openrouter.ai) - Multi-model access to 100+ models
-
-2. Generate an API key from your provider's dashboard
-
-#### Step 2: Configure API Key (Choose One Method)
-
-**Method 1: User Settings File** (Recommended)
-
-Create `~/.ax/user-settings.json`:
-
-```json
-{
-  "apiKey": "your_api_key_here",
-  "baseURL": "https://api.x.ai/v1",
-  "defaultModel": "grok-code-fast-1",
-  "models": [
-    "grok-code-fast-1",
-    "grok-4-latest",
-    "grok-3-latest"
-  ]
-}
-```
-
-**Method 2: Environment Variable**
-
-```bash
-export GROK_API_KEY="your_api_key_here"
-export GROK_BASE_URL="https://api.x.ai/v1"
-export GROK_MODEL="grok-code-fast-1"
-```
-
-**Method 3: .env File**
-
-```bash
-cp .env.example .env
-# Edit .env and add:
-GROK_API_KEY=your_api_key_here
-GROK_BASE_URL=https://api.x.ai/v1
-GROK_MODEL=grok-code-fast-1
-```
-
-**Method 4: Command Line Flags**
-
-```bash
-ax-cli --api-key your_api_key_here --base-url https://api.x.ai/v1 --model grok-code-fast-1
-```
-
-#### Step 3: (Optional) Configure Morph Fast Apply
-
-For lightning-fast code editing at 4,500+ tokens/sec:
-
-1. Get API key from [Morph Dashboard](https://morphllm.com/dashboard/api-keys)
-2. Add to environment or `.env`:
-
-```bash
-export MORPH_API_KEY="your_morph_key_here"
-```
-
----
-
-###  Multi-Provider Usage Examples
-
-AX CLI works with ANY OpenAI-compatible API. Here are examples for popular providers:
-
-**Z.AI (GLM Models - Recommended)**
-```bash
-# Cloud GLM 4.6 via Z.AI
-ax-cli --api-key YOUR_ZAI_KEY --base-url https://api.z.ai/v1 --model glm-4.6
-
-# Local Z.AI deployment
-ax-cli --base-url http://localhost:8000/v1 --model glm-4.6
-```
-
-**OpenAI (GPT-4)**
-```bash
-ax-cli --api-key YOUR_OPENAI_KEY --base-url https://api.openai.com/v1 --model gpt-4
-```
-
-**Anthropic (Claude)**
-```bash
-ax-cli --api-key YOUR_ANTHROPIC_KEY --base-url https://api.anthropic.com/v1 --model claude-3.5-sonnet
-```
-
-**Google Gemini (via OpenRouter)**
-```bash
-ax-cli --api-key YOUR_OPENROUTER_KEY --base-url https://openrouter.ai/api/v1 --model google/gemini-pro-1.5
-```
-
-**Ollama (Local - No API Key Needed)**
-```bash
-# Any Ollama model
-ax-cli --base-url http://localhost:11434/v1 --model llama3.1
-ax-cli --base-url http://localhost:11434/v1 --model qwen2.5
-ax-cli --base-url http://localhost:11434/v1 --model deepseek-coder
-```
-
-**X.AI (Grok)**
-```bash
-ax-cli --api-key YOUR_XAI_KEY --base-url https://api.x.ai/v1 --model grok-code-fast-1
+# Available slash commands:
+/help              # Show help
+/init              # Initialize project
+/clear             # Clear chat history
+/models            # Switch AI model
+/commit-and-push   # AI-powered git commit
+/exit              # Exit application
 ```
 
-**OpenRouter (100+ Models)**
-```bash
-ax-cli --api-key YOUR_OPENROUTER_KEY --base-url https://openrouter.ai/api/v1 --model anthropic/claude-3.5-sonnet
-```
-
----
-
-## 🎯 Project Initialization
-
-AX CLI can automatically analyze your project and generate optimized custom instructions for better performance and accuracy.
-
-### Quick Setup
+### Headless Mode
 
 ```bash
-# Navigate to your project
-cd /path/to/your/project
-
-# Initialize AX CLI (one-time setup)
-ax-cli init
+# One-shot commands
+ax-cli -p "analyze this codebase"
+ax-cli -p "fix TypeScript errors" -d /path/to/project
+ax-cli -p "write tests for utils/" --max-tool-rounds 50
 
-# Start using AX CLI with project-aware intelligence
-ax-cli
+# With specific model
+ax-cli -p "refactor" --model glm-4.6
 ```
 
-### What Gets Detected Automatically
-
-The `init` command intelligently analyzes your project:
-
-- ✅ **Project Type**: CLI, library, web-app, API, etc.
-- ✅ **Tech Stack**: React, Vue, Express, NestJS, Vitest, Jest, etc.
-- ✅ **Language & Conventions**: TypeScript with ESM/CJS, import extensions
-- ✅ **Directory Structure**: Source, tests, tools, config directories
-- ✅ **Build Scripts**: Test, build, lint, dev commands
-- ✅ **Package Manager**: npm, yarn, pnpm, or bun
-- ✅ **Code Conventions**: Module system, validation library, test framework
-
-### Generated Files
-
-**`.ax-cli/CUSTOM.md`** - Project-specific custom instructions:
-```markdown
-# Custom Instructions for AX CLI
-
-**Project**: your-project v1.0.0
-**Type**: cli
-**Language**: TypeScript
-**Stack**: Commander, Vitest, Zod, ESM
-
-## Code Conventions
-
-### TypeScript
-- Use explicit type annotations
-- **CRITICAL**: Always use `.js` extension in imports (ESM requirement)
-
-### Validation
-- Use **zod** for runtime validation
-- Validate all external inputs
-
-## File Structure
-- Commands: `src/commands/`
-- Utilities: `src/utils/`
-- Types: `src/types/`
-```
-
-**`.ax-cli/index.json`** - Fast project reference for quick lookups
-
-### Command Options
+### Project Initialization
 
 ```bash
-# Basic initialization
+# Analyze and initialize project
 ax-cli init
 
-# Force regeneration (after major project changes)
+# Force regeneration
 ax-cli init --force
 
-# Verbose output showing detection details
+# Verbose output
 ax-cli init --verbose
-
-# Initialize specific directory
-ax-cli init --directory /path/to/project
 ```
 
-### Benefits
-
-**🚀 Performance Improvements:**
-- **25-30% fewer tokens** - No repeated project exploration
-- **23% faster responses** - Direct file access using generated index
-- **Better accuracy** - Project conventions understood from the start
+[CLI Reference →](docs/cli-reference.md) | [Usage Guide →](docs/usage.md)
 
-**🧠 Smart Context:**
-- Knows your project structure instantly
-- Understands your tech stack and conventions
-- References correct file paths automatically
-- Follows project-specific patterns
+## 🔌 MCP (Model Context Protocol)
 
-### When to Run Init
-
-- ✅ After cloning a new repository
-- ✅ When starting a new project
-- ✅ After changing major dependencies
-- ✅ When migrating frameworks (e.g., Jest → Vitest)
-- ✅ After restructuring directories
-
-### Team Usage
-
-**Option 1: Share Configuration**
-```bash
-# Commit configuration to repository
-git add .ax-cli/
-git commit -m "Add AX CLI project configuration"
-```
-
-**Option 2: Personal Configuration**
-```bash
-# Add to .gitignore for personal customization
-echo ".ax-cli/" >> .gitignore
-```
-
----
-
-## 📖 Usage
-
-### Interactive Mode
-
-Start a conversational AI session:
+Extend AX CLI with MCP servers for additional capabilities:
 
 ```bash
-# Basic usage (uses glm-4.6 by default)
-ax-cli
-
-# Specify working directory
-ax-cli --directory /path/to/project
-
-# Use specific built-in model
-ax-cli --model grok-code-fast-1
-ax-cli --model glm-4-air
-
-# Connect to Z.AI
-ax-cli --base-url https://api.z.ai/v1 --model glm-4.6
-
-# Offline mode with Ollama
-ax-cli --model llama3.1 --base-url http://localhost:11434/v1
-```
-
-**Example Session:**
-```
-AX> Show me the package.json file
-
-[AX reads and displays package.json]
-
-AX> Create a new TypeScript file called utils.ts with helper functions
-
-[AX creates the file with intelligent content]
-
-AX> Run npm test and show me the results
-
-[AX executes the command and displays output]
-```
-
-### Headless Mode (Scriptable)
-
-Process a single prompt and exit — perfect for CI/CD, automation, and scripting:
-
-```bash
-# Basic headless execution
-ax-cli --prompt "show me the package.json file"
-
-# Short form
-ax-cli -p "list all TypeScript files in src/"
-
-# With working directory
-ax-cli -p "run npm test" -d /path/to/project
-
-# Control tool execution rounds
-ax-cli -p "comprehensive code refactoring" --max-tool-rounds 50
-
-# Combine with shell scripting
-RESULT=$(ax-cli -p "count lines of code in src/") && echo $RESULT
-```
-
-**Use Cases:**
-- **CI/CD Pipelines**: Automate code analysis, testing, linting
-- **Shell Scripts**: Integrate AI into bash automation
-- **Batch Processing**: Process multiple prompts programmatically
-- **Terminal Benchmarks**: Non-interactive execution for tools like Terminal Bench
-
-### Tool Execution Control
-
-Fine-tune AI behavior with configurable tool execution limits:
-
-```bash
-# Fast responses for simple queries (limit: 10 rounds)
-ax-cli --max-tool-rounds 10 -p "show current directory"
-
-# Complex automation (limit: 500 rounds)
-ax-cli --max-tool-rounds 500 -p "refactor entire codebase to TypeScript"
-
-# Works with all modes
-ax-cli --max-tool-rounds 20                    # Interactive
-ax-cli -p "task" --max-tool-rounds 30          # Headless
-ax-cli git commit-and-push --max-tool-rounds 30 # Git commands
-```
-
-**Default**: 400 rounds (sufficient for most tasks)
-
----
-
-## 🛠️ Configuration
-
-### Configuration Architecture
-
-AX CLI uses a **two-tier configuration system** for maximum flexibility:
-
-1. **User-Level Settings** (`~/.ax/user-settings.json`) - Global defaults
-2. **Project-Level Settings** (`.ax/settings.json`) - Project-specific overrides
-
-#### User-Level Settings
-
-**Location**: `~/.ax/user-settings.json`
-
-**Purpose**: Global settings that apply across all projects
-
-**Example (Offline with GLM 4.6)**:
-```json
-{
-  "baseURL": "http://localhost:11434/v1",
-  "defaultModel": "glm4:9b",
-  "models": [
-    "glm4:9b",
-    "glm4v:9b",
-    "llama3.1:8b",
-    "qwen2.5:7b",
-    "mistral:7b"
-  ]
-}
-```
-
-**Example (Cloud Provider - X.AI)**:
-```json
-{
-  "apiKey": "xai-your_api_key_here",
-  "baseURL": "https://api.x.ai/v1",
-  "defaultModel": "grok-code-fast-1",
-  "models": [
-    "grok-code-fast-1",
-    "grok-4-latest",
-    "grok-3-latest",
-    "grok-2-latest"
-  ]
-}
-```
-
-**Example (OpenRouter for Multi-Model Access)**:
-```json
-{
-  "apiKey": "sk-or-your_api_key_here",
-  "baseURL": "https://openrouter.ai/api/v1",
-  "defaultModel": "anthropic/claude-3.5-sonnet",
-  "models": [
-    "anthropic/claude-3.5-sonnet",
-    "openai/gpt-4o",
-    "meta-llama/llama-3.1-70b-instruct",
-    "google/gemini-pro-1.5"
-  ]
-}
-```
-
-#### Project-Level Settings
-
-**Location**: `.ax/settings.json` (in your project directory)
-
-**Purpose**: Project-specific model selection and MCP server configuration
-
-**Example**:
-```json
-{
-  "model": "grok-code-fast-1",
-  "mcpServers": {
-    "linear": {
-      "name": "linear",
-      "transport": "sse",
-      "url": "https://mcp.linear.app/sse"
-    },
-    "github": {
-      "name": "github",
-      "transport": "stdio",
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "your_github_token"
-      }
-    }
-  }
-}
-```
-
-#### Configuration Priority
-
-```
-Command Line Flags  >  Environment Variables  >  Project Settings  >  User Settings  >  System Defaults
-```
-
-**Example**:
-```bash
-# 1. Command line takes highest priority
-ax-cli --model grok-4-latest
-
-# 2. Then environment variables
-export GROK_MODEL="grok-code-fast-1"
-
-# 3. Then project settings (.ax/settings.json)
-{ "model": "glm4:9b" }
-
-# 4. Then user settings (~/.ax/user-settings.json)
-{ "defaultModel": "grok-3-latest" }
-
-# 5. Finally system default
-grok-code-fast-1
-```
-
----
-
-## 🎨 Custom Instructions
-
-Tailor AX CLI's behavior to your project's specific needs with custom instructions.
-
-### Setup
-
-Create `.ax/AX.md` in your project root:
-
-```bash
-mkdir -p .ax
-touch .ax/AX.md
-```
-
-### Example Custom Instructions
-
-**TypeScript Project**:
-```markdown
-# Custom Instructions for AX CLI
-
-## Code Style
-- Always use TypeScript for new code files
-- Prefer const assertions and explicit typing
-- Use functional components with React hooks
-- Follow the project's existing ESLint configuration
-
-## Documentation
-- Add JSDoc comments for all public functions
-- Include type annotations in JSDoc
-- Document complex algorithms with inline comments
-
-## Testing
-- Write tests using Vitest
-- Aim for 80%+ code coverage
-- Include edge cases and error scenarios
-
-## File Structure
-- Place components in src/components/
-- Place utilities in src/utils/
-- Place types in src/types/
-```
-
-**Python Data Science Project**:
-```markdown
-# Custom Instructions for AX CLI
-
-## Code Standards
-- Follow PEP 8 style guide
-- Use type hints for function signatures
-- Prefer pandas for data manipulation
-- Use numpy for numerical operations
-
-## Documentation
-- Add docstrings in Google format
-- Include usage examples in docstrings
-- Document data schemas and transformations
-
-## Best Practices
-- Always validate input data types
-- Handle missing values explicitly
-- Add error handling for file operations
-```
-
-### How It Works
-
-1. **Auto-Loading**: AX automatically loads `.ax/AX.md` when working in your project
-2. **Priority**: Custom instructions override default AI behavior
-3. **Scope**: Instructions apply only to the current project
-4. **Format**: Use markdown for clear, structured instructions
-
----
-
-## 🔌 MCP (Model Context Protocol) Integration
-
-Extend AX CLI with powerful integrations through the Model Context Protocol.
-
-### What is MCP?
-
-MCP enables AI models to interact with external tools and services. Think of it as "plugins for AI" — you can add capabilities like project management (Linear), version control (GitHub), databases, APIs, and more.
-
-### Adding MCP Servers
-
-#### Linear Integration (Project Management)
-
-```bash
-# Add Linear MCP server via SSE
-ax-cli mcp add linear --transport sse --url "https://mcp.linear.app/sse"
-
-# Now you can:
-# - Create and manage Linear issues
-# - Search and filter tasks
-# - Update issue status and assignees
-# - Access team and project information
-```
-
-#### GitHub Integration (Version Control)
-
-```bash
-# Add GitHub MCP server via stdio
-ax-cli mcp add github \
-  --transport stdio \
-  --command "npx" \
-  --args "@modelcontextprotocol/server-github" \
-  --env "GITHUB_TOKEN=your_github_token"
-
-# Now you can:
-# - Create pull requests
-# - Manage issues
-# - Review code
-# - Access repository information
-```
-
-#### Custom MCP Server
-
-```bash
-# Stdio transport (most common)
-ax-cli mcp add my-server \
-  --transport stdio \
-  --command "bun" \
-  --args "server.js"
-
-# HTTP transport
-ax-cli mcp add my-api \
-  --transport http \
-  --url "http://localhost:3000"
-
-# With environment variables
-ax-cli mcp add my-server \
-  --transport stdio \
-  --command "python" \
-  --args "-m" "my_mcp_server" \
-  --env "API_KEY=secret" \
-  --env "DEBUG=true"
-```
-
-#### Add from JSON
-
-```bash
-ax-cli mcp add-json my-server '{
-  "command": "bun",
-  "args": ["server.js"],
-  "env": {
-    "API_KEY": "your_key",
-    "LOG_LEVEL": "debug"
-  }
-}'
-```
-
-### Managing MCP Servers
+# Add MCP server
+ax-cli mcp add linear --transport sse --url https://mcp.linear.app/sse
 
-```bash
-# List all configured servers
+# List servers
 ax-cli mcp list
 
-# Test server connection and tools
-ax-cli mcp test server-name
-
-# Remove a server
-ax-cli mcp remove server-name
-
-# View server details
-ax-cli mcp info server-name
-```
-
-### Transport Types
-
-| Transport | Use Case | Example |
-|-----------|----------|---------|
-| **stdio** | Local processes, Node.js/Python servers | `npx @linear/mcp-server` |
-| **http** | RESTful APIs, remote services | `http://localhost:3000` |
-| **sse** | Server-Sent Events, real-time updates | `https://mcp.linear.app/sse` |
-
-### Configuration Storage
-
-MCP servers are stored in `.ax/settings.json`:
-
-```json
-{
-  "model": "grok-code-fast-1",
-  "mcpServers": {
-    "linear": {
-      "name": "linear",
-      "transport": "sse",
-      "url": "https://mcp.linear.app/sse"
-    },
-    "github": {
-      "name": "github",
-      "transport": "stdio",
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "ghp_your_token"
-      }
-    },
-    "custom-api": {
-      "name": "custom-api",
-      "transport": "http",
-      "url": "https://api.example.com/mcp"
-    }
-  }
-}
-```
-
----
-
-## 🎯 Strategic Architecture: AutomatosX vs Morph
-
-AX CLI is built on **two complementary technologies** that solve different problems at different architectural layers:
-
-### 🧠 AutomatosX: Orchestration Layer (Core Strategy)
-
-**AutomatosX is the strategic foundation** of AX CLI, providing enterprise-grade multi-agent orchestration:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    AutomatosX Orchestration                  │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
-│  │ Claude Code  │  │  Gemini CLI  │  │   OpenAI     │      │
-│  │  (Priority 3)│  │  (Priority 2)│  │  (Priority 1)│      │
-│  └──────────────┘  └──────────────┘  └──────────────┘      │
-│                                                               │
-│  • Multi-Agent Coordination    • Health Checks              │
-│  • Intelligent Routing         • Circuit Breakers           │
-│  • Session Management          • Provider Fallback          │
-│  • Memory Persistence          • Workload Distribution      │
-└─────────────────────────────────────────────────────────────┘
-                            ↓
-                    AX CLI Execution
-                            ↓
-           ┌────────────────┼────────────────┐
-           ↓                ↓                ↓
-    ┌──────────┐    ┌──────────┐    ┌──────────┐
-    │   Bash   │    │  Search  │    │   Edit   │
-    │   Tool   │    │   Tool   │    │   Tool   │
-    └──────────┘    └──────────┘    └──────────┘
-```
-
-**Key Capabilities**:
-- **Provider Coordination**: Routes tasks to Claude Code, Gemini CLI, OpenAI, or Grok based on availability and workload
-- **Intelligent Fallback**: Automatically switches to backup providers when primary fails
-- **Session/Memory**: Maintains context across multi-agent conversations
-- **Health & Reliability**: Circuit breakers, health checks, retry logic
-
-#### 🏛️ Architecture Purity: Why AX CLI Handles LLM Integration
-
-**Strategic Decision**: AutomatosX remains a **pure orchestration framework** while AX CLI handles all LLM-specific integration:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│             AutomatosX (Pure Orchestration)                  │
-│  • Provider-agnostic routing                                 │
-│  • Session/memory management                                 │
-│  • Health checks & circuit breakers                          │
-│  • NO LLM-specific code                                      │
-│  • NO model integration (0 lines)                            │
-│  • NO tree-sitter parsing                                    │
-└─────────────────────────────────────────────────────────────┘
-                           ↓ delegates to
-┌─────────────────────────────────────────────────────────────┐
-│           AX CLI (LLM Integration Layer)                     │
-│  • GLM-4.6, Grok, OpenAI, Anthropic, Google API clients      │
-│  • ~30,000 lines of LLM provider integration code            │
-│  • Tree-sitter parsing for code intelligence                │
-│  • Model-specific optimizations (reasoning mode, streaming)  │
-│  • Tool definitions (bash, editor, search)                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Why This Separation Matters**:
-
-1. **Maintainability** 🛠️
-   - AutomatosX stays clean: orchestration logic only (~3K LOC)
-   - AX CLI absorbs complexity: LLM APIs, model quirks, provider changes
-   - Bug fixes isolated to appropriate layer
-
-2. **Reusability** ♻️
-   - AutomatosX can orchestrate ANY tool/agent, not just LLM-based ones
-   - Same orchestration works for Python agents, Rust tools, shell scripts
-   - Other projects can use AutomatosX without inheriting LLM baggage
-
-3. **Testing & Reliability** ✅
-   - AutomatosX: Pure logic testing (fast, deterministic)
-   - AX CLI: Integration testing against real LLM APIs
-   - Clear boundaries make issues easy to diagnose
-
-4. **Evolution** 🚀
-   - LLM landscape changes rapidly (new models monthly)
-   - AutomatosX orchestration patterns remain stable
-   - AX CLI can add GPT-5, Claude 4, GLM-5 without touching AutomatosX core
-
-**What We Avoided**:
-- ❌ Mixing 30K lines of LLM code into orchestration framework
-- ❌ Coupling AutomatosX to specific model APIs
-- ❌ Making every AutomatosX user depend on OpenAI/Anthropic SDKs
-- ❌ Tree-sitter parser dependencies in core framework
-
-**The Result**: AutomatosX is a **pure, reusable orchestration platform**. AX CLI is a **specialized LLM CLI** built on top of it. Clean separation of concerns wins.
-
-### ⚡ Morph Fast Apply: Execution Layer (Optional Enhancement)
-
-**Morph is an optional performance enhancement** for file editing, not a core architectural component:
-
-```
-AutomatosX decides WHAT to edit
-            ↓
-┌───────────────────────────────┐
-│   How should we edit files?   │
-├───────────────┬───────────────┤
-│  Standard     │  Morph Fast   │
-│  Editor (✓)   │  Apply (opt)  │
-│               │               │
-│  • Free       │  • 4,500+     │
-│  • Built-in   │    tokens/sec │
-│  • Simple     │  • AI-powered │
-│    string     │  • Complex    │
-│    replace    │    refactors  │
-│               │  • Requires   │
-│               │    paid key   │
-└───────────────┴───────────────┘
-```
-
-**Why Keep Morph?**
-- ✅ Some users value speed for complex refactoring
-- ✅ Already optional - zero impact on non-users
-- ✅ Low maintenance burden (392 lines, stable)
-- ✅ Different problem space than AutomatosX
-
-**Why It's Not Core Strategy?**
-- ❌ Solves only ONE execution step (file editing)
-- ❌ No orchestration capabilities
-- ❌ Requires paid external API
-- ❌ Can be replaced by standard editor
-
-### 📊 Comparison Table
-
-| Capability | AutomatosX | AX CLI | Morph | Standard Editor |
-|------------|------------|--------|-------|-----------------|
-| **Strategic Value** | ⭐⭐⭐⭐⭐ Highest | ⭐⭐⭐⭐⭐ Highest | ⭐⭐ Low | ⭐⭐⭐ Medium |
-| **Architecture Layer** | Orchestration | Integration | Execution | Execution |
-| **Lines of Code** | ~3K (pure) | ~30K (LLM) | 392 | ~500 |
-| Multi-agent orchestration | ✅ | ❌ | ❌ | ❌ |
-| Provider routing/fallback | ✅ | ❌ | ❌ | ❌ |
-| Session management | ✅ | ❌ | ❌ | ❌ |
-| Health checks & reliability | ✅ | ❌ | ❌ | ❌ |
-| LLM API integration | ❌ | ✅ (all) | ❌ | ❌ |
-| Model-specific features | ❌ | ✅ | ❌ | ❌ |
-| Tree-sitter parsing | ❌ | ✅ | ❌ | ❌ |
-| File editing | ❌ | ❌ | ✅ (fast) | ✅ (basic) |
-| Complex code refactoring | ❌ | ❌ | ✅ | ❌ |
-| Reusable framework | ✅ | ❌ | ❌ | ✅ |
-| Cost | Free | Free | Paid | Free |
-| Required | ✅ Core | ✅ Core | ❌ Optional | ✅ Core |
-
-### 🎯 Bottom Line
-
-- **AutomatosX = Brain**: Pure orchestration framework - coordinates multiple agents, handles failures, manages state (reusable across any domain)
-- **AX CLI = Nervous System**: LLM integration layer - connects to GLM/Grok/Claude/GPT, handles model specifics, provides tools (~30K LOC)
-- **Morph = Fast Hands** (optional): Executes file edits quickly when you need performance
-- **Standard Editor = Reliable Hands**: Executes file edits reliably for everyone
-
-**Architectural Philosophy**:
-- **AutomatosX stays pure** (no LLM code) → reusable orchestration framework
-- **AX CLI absorbs complexity** (30K lines of LLM integration) → keeps AutomatosX clean
-- **We keep Morph** because some users find the speed valuable for refactoring
-
-This clean separation means AutomatosX can orchestrate Python agents, Rust tools, or any future AI models without being coupled to today's LLM APIs.
-
----
-
-## ⚡ Morph Fast Apply (Optional)
-
-Ultra-fast code editing at **4,500+ tokens/second with 98% accuracy**.
-
-### Setup
-
-1. Get API key from [Morph Dashboard](https://morphllm.com/dashboard/api-keys)
-2. Configure your key:
-
-```bash
-# Environment variable
-export MORPH_API_KEY="your_morph_key_here"
-
-# Or in .env
-echo "MORPH_API_KEY=your_morph_key_here" >> .env
-```
-
-### How It Works
-
-When Morph is configured, AX CLI gains the `edit_file` tool for high-speed editing:
-
-- **`edit_file`** (Morph): Complex edits, refactoring, multi-line changes, file transformations
-- **`str_replace_editor`** (Standard): Simple replacements, single-line edits
-
-The AI automatically chooses the optimal tool based on the task complexity.
-
-### Example Usage
-
-```bash
-# Complex refactoring (uses Morph Fast Apply)
-ax-cli -p "refactor this class to use async/await and add proper error handling"
-
-# Type annotation conversion (uses Morph Fast Apply)
-ax-cli -p "convert all JavaScript files in src/ to TypeScript with type annotations"
-
-# Simple text replacement (uses standard editor)
-ax-cli -p "change variable name from foo to bar in utils.ts"
-```
-
-### Performance
-
-| Task | Standard Editor | Morph Fast Apply | Speedup |
-|------|----------------|------------------|---------|
-| Refactor 1000 lines | ~45s | ~8s | **5.6x faster** |
-| Add type annotations | ~30s | ~5s | **6x faster** |
-| Multi-file changes | ~60s | ~10s | **6x faster** |
-
----
-
-## 📚 Command Reference
-
-### Main Commands
-
-```bash
-ax-cli [options]
-
-Options:
-  -V, --version                  Output version number
-  -d, --directory <dir>          Set working directory
-  -k, --api-key <key>            API key (or GROK_API_KEY env var)
-  -u, --base-url <url>           API base URL (or GROK_BASE_URL env var)
-  -m, --model <model>            AI model to use (or GROK_MODEL env var)
-  -p, --prompt <prompt>          Single prompt (headless mode)
-  --max-tool-rounds <rounds>     Max tool execution rounds (default: 400)
-  -h, --help                     Display help
+# Remove server
+ax-cli mcp remove linear
 ```
 
-### MCP Commands
+[MCP Integration Guide →](docs/mcp.md)
 
-```bash
-ax-cli mcp <command> [options]
+## 🏗️ Architecture
 
-Commands:
-  add <name>           Add MCP server
-  add-json <name>      Add from JSON config
-  list                 List all servers
-  test <name>          Test server connection
-  remove <name>        Remove server
-  info <name>          View server details
+AX CLI implements enterprise-grade architecture with:
 
-Add Options:
-  --transport <type>   Transport type (stdio|http|sse)
-  --command <cmd>      Command to run (stdio only)
-  --args <args...>     Command arguments (stdio only)
-  --url <url>          Server URL (http|sse only)
-  --env <key=val...>   Environment variables
-```
+- **Single Source of Truth (SSOT)** type system via `@ax-cli/schemas`
+- **TypeScript strict mode** with Zod runtime validation
+- **98%+ test coverage** (306 tests)
+- **Modular design** with clean separation of concerns
 
-### Examples
+[Architecture Documentation →](docs/architecture.md)
 
-```bash
-# Interactive mode
-ax-cli
-ax-cli -d /path/to/project
-ax-cli -m grok-code-fast-1
+## 📚 Documentation
 
-# Headless mode
-ax-cli -p "list TypeScript files"
-ax-cli -p "run tests" -d /project
-ax-cli -p "refactor" --max-tool-rounds 50
+- [Features](docs/features.md) - Complete feature list and capabilities
+- [Installation](docs/installation.md) - Detailed installation guide
+- [Configuration](docs/configuration.md) - Configuration options and settings
+- [Usage](docs/usage.md) - Comprehensive usage guide
+- [CLI Reference](docs/cli-reference.md) - Command-line interface reference
+- [MCP Integration](docs/mcp.md) - Model Context Protocol guide
+- [Architecture](docs/architecture.md) - Technical architecture details
+- [Development](docs/development.md) - Development and contribution guide
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
 
-# MCP operations
-ax-cli mcp add linear --transport sse --url https://mcp.linear.app/sse
-ax-cli mcp list
-ax-cli mcp test linear
-ax-cli mcp remove linear
+## 🤝 Contributing
 
-# Model selection
-ax-cli -m glm4:9b -u http://localhost:11434/v1
-ax-cli -m grok-4-latest -k $GROK_API_KEY
-ax-cli -m anthropic/claude-3.5-sonnet -u https://openrouter.ai/api/v1
-```
+We welcome contributions! Please see our [Development Guide](docs/development.md) for details on:
 
----
+- Setting up your development environment
+- Running tests
+- Code style guidelines
+- Submitting pull requests
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details
-
----
+MIT License - see [LICENSE](LICENSE) for details
 
 ## 🙏 Acknowledgments
 
-- **Original Project**: [grok-cli](https://github.com/superagent-ai/grok-cli) by SuperAgent AI
-- **Enterprise Upgrade**: Powered by [AutomatosX](https://github.com/defai-digital/automatosx) multi-agent orchestration
-- **AI Providers**: X.AI, OpenAI, Anthropic, and the open-source LLM community
-- **Contributors**: All developers who have contributed to making AX CLI production-ready
-
----
-
-## 🔗 Links
-
-- **NPM Package**: https://www.npmjs.com/package/@defai.digital/ax-cli
-- **GitHub Repository**: https://github.com/defai-digital/ax-cli
-- **Issue Tracker**: https://github.com/defai-digital/ax-cli/issues
-- **AutomatosX**: https://github.com/defai-digital/automatosx
-- **MCP Protocol**: https://modelcontextprotocol.io
+Originally forked from [grok-cli](https://github.com/superagent-ai/grok-cli), AX CLI has been extensively upgraded using **AutomatosX** multi-agent orchestration to achieve enterprise-class standards.
 
 ---
 
 <p align="center">
-  <strong>Built with ❤️ using AutomatosX multi-agent collaboration</strong><br>
-  <em>Enterprise-class AI CLI for developers who demand quality</em>
+  Made with ❤️ by <a href="https://github.com/defai-digital">DefAI Digital</a>
 </p>