@defai.digital/ax-cli 4.0.4 → 4.0.6

package/README.md

@@ -1,10 +1,10 @@
 # AX CLI - Enterprise-Class CLI for Vibe Coding
 
-[![downloads](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)
+[![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-2265%20passing-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli/actions/workflows/test.yml)
-[![macOS](https://img.shields.io/badge/macOS-26.0-blue?style=flat-square&logo=apple)](https://www.apple.com/macos/)
-[![Windows](https://img.shields.io/badge/Windows-10%2B-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/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/badge/coverage-98%2B%25-brightgreen?style=flat-square)](https://github.com/defai-digital/ax-cli)
+[![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)
 
 <p align="center">
   <img src=".github/assets/screenshot1.png" alt="AX CLI Screenshot" width="800"/>
@@ -22,17 +22,20 @@
 # Install globally
 npm install -g @defai.digital/ax-cli
 
-# Configure API credentials (one-time setup)
+# Configure (secure API key setup)
 ax-cli setup
 
-# Start interactive mode
-ax-cli
+# For VSCode users - install the extension (recommended)
+code --install-extension defai-digital.ax-cli-vscode
 
-# Inside interactive mode, initialize your project
-> /init
+# Initialize your project
+ax-cli init
+
+# Start coding!
+ax-cli
 ```
 
-**That's it!** AX CLI is now ready to help you build, debug, and ship code faster.
+**That's it!** AX CLI is now ready to help you build, debug, and ship code faster. VSCode users get enhanced features with the native extension.
 
 ---
 
@@ -42,14 +45,14 @@ ax-cli
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Usage](#usage)
+- [VSCode Integration](#vscode-integration)
 - [MCP Integration](#mcp-integration)
-- [Figma Integration](#figma-integration)
 - [Project Memory](#project-memory)
 - [Multi-Phase Planner](#multi-phase-task-planner)
 - [Security](#security)
 - [Architecture](#architecture)
 - [Changelog](#changelog)
-- [Recent Changes (v4.0.2)](#recent-changes-v402)
+- [Recent Changes (v3.12.8)](#recent-changes-v3128)
 - [Documentation](#documentation)
 
 ---
@@ -77,8 +80,6 @@ ax-cli
 - **Ollama** - Local models
 - **Custom endpoints** - Any OpenAI-compatible API
 
-> **Note**: For xAI Grok, use [grok-cli](https://github.com/superagent-ai/grok-cli). For Anthropic Claude, use [claude-code](https://claude.ai/code).
-
 ### Security (Enterprise-Grade, FREE)
 
 | Protection | Severity | Description |
@@ -296,6 +297,70 @@ For long-running tools (e.g., AutomatosX):
 
 ---
 
+## VSCode Integration
+
+AX CLI offers two powerful VSCode integration options:
+
+### Option 1: Native VSCode Extension (Recommended)
+
+The official AX CLI extension provides the most seamless experience:
+
+```bash
+# Install extension from VSCode Marketplace
+code --install-extension defai-digital.ax-cli-vscode
+
+# Or install via VSCode: Extensions → Search "AX CLI"
+```
+
+**Key Features:**
+- **Terminal Integration with Diff Preview** - File changes appear as diffs with accept/reject
+- **Sidebar Chat Panel** - Native chat interface with multiple sessions
+- **Secure API Key Storage** - OS-level credential storage (Keychain/Credential Manager)
+- **Context-Aware Commands** - Right-click actions for current file/selection
+- **Checkpoint & Rewind System** - Automatic checkpoints before changes
+- **Multi-Provider AI Support** - Switch between Grok, GLM, Claude, GPT-4o from status bar
+
+**Quick Start:**
+1. Install extension: `code --install-extension defai-digital.ax-cli-vscode`
+2. Set API key: `Cmd+Shift+K` (Mac) or `Ctrl+Shift+K` (Windows/Linux)
+3. Open chat: `Cmd+Shift+A` or click AX icon in sidebar
+4. Start coding with AI assistance!
+
+**Keyboard Shortcuts:**
+| Shortcut (Mac) | Shortcut (Win/Linux) | Action |
+|----------------|---------------------|---------|
+| `Cmd+Shift+A` | `Ctrl+Shift+A` | Open Chat |
+| `Cmd+Shift+E` | `Ctrl+Shift+E` | Explain Selection |
+| `Cmd+Shift+R` | `Ctrl+Shift+R` | Refactor Selection |
+| `Cmd+Shift+T` | `Ctrl+Shift+T` | Generate Tests |
+| `Cmd+Shift+B` | `Ctrl+Shift+B` | Find Bugs |
+
+### Option 2: Terminal Integration (Lightweight)
+
+Use AX CLI in VSCode's integrated terminal with pre-configured tasks:
+
+```bash
+# Copy VSCode templates to your project
+cd your-project
+mkdir -p .vscode
+cp node_modules/@defai.digital/ax-cli/templates/vscode/*.json .vscode/
+
+# Run tasks via Command Palette
+Cmd+Shift+P → "Tasks: Run Task" → Select AX task
+```
+
+**Available Tasks:**
+- AX: Interactive Chat
+- AX: Analyze Current File
+- AX: Explain Selection  
+- AX: Generate Tests for File
+- AX: Review Git Changes
+- AX: Find Bugs in File
+
+For detailed setup instructions, see **[VSCode Integration Guide](docs/vscode-integration-guide.md)**.
+
+---
+
 ## Figma Integration
 
 Connect AX CLI with Figma for design-to-code workflows:
@@ -443,581 +508,60 @@ Email: **security@defai.digital** (private disclosure)
 
 ---
 
-## Recent Changes (v4.0.4)
+## Changelog
 
-### VS Code Extension Bug Fixes
+### v4.0.5 - SDK Data Mutation Bug Fixes
 
-- **IPC Server Timeout Handling**: Added timeout protection for `diff_preview` (5 min) and `chat_request` (30 sec) handlers to prevent indefinite hangs
-- **Memory Leak Fixes**: Fixed timer memory leaks in IPC message handlers with proper `clearTimeout()` cleanup
-- **DiffContentProvider Memory Management**: Added automatic cleanup of stale diff entries (10 min expiry), max entries limit (50), and proper disposal
-- **StatusBar Auto-Reset**: `updateStatus()` now auto-resets to model display after 5 seconds with proper disposal guards
-- **Cross-Platform Path Handling**: Fixed `showDiffPreview` to use `path.basename()` instead of string split for Windows compatibility
-- **Git Diff Context**: `getGitDiffContext()` now actually checks for changes instead of always returning `true`
-- **Webview Disposal Guards**: Added guards against webview disposal in message handlers
+Comprehensive fixes for data mutation vulnerabilities across the SDK:
 
-### SDK Bug Fixes & Improvements
+- **Event Isolation**: Progress reporter and logger now emit separate object copies to prevent cross-listener contamination
+- **Tool Registry**: Clones definitions, tags, and execution args to prevent external mutation
+- **Testing Utilities**: MockAgent, MockMCPServer, MockSettingsManager now return/store deep copies
+- **Agent Lifecycle**: Double disposal guard, non-Error throwable handling, subagent config isolation
 
-- **Multiple Agent Cleanup**: Fixed `process.once()` to `process.on()` to allow multiple agents to register cleanup handlers
-- **Double Cleanup Prevention**: Manual `dispose()` now properly marks SDK internal state to prevent auto-cleanup from running again
-- **Version Parsing**: Added support for 'v' prefix, validation for negative numbers, and warnings for extra version parts
-- **UnifiedLogger Improvements**: Fixed regex `lastIndex` state issue in log filtering, added count validation in `getRecentLogs()`
-- **ToolRegistry Source Tracking**: Fixed tool overwrite not updating source tracking when registered by different source
-- **ProgressReporter Validation**: Added required field validation for `agentId`, `name`, and `type` in `report()` method
-- **MockAgent Empty Array Fix**: Fixed modulo-by-zero crash when responses array is empty
-- **MockMCPServer Error Handling**: Added try-catch wrappers for `callTool`, `readResource`, and `executePrompt` handlers
-- **Testing Utilities**: Added validation for `setResponses()` to reject empty arrays, warning for invalid settings keys
+### v4.0.4 - VS Code Extension & SDK Bug Fixes
 
----
+- VS Code extension: IPC timeout handling, memory leak fixes, cross-platform path handling
+- SDK: Multiple agent cleanup, version parsing improvements, testing utility fixes
 
-## Previous Changes (v4.0.3)
+### v4.0.3 - Theme System Bug Fixes
 
-### Theme System Bug Fixes & Improvements
+- Case-insensitive theme names, diff renderer theme support, cache mutation protection
 
-- **Case-insensitive Theme Names**: `/theme DARK` and `/theme Dark` now work correctly
-- **Diff Renderer Theme Support**: Diff displays now use theme-aware colors
-- **Cache Mutation Protection**: Theme colors cache is now protected from external mutation
-- **Frozen Theme Objects**: Theme registry objects are frozen to prevent accidental corruption
-- **Consistent Theme APIs**: `getCurrentThemeName()` now uses shared cache for consistency
-- **Derived Theme Names**: Theme name list is now derived from registry to prevent sync issues
+### v4.0.2 - Color Theme System
 
----
-
-## Previous Changes (v4.0.2)
-
-### Color Theme System
-
-- **5 Built-in Themes**: Choose from `default`, `dark`, `light`, `dracula`, and `monokai` color themes
-- **Theme Command**: New `/theme` slash command to list available themes or set a new theme
-- **Semantic Colors**: Theme-aware colors for primary, secondary, success, warning, error, muted, border, accent, and info states
-- **Light/Dark Support**: Optimized visibility for both light and dark terminal backgrounds
-- **Persistent Settings**: Theme preference saved to user settings (`~/.ax-cli/config.json`)
-
-**Usage:**
-```bash
-/theme              # List all available themes
-/theme dark         # Switch to dark theme
-/theme dracula      # Switch to Dracula theme
-```
+- 5 built-in themes: `default`, `dark`, `light`, `dracula`, `monokai`
+- New `/theme` slash command
 
----
+### v4.0.0 - Tool System v3.0
 
-## Previous Changes (v4.0.1)
+- Rich tool definitions with 500+ word descriptions, usage notes, and anti-patterns
+- Format generators for OpenAI/Anthropic from single source of truth
+- Result enhancer with malware detection and sensitive data warnings
 
-### UX Improvements & Bug Fixes
+### Earlier Versions
 
-- **Enhanced CLI UX**: Applied `@clack/prompts` library to `doctor`, `mcp health`, `cache show`, and `usage show` commands for beautiful interactive output with spinners, note boxes, and formatted summaries
-- **Parallel Agent Execution**: New `ax_agents_parallel` tool enables concurrent execution of multiple AutomatosX AI agents for faster multi-perspective reviews
-- **Bug Fix**: Fixed global regex `lastIndex` state contamination in image handler that caused flaky tests when run in sequence
-- **Tool System Refinements**: Renamed `getAllGrokTools` to `getAllTools` for clarity
+For complete changelog history, see [GitHub Releases](https://github.com/defai-digital/ax-cli/releases).
 
 ---
 
-## Previous Changes (v4.0.0)
-
-### Tool System v3.0 - Major Architecture Upgrade
-
-This major release introduces a completely redesigned tool definition system inspired by Claude Code's quality standards:
-
-#### Rich Tool Definitions (Single Source of Truth)
-
-- **Comprehensive Metadata**: Each tool now has 500+ word descriptions, usage notes, constraints, anti-patterns, and concrete examples
-- **Type-Safe Architecture**: New `ToolDefinition` interface with full TypeScript support
-- **Format Generators**: OpenAI and Anthropic formats are now derived from rich definitions, not hand-written
-
-#### New Tool Definition System
-
-| Component | Purpose |
-|-----------|---------|
-| `src/tools/types.ts` | Core type definitions (ToolDefinition, ParameterDefinition, etc.) |
-| `src/tools/format-generators.ts` | Converts rich definitions to OpenAI/Anthropic formats |
-| `src/tools/result-enhancer.ts` | Adds security reminders and contextual guidance |
-| `src/tools/definitions/*.ts` | 17 rich tool definitions with Claude Code quality |
-
-#### Tool Categories
-
-- **File Operations**: view_file, create_file, str_replace_editor, multi_edit
-- **Command Execution**: bash, bash_output
-- **Search**: search (unified text/file search)
-- **Task Management**: create_todo_list, update_todo_list
-- **User Interaction**: ask_user
-- **Agent Delegation**: ax_agent
-- **Design Tools**: figma_map, figma_tokens, figma_audit, figma_search, figma_alias_list, figma_alias_resolve
-
-#### Result Enhancer Features
-
-- **Malware Detection**: Warns about potentially malicious code patterns
-- **Sensitive Data Detection**: Identifies exposed credentials, API keys, tokens
-- **Failure Guidance**: Provides contextual help when tools fail
-- **Format Reminders**: Handles truncated output and long lines
-
-#### Benefits
-
-- **Better LLM Behavior**: Rich descriptions guide correct tool usage
-- **Reduced Errors**: Anti-patterns and constraints prevent common mistakes
-- **Easier Maintenance**: Single source of truth for all tool metadata
-- **Token Cost Tracking**: Each tool has estimated token cost for budget planning
-
-## Previous Changes (v3.15.26)
-
-### Command Separation Clarification
-
-- **`ax-cli setup`**: Handles user-level API configuration (provider, API key, model) - stored in `~/.ax-cli/config.json`
-- **`/init` in interactive mode**: Initializes the current project - stored in `.ax-cli/`
-
-## Previous Changes (v3.15.25)
-
-### UI Improvements
-
-- **Status bar agent roles**: The status bar now shows agent roles (e.g., "CTO", "Backend", "Architect") instead of agent names (e.g., "tony", "bob", "avery") for better clarity
-
-## Previous Changes (v3.15.24)
-
-### Enhancements
-
-- **Parallel agent invocation**: Updated `ax_agent` tool description to instruct LLM to invoke multiple agents in parallel when user requests collaboration with multiple agents
-
-## Previous Changes (v3.15.23)
-
-### Bug Fixes
-
-- **Flaky test fix**: Fixed timing-sensitive mutex duration test that occasionally failed due to timer precision issues
-
-## Previous Changes (v3.15.22)
-
-### Codebase Cleanup
-
-- **Removed analyzer modules**: Removed deprecated code analyzer modules (architecture, AST, best practices, code smells, dependency, git, metrics, security) that were no longer maintained
-- **Removed analysis tools**: Removed associated analysis tools (architecture-tool, validation-tool) and types
-- **Cleaned up tests**: Removed corresponding test files for deleted modules
-
-## Previous Changes (v3.15.21)
-
-### Bug Fixes
-
-- **Node.js deprecation fix**: Removed `shell: true` from spawn() to avoid DEP0190 deprecation warning
-- **Tool description cleanup**: Removed stale references to deleted static tools in `ax_agent` description
-
-## Previous Changes (v3.15.20)
-
-### AutomatosX Agent Integration
-
-This release adds first-class support for invoking AutomatosX AI agents directly from ax-cli:
-
-- **New `ax_agent` tool**: Invoke AI agents (Tony, Bob, Avery, Stan, etc.) for collaborative analysis
-- **Agent routing rules**: System prompt now routes agent-related requests to the `ax_agent` tool
-- **Removed orphaned static tools**: `analyze_architecture` and `validate_best_practices` removed (backend deleted)
-
-### Bug Fixes
-
-- **Race condition fix**: Fixed double-resolution bug in `ax-agent.ts` timeout handling
-- **AGENTS.md cleanup**: Removed 4x duplicate content, updated stale agent names (`backend`→`bob`, etc.)
-
-### Documentation Updates
-
-- Updated AGENTS.md with correct agent names and added missing agents (tony, avery)
-- Updated prompts.yaml with agent invocation routing rules
-
-## Previous Changes (v3.15.19)
-
-### Enhanced Setup Wizard UI
-
-This release modernizes the `ax setup` command with a beautiful wizard-style interface using `@clack/prompts`, matching the visual style of `ax init`:
-
-- **Modern prompts**: Replaced `enquirer` with `@clack/prompts` for consistent styling
-- **Visual progress**: Added step indicators (Step 1/5, Step 2/5, etc.)
-- **Spinners**: Added loading spinners for validation and configuration steps
-- **Information boxes**: Added styled note boxes for configuration summaries
-- **Better UX**: Improved visual hierarchy with intro/outro screens
-
-The setup wizard now provides a polished, professional experience when configuring your AI provider credentials.
-
-## Previous Changes (v3.15.18)
-
-### Command Separation Fix
-
-This release fixes the command flow separation between `ax setup` and `ax init`:
-
-- **`ax setup`**: Handles user-level API configuration (provider, API key, model) - stored in `~/.ax-cli/config.json`
-- **`ax init`** / **`/init`**: Handles project-level initialization (CUSTOM.md, index.json) - stored in `.ax-cli/`
-
-Previously, running `ax init` would also prompt for API configuration, which was redundant with `ax setup`. Now the init command focuses solely on project initialization.
-
-**Recommended workflow:**
-1. Run `ax setup` once to configure your API credentials
-2. Run `ax-cli` to start interactive mode
-3. Use `/init` inside interactive mode to initialize your project
-
-## Previous Changes (v3.15.17)
-
-### Node.js 24 Compatibility (Comprehensive Review)
-
-This release ensures full Node.js 24 compatibility across all modules:
-
-- **Updated `@ax-cli/schemas` package**: Engines updated from `>=20.0.0` to `>=24.0.0`
-- **Updated `@types/node`** in schemas package to `^24.0.0`
-- **Verified all native modules**: fsevents, rollup bindings all compatible with Node 24 ABI
-- **Full test suite passing**: 2423 tests pass on Node 24.11.1
-
-### Node.js 24 Requirements Summary
-
-| Component | Node Requirement |
-|-----------|------------------|
-| ax-cli (main) | `>=24.0.0` |
-| @ax-cli/schemas | `>=24.0.0` |
-| CI Workflows | Node 24.x |
-| .nvmrc | 24 |
-
-## Previous Changes (v3.15.16)
-
-### Runtime Health & DX Improvements (CTO/Bob suggestions)
-
-- **Added `.nvmrc` file**: Pins Node.js version to 24 for consistent development environment
-- **Enhanced `ax-cli doctor` command** with new checks:
-  - **Native Module ABI Check**: Detects NODE_MODULE_VERSION mismatches (e.g., better-sqlite3 compiled for wrong Node.js version) and provides rebuild instructions
-  - **File System Permission Check**: Validates read/write access to config directories (~/.ax-cli, ~/.automatosx) and provides fix suggestions for EPERM errors
-- **Actionable error messages**: Doctor command now provides specific remediation steps for common issues
-
-### Usage
-
-Run `ax-cli doctor` to check for:
-- Node.js version compatibility
-- API configuration validity
-- MCP server status
-- Native module ABI compatibility
-- Directory permission issues
-
-## Previous Changes (v3.15.15)
-
-### Code Quality Improvements
-
-- **Extracted reusable helper functions** in status-bar.tsx: `getEffectiveVerbosityLevel()`, `combineActiveAgents()`, `getContextColor()`, and `AXIndicator` component to reduce code duplication
-- **Simplified subagent state management** in chat-interface.tsx: Using modern `Array.toSpliced()` for cleaner immutable array updates
-- **Cleaner event forwarding** in llm-agent.ts: Using event mapping table instead of repetitive handlers
-
-## Previous Changes (v3.15.14)
-
-### Setup Improvements
-
-- **Agent-First Mode Configuration in Setup**: Running `ax-cli setup` now prompts users to enable/disable agent-first mode when AutomatosX is available. The default is disabled, giving users explicit control over whether tasks are automatically routed to specialized agents.
-
-## Previous Changes (v3.15.13)
-
-### Behavior Change
-
-- **Agent-First Mode Disabled by Default**: The automatic agent routing is now disabled by default. Users will use the direct LLM unless they explicitly request an agent (e.g., via `--agent` flag or by enabling agent-first mode in settings). This gives users more control over when specialized agents are used.
-
-To enable agent-first mode, add to your settings:
-```json
-{
-  "agentFirst": {
-    "enabled": true
-  }
-}
-```
-
-## Previous Changes (v3.15.12)
-
-### UI Improvements
-
-- **Multiple Active Agents Display**: Status bar now shows all concurrently running agents (e.g., `⚡ testing, documentation, analysis`) instead of just one. Agents disappear individually as they complete their tasks.
-- **AX Indicator Repositioned**: Moved the `⚡ ax` indicator to the center section, right after the AI model name, for better visibility.
-
-### Technical Changes
-
-- Added `activeAgents` prop to StatusBar component for tracking multiple concurrent agents
-- LLMAgent now forwards subagent lifecycle events (`subagent:spawn`, `subagent:complete`, `subagent:terminate`) from SubagentOrchestrator
-- Chat interface tracks active agents state and updates UI in real-time
-
-## Previous Changes (v3.15.11)
-
-### Bug Fixes
-
-- **Figma Token remBase NaN Handling**: Fixed issue where invalid `--rem-base` values (e.g., non-numeric input) could cause NaN output in design token conversion. Now properly validates and falls back to default value of 16.
-
-### Performance Improvements
-
-- **Deep Clone Optimization**: Replaced `JSON.parse(JSON.stringify())` with native `structuredClone()` for ~2x faster object cloning in MCP config handling and checkpoint creation.
-- **String Case Conversion Caching**: Pre-compute `toLowerCase()` and `toUpperCase()` outside hot-path callbacks in Figma node search operations.
-- **RegExp Pre-compilation**: Pre-compile positional argument patterns (`$1`-`$10`) in custom commands to avoid creating 10 new RegExp objects on every command execution.
-
-## Previous Changes (v3.15.10)
-
-### Improvements
-
-- **Setup Refreshes MCP Servers**: Running `ax-cli setup` now removes and re-adds Z.AI MCP servers to ensure configuration is always up-to-date with latest headers and settings.
-
-## Previous Changes (v3.15.9)
-
-### Bug Fixes
-
-- **Z.AI MCP HTTP Headers**: Fixed Z.AI MCP servers (web-search, web-reader) failing to connect due to missing required HTTP headers. Added `Accept: application/json, text/event-stream` and `Content-Type: application/json` headers required by Z.AI's MCP endpoints.
-
-## Previous Changes (v3.15.8)
-
-### Improvements
-
-- **MCP Client Refactoring**: Improved code quality in MCP client with extracted helper methods (`toError`, `_setFailedState`) to reduce duplication and improve maintainability.
-- **Bash Tool Cleanup**: Extracted `expandHomePath` method for better path expansion handling. Moved `escapeShellArg` to input-sanitizer.ts for improved cross-platform support.
-- **File Cache Optimization**: Simplified file caching logic with cleaner error handling.
-- **Code Quality**: General codebase cleanup with reduced code duplication (-48 lines net reduction).
-
-## Previous Changes (v3.15.7)
-
-### Bug Fixes
-
-- **MCP Tools Timing Fix**: Fixed critical timing issue where MCP tools weren't included in the system prompt because the prompt was built before MCP servers finished initializing. Now the system prompt is updated after MCP initialization completes, ensuring the LLM knows about web search and other MCP capabilities.
-
-## Previous Changes (v3.15.6)
-
-### Improvements
-
-- **MCP Tools in System Prompt**: The LLM now knows about available MCP tools (webSearchPrime, webReader) through the system prompt. This enables agents to use web search and URL fetching capabilities when configured.
-- **Flaky Test Fix**: Fixed timing-sensitive test that occasionally failed due to timer precision.
-
-## Previous Changes (v3.15.5)
-
-### Bug Fixes
-
-- **MCP Parallel Initialization**: Fixed MCP server initialization blocking issue. Servers now initialize in parallel using `Promise.allSettled()`, so slow/failing servers don't block others.
-- **Stdio Transport Startup Timeout**: Added configurable startup timeout (default 30s) to `ContentLengthStdioTransport` to prevent hanging on slow `npx` commands.
-- **Improved Error Handling**: Failed MCP servers are logged but don't prevent successful servers from registering their tools.
-
-These fixes ensure Z.AI web search and web reader MCP tools are reliably available even when other MCP servers (like zai-vision) fail to initialize.
-
-## Previous Changes (v3.15.4)
-
-### Maintenance
-
-- **Version Bump**: General maintenance release with internal improvements
-
-## Previous Changes (v3.15.3)
-
-### Bug Fixes
-
-- **Z.AI MCP HTTP Transport Fix**: Fixed critical bug where Z.AI web search and web reader MCP servers couldn't connect due to missing `Accept` header. The MCP Streamable HTTP transport now correctly sets `Accept: application/json, text/event-stream` as required by the MCP specification.
-
-## Previous Changes (v3.15.2)
-
-### Bug Fixes
-
-- **Z.AI Vision Timeout Fix**: Fixed MCP timeout issue where existing `zai-vision` configs were using the default 60s timeout instead of the required 120s. Now auto-applies the correct timeout for Z.AI Vision servers.
-- **Z.AI Vision Quiet Mode Fix**: Fixed INFO log messages still appearing despite quiet mode. Now auto-applies `quiet: true` for Z.AI Vision servers to suppress console output.
-
-These fixes are backward-compatible - existing users don't need to re-run setup; the defaults are applied automatically when loading configs.
-
-## Previous Changes (v3.15.1)
-
-### Improvements
-
-- **MCP Init Timeout Configuration**: Added `initTimeout` option for MCP server initialization (separate from tool call timeout). Useful for servers that need longer startup time (e.g., npx-based servers that download packages).
-- **Z.AI Vision MCP Quiet Mode**: Suppressed INFO/DEBUG logs and npm warnings from Z.AI Vision MCP server for cleaner console output.
-
-## Previous Changes (v3.15.0)
-
-### New Features
-
-- **MCP Progress Tracking**: Support for `notifications/progress` to track long-running MCP operations with real-time progress updates
-- **MCP Cancellation Support**: Full cancellation support via `notifications/cancelled` to abort long-running operations
-- **MCP Resource Subscriptions**: Subscribe to resource changes with `resources/subscribe` and `resources/unsubscribe`
-- **MCP Output Schema Validation**: Automatic validation of tool outputs against JSON Schema definitions
-- **Figma MCP Template Update**: Switched to community `mcp-figma` package for better compatibility
-
-### Bug Fixes
-
-- **Non-Interactive Environment Fix**: Setup wizard now gracefully handles non-interactive environments (CI/tests)
-- **AutomatosX Auto-Update**: `ax-cli update` now automatically updates AutomatosX after successful ax-cli update
-
-## Previous Changes (v3.14.15)
-
-### New Features
-
-- **AutomatosX Integration in Setup**: Setup wizard now detects AutomatosX and offers to update (if installed) or install (if not) for multi-agent AI orchestration with persistent memory.
-
-## Previous Changes (v3.14.14)
-
-### Bug Fixes
-
-- **MCP SDK HTTP Transport Integration**: Replaced custom HTTP transport with MCP SDK's official `StreamableHTTPClientTransport` for proper MCP protocol support. This enables Z.AI MCP servers (web-search, web-reader, vision) to connect and work correctly.
-- **MCP SSE Transport Update**: Updated SSE transport to use MCP SDK's official `SSEClientTransport` for better compatibility.
-
-## Previous Changes (v3.14.13)
-
-### Bug Fixes
-
-- **Z.AI MCP HTTP Transport Fix**: Fixed HTTP transport to post directly to the endpoint URL instead of appending `/rpc`. This enables Z.AI MCP servers (web-search, web-reader) to connect properly.
-- **MCP Health Check Removed**: Removed unnecessary HTTP health check that was failing for MCP endpoints without `/health` endpoints.
-
-## Previous Changes (v3.14.12)
-
-### Bug Fixes
-
-- **MCP Setup Hang Fix**: Fixed critical issue where `ax-cli setup` would hang indefinitely after enabling Z.AI MCP servers. The setup was incorrectly connecting to MCP servers (spawning long-running processes) instead of just saving the configuration.
-
-## Previous Changes (v3.14.11)
-
-### Bug Fixes
-
-- **Settings Save Fix**: Fixed issue where `ax-cli setup` would fail with "Cannot save settings: failed to decrypt existing API key" when the existing encrypted API key was corrupted or undecryptable. Now correctly uses the new API key provided by the user instead of failing.
-- **History Navigation Fix**: Fixed state management bug in input history where pressing down arrow at the last history item didn't properly reset the navigation state.
-- **Non-null Assertion Fixes**: Removed unsafe non-null assertions in `figma-map.ts` and `image-handler.ts` with proper null-safe alternatives.
-- **Type Safety Improvements**: Fixed TypeScript type errors and removed unused variable warnings across multiple files.
-
-## Previous Changes (v3.14.10)
-
-### Security Fix
-
-- **MCP SDK Update**: Updated `@modelcontextprotocol/sdk` from 1.22.0 to 1.24.0 to fix DNS rebinding protection vulnerability (GHSA-w48q-cv73-mx4w)
-
-## Previous Changes (v3.14.9)
-
-### AST Parser Simplification
-
-- **Removed tree-sitter Dependency**: Simplified AST parsing to focus on TypeScript/JavaScript via ts-morph, reducing dependencies and complexity
-- **Extended Language Detection**: Added file extension detection for Java, Ruby, PHP, Kotlin, Dart, C#, JSON, YAML, and TOML
-
-### Checkpoint System Improvements
-
-- **File Integrity Verification**: Added hash verification before restoring checkpoint files to detect corruption
-- **Configuration Validation**: Improved validation for `pruneAfterDays` and `compressAfterDays` settings
-- **Error Isolation**: Maintenance operations now continue even if individual stages fail
-
-## Previous Changes (v3.14.8)
-
-### CI/CD Improvements
-
-- **NPM Publish Fix**: Added `--tag latest` to npm publish command to support version rollbacks in CI/CD
-
-## Previous Changes (v3.14.7)
-
-### Code Refactoring
-
-- **Image Handler Optimization**: Consolidated duplicate regex patterns, reducing from 6 to 3 patterns with `lastIndex` reset for quick checks
-- **Simplified Message Builder**: Streamlined `buildMessageContent` function with direct `push()` calls for better readability
-- **Path Security Cleanup**: Simplified path traversal security check with improved readability using `.catch()` pattern
-
-### Bug Fixes
-
-- **Vision Model Max Tokens**: Fixed "Max tokens exceeds limit" error when auto-switching to glm-4.5v for image processing - now automatically clamps max tokens to model limit
-
-## Previous Changes (v3.14.4)
-
-### Improvements
-
-- **Absolute Path Access**: Images from any location (Downloads, Desktop, etc.) now accessible when using absolute paths - security checks only apply to relative paths to prevent traversal attacks
-
-### New Features (v3.14.3)
-
-- **Quoted Path Support**: Image paths with spaces now supported using quotes (`@"path with spaces/image.png"` or `'/path/file name.jpg'`)
-
-### Bug Fixes
-
-- **Image Path Security**: Fixed edge case where root directory as base path incorrectly rejected valid files
-- **Windows Path Support**: Added support for Windows absolute paths (`C:\path`) and UNC paths (`\\server\share`) in direct image input
-- **Error Message Consistency**: Improved error messages to consistently include file path context
-- **Token Constant Consolidation**: Unified `TOKENS_PER_IMAGE` to use single source of truth from configuration
-
----
-
-## Previous Changes (v3.14.1)
-
-### New Features
-
-- **Image/Multimodal Support**: Send images directly in chat messages with automatic vision model switching (glm-4.5v)
-- **Image Processing**: Support for PNG, JPG, JPEG, GIF, and WebP formats up to 10MB
-- **Terminal Title**: Shows "ax-cli" instead of "node" in VS Code terminal
-
-### Improvements
-
-- **Token Counting**: Enhanced token estimation for multimodal messages
-- **Chat Display**: Images shown as `[Image attached]` in chat history
-
----
-
-## Previous Changes (v3.14.0)
-
-### New Features
-
-- **Z.AI MCP Auto-Detection**: Automatic detection and template suggestion for Z.AI's native MCP servers including Context7, Puppeteer, Memory, Filesystem, Exa, and PostgreSQL
-- **Enhanced MCP Templates**: Updated MCP template system with Z.AI-optimized configurations
-- **Improved Setup Flow**: Streamlined setup wizard with better provider detection
-
-### SDK Updates (v1.3.0)
-
-- **New Export**: `getMCPConnectionStatus()` returns `{ connected, failed, connecting, total }` for MCP server status monitoring
-
----
-
-## Previous Changes (v3.13.0)
-
-### New Features
-
-- **MCP Status Indicator**: Status bar now shows MCP connection status with color coding (`mcp: ✓ 2/2` green, `mcp: ◐ 1/2` yellow/connecting, `mcp: ✗ 1/2` red/failed)
-- **Enhanced MCP Error Messages**: Comprehensive error remediation for 20+ error codes including network errors (ECONNREFUSED, ETIMEDOUT), SSL errors, HTTP status codes (401, 403, 500), and MCP-specific errors with actionable troubleshooting steps
-
----
-
-## Previous Changes (v3.12.10)
-
-### Bug Fixes
-
-- **Fixed parseInt NaN bug**: Git churn calculator now properly handles binary file stats (shown as `-` in git output) by defaulting to 0 instead of NaN.
-- **Code quality improvements**: Multiple refactoring passes to improve readability, reduce duplication, and optimize performance across UI components and core modules.
-
----
-
-## Previous Changes (v3.12.8)
-
-### Bug Fixes
-
-- **Fixed `/doctor` color display**: The `/doctor` command inside the CLI now shows proper colors - passing checks display with ✅ green checkmarks instead of red text. Fixed by disabling ANSI codes in subprocess output and converting to emoji indicators.
-
----
-
-## Previous Changes (v3.12.7)
-
-### New Features
-
-- **VS Code File Reveal**: Files automatically open in VS Code after creation or modification, similar to Claude Code's IDE integration. Newly created files also appear in the Explorer panel.
-- **File Organization Guidelines**: Added comprehensive prompt instructions for standardized file output paths (`automatosx/tmp/`, `automatosx/PRD/`, `automatosx/REPORT/`).
-
-### VS Code Extension (v0.3.2)
-
-- Added `file_reveal` IPC message type for automatic file display
-- Files open in preview mode by default after write operations
-- New files are revealed in VS Code Explorer
-
----
-
-## Previous Changes (v3.12.6)
-
-### New Features
-
-- **Rolling Tool Display**: Implements Claude Code-style rolling display for consecutive tool operations. When there are more than 5 consecutive tool calls, older entries are collapsed with a "... X more (ctrl+o to expand)" summary, keeping the UI clean and focused on recent activity.
-
-### Configuration
-
-- **`max_visible_tool_lines`**: New UI setting (default: 5) to control how many consecutive tool operations are visible before older ones are rolled up.
-
----
-
-## Previous Changes (v3.12.5)
-
-### Bug Fixes
-
-- **Fixed `[INFO]` logging pollution**: Analyzer log messages no longer appear in CLI output. Set `DEBUG=1` to enable verbose logging.
-- **Fixed `ask_user` tool**: Implemented complete interactive question dialog system with EventEmitter pattern, multi-question flow support, and graceful fallback in non-TTY mode.
+## Recent Changes (v3.12.8)
 
-### New Features
+### Latest Release Highlights
 
-- **QuestionDialog UI Component**: New interactive dialog for AI to ask clarifying questions during task execution
-- **Multi-question support**: Ask multiple questions with progress indicators (e.g., "1/3")
-- **Custom input option**: Users can select "Other" to provide free-text responses
+- **Enhanced MCP Integration**: Improved template system with 12+ production-ready servers
+- **Performance Optimizations**: 50% token savings with intelligent project memory caching
+- **Security Updates**: Enhanced API key encryption with PBKDF2 key derivation (600,000 iterations)
+- **UI Improvements**: New color theme system with 5 built-in themes
+- **Bug Fixes**: Resolved data mutation vulnerabilities in SDK components
 
-### Technical Improvements
+### Key Features Added
 
-- Refactored `AskUserService` to use EventEmitter pattern (consistent with `ConfirmationService`)
-- Added 13 new tests for question dialog functionality
-- Improved code quality and test coverage
+- **Figma Integration**: Complete design-to-code workflow with natural language commands
+- **Multi-Phase Planner**: Automatic task decomposition for complex requests
+- **Background Tasks**: Run long-running operations in background with task management
+- **Health Check**: Comprehensive diagnostics with `ax-cli doctor` command
+- **Auto-Update**: Automatic update checking with user confirmation prompts
 
 ---
 
@@ -1030,6 +574,7 @@ These fixes are backward-compatible - existing users don't need to re-run setup;
 | [Configuration](docs/configuration.md) | Configuration options |
 | [Usage](docs/usage.md) | Comprehensive usage guide |
 | [CLI Reference](docs/cli-reference.md) | Command-line reference |
+| [VSCode Integration](docs/vscode-integration-guide.md) | VSCode extension & terminal setup |
 | [MCP Integration](docs/mcp.md) | Model Context Protocol guide |
 | [Figma Integration](docs/figma-guide.md) | Design-to-code workflow with Figma |
 | [Architecture](docs/architecture.md) | Technical architecture |