@defai.digital/ax-cli 3.8.21 → 3.8.23

package/README.md

@@ -1,842 +1,159 @@
-# AX CLI - Enterprise-Class CLI for GenAI coding
+# AX CLI - Enterprise-Class CLI for GenAI Coding
 
 [![npm](https://img.shields.io/npm/dt/@defai.digital/ax-cli?style=flat-square&logo=npm&label=downloads)](https://npm-stat.com/charts.html?package=%40defai.digital%2Fax-cli)
-[![Tests](https://img.shields.io/badge/tests-1517%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
+[![Tests](https://img.shields.io/badge/tests-2083%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
 [![Coverage](https://img.shields.io/badge/coverage-98%2B%25-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-blue?style=flat-square)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-blue?style=flat-square&logo=node.js)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![macOS](https://img.shields.io/badge/macOS-26-blue?style=flat-square&logo=apple)](https://www.apple.com/macos/)
-[![Windows](https://img.shields.io/badge/Windows-11-blue?style=flat-square&logo=windows)](https://www.microsoft.com/windows/)
-[![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-blue?style=flat-square&logo=ubuntu)](https://ubuntu.com/)
 
-![AX CLI Screenshot](.github/assets/screenshot1.png)
+<p align="center">
+  <img src=".github/assets/screenshot1.png" alt="AX CLI Screenshot" width="800"/>
+</p>
 
 <p align="center">
   <strong>GLM-Optimized CLI • Enterprise Architecture • 98%+ Test Coverage • TypeScript & Zod</strong>
 </p>
 
-## 📋 Table of Contents
-
-- [🚀 Quick Start](#-quick-start)
-- [✨ Features](#-features)
-- [🎉 What's New](#-whats-new-in-v3821)
-- [📦 Installation](#-installation)
-- [⚙️ Configuration](#️-configuration)
-- [🔒 Security](#-security--api-key-handling)
-- [🎯 Usage Examples](#-usage-examples)
-- [🔌 MCP Integration](#-mcp-model-context-protocol)
-- [🧠 Project Memory](#-project-memory)
-- [🎯 Multi-Phase Planner](#-multi-phase-task-planner-v300)
-- [🏗️ Architecture](#️-architecture)
-- [📚 Documentation](#-documentation)
-- [📋 Changelog](#-changelog)
-
 ---
 
-## 🚀 Quick Start
-
-Get up and running in under 2 minutes:
+## Quick Start
 
 ```bash
-# 1️⃣ Install globally
+# Install globally
 npm install -g @defai.digital/ax-cli
 
-# 2️⃣ Configure (secure API key setup)
+# Configure (secure API key setup)
 ax-cli setup
 
-# 3️⃣ Initialize your project
+# Initialize your project
 ax-cli init
 
-# 4️⃣ Start coding!
+# Start coding!
 ax-cli
 ```
 
-**That's it!** 🎉 AX CLI is now ready to help you build, debug, and ship code faster.
-
-**Need help?** Run `ax-cli --help` or check the [Usage Guide](#-usage-examples).
-
-## ✨ Features
-
-- **🤖 GLM-Focused AI CLI**: Optimized for Z.AI's GLM-4.6 (default, configurable)
-  - **Note**: For xAI Grok models, use [grok-cli](https://github.com/superagent-ai/grok-cli)
-  - **Note**: For Anthropic Claude models, use [claude-code](https://claude.ai/code)
-- **🧠 GLM 4.6 Optimized**: Primary support for General Language Model with advanced reasoning
-  - **32K max tokens** (industry-standard, matches Claude Code CLI)
-  - 200K context window, 128K max output capability
-  - 30% more token efficient than GLM 4.5
-  - Optimized for complex code generation and refactoring
-- **🎯 Multi-Phase Task Planner**: Intelligent task decomposition for complex requests
-  - Automatic complexity detection (57 keyword patterns)
-  - LLM-based plan generation with phases and dependencies
-  - Phase-by-phase execution with progress tracking
-  - File modification tracking and context pruning between phases
-  - Plan management commands: `/plans`, `/plan`, `/phases`, `/pause`, `/resume`, `/skip`, `/abandon`
-- **🔄 Session Continuity**: Directory-specific conversation history with `--continue` flag
-  - Preserve context across sessions for multi-day development
-  - Each project maintains its own independent history
-  - Seamlessly resume conversations where you left off
-- **🔌 Enhanced MCP Integration**: Model Context Protocol with production-ready templates
-  - **One-command setup**: `ax-cli mcp add figma --template`
-  - **12+ pre-configured templates**: Figma, GitHub, Vercel, Puppeteer, Storybook, Sentry, and more
-  - **Tool discovery**: `ax-cli mcp tools <server>` to preview capabilities
-  - **Template browser**: `ax-cli mcp browse` for quick navigation
-  - **Front-end focused**: Design-to-code workflows with Figma integration
-  - **[Complete Guide](docs/mcp-frontend-guide.md)**: Front-end developer workflows
-- **✅ 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
-- **🧠 Project Memory**: Intelligent context caching for z.ai GLM-4.6
-  - Automatic project scanning and context generation
-  - z.ai implicit caching support (50% token savings on repeated context)
-  - Cache statistics tracking and efficiency monitoring
-- **🏥 Health Check**: Comprehensive diagnostics with `ax-cli doctor`
-  - Verify configuration, API connectivity, and dependencies
-  - Detailed error messages with actionable suggestions
-- **🎨 Smart Verbosity Control**: Multi-level output for optimal UX
-  - **Quiet mode** (default): Groups tool operations → 85% less noise
-  - **Concise mode**: One line per tool execution
-  - **Verbose mode**: Full details for debugging
-  - Press `Ctrl+O` to cycle between levels
-  - Auto-expands errors with full details
-- **🔄 Auto-Update**: Built-in update checker and installer
-- **🔒 Enterprise-Grade Security**: **FREE & Open Source**
-  - **Command Injection Protection**: CVSS 9.8 CRITICAL fix - Safe command execution with whitelisting
-  - **Path Traversal Hardening**: CVSS 8.6 HIGH fix - Prevent unauthorized file system access
-  - **SSRF Attack Prevention**: CVSS 7.5 HIGH fix - Validate MCP transport URLs and block private IPs
-  - **Input Sanitization**: CVSS 7.0 HIGH fix - Comprehensive input validation and sanitization
-  - **Error Sanitization**: CVSS 6.5 MEDIUM fix - Prevent sensitive data leakage in error messages
-  - **API Key Encryption**: AES-256-GCM encryption at rest with automatic migration
-  - **Memory Leak Fixes**: Process pool management for long-running operations
-  - **Security Audit Logging**: Basic JSON logging with 30-day retention
-  - **Rate Limiting**: Token bucket algorithm to prevent API abuse (100 req/min)
-  - **1517+ tests passing** with **98.29% coverage** - Production-ready security
-  - **User-friendly defaults**: Full functionality with enterprise-grade security for everyone
-- **🏢 Enterprise Features**: Advanced capabilities for teams and compliance
-  - **Compliance Report Generation**: SOC2, HIPAA, PCI-DSS automated reporting
-  - **Advanced Audit Logging**: Tamper-proof encrypted logs with hash chains and extended retention (1+ years)
-  - **Real-time Security Dashboards**: Monitor security events, anomalies, and compliance status
-  - **Advanced Rate Limiting**: Custom quotas per user/team/project with cost analytics and budget alerts
-  - **Team Collaboration**: Shared chat history with full-text search and multi-format export
-  - **Policy Enforcement**: Tool execution policies, approval workflows, and usage analytics
-  - **SSO/SAML Integration**: Enterprise identity provider support
-  - **Priority Support**: 24-hour SLA email support
-  - 📧 **Contact sales@defai.digital** for enterprise licensing and pricing
-- **📊 Advanced Code Analysis**: Professional-grade static analysis tools
-  - **Dependency Analyzer**: Detect circular dependencies, calculate coupling metrics, identify orphan and hub files
-  - **Code Smell Detector**: Find 10+ anti-patterns (long methods, large classes, duplicates, dead code, etc.)
-  - **Hotspot Analyzer**: Identify frequently changing, complex code using git history analysis
-  - **Metrics Calculator**: Cyclomatic complexity, Halstead metrics, Maintainability Index (MI)
-  - **Security Scanner**: Detect SQL injection, XSS, path traversal, hardcoded secrets, and more
-  - **[Complete Guide](docs/analysis-tools.md)** and **[API Documentation](docs/api/analyzers.md)**
-
-### Max Tokens Configuration
-
-AX CLI uses **industry-standard max tokens** based on research of leading AI coding tools:
-
-| Tool | Max Tokens | Notes |
-|------|-----------|-------|
-| **Claude Code CLI** | 16k - 32k | Industry standard |
-| **GitHub Copilot** | 64k | GPT-4o default |
-| **Cursor AI** | 200k | With intelligent pruning |
-| **AX CLI (GLM 4.6)** | **32k** ✅ | Matches Claude Code upper default |
-| **AX CLI (Others)** | 8k | Appropriate for each model |
-
-**Why 32k for GLM 4.6?**
-- Competitive with industry leaders (Claude Code, GitHub Copilot)
-- GLM 4.6 supports up to 128k max output (our 32k is conservative at 25%)
-- Better for complex code generation, large file modifications, and multi-file context
-- Based on official Z.AI documentation and industry benchmarking
-
-[View all features →](docs/features.md)
-
-## 🎉 What's New in v3.8.21
-
-**Bug Fixes & Configurable Timeouts** - Adds configurable confirmation timeout.
-
-### 🐛 Bug Fixes
-
-- **Configurable confirmation timeout** - File operation confirmation timeout is now configurable via `TIMEOUT_CONFIG.CONFIRMATION_TIMEOUT` (default: 60 seconds)
-- **Dynamic timeout message** - Confirmation timeout message now displays the actual timeout value instead of hardcoded "60 seconds"
-
-### 📝 Configuration
-
-Added new timeout constant in `config-defaults/settings.yaml`:
-
-```yaml
-timeouts:
-  # ... existing timeouts ...
-  confirmation_timeout: 60000  # 60 seconds for file operation confirmation
-```
-
-### ✅ Quality
-
-- All 2083 tests passing
-- 0 lint errors (570 warnings)
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.20
-
-**Centralized Paths & Unified Timeouts** - Uses centralized constants for paths and timeouts.
-
-### 🔧 Improvements
-
-- **Centralized path constants** - Updated files to use `CONFIG_PATHS`:
-  - `memory.ts`: Uses `CONFIG_PATHS.CUSTOM_MD` and `CONFIG_PATHS.INDEX_JSON` (replaces 5 duplicated path constructions)
-  - `mcp-migrate.ts`: Uses `CONFIG_PATHS.PROJECT_SETTINGS`
-  - `path-helpers.ts`: Uses `CONFIG_PATHS.PROJECT_DIR`
-- **Unified timeout usage** - Updated files to use `TIMEOUT_CONFIG` and `MCP_CONFIG`:
-  - `permission-manager.ts`: Uses `TIMEOUT_CONFIG.TOOL_APPROVAL`
-  - `mcp.ts`: Uses `MCP_CONFIG.HEALTH_CHECK_INTERVAL` for health monitoring
-
-### 📝 Benefits
-
-- **Less Duplication**: Path constructions like `path.join(process.cwd(), CONFIG_DIR_NAME, FILE_NAMES.CUSTOM_MD)` replaced with `CONFIG_PATHS.CUSTOM_MD`
-- **Single Source of Truth**: All timeout and path values centralized in constants
-- **Better Maintainability**: Changes to paths only need to be made in one place
-
-### ✅ Quality
-
-- All 2083 tests passing
-- 0 lint errors (570 warnings)
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.19
-
-**Deduplicated Code, Performance & Stability** - Reduces code duplication and improves stability.
-
-### 🔧 Improvements
-
-- **Exported reusable utilities** - Added `sleep()` and `calculateExponentialBackoff()` from retry-helper:
-  - `sleep(ms)`: Promise-based delay utility
-  - `calculateExponentialBackoff(attempt, initialDelay, maxDelay, addJitter)`: Calculates backoff with overflow protection
-- **Reduced duplicated code** - Updated files to use centralized utilities:
-  - `task-planner.ts`: Uses `sleep()` and `calculateExponentialBackoff()` instead of inline implementations
-  - `process-pool.ts`: Uses `sleep()` instead of `new Promise(resolve => setTimeout(...))`
-  - `llm-agent.ts`: Uses `TIMEOUT_CONFIG.TOOL_APPROVAL` instead of hardcoded `5 * 60 * 1000`
-- **Extended timeout configuration** - Added new timeout constants:
-  - `tool_approval`: 5 minutes for tool approval timeout
-  - `context_cleanup_interval`: 5 minutes for context manager cleanup
-- **Updated cleanup intervals** - Centralized cleanup timing:
-  - `context-manager.ts`: Uses `TIMEOUT_CONFIG.CONTEXT_CLEANUP_INTERVAL`
-  - `rate-limiter.ts`: Uses `TIMEOUT_CONFIG.CONTEXT_CLEANUP_INTERVAL`
-
-### 📝 Configuration
-
-Extended `timeouts` section in `config-defaults/settings.yaml`:
-```yaml
-timeouts:
-  # ... existing timeouts ...
-  tool_approval: 300000
-  context_cleanup_interval: 300000
-```
-
-### ✅ Quality
-
-- All 2083 tests passing
-- 0 lint errors (570 warnings)
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.18
-
-**Extended Timeout Configuration** - Adds network/API and UI timeout constants.
-
-### 🔧 Improvements
-
-- **Extended timeout configuration** - Added new timeout constants:
-  - `settings_cache_ttl`: 5 seconds for settings manager cache
-  - `api_health_check`: 5 seconds for API health checks
-  - `command_check`: 3 seconds for command availability checks
-  - `mcp_init`: 5 seconds for MCP initialization
-  - `shutdown`: 10 seconds for graceful shutdown
-  - `notification_display`: 3 seconds for notification display
-- **Updated files to use centralized constants**:
-  - `bash-output.ts`: Uses `TIMEOUT_CONFIG.BASH_DEFAULT`
-  - `task-planner.ts`: Uses `TIMEOUT_CONFIG.MS_PER_SECOND` and `MCP_CONFIG.RECONNECT_MAX_DELAY`
-  - `use-input-handler.ts`: Uses `TIMEOUT_CONFIG.BASH_DEFAULT`
-  - `settings-manager.ts`: Uses `TIMEOUT_CONFIG.SETTINGS_CACHE_TTL`
-  - `llm/tools.ts`: Uses `TIMEOUT_CONFIG.MCP_INIT`
-
-### 📝 Configuration
-
-Extended `timeouts` section in `config-defaults/settings.yaml`:
-```yaml
-timeouts:
-  # ... existing timeouts ...
-  settings_cache_ttl: 5000
-  api_health_check: 5000
-  command_check: 3000
-  mcp_init: 5000
-  shutdown: 10000
-  notification_display: 3000
-```
-
-### ✅ Quality
-
-- All 2083 tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.17
-
-**Code Quality & Configuration Centralization** - Removes hardcoded values and unifies configuration.
-
-### 🔧 Improvements
-
-- **Centralized timeout configuration** - All timeout values now configurable via `config-defaults/settings.yaml`
-  - `TIMEOUT_CONFIG` exported from `constants.ts` for consistent access
-  - Bash, search, hook, streaming, and process pool timeouts centralized
-- **Unified MCP configuration** - Health check interval and reconnect delay now in `MCP_CONFIG`
-- **Extended `SettingsYaml` interface** - Added `timeouts` section for configurable timeout values
-- **Removed hardcoded values** - Replaced magic numbers with named constants
-
-### 📝 Configuration
-
-New `timeouts` section in `config-defaults/settings.yaml`:
-```yaml
-timeouts:
-  bash_default: 30000
-  search_default: 30000
-  hook_default: 30000
-  streaming_first_chunk: 90000
-  streaming_idle: 120000
-  process_execution: 30000
-  process_idle: 60000
-```
-
-### ✅ Quality
-
-- All 2083 tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.16
-
-**MCP Timeout Configuration** - Fixes [#13](https://github.com/defai-digital/ax-cli/issues/13): AutomatosX agent timeout errors.
-
-### ✨ New Features
-
-- **Per-server MCP timeout configuration** - Configure custom timeouts for long-running MCP tools
-  - Add `timeout` field to MCP server config (in milliseconds)
-  - Supports AutomatosX agents with 45+ minute execution times
-  - Default: 60 seconds (MCP SDK default)
-
-### 📝 Configuration Example
-
-```json
-{
-  "mcpServers": {
-    "automatosx": {
-      "name": "automatosx",
-      "transport": { "type": "stdio", "command": "ax", "args": ["mcp"] },
-      "timeout": 2700000
-    }
-  }
-}
-```
-
-### 🐛 Bug Fixes
-
-- **Fixed MCP error -32001 "Request timed out"** - Long-running tools no longer fail prematurely
-- **Per-tool timeout propagation** - Timeout now correctly passed to MCP SDK `callTool()`
-
-### ✅ Quality
-
-- All tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.15
-
-**Stability & Robustness Release** - Fixes streaming timeouts, search tool errors, and bash command validation:
-
-### 🔧 Improvements
-
-- **Increased streaming timeouts** - First chunk timeout increased from 30s to 90s, idle timeout from 60s to 120s to handle complex operations with large context
-- **Better file type handling in search** - Fixed ripgrep `tsx` file type error by using glob patterns for non-builtin types (tsx, jsx, vue, svelte, etc.)
-- **Improved cd command validation** - Compound commands like `cd /path && grep` now show helpful error messages instead of failing silently
-
-### 🐛 Bug Fixes
-
-- **Fixed "Streaming first chunk timeout" errors** - Complex operations no longer timeout prematurely
-- **Fixed "unrecognized file type: tsx" in search** - Search tool now handles modern file extensions correctly
-- **Fixed cd command with compound operators** - Clear error message explaining how to run commands in different directories
-
-### ✅ Quality
-
-- All tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.14
-
-**MCP Stability & Validation Release** - Prevents MCP server timeouts from misconfigured servers:
-
-### 🔧 Improvements
-
-- **Proactive REPL command detection** - MCP config loader now detects commands that would start a REPL and hang forever (`node`, `python`, `python3`, `deno`, `bun`, `ruby`, `irb` without arguments)
-- **Automatic server skipping** - Problematic MCP servers are automatically skipped with a clear warning instead of causing 60-second timeouts
-- **Better error messages** - Clear guidance on how to fix misconfigured MCP servers
-
-### 🐛 Bug Fixes
-
-- **Fixed MCP server timeout on REPL commands** - Servers configured with `node` (no args) no longer hang indefinitely
-- **Improved config validation** - Both legacy and modern MCP config formats now validated for REPL commands
-
-### ✅ Quality
-
-- All tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.13
-
-**Code Quality & Refactoring Release** - Centralized configuration and unified patterns:
-
-### 🔧 Improvements
-
-- **Centralized hardcoded values** - Replaced hardcoded `400` max tool rounds in `src/index.ts` with `AGENT_CONFIG.MAX_TOOL_ROUNDS`
-- **New STREAMING_CONFIG constant** - Created centralized streaming configuration in `src/llm/client.ts` for timeout values
-- **Unified cache eviction strategy** - Standardized 80% target capacity eviction across `subagent.ts`, `llm-agent.ts`, and `progress-tracker.ts`
-- **New BASH_OUTPUT_CACHE_MAX_SIZE constant** - Added to `CACHE_CONFIG` for bash output hash cache
-- **Improved Map iteration safety** - Cache eviction now creates key array before deletion to avoid iterator invalidation
-
-### 🐛 Bug Fixes
-
-- **Cleaned up orphaned test files** - Removed temporary `test-file-*.ts` files causing ESLint parsing errors
-
-### ✅ Quality
-
-- All 2083 tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.12
-
-**Security & Code Quality Release** - ReDoS vulnerability fixes and code cleanup:
-
-### 🔒 Security Fixes
-
-- **Fixed ReDoS vulnerability in permission manager** - Glob pattern matching now uses `[^/]*` instead of `.*` to prevent catastrophic backtracking attacks
-- **Fixed ReDoS vulnerability in incremental analyzer** - Same fix applied to prevent exponential time complexity on malicious patterns
-
-### 🐛 Bug Fixes
-
-- **Fixed 5 unused error variables in catch blocks** - Removed `_error` variables that ESLint warned about in:
-  - `churn-calculator.ts`
-  - `hotspot-detector.ts` (2 instances)
-  - `metrics-analyzer.ts`
-  - `security-analyzer.ts`
-- **Fixed 2 parseInt calls missing radix parameter** - Added explicit radix `10` to `parseInt()` calls in `status.ts` to ensure correct decimal parsing
-
-### ✅ Quality
-
-- All 2083 tests passing
-- TypeScript strict mode passes
-- Zero breaking changes
-- Improved security posture against ReDoS attacks
-
----
-
-## 🎉 What's New in v3.8.11
-
-**Critical npm Install Fix** - Fixes the `ERR_MODULE_NOT_FOUND` error when running ax-cli after npm install:
-
-### 🐛 Bug Fixes
-
-- **Fixed @ax-cli/schemas module not found** - Resolved the error where Node.js couldn't find the bundled `@ax-cli/schemas` package
-  - Added `prepublishOnly` script that properly copies workspace package to `node_modules/` before publishing
-  - Added `postpublish` script to restore workspace symlink for local development
-  - `bundleDependencies` now correctly includes the package files in the npm tarball
-
-### 🔧 Technical Details
-
-The issue was that npm's `bundleDependencies` doesn't follow workspace symlinks. The fix:
-1. Before publish: Replace symlink with real directory copy
-2. npm pack/publish: Bundles the actual files into tarball
-3. After publish: Restore symlink for local development
-
-### ✅ Quality
-
-- Verified: Package extracts and runs correctly after npm install
-- All tests passing
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.10
-
-**npm Publish Fix & Code Quality** - Critical fix for npm installation and continued refactoring:
-
-### 🐛 Bug Fixes
-
-- **Fixed npm install failure** - Resolved `EUNSUPPORTEDPROTOCOL` error when installing from npm
-  - Changed `workspace:*` (pnpm-specific) to `*` (npm-compatible) for `@ax-cli/schemas` dependency
-  - Added `bundleDependencies` to properly bundle the workspace package in npm tarball
-  - Users can now install with `npm install -g @defai.digital/ax-cli` without errors
-
-### 🔧 Improvements
-
-- **Centralized tool constants** - Added `TOOL_DEFAULTS` constant object in `src/llm/tools.ts`
-- **Unified naming conventions** - Renamed `GROK_TOOLS` to `LLM_TOOLS` with backwards-compatible aliases
-- **Enhanced text editor** - Added `EDITOR_CONFIG` and `ERROR_MESSAGES` constants for maintainability
-- **Atomic file writes** - Extracted `atomicWriteFile()` helper to eliminate code duplication
-
-### ✅ Quality
-
-- All 2083 tests passing
-- TypeScript strict mode passes
-- Build succeeds
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.9
-
-**Refactoring & Configuration Improvements** - Further centralization and code quality enhancements:
-
-### 🔧 Improvements
-
-- **Centralized file name constants** - Added `FILE_NAMES` constant object to eliminate hard-coded file names across the codebase
-- **Extended CONFIG_PATHS** - Added new path constants for CUSTOM_MD, INDEX_JSON, MEMORY_JSON, and user directories
-- **Unified path handling** - Replaced 15+ hard-coded `.ax-cli` path references with centralized constants
-- **Improved text editor tool** - Enhanced functionality and reliability
-- **Subagent types refinement** - Streamlined specialized agent type definitions
-- **Prompt improvements** - Enhanced default prompts configuration
-
-### ✅ Quality
-
-- TypeScript strict mode passes
-- Build succeeds
-- 76/77 test files pass
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.8
-
-**Code Quality & Maintainability Release** - Major refactoring for improved code consistency:
-
-### 🔧 Improvements
-
-- **Centralized configuration constants** - Added `CONFIG_DIR_NAME` constant to eliminate hard-coded `.ax-cli` strings across 15+ files
-- **Unified error handling** - Replaced inline `error instanceof Error ? error.message : String(error)` patterns with `extractErrorMessage()` utility across 20+ files
-- **Improved ES module consistency** - Converted inline `require()` calls to proper ES module imports
-- **Better home directory handling** - Replaced `process.env.HOME || process.env.USERPROFILE` patterns with Node.js `homedir()` function
-- **Removed examples folder** - Cleaned up unused example files
-
-### ✅ Quality
-
-- All tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
-- Improved code maintainability
-
----
-
-## 🎉 What's New in v3.8.7
-
-**Critical Bug Fixes & Resilience Improvements** - Stability and reliability enhancements.
-
----
-
-## 🎉 What's New in v3.8.6
-
-**Patch Release** - Bug fixes and stability improvements:
-
-### 🐛 Bug Fixes
-
-- **Performance optimizations** - Improved response times for tool operations
-- **Stability improvements** - Enhanced error handling in edge cases
-
-### ✅ Quality
-
-- All 2029 tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.5
-
-**Maintenance Release** - Dependency updates and minor improvements:
-
-### 🔧 Improvements
-
-- **Updated dependencies** - Latest package versions for improved security and performance
-- **Documentation refinements** - Minor improvements to clarity and accuracy
-
-### ✅ Quality
-
-- All 2029 tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
-
----
-
-## 🎉 What's New in v3.8.4
-
-**Security & Stability Fixes** - Improved error handling and audit logging robustness:
-
-### 🐛 Bug Fixes
-
-- **Fixed audit logger crash on permission errors** - Gracefully handle EPERM/EACCES/EROFS errors instead of crashing
-- **Fixed search validation errors being lost** - Validation errors now returned even when audit logging fails
-- **Fixed auto-accept logger always enabled** - Now defaults to disabled to prevent unexpected disk writes
-- **Fixed encryption error logging** - No longer leaks crypto implementation details (requires DEBUG env var)
-- **Improved quiet mode error display** - Shows actual error messages instead of generic "encountered errors"
-
-### 🔒 Security
-
-- Audit logging failures no longer mask security validation errors (ReDoS protection preserved)
-- Encryption errors only logged when DEBUG or AX_DEBUG environment variable is set
-- Auto-accept audit logging requires explicit configuration to enable
-
-### ✅ Quality
-
-- All 2029 tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
+**That's it!** AX CLI is now ready to help you build, debug, and ship code faster.
 
 ---
 
-## 🎉 What's New in v3.8.3
-
-**MCP Protocol Fix** - Critical fix for MCP server connectivity:
-
-### 🐛 Bug Fixes
-
-- **Fixed MCP server timeout issue** - Resolved 60-second timeout when connecting to AutomatosX MCP server
-- **Added Content-Length framing transport** - New `ContentLengthStdioTransport` class for LSP-style protocol compatibility
-- **Protocol mismatch fix** - MCP SDK uses NDJSON but AutomatosX uses Content-Length framing; now supports both
-- **Updated MCP SDK to v1.22.0** - Latest SDK with improved capabilities
-- **Fixed SDK v1.22 compatibility** - Updated client capabilities structure for new SDK version
+## Table of Contents
 
-### ✨ Improvements
-
-- **Faster MCP connections** - Connection time reduced from 60s timeout to ~200ms
-- **Better transport abstraction** - Configurable framing protocol (NDJSON or Content-Length)
-- **19 AutomatosX tools** - Full tool suite now available: `run_agent`, `list_agents`, `search_memory`, and more
-
-### ✅ Quality
-
-- All tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
-- Improved MCP server stability
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [MCP Integration](#mcp-integration)
+- [Project Memory](#project-memory)
+- [Multi-Phase Planner](#multi-phase-task-planner)
+- [Security](#security)
+- [Architecture](#architecture)
+- [Changelog](#changelog)
+- [Documentation](#documentation)
 
 ---
 
-## 🎉 What's New in v3.8.2
+## Features
 
-**Deep Bug Fixes** - Comprehensive stability improvements for enhanced input handling:
+### Core Capabilities
 
-### 🐛 Bug Fixes
+| Feature | Description |
+|---------|-------------|
+| **GLM-Optimized** | Primary support for Z.AI's GLM-4.6 with 200K context window |
+| **Multi-Phase Planner** | Intelligent task decomposition for complex requests |
+| **Session Continuity** | Directory-specific conversation history with `--continue` |
+| **MCP Integration** | Model Context Protocol with 12+ production-ready templates |
+| **Project Memory** | Intelligent context caching with 50% token savings |
+| **Smart Verbosity** | Three-level output control (Quiet → Concise → Verbose) |
 
-- **Fixed external editor paste buffer race condition** - External editor callback now properly clears pending paste accumulation to prevent content overwrite
-- **Fixed `pastedBlocks` stale closure in submit** - Added `pastedBlocksRef` to ensure `expandPlaceholdersForSubmit` always has current paste block data during rapid paste + submit sequences
-- **Synchronized paste block refs** - All `setPastedBlocks` calls now sync `pastedBlocksRef` immediately to prevent race conditions
-- **Fixed async iterator cleanup** - Proper cleanup for async iterators in LLM agent
-- **Fixed cache eviction improvements** - Better memory management for token counter cache
-- **Fixed state validation and race conditions** - Improved state handling in MCP reconnection logic
-- **Fixed event listener error handling** - Better error boundaries for edge cases
+### AI Provider Support
 
-### ✅ Quality
+- **Z.AI GLM-4.6** (default) - 32K max tokens, optimized for complex code generation
+- **OpenAI** - GPT-4, GPT-3.5
+- **Anthropic** - Claude models
+- **Ollama** - Local models
+- **Custom endpoints** - Any OpenAI-compatible API
 
-- All tests passing
-- 98%+ test coverage maintained
-- Zero breaking changes
-- Improved stability for paste operations
-
----
+> **Note**: For xAI Grok, use [grok-cli](https://github.com/superagent-ai/grok-cli). For Anthropic Claude, use [claude-code](https://claude.ai/code).
 
-## 🎉 What's New in v3.8.0
+### Security (Enterprise-Grade, FREE)
 
-**UI/UX Refinements & Bug Fixes** - Polish and stability improvements:
+| Protection | Severity | Description |
+|------------|----------|-------------|
+| API Key Encryption | - | AES-256-GCM encryption at rest |
+| Command Injection | CVSS 9.8 | Safe command execution with whitelisting |
+| Path Traversal | CVSS 8.6 | Prevent unauthorized file system access |
+| SSRF Prevention | CVSS 7.5 | Validate MCP transport URLs |
+| Input Sanitization | CVSS 7.0 | Comprehensive input validation |
+| Rate Limiting | - | Token bucket algorithm (100 req/min) |
 
-### ✨ Improvements
+### Code Analysis Tools
 
-- **🎨 Unified Terminology**: Consistent "Auto-Edit" naming across entire UI
-  - Changed "Auto-apply" to "Auto-Edit" throughout all components
-  - Unified color scheme: Yellow for active, gray for inactive
-  - Consistent display in status bar, keyboard help, welcome panel, and toast messages
-
-- **🎨 Color Consistency**: Fixed UI color inconsistencies
-  - Auto-edit mode now consistently shows yellow when enabled (was mixed green/yellow)
-  - Verbosity mode properly shows yellow when active (Concise/Verbose), gray when Quiet
-  - All keyboard shortcuts and status indicators use matching colors
-
-### 🐛 Bug Fixes
-
-- **Fixed ModePill component** - Empty string values now display correctly
-- **Fixed ContextBar crashes** - Added bounds checking for invalid percentage values (NaN, Infinity, negative)
-- **Fixed formatTokenCount** - Handles invalid token counts gracefully (NaN, Infinity, negative)
-- **Fixed Verbosity display** - Pills now correctly highlight yellow when not in Quiet mode
-- **Fixed keyboard help colors** - Auto-edit status matches status bar coloring
-
-### ✅ Quality
-
-- All 1,517 tests passing (9 skipped)
-- 98.29% test coverage maintained
-- Zero breaking changes
-- Improved UI/UX consistency
+- **Dependency Analyzer** - Circular dependencies, coupling metrics
+- **Code Smell Detector** - 10+ anti-patterns detection
+- **Hotspot Analyzer** - Git history-based complexity analysis
+- **Security Scanner** - SQL injection, XSS, hardcoded secrets
 
 ---
-- **Type Safety**: Full TypeScript support with proper type exports
 
-### 📦 Breaking Changes
-
-**None!** All changes are backward compatible.
-
----
-
-## 📦 Installation
+## Installation
 
 ### Supported Platforms
 
-AX CLI officially supports the following platforms:
-
 | Platform | Versions | Architecture |
 |----------|----------|--------------|
-| 🍎 **macOS** | 26+ | x64, ARM64 (Apple Silicon) |
-| 🪟 **Windows** | 11+ | x64, ARM64 |
-| 🐧 **Ubuntu** | 24.04+ | x64, ARM64 |
-
-**Note:** AX CLI may work on other platforms and older versions, but the above platforms are officially tested and supported.
+| **macOS** | 26+ | x64, ARM64 (Apple Silicon) |
+| **Windows** | 11+ | x64, ARM64 |
+| **Ubuntu** | 24.04+ | x64, ARM64 |
 
 ### Prerequisites
 
 - Node.js 24.0.0 or higher
 - npm package manager
 
-### Global Installation (Recommended)
+### Install
 
 ```bash
 npm install -g @defai.digital/ax-cli
 ```
 
-[Installation Guide →](docs/installation.md)
-
-## ⚙️ Configuration
+---
 
-### Quick Setup
+## Configuration
 
-The recommended way to configure AX CLI is using the interactive setup wizard:
+### Quick Setup (Recommended)
 
 ```bash
-# Run the setup wizard (recommended)
 ax-cli setup
-
-# This will:
-# 1. Guide you through provider selection (Z.AI, OpenAI, Anthropic, Ollama, etc.)
-# 2. Securely encrypt and store your API key (AES-256-GCM encryption)
-# 3. Configure default model and settings
-# 4. Validate your configuration
 ```
 
-**Alternative: Environment Variable Override**
+This interactive wizard will:
+1. Guide you through provider selection
+2. Securely encrypt and store your API key (AES-256-GCM)
+3. Configure default model and settings
+4. Validate your configuration
+
+### Environment Variable Override
 
-For CI/CD pipelines or temporary overrides, you can set an environment variable:
+For CI/CD pipelines:
 
 ```bash
-# Override API key temporarily (not recommended for daily use)
 export YOUR_API_KEY=your_api_key_here
 ax-cli
 ```
 
-**⚠️ Security Note**: API keys are automatically encrypted in config files using AES-256-GCM encryption. **Do not manually edit `~/.ax-cli/config.json`** - always use `ax-cli setup` to update your API key securely.
-
 ### Configuration Files
 
-- **User Settings**: `~/.ax-cli/config.json` (API keys are encrypted)
-- **Project Settings**: `.ax-cli/settings.json` (project-specific overrides)
-- **Custom Instructions**: `.ax-cli/CUSTOM.md` (AI behavior customization)
-- **Project Memory**: `.ax-cli/memory.json` (auto-generated context cache)
-
-[Configuration Guide →](docs/configuration.md)
+| File | Purpose |
+|------|---------|
+| `~/.ax-cli/config.json` | User settings (API keys encrypted) |
+| `.ax-cli/settings.json` | Project-specific overrides |
+| `.ax-cli/CUSTOM.md` | AI behavior customization |
+| `.ax-cli/memory.json` | Auto-generated context cache |
 
 ---
 
-## 🔒 Security & API Key Handling
-
-🛡️ **Enterprise-Grade Security** - Your API keys and data are protected with multiple layers of security:
-
-### 🔐 API Key Encryption
-
-- **AES-256-GCM Encryption**: Military-grade authenticated encryption at rest
-- **PBKDF2 Key Derivation**: 600,000 iterations (OWASP 2024 standard)
-- **Secure File Permissions**: Config files automatically set to `0600` (owner-only)
-- **Auto-Migration**: Existing plain-text keys are automatically encrypted
-
-### 🎯 What's Protected
-
-✅ **Casual file browsing** - Prevents accidental exposure in editors  
-✅ **Config backups** - Keys unreadable in plain-text backups  
-✅ **Accidental commits** - Encrypted keys are useless without machine context  
-✅ **Data at rest** - Never stored in plain-text on disk  
-
-### ⚠️ Limitations (Transparent)
-
-❌ **Determined attackers** with machine access can derive encryption keys  
-❌ **Open-source analysis** - Implementation is publicly visible  
-
-> **Trade-off**: Like AWS CLI, kubectl, and GitHub CLI, we balance security with usability and portability.
-
-### 🛡️ Security Best Practices
-
-1. **CI/CD**: Use environment variables (`export API_KEY=...`)
-2. **File Permissions**: Verify `ls -la ~/.ax-cli/config.json` shows `-rw-------`
-3. **Git Safety**: Add `.ax-cli/` to `.gitignore`
-4. **Key Rotation**: Update regularly via `ax-cli setup`
-5. **Scoped Keys**: Use minimal permissions and spending limits
-6. **Monitoring**: Check provider dashboards for unusual activity
-
-### 📊 Privacy & Logging
-
-- ✅ **API keys**: NEVER logged
-- ✅ **Prompts**: Stored locally (encrypted if keys present)
-- ✅ **Errors**: Sanitized to remove sensitive data
-- ✅ **Telemetry**: NONE collected
-
-### 🚨 Report Security Issues
-
-Email: **security@defai.digital** (private, not public issues)
-
-Include: vulnerability description, reproduction steps, impact, and suggested fix. Response within 48 hours.
-
----
-
-## 🎯 Usage Examples
+## Usage
 
 ### Interactive Mode
 
@@ -844,75 +161,35 @@ Include: vulnerability description, reproduction steps, impact, and suggested fi
 # Start interactive chat
 ax-cli
 
-# Continue the most recent conversation in this directory
+# Continue previous conversation
 ax-cli --continue
-# or
 ax-cli -c
-
-# Available slash commands:
-/help              # Show help
-/continue          # Continue incomplete response
-/init              # Initialize project
-/clear             # Clear chat history
-/models            # Switch AI model
-/usage             # Show API usage statistics
-/doctor            # Run health check diagnostics
-/tasks             # List background tasks
-/task <id>         # View background task output
-/kill <id>         # Kill a background task
-/version           # Show AX CLI version
-/commit-and-push   # AI-powered git commit
-/exit              # Exit application
-
-# Multi-Phase Planner commands:
-/plans             # List all execution plans
-/plan              # Show current plan details
-/phases            # Show phase progress
-/pause             # Pause current plan execution
-/resume            # Resume paused plan
-/skip              # Skip current phase
-/abandon           # Abandon current plan
 ```
 
-### ⌨️ Keyboard Shortcuts (Claude Code-style)
-
-AX CLI supports powerful keyboard shortcuts for enhanced productivity:
-
-| Shortcut | Action | Description |
-|----------|--------|-------------|
-| **Ctrl+O** | Cycle verbosity | Quiet (grouped) → Concise (per-tool) → Verbose (full details) → Quiet |
-| **Ctrl+B** | Background mode | Move running command to background, or toggle "always background" mode |
-| **Ctrl+K** | Quick actions | Open quick actions menu |
-| **Shift+Tab** | Auto-edit mode | Toggle automatic approval for all operations |
-| **Ctrl+C** | Clear/Exit | Clear input (press twice to exit) |
-| **↑/↓** | History | Navigate command history |
-| **Ctrl+A/E** | Cursor | Move to line start/end |
-| **Ctrl+W** | Delete word | Delete word before cursor |
-
-**Verbosity Levels** (Ctrl+O to cycle):
-- **Quiet** (default): Groups operations → `⏺ Working on app.ts (3 edits, 5 reads) ✓ 2.3s`
-- **Concise**: One line per tool → `⏺ Read (app.ts) ✓ 22 lines`
-- **Verbose**: Full details → Shows args, outputs, diffs, timings
-
-### 🔄 Background Tasks
-
-Run long-running commands in the background (like Claude Code's Ctrl+B):
-
-```bash
-# Method 1: Append ' &' to any command
-> npm run dev &
-🔄 Background task started
-Task ID: bg_abc123
-
-# Method 2: Press Ctrl+B during execution to move to background
-
-# Method 3: Toggle "always background" mode with Ctrl+B when idle
-
-# Manage background tasks:
-/tasks              # List all background tasks
-/task bg_abc123     # View task output
-/kill bg_abc123     # Kill a running task
-```
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/continue` | Continue incomplete response |
+| `/init` | Initialize project |
+| `/clear` | Clear chat history |
+| `/models` | Switch AI model |
+| `/usage` | Show API usage statistics |
+| `/doctor` | Run health check diagnostics |
+| `/tasks` | List background tasks |
+| `/exit` | Exit application |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Ctrl+O** | Cycle verbosity (Quiet → Concise → Verbose) |
+| **Ctrl+B** | Move command to background |
+| **Ctrl+K** | Quick actions menu |
+| **Shift+Tab** | Toggle auto-edit mode |
+| **Ctrl+C** | Clear input (press twice to exit) |
+| **↑/↓** | Navigate command history |
 
 ### Headless Mode
 
@@ -920,558 +197,269 @@ Task ID: bg_abc123
 # 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
+ax-cli -p "write tests" --max-tool-rounds 50
 
 # With specific model
 ax-cli -p "refactor" --model glm-4.6
 ```
 
-### 🔌 VSCode Integration
-
-AX CLI integrates seamlessly with Visual Studio Code via tasks and keyboard shortcuts:
+### Background Tasks
 
 ```bash
-# Analyze current file
-ax-cli --prompt "Analyze this file" --file src/index.ts --json --vscode
-
-# Explain selected code
-ax-cli --prompt "Explain this code" --selection "function foo() {...}" --json --vscode
+# Append '&' to run in background
+> npm run dev &
 
-# Review git changes
-ax-cli --prompt "Review my changes" --git-diff --json --vscode
+# Or press Ctrl+B during execution
 
-# Analyze specific line range
-ax-cli --prompt "Optimize this section" --file app.ts --line-range 50-100 --json
+# Manage tasks
+/tasks              # List all
+/task bg_abc123     # View output
+/kill bg_abc123     # Kill task
 ```
 
-**Quick Setup:**
-```bash
-# Copy VSCode templates to your project
-cd your-project
-mkdir -p .vscode
-cp node_modules/@defai.digital/ax-cli/templates/vscode/*.json .vscode/
+### Health Check
 
-# Start using with Cmd+Shift+P → "Tasks: Run Task" → Select AX task
+```bash
+ax-cli doctor           # Run diagnostics
+ax-cli doctor --verbose # Detailed output
+ax-cli doctor --json    # JSON format
 ```
 
-**Pre-configured Tasks:**
-- 🔍 Analyze Current File
-- 📝 Explain Selection
-- 🔄 Review Git Changes
-- 🧪 Generate Tests
-- 📚 Document Code
-- ♻️ Refactor Selection
-- 🐛 Find Bugs
-- ⚡ Optimize Performance
-
-[VSCode Integration Guide →](docs/vscode-integration-guide.md)
+---
 
-### 🔄 Session Continuity (`--continue`)
+## MCP Integration
 
-Resume conversations seamlessly with directory-specific session history:
+Extend AX CLI with Model Context Protocol servers:
 
 ```bash
-# Start a conversation in your project
-cd /path/to/your/project
-ax-cli
-# > Work on some features, then exit
+# Add from template (one command!)
+ax-cli mcp add figma --template
 
-# Later, continue where you left off
-cd /path/to/your/project
-ax-cli --continue
-# All previous context is restored!
+# Add custom server
+ax-cli mcp add linear --transport sse --url https://mcp.linear.app/sse
 
-# Each project maintains its own independent history
-cd /path/to/another/project
-ax-cli --continue
-# Fresh context for this project
-```
+# List servers
+ax-cli mcp list
 
-**How It Works:**
-- Each project directory gets its own conversation session
-- History includes all messages, tool calls, and results
-- Integrated with `.ax-cli/CUSTOM.md` for project-specific context
-- Sessions stored in `~/.ax-cli/sessions/` by project hash
-- Up to 50 most recent messages preserved per session
+# Preview tools
+ax-cli mcp tools <server>
 
-**Use Cases:**
-- Multi-day feature development with accumulated knowledge
-- Resume after interruptions without losing context
-- Maintain separate conversations per project
-- Natural workflow continuity across sessions
+# Browse templates
+ax-cli mcp browse
+```
 
-### Project Initialization
+### Available Templates
 
-```bash
-# Analyze and initialize project
-ax-cli init
+Figma, GitHub, Vercel, Puppeteer, Storybook, Sentry, and 6+ more.
 
-# Force regeneration
-ax-cli init --force
+### Per-Server Timeout
 
-# Verbose output
-ax-cli init --verbose
-```
+For long-running tools (e.g., AutomatosX):
 
-### Usage Tracking
+```json
+{
+  "mcpServers": {
+    "automatosx": {
+      "transport": { "type": "stdio", "command": "ax", "args": ["mcp"] },
+      "timeout": 2700000
+    }
+  }
+}
+```
 
-Track your API usage across the current session:
+---
 
-```bash
-# Show current session usage statistics
-ax-cli usage show
+## Project Memory
 
-# Show detailed breakdown by model
-ax-cli usage show --detailed
+Intelligent context caching for reduced token costs:
 
-# Export as JSON
-ax-cli usage show --json
+```bash
+# Initialize (scans codebase)
+ax-cli memory warmup
 
-# Reset session statistics
-ax-cli usage reset
+# Output:
+# ✓ Project memory generated (3,305 tokens)
+# 📊 Token Distribution:
+#    Structure:  1,252 tokens (38%)
+#    README:     1,111 tokens (34%)
+#    Config:       835 tokens (25%)
+#    Patterns:      99 tokens (3%)
 ```
 
-**Phase 1**: Z.AI provider with session-based tracking
-- Tracks prompt tokens, completion tokens, and reasoning tokens
-- Per-model breakdown available
-- Historical data available via Z.AI dashboard: https://z.ai/manage-apikey/billing
+### Commands
 
-**Phase 2** (Coming Soon): Support for additional providers (OpenAI, Anthropic, etc.)
+| Command | Description |
+|---------|-------------|
+| `memory warmup` | Create project memory |
+| `memory refresh` | Update after changes |
+| `memory status` | Show status & token distribution |
+| `memory clear` | Remove project memory |
+| `memory cache-stats` | Show cache efficiency |
 
-[CLI Reference →](docs/cli-reference.md) | [Usage Guide →](docs/usage.md)
+### Options
 
-## 📋 Working with Large Content
-
-AX CLI has **intelligent paste handling** that automatically manages large text inputs for better readability.
+```bash
+ax-cli memory warmup -d 5           # Custom scan depth (1-10)
+ax-cli memory warmup -m 12000       # Custom max tokens
+ax-cli memory warmup --dry-run      # Preview without saving
+```
 
-### 📝 Smart Paste Auto-Collapse
+---
 
-When you paste **20+ lines** of text, AX CLI automatically collapses it:
+## Multi-Phase Task Planner
 
-- ✅ **Automatic Detection**: Pastes with 20+ lines are auto-collapsed
-- ✅ **Clean Display**: Shows `[Pasted text #1 +89 lines]` instead of cluttering the UI
-- ✅ **Full Submission**: Complete text is still sent to the AI (not just the placeholder)
-- ✅ **Review Anytime**: Press **Ctrl+P** on a collapsed block to expand/collapse
+Automatic decomposition for complex requests:
 
-**Example:**
 ```bash
-# Paste a 100-line error log
-# → Shows: [Pasted text #1 +100 lines]
-# → AI receives: Full 100 lines
+> "Refactor auth, add tests, update docs"
 
-# Position cursor on placeholder and press Ctrl+P to review
-# → Expands to show all 100 lines
+📋 Plan Generated: 4 phases
+├── Phase 1: Analysis (low risk)
+├── Phase 2: Implementation (medium risk)
+├── Phase 3: Testing (low risk)
+└── Phase 4: Documentation (low risk)
 ```
 
-**Configure in `~/.ax-cli/config.json`:**
-```json
-{
-  "paste": {
-    "autoCollapse": true,        // Enable/disable (default: true)
-    "collapseThreshold": 20      // Min lines to collapse (default: 20)
-  }
-}
-```
+### Plan Commands
 
-### ⚠️ Character Counter Warning
+| Command | Description |
+|---------|-------------|
+| `/plans` | List all execution plans |
+| `/plan` | Show current plan details |
+| `/phases` | Show phase progress |
+| `/pause` | Pause current plan |
+| `/resume` | Resume paused plan |
+| `/skip` | Skip current phase |
+| `/abandon` | Abandon current plan |
 
-The character counter shows visual warnings for very large single inputs:
-- Gray (0-999) → Cyan (1000-1599) → Yellow (1600-1999) → **Red (2000+)**
+### Complexity Triggers
 
-### ✅ Alternative Approaches for Extremely Large Content
+- Refactoring, migration, restructuring
+- Multi-file changes
+- Testing and documentation requests
+- Multi-step instructions
 
-**Option 1: File Reference (Interactive Mode)**
-```bash
-# Save your content to a file first
-cat > context.txt
-# (paste content, then Ctrl+D)
+---
 
-# Then use memory commands
-ax-cli
-> /memory add context.txt
-> analyze the content I just added
-```
+## Security
 
-**Option 2: Headless Mode with File Input**
-```bash
-# Direct file processing
-ax-cli --prompt "analyze this: $(cat large-file.txt)"
+### API Key Protection
 
-# Or use the --file flag
-ax-cli --file path/to/code.ts --prompt "review this code"
-```
+- **AES-256-GCM** encryption at rest
+- **PBKDF2** key derivation (600,000 iterations)
+- **Secure permissions** (0600 owner-only)
+- **Auto-migration** from plain-text
 
-**Option 3: Use `/memory` Commands**
-```bash
-# In interactive mode
-> /memory add src/
-> /memory add logs/error.log
-> analyze the errors in the log file
-```
+### Best Practices
 
-### Character Count Guide
+1. **CI/CD**: Use environment variables
+2. **Permissions**: Verify `ls -la ~/.ax-cli/config.json` shows `-rw-------`
+3. **Git**: Add `.ax-cli/` to `.gitignore`
+4. **Rotation**: Update regularly via `ax-cli setup`
 
-The interactive terminal shows a character counter `[count/2000]` with color-coded warnings:
+### Privacy
 
-| Color | Range | Recommendation |
-|-------|-------|----------------|
-| **Gray** | 0-999 | ✅ Optimal length |
-| **Cyan** | 1000-1599 | ⚠️ Getting long |
-| **Yellow** | 1600-1999 | ⚠️ Consider using files |
-| **Red** | 2000+ | ❌ Use file-based workflow |
+- API keys: **Never logged**
+- Telemetry: **None collected**
+- Errors: Sanitized to remove sensitive data
 
-## 🏥 Health Check & Diagnostics
+### Report Issues
 
-Run comprehensive diagnostics to verify your AX CLI configuration:
+Email: **security@defai.digital** (private disclosure)
 
-```bash
-# Run full diagnostic check
-ax-cli doctor
+---
 
-# Get detailed diagnostic information
-ax-cli doctor --verbose
+## Architecture
 
-# Output results as JSON
-ax-cli doctor --json
-```
+- **SSOT Type System** via `@ax-cli/schemas`
+- **TypeScript strict mode** with Zod validation
+- **98%+ test coverage** (2083 tests)
+- **Modular design** with clean separation
+- **Enterprise security** with AES-256-GCM encryption
 
-The `doctor` command checks:
-- ✓ Node.js version (24+)
-- ✓ Configuration files (user and project)
-- ✓ API key and base URL
-- ✓ API connectivity and authentication
-- ✓ Model configuration
-- ✓ MCP server configuration
-- ✓ Dependencies (ripgrep, git)
+---
 
-## 🔌 MCP (Model Context Protocol)
+## Changelog
 
-Extend AX CLI with MCP servers for additional capabilities:
+### v3.8.23 (Latest)
 
-```bash
-# Add MCP server
-ax-cli mcp add linear --transport sse --url https://mcp.linear.app/sse
+- **Bug fix: Background task status** - Killed tasks now correctly show 'killed' instead of 'failed'
+- **Bug fix: Project settings corruption** - Now throws error instead of silent data loss
+- **Bug fix: Destructive operation confirmation** - `alwaysConfirm` flag now properly forces confirmation
 
-# List servers
-ax-cli mcp list
+### v3.8.21
 
-# Remove server
-ax-cli mcp remove linear
-```
+- **Configurable confirmation timeout** - Now uses `TIMEOUT_CONFIG.CONFIRMATION_TIMEOUT`
+- **Dynamic timeout message** - Displays actual configured value
 
-[MCP Integration Guide →](docs/mcp.md)
+### v3.8.20
 
-## 🧠 Project Memory
+- **Centralized path constants** - `CONFIG_PATHS` for unified path handling
+- **Unified timeout usage** - `TIMEOUT_CONFIG` and `MCP_CONFIG`
 
-Project Memory enables intelligent context caching for z.ai GLM-4.6, reducing token costs and improving response consistency:
+### v3.8.19
 
-```bash
-# Initialize project memory (scans codebase)
-ax-cli memory warmup
+- **Exported utilities** - `sleep()` and `calculateExponentialBackoff()`
+- **Reduced code duplication** - Centralized backoff logic
 
-# Output:
-# ✓ Project memory generated (3,305 tokens)
-#
-# 📊 Context breakdown:
-#    Structure:  1,252 tokens (38%)
-#    README:     1,111 tokens (34%)
-#    Config:       835 tokens (25%)
-#    Patterns:      99 tokens (3%)
-```
+### v3.8.18
 
-### How It Works
+- **Extended timeout configuration** - Network/API and UI timeouts
 
-1. **Warmup**: Scans your project structure, README, configs, and detects architecture patterns
-2. **Auto-Injection**: Memory context is automatically prepended to system prompts
-3. **z.ai Caching**: Identical prompt prefixes are automatically cached by z.ai (50% token savings)
-4. **Statistics**: Track cache efficiency with `ax-cli memory cache-stats`
+### v3.8.17
 
-### Memory Commands
+- **Centralized configuration** - All timeouts configurable via YAML
 
-```bash
-ax-cli memory warmup        # Create project memory
-ax-cli memory refresh       # Update after changes
-ax-cli memory status        # Show memory status & token distribution
-ax-cli memory clear         # Remove project memory
-ax-cli memory cache-stats   # Show cache efficiency statistics
+### v3.8.16
 
-# Options
-ax-cli memory warmup -d 5           # Custom scan depth (1-10)
-ax-cli memory warmup -m 12000       # Custom max tokens
-ax-cli memory warmup --dry-run      # Preview without saving
-ax-cli memory status --verbose      # Show full context
-ax-cli memory status --json         # JSON output
-```
+- **Per-server MCP timeout** - Fixes AutomatosX timeout errors
 
-### Token Distribution Visualization
+### v3.8.15
 
-```
-📊 Token Distribution:
-   ████████░░░░░░░░░░░░  Structure  (38%)
-   ███████░░░░░░░░░░░░░  README     (34%)
-   █████░░░░░░░░░░░░░░░  Config     (25%)
-   █░░░░░░░░░░░░░░░░░░░  Patterns   (3%)
-```
+- **Increased streaming timeouts** - 90s first chunk, 120s idle
+- **Better file type handling** - Glob patterns for tsx, jsx, vue
 
-### Recommended Workflow
+### v3.8.14
 
-```bash
-# 1. Initialize project (if not done)
-ax-cli init
+- **REPL command detection** - Prevents MCP server hangs
 
-# 2. Create project memory
-ax-cli memory warmup
+[View full changelog →](https://github.com/defai-digital/ax-cli/releases)
 
-# 3. Use ax-cli normally - memory is auto-injected
-ax-cli -p "refactor authentication module"
+---
 
-# 4. After major changes, refresh memory
-ax-cli memory refresh
-```
+## Documentation
 
-## 🎯 Multi-Phase Task Planner (v3.0.0)
+| Guide | Description |
+|-------|-------------|
+| [Features](docs/features.md) | Complete feature list |
+| [Installation](docs/installation.md) | Detailed installation guide |
+| [Configuration](docs/configuration.md) | Configuration options |
+| [Usage](docs/usage.md) | Comprehensive usage guide |
+| [CLI Reference](docs/cli-reference.md) | Command-line reference |
+| [MCP Integration](docs/mcp.md) | Model Context Protocol guide |
+| [Architecture](docs/architecture.md) | Technical architecture |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues |
 
-AX CLI now includes an intelligent multi-phase task planner that automatically decomposes complex requests:
+---
 
-```bash
-# Complex requests are automatically detected and planned
-> "Refactor the authentication system, add tests, and update documentation"
+## Enterprise Features
 
-📋 Plan Generated: 4 phases
-├── Phase 1: Analysis (low risk)
-├── Phase 2: Implementation (medium risk)
-├── Phase 3: Testing (low risk)
-└── Phase 4: Documentation (low risk)
+For teams requiring advanced capabilities:
 
-Executing Phase 1/4: Analysis...
-```
+- **Compliance Reports** - SOC2, HIPAA, PCI-DSS
+- **Advanced Audit Logging** - Tamper-proof with 1+ year retention
+- **Team Collaboration** - Shared history with full-text search
+- **Policy Enforcement** - Approval workflows
+- **SSO/SAML** - Enterprise identity provider support
+- **Priority Support** - 24-hour SLA
 
-**Features:**
-- **Automatic Complexity Detection**: 57 keyword patterns detect when planning is needed
-- **LLM-Based Decomposition**: Intelligent breakdown into logical phases
-- **Dependency Management**: Phases execute in proper order
-- **Progress Tracking**: Real-time updates on phase completion
-- **File Tracking**: Monitors which files are modified per phase
-- **Context Pruning**: Automatically manages token limits between phases
-
-**Complexity Triggers:**
-- Refactoring, migration, or restructuring tasks
-- Multi-file changes or feature implementations
-- Testing and documentation requests
-- Architecture or design tasks
-- Multi-step instructions (first...then...finally)
+Contact: **sales@defai.digital**
+
+---
+
+## License
 
-## 🤖 Advanced Multi-Agent Orchestration
-
-**AX CLI** is designed as a focused, single-agent CLI tool for direct AI-powered development tasks. For advanced multi-agent orchestration, collaborative AI workflows, and complex task automation, we recommend **[AutomatosX](https://automatosx.com)**.
-
-### When to Use AutomatosX Instead
-
-- **Multi-Agent Collaboration**: Coordinate multiple AI agents working together on complex projects
-- **Specialized Agent Teams**: Use domain-specific agents (QA, architecture, security, etc.)
-- **Advanced Workflows**: Build sophisticated automation pipelines with agent orchestration
-- **Enterprise Scale**: Large-scale projects requiring parallel agent execution and coordination
-
-AX CLI focuses on being a reliable, single-agent development assistant, while AutomatosX provides the full multi-agent orchestration platform for advanced use cases.
-
-## 🏗️ Architecture
-
-AX CLI implements enterprise-grade architecture with:
-
-- **Single Source of Truth (SSOT)** type system via `@ax-cli/schemas`
-- **TypeScript strict mode** with Zod runtime validation
-- **98%+ test coverage** (1517 tests passing)
-- **Modular design** with clean separation of concerns
-- **Enterprise security** with AES-256-GCM encryption for sensitive data
-
-[Architecture Documentation →](docs/architecture.md)
-
-## 📚 Documentation
-
-- [Features](docs/features.md) - Complete feature list and capabilities
-- [Installation](docs/installation.md) - Detailed installation guide
-- [Configuration](docs/configuration.md) - Configuration options and settings
-- [Security & API Key Handling](#-security--api-key-handling) - Security model, encryption details, and best practices
-- [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
-- [Project Memory](automatosx/prd/project-memory-prd.md) - Project memory feature specification
-- [Architecture](docs/architecture.md) - Technical architecture details
-- [Development](docs/development.md) - Development and contribution guide
-- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
-
-## 📋 Changelog
-
-### v3.8.0 (2025-11-23)
-
-**🎨 UI/UX Refinements & Bug Fixes:**
-
-**✨ Improvements:**
-- Unified "Auto-Edit" terminology throughout entire UI (was inconsistently "Auto-apply")
-- Consistent yellow color scheme for Auto-Edit mode when enabled
-- Fixed Verbosity mode color display (yellow when active, gray when Quiet)
-- Improved visual consistency across status bar, keyboard help, and welcome panel
-
-**🐛 Bug Fixes:**
-- Fixed ModePill component handling of empty string values
-- Fixed ContextBar crashes with invalid percentage values (NaN, Infinity, negative)
-- Fixed formatTokenCount handling of invalid inputs
-- Fixed Verbosity pill not highlighting when not in Quiet mode
-- Fixed keyboard help color inconsistencies
-
-**✅ Quality:**
-- All 1,517 tests passing (9 skipped)
-- 98.29% test coverage maintained
-- Zero breaking changes
-
-### v3.7.2 (2025-11-23)
-
-**🐛 Bug Fixes - Test Stability:**
-- Fixed flaky process-pool tests failing in CI/CD environments
-  - Added proper async cleanup waiting with `setImmediate()`
-  - Fixed race condition where `activeProcesses` count was checked before cleanup completed
-  - Tests: "should handle errors without leaking resources" and "should remove all event listeners after execution"
-  - Follows Node.js best practices for testing async cleanup operations
-
-**✅ Test Results:**
-- All 1,517 tests passing (9 skipped)
-- 98.29% test coverage maintained
-- Zero breaking changes
-- Improved CI/CD reliability
-
-### v3.6.1 (2025-11-22)
-
-**🔧 Improvements:**
-- **Smart Paste Auto-Collapse**: Intelligent handling of large text inputs
-  - Automatic collapse of 20+ line pastes for better readability
-  - Press Ctrl+P to expand/collapse pasted content
-  - Configurable threshold in `~/.ax-cli/config.json`
-  - Full content still sent to AI (not just the placeholder)
-
-**✅ Quality:**
-- All 1,381 tests passing with 98.29% coverage
-- Zero breaking changes
-- Cleaner codebase with reduced complexity
-
-### v3.6.0 (2025-11-22)
-
-**🔒 Enterprise-Grade Security (FREE & Open Source):**
-- **API Key Encryption**: AES-256-GCM encryption for API keys at rest
-- **Command Injection Protection**: CVSS 9.8 CRITICAL fix with command whitelisting
-- **Path Traversal Hardening**: CVSS 8.6 HIGH fix preventing unauthorized file access
-- **SSRF Attack Prevention**: CVSS 7.5 HIGH fix for MCP transport URL validation
-- **Input Sanitization**: CVSS 7.0 HIGH fix for comprehensive input validation
-- **Error Sanitization**: CVSS 6.5 MEDIUM fix preventing credential leakage
-- **Security Audit Logging**: Basic JSON logging with 30-day retention
-- **Rate Limiting**: Token bucket algorithm to prevent API abuse
-- **Memory Leak Fixes**: Process pool management for long-running operations
-
-**✅ Test Quality:**
-- **1517+ tests passing** with 98.29% coverage
-- All security modules fully tested and validated
-- Production-ready security implementation
-
-**🏢 Enterprise Features (Available):**
-- Advanced audit logging with compliance reports (SOC2, HIPAA, PCI-DSS)
-- Team collaboration with shared chat history
-- Policy enforcement and approval workflows
-- Extended audit log retention (1+ years)
-- SSO/SAML integration support
-- Priority 24-hour SLA support
-- Contact sales@defai.digital for enterprise licensing
-
-**🔧 Configuration Improvements:**
-- New `ax-cli setup` wizard for secure API key configuration
-- Automatic migration of plain-text API keys to encrypted format
-- Environment variable override support for CI/CD workflows
-
-### v3.5.3 (2025-11-22)
-
-**Bug Fixes - Test Quality & Reliability:**
-- Fixed unhandled promise rejection in subagent tests that caused Node.js warnings
-- Replaced meaningless test assertions (`expect(true).toBe(true)`) with real validation
-- Properly skipped untestable tests with clear TODO documentation
-- Fixed flaky performance test by adjusting timing threshold (0.9x instead of 0.7x)
-
-**Test Suite Improvements:**
-- Improved test isolation and error handling patterns
-- Enhanced performance test reliability for CI/CD environments
-- Better documentation of test limitations
-- All 1,038 tests passing (1,036 passed + 2 properly skipped)
-
-**Code Quality:**
-- Comprehensive test quality analysis across all test files
-- Eliminated false confidence from placeholder tests
-- Maintained 98%+ test coverage with genuine validation
-
-### v3.7.1 (2025-11-22)
-
-**Bug Fixes - Critical Stability Improvements:**
-- Fixed crash on malformed LLM responses: Added try-catch to `parseToolArgumentsCached` in LLMAgent
-  - Prevents agent crash when LLM sends invalid JSON in tool arguments
-  - Returns empty object instead of throwing, allowing session to continue
-  - Affects ~1 in 1000 tool calls based on observed LLM behavior
-- Fixed memory leak in BashTool: Added dispose() method
-  - Properly terminates running bash processes on cleanup
-  - Removes all event listeners to prevent accumulation
-  - Fixes resource leak from orphaned process handles
-- Fixed agent disposal: Added tool cleanup cascade
-  - Agent now calls bash.dispose() during cleanup
-  - Ensures all tool resources are properly released
-
-**Bug Fixes - Performance & Memory:**
-- Fixed unbounded cache growth in `toolCallArgsCache`
-  - Limited to 500 entries with LRU eviction (oldest 100)
-  - Prevents 5+ MB memory leak per 10,000 tool calls
-  - Applied to both LLMAgent and Subagent classes
-- Fixed resource leak in bash abort handler
-  - Cleanup listener now called even when moveToBackground() fails
-  - Prevents event listener memory leaks
-- Updated MCPManager to use singleton TokenCounter
-  - Saves 100-200ms initialization time
-  - Shares tiktoken encoder instance across MCP operations
-
-**Test Results:**
-- All 1,497 tests passing (9 skipped)
-- 98.29% test coverage maintained
-- Zero breaking changes
-
-**Combined Performance Gains:**
-- Startup: 245-495ms faster (30-50% improvement)
-- Runtime: 70-150ms faster per session
-- Memory: Bounded, predictable usage with no leaks
-
-### v3.5.2 (2025-11-22)
-
-**Bug Fixes - Resource Leak Prevention:**
-- Fixed uncleaned nested timeout in bash tool that held process references after exit
-- Fixed uncleaned timeout in MCP URL validation causing 3-second memory leaks
-- Added `.unref()` to background cleanup timers to prevent GC blocking
-- Added try-finally blocks for guaranteed timeout cleanup in error scenarios
-
-**Bug Fixes - Platform Compatibility:**
-- Fixed Windows home directory bug in command history (used `os.homedir()` instead of `"~"` fallback)
-
-**Code Quality:**
-- Comprehensive resource leak analysis across 78+ potential issues
-- Improved timeout cleanup patterns following Node.js best practices
-- Enhanced memory management for better garbage collection
-
-### v3.5.0
-
-**Features:**
-- Multi-phase task planner with automatic complexity detection
-- Enhanced MCP integration with production-ready templates
-- Project memory system with intelligent context caching
-- Advanced code analysis tools (dependency, security, metrics)
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) for details
-
-## 🙏 Acknowledgments
-
-Built with **AutomatosX** multi-agent orchestration to achieve enterprise-class standards.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---