feat: enhance docs with AI agent selection and improved getting started

- Add AI agent selection page with visual cards and logos
- Create dedicated setup guides for Cursor, Claude Code, and CLI
- Move Windows-specific MCP config from README to docs
- Enhance quick-start page with agent selection flow
- Improve user experience with clear visual hierarchy

Co-authored-by: Ralph Khreish <Crunchyman-ralph@users.noreply.github.com>

.changeset/chore-fix-docs.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Improve `analyze-complexity` cli docs and `--research` flag documentation

.changeset/curvy-weeks-flow.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Change parent task back to "pending" when all subtasks are in "pending" state

.changeset/mcp-timeout-configuration.md

@@ -1,13 +0,0 @@
----
-"task-master-ai": minor
----
-
-Enhanced Roo Code profile with MCP timeout configuration for improved reliability during long-running AI operations. The Roo profile now automatically configures a 300-second timeout for MCP server operations, preventing timeouts during complex tasks like `parse-prd`, `expand-all`, `analyze-complexity`, and `research` operations. This change also replaces static MCP configuration files with programmatic generation for better maintainability.
-
-**What's New:**
-- 300-second timeout for MCP operations (up from default 60 seconds)
-- Programmatic MCP configuration generation (replaces static asset files)
-- Enhanced reliability for AI-powered operations
-- Consistent with other AI coding assistant profiles
-
-**Migration:** No user action required - existing Roo Code installations will automatically receive the enhanced MCP configuration on next initialization.

.changeset/petite-ideas-grab.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Fix Claude Code settings validation for pathToClaudeCodeExecutable

.changeset/silly-pandas-find.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Fix sonar deep research model failing, should be called `sonar-deep-research`

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
       - main
       - next
   pull_request:
+    branches:
+      - main
+      - next
   workflow_dispatch:
 
 concurrency:

.taskmaster/CLAUDE.md

@@ -102,6 +102,35 @@ Task Master provides an MCP server that Claude Code can connect to. Configure in
 }
 ```
 
+For Windows users without WSL, use this configuration instead:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "cmd",
+      "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your_key_here",
+        "PERPLEXITY_API_KEY": "your_key_here",
+        "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
+        "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
+        "XAI_API_KEY": "XAI_API_KEY_HERE",
+        "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
+        "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
+        "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
+        "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Or install at the project level with Claude Code:
+```bash
+claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+```
+
 ### Essential MCP Tools
 
 ```javascript

CHANGELOG.md

@@ -1,5 +1,12 @@
 # task-master-ai
 
+## 0.27.3
+
+### Patch Changes
+
+- [#1254](https://github.com/eyaltoledano/claude-task-master/pull/1254) [`af53525`](https://github.com/eyaltoledano/claude-task-master/commit/af53525cbc660a595b67d4bb90d906911c71f45d) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Fixed issue where `tm show` command could not find subtasks using dotted notation IDs (e.g., '8.1').
+  - The command now properly searches within parent task subtasks and returns the correct subtask information.
+
 ## 0.27.2
 
 ### Patch Changes

README.md

@@ -60,19 +60,6 @@ The following documentation is also available in the `docs` directory:
 
 > **Note:** After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.
 
-#### Claude Code Quick Install
-
-For Claude Code users:
-
-```bash
-claude mcp add taskmaster-ai -- npx -y task-master-ai
-```
-
-Don't forget to add your API keys to the configuration:
-- in the root .env of your Project
-- in the "env" section of your mcp config for taskmaster-ai
-
-
 ## Requirements
 
 Taskmaster utilizes AI across several commands, and those require a separate API key. You can use a variety of models from different AI providers provided you add your API keys. For example, if you want to use Claude 3.7, you'll need an Anthropic API key.
@@ -105,11 +92,10 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 |              | Project | `<project_folder>/.cursor/mcp.json`   | `<project_folder>\.cursor\mcp.json`               | `mcpServers` |
 | **Windsurf** | Global  | `~/.codeium/windsurf/mcp_config.json` | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` | `mcpServers` |
 | **VS Code**  | Project | `<project_folder>/.vscode/mcp.json`   | `<project_folder>\.vscode\mcp.json`               | `servers`    |
-| **Q CLI**    | Global  | `~/.aws/amazonq/mcp.json`             |                                                   | `mcpServers` |
 
 ##### Manual Configuration
 
-###### Cursor & Windsurf & Q Developer CLI (`mcpServers`)
+###### Cursor & Windsurf (`mcpServers`)
 
 ```json
 {
@@ -138,6 +124,7 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 
 > **Note**: If you see `0 tools enabled` in the MCP settings, restart your editor and check that your API keys are correctly configured.
 
+
 ###### VS Code (`servers` + `type`)
 
 ```json

apps/docs/README.md

@@ -1,24 +1,22 @@
 # Task Master Documentation
 
-Welcome to the Task Master documentation. This documentation site provides comprehensive guides for getting started with Task Master.
+Welcome to the Task Master documentation. Use the links below to navigate to the information you need:
 
 ## Getting Started
 
-- [Quick Start Guide](/getting-started/quick-start) - Complete setup and first-time usage guide
-- [Requirements](/getting-started/quick-start/requirements) - What you need to get started
-- [Installation](/getting-started/quick-start/installation) - How to install Task Master
+- [Configuration Guide](archive/configuration.md) - Set up environment variables and customize Task Master
+- [Tutorial](archive/ctutorial.md) - Step-by-step guide to getting started with Task Master
 
-## Core Capabilities
+## Reference
 
-- [MCP Tools](/capabilities/mcp) - Model Control Protocol integration
-- [CLI Commands](/capabilities/cli-root-commands) - Command line interface reference
-- [Task Structure](/capabilities/task-structure) - Understanding tasks and subtasks
+- [Command Reference](archive/ccommand-reference.md) - Complete list of all available commands
+- [Task Structure](archive/ctask-structure.md) - Understanding the task format and features
 
-## Best Practices
+## Examples & Licensing
 
-- [Advanced Configuration](/best-practices/configuration-advanced) - Detailed configuration options
-- [Advanced Tasks](/best-practices/advanced-tasks) - Working with complex task structures
+- [Example Interactions](archive/cexamples.md) - Common Cursor AI interaction examples
+- [Licensing Information](archive/clicensing.md) - Detailed information about the license
 
 ## Need More Help?
 
-If you can't find what you're looking for in these docs, please check the root README.md or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).
+If you can't find what you're looking for in these docs, please check the [main README](../README.md) or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).

apps/docs/capabilities/cli-root-commands.mdx

@@ -156,7 +156,7 @@ sidebarTitle: "CLI Commands"
     # Use an alternative tasks file
     task-master analyze-complexity --file=custom-tasks.json
 
-    # Use your configured research model for research-backed complexity analysis
+    # Use Perplexity AI for research-backed complexity analysis
     task-master analyze-complexity --research
     ```
   </Accordion>

apps/docs/getting-started/agents/claude-code.mdx

@@ -0,0 +1,275 @@
+---
+title: Claude Code Setup  
+sidebarTitle: "Claude Code"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/claude-logo.svg" className="w-12 h-12" alt="Claude Code" />
+  <div>
+    <h1 className="text-2xl font-bold">Claude Code</h1>
+    <p className="text-gray-600">Anthropic's official CLI for Claude</p>
+  </div>
+</div>
+
+Claude Code offers the smoothest Task Master experience with **zero API key setup** and direct Claude integration.
+
+## 🎯 Why Choose Claude Code?
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
+  <div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800">
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200 mb-2">🔓 No API Keys</h3>
+    <p className="text-sm text-blue-700 dark:text-blue-300">Uses your existing Claude subscription - no separate API setup needed</p>
+  </div>
+  <div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+    <h3 className="font-semibold text-green-800 dark:text-green-200 mb-2">⚡ Native Integration</h3>
+    <p className="text-sm text-green-700 dark:text-green-300">Built specifically for Claude - seamless Task Master experience</p>
+  </div>
+</div>
+
+## 📦 Installation
+
+### Step 1: Install Claude Code
+
+Follow the [official Claude Code installation guide](https://docs.anthropic.com/en/docs/claude-code) or use our quick setup:
+
+<Tabs>
+  <Tab title="macOS">
+    ```bash
+    # Install via Homebrew (recommended)
+    brew install claude-code
+    
+    # Or download from GitHub releases
+    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-macos.tar.gz | tar xz
+    sudo mv claude-code /usr/local/bin/
+    ```
+  </Tab>
+  
+  <Tab title="Windows">
+    ```powershell
+    # Download and install from GitHub releases
+    # Visit: https://github.com/anthropics/claude-code/releases/latest
+    # Download: claude-code-windows.exe
+    
+    # Or use winget (if available)
+    winget install Anthropic.ClaudeCode
+    ```
+  </Tab>
+  
+  <Tab title="Linux">
+    ```bash
+    # Download from GitHub releases
+    curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-linux.tar.gz | tar xz
+    sudo mv claude-code /usr/local/bin/
+    
+    # Or install via package manager (if available)
+    sudo apt install claude-code  # Ubuntu/Debian
+    sudo yum install claude-code  # RHEL/CentOS
+    ```
+  </Tab>
+</Tabs>
+
+### Step 2: Authenticate with Claude
+
+```bash
+# Login to your Claude account
+claude auth login
+```
+
+Follow the prompts to authenticate with your Anthropic account.
+
+## 🔧 Task Master Integration
+
+### Method 1: MCP Integration (Recommended)
+
+Add Task Master to your Claude Code MCP configuration:
+
+<Tabs>
+  <Tab title="Global Setup">
+    ```bash
+    # Add Task Master MCP server globally
+    claude mcp add task-master-ai -s global -- npx -y task-master-ai
+    ```
+  </Tab>
+  
+  <Tab title="Project Setup">
+    ```bash
+    # Add for current project only  
+    claude mcp add task-master-ai -s project -- npx -y task-master-ai
+    ```
+  </Tab>
+  
+  <Tab title="Windows">
+    ```bash
+    # Windows-specific command
+    claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+    ```
+  </Tab>
+</Tabs>
+
+### Method 2: Direct CLI Usage
+
+You can also use Task Master commands directly alongside Claude Code:
+
+```bash
+# Initialize Task Master in your project
+npx task-master-ai init
+
+# Use Claude Code for AI interactions
+claude "Help me implement the next task"
+
+# Use Task Master for task management  
+npx task-master-ai next
+npx task-master-ai show 1.2
+```
+
+## 🚀 Getting Started
+
+### 1. Initialize Your Project
+
+In your project directory:
+
+```bash
+# Start Claude Code
+claude
+
+# In the Claude Code chat, initialize Task Master
+Initialize taskmaster-ai in my project
+```
+
+### 2. Configure Models (Optional)
+
+Since Claude Code doesn't need API keys, you can use it as your main model:
+
+```
+Change the main model to claude-code/sonnet
+```
+
+Available Claude Code models:
+- `claude-code/sonnet` - Claude 3.5 Sonnet (recommended)
+- `claude-code/opus` - Claude 3 Opus (for complex tasks)
+
+### 3. Create Your First Tasks
+
+```
+Can you parse my PRD and create tasks for building a todo app?
+```
+
+## 💡 Advanced Configuration
+
+### Hybrid Setup
+
+Use Claude Code as your main model with other APIs for research:
+
+Create `.env` in your project:
+```bash
+# Optional: Add research capabilities
+PERPLEXITY_API_KEY=your_perplexity_key_here
+OPENAI_API_KEY=your_openai_key_here
+```
+
+Then configure models:
+```
+Change the main model to claude-code/sonnet and research model to perplexity-llama-3.1-sonar-large-128k-online
+```
+
+### Multi-Session Workflows
+
+Claude Code excels at parallel development:
+
+```bash
+# Terminal 1: Main development
+cd my-project && claude
+
+# Terminal 2: Testing and validation  
+cd my-project && claude
+
+# Terminal 3: Documentation
+cd my-project && claude
+```
+
+Each session maintains Task Master context while allowing focused work streams.
+
+## 🔍 Troubleshooting
+
+<Accordion title="Claude Code not found">
+- **Check installation**: Run `claude --version` to verify installation
+- **Update PATH**: Ensure Claude Code is in your system PATH
+- **Reinstall**: Try reinstalling Claude Code from scratch
+- **Permissions**: Check file permissions for the claude binary
+</Accordion>
+
+<Accordion title="Authentication issues">
+- **Re-login**: Run `claude auth logout` then `claude auth login`
+- **Check account**: Verify your Anthropic account is active
+- **Network issues**: Check if you're behind a proxy or firewall
+- **Clear cache**: Delete `~/.claude` directory and re-authenticate
+</Accordion>
+
+<Accordion title="MCP server connection fails">
+- **Check Node.js**: Ensure Node.js 16+ is installed
+- **Test manually**: Run `npx task-master-ai` to test the server
+- **Clear MCP cache**: Remove and re-add the MCP server
+- **Check permissions**: Ensure npm can install packages
+</Accordion>
+
+<Accordion title="Task Master commands not working">
+- **Verify MCP**: Run `claude mcp list` to see installed servers
+- **Re-add server**: Remove and re-add the task-master-ai MCP server
+- **Check initialization**: Ensure project is initialized with `Initialize taskmaster-ai`
+- **Review logs**: Check Claude Code logs for error messages
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use headless mode** for automation: `claude -p "What's the next task I should work on?"` gives quick answers without opening the full chat interface.
+</Tip>
+
+<Tip>
+**Create custom commands** using Claude Code's command system for repeated Task Master workflows like "complete task and get next".
+</Tip>
+
+<Tip>
+**Leverage context persistence** - Claude Code maintains conversation history, making it perfect for long-running development sessions.
+</Tip>
+
+## 🎯 Best Practices
+
+### Development Workflow
+
+```bash
+# Morning routine
+claude "Show me today's tasks and priorities"
+
+# During development  
+claude "Help me implement task 2.1"
+claude "Update task 2.1 with implementation notes"
+
+# End of day
+claude "Mark completed tasks as done and show tomorrow's priorities"
+```
+
+### Team Collaboration
+
+```bash
+# Share task status
+claude "Generate a progress report for the team"
+
+# Review dependencies
+claude "Check which tasks are blocked and why"
+
+# Planning sessions
+claude "Analyze complexity of remaining tasks"
+```
+
+---
+
+<div className="bg-purple-50 dark:bg-purple-900/20 p-4 rounded-lg border border-purple-200 dark:border-purple-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-purple-600 dark:text-purple-400 text-lg">🎉</span>
+    <h3 className="font-semibold text-purple-800 dark:text-purple-200">You're all set with Claude Code!</h3>
+  </div>
+  <p className="text-purple-700 dark:text-purple-300">
+    Claude Code offers the most seamless Task Master experience. Ready to create your first project? Check out our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a>.
+  </p>
+</div>

apps/docs/getting-started/agents/cli.mdx

@@ -0,0 +1,373 @@
+---
+title: Command Line Setup
+sidebarTitle: "CLI"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/terminal-logo.svg" className="w-12 h-12" alt="Terminal" />
+  <div>
+    <h1 className="text-2xl font-bold">Command Line Interface</h1>
+    <p className="text-gray-600">Direct CLI usage without IDE integration</p>
+  </div>
+</div>
+
+Use Task Master directly from the command line for maximum flexibility and control.
+
+## 🎯 Why Choose CLI?
+
+<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
+  <div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800">
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200 mb-2">🚀 Maximum Performance</h3>
+    <p className="text-sm text-blue-700 dark:text-blue-300">No IDE overhead - pure command line speed</p>
+  </div>
+  <div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+    <h3 className="font-semibold text-green-800 dark:text-green-200 mb-2">🔧 Full Control</h3>
+    <p className="text-sm text-green-700 dark:text-green-300">Access to all Task Master features and configurations</p>
+  </div>
+  <div className="bg-purple-50 dark:bg-purple-900/20 p-4 rounded-lg border border-purple-200 dark:border-purple-800">
+    <h3 className="font-semibold text-purple-800 dark:text-purple-200 mb-2">📜 Scriptable</h3>
+    <p className="text-sm text-purple-700 dark:text-purple-300">Perfect for automation and CI/CD integration</p>
+  </div>
+  <div className="bg-orange-50 dark:bg-orange-900/20 p-4 rounded-lg border border-orange-200 dark:border-orange-800">
+    <h3 className="font-semibold text-orange-800 dark:text-orange-200 mb-2">🌐 Universal</h3>
+    <p className="text-sm text-orange-700 dark:text-orange-300">Works on any system with Node.js</p>
+  </div>
+</div>
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+
+```bash
+# Install Task Master globally
+npm install -g task-master-ai
+
+# Verify installation
+task-master --version
+```
+
+### Local Installation
+
+```bash
+# Install in your project
+npm install task-master-ai
+
+# Use with npx
+npx task-master-ai --version
+```
+
+## 🔧 Configuration
+
+### Step 1: Set Up API Keys
+
+Create a `.env` file in your project root:
+
+```bash
+# At least one of these is required
+ANTHROPIC_API_KEY=your_anthropic_key_here
+PERPLEXITY_API_KEY=your_perplexity_key_here  # Recommended for research
+OPENAI_API_KEY=your_openai_key_here
+
+# Optional additional providers
+GOOGLE_API_KEY=your_google_key_here
+MISTRAL_API_KEY=your_mistral_key_here
+OPENROUTER_API_KEY=your_openrouter_key_here
+XAI_API_KEY=your_xai_key_here
+```
+
+### Step 2: Configure Models
+
+```bash
+# Interactive model configuration
+task-master models --setup
+
+# Or set specific models
+task-master models --set-main claude-3-5-sonnet-20241022
+task-master models --set-research perplexity-llama-3.1-sonar-large-128k-online
+task-master models --set-fallback gpt-4o-mini
+```
+
+### Step 3: Initialize Your Project
+
+```bash
+# Initialize Task Master in current directory
+task-master init
+
+# Initialize with specific rules
+task-master init --rules cursor,windsurf,vscode
+```
+
+## 🚀 Quick Start Guide
+
+### 1. Create Your PRD
+
+```bash
+# Create a Product Requirements Document
+touch .taskmaster/docs/prd.txt
+
+# Edit with your favorite editor
+nano .taskmaster/docs/prd.txt
+# or
+code .taskmaster/docs/prd.txt
+```
+
+### 2. Generate Tasks
+
+```bash
+# Parse your PRD and create tasks
+task-master parse-prd .taskmaster/docs/prd.txt
+
+# Analyze task complexity
+task-master analyze-complexity --research
+
+# Expand tasks into subtasks
+task-master expand --all --research
+```
+
+### 3. Start Working
+
+```bash
+# See all tasks
+task-master list
+
+# Get next task to work on
+task-master next
+
+# Show specific task details
+task-master show 1.2
+
+# Mark task as in-progress
+task-master set-status --id=1.2 --status=in-progress
+```
+
+## 📋 Essential Commands
+
+### Task Management
+
+```bash
+# List all tasks
+task-master list
+
+# Show specific tasks (comma-separated)
+task-master show 1,2,3
+
+# Get next available task
+task-master next
+
+# Add a new task
+task-master add-task --prompt="Implement user login" --research
+
+# Update task with notes
+task-master update-task --id=1.2 --prompt="Added JWT authentication"
+
+# Update subtask with implementation notes
+task-master update-subtask --id=1.2.1 --prompt="Used bcrypt for password hashing"
+```
+
+### Task Status Management
+
+```bash
+# Mark task as done
+task-master set-status --id=1.2 --status=done
+
+# Mark as in-progress
+task-master set-status --id=1.2 --status=in-progress
+
+# Mark as blocked
+task-master set-status --id=1.2 --status=blocked
+```
+
+### Analysis and Planning
+
+```bash
+# Research latest information
+task-master research "What are the latest React best practices?"
+
+# Analyze project complexity
+task-master analyze-complexity --research
+
+# View complexity report
+task-master complexity-report
+
+# Expand task into subtasks
+task-master expand --id=1.2 --research --force
+```
+
+### Dependencies and Organization
+
+```bash
+# Add task dependency
+task-master add-dependency --id=2.1 --depends-on=1.2
+
+# Move task to different position
+task-master move --from=3 --to=1
+
+# Validate dependencies
+task-master validate-dependencies
+
+# Generate markdown files
+task-master generate
+```
+
+## 🎯 Advanced Usage
+
+### Scripting and Automation
+
+Create shell scripts for common workflows:
+
+```bash
+#!/bin/bash
+# daily-standup.sh
+
+echo "=== Today's Tasks ==="
+task-master next
+
+echo -e "\n=== In Progress ==="
+task-master list | grep "in-progress"
+
+echo -e "\n=== Blocked Tasks ==="
+task-master list | grep "blocked"
+
+echo -e "\n=== Complexity Report ==="
+task-master complexity-report
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/task-validation.yml
+name: Task Validation
+
+on: [push, pull_request]
+
+jobs:
+  validate-tasks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      
+      - name: Install Task Master
+        run: npm install -g task-master-ai
+        
+      - name: Validate task dependencies
+        run: task-master validate-dependencies
+        
+      - name: Generate task report
+        run: task-master complexity-report > task-report.json
+```
+
+### Custom Aliases
+
+Add these to your `.bashrc` or `.zshrc`:
+
+```bash
+# Task Master shortcuts
+alias tm="task-master"
+alias tmn="task-master next"
+alias tml="task-master list"  
+alias tmr="task-master research"
+alias tms="task-master show"
+```
+
+## 🔍 Troubleshooting
+
+<Accordion title="Command not found: task-master">
+**Solutions:**
+- Verify Node.js installation: `node --version`
+- Reinstall globally: `npm install -g task-master-ai`
+- Check npm global path: `npm config get prefix`
+- Use npx if global install fails: `npx task-master-ai`
+</Accordion>
+
+<Accordion title="API key errors">
+**Solutions:**
+- Check `.env` file exists and has correct keys
+- Verify API key format and validity
+- Test with a single API key first
+- Check for typos in environment variable names
+</Accordion>
+
+<Accordion title="Tasks not generating">
+**Solutions:**
+- Verify PRD file exists and has content
+- Check API keys are working: `task-master models`
+- Try with different model: `task-master models --set-main gpt-4o-mini`
+- Add `--research` flag for better results
+</Accordion>
+
+<Accordion title="Permission errors">
+**Solutions:**
+- Use `sudo` for global installs (not recommended)
+- Configure npm to use different directory: `npm config set prefix ~/.local`
+- Use local installation: `npm install task-master-ai`
+- Check file permissions in `.taskmaster` directory
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use `--research` flag** with AI commands for more informed and up-to-date task suggestions based on current best practices.
+</Tip>
+
+<Tip>
+**Create project templates** with pre-configured `.taskmaster` directories for different types of projects (web apps, APIs, mobile apps).
+</Tip>
+
+<Tip>
+**Combine with other tools** like `jq` for parsing JSON outputs: `task-master list --json | jq '.[] | select(.status=="pending")'`
+</Tip>
+
+<Tip>
+**Use environment-specific configs** by creating different `.env` files (.env.development, .env.production) and symlinking as needed.
+</Tip>
+
+## 📚 Integration Examples
+
+### With Git Hooks
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+# Check if any tasks are marked as done
+if task-master list | grep -q "done"; then
+    echo "✅ Tasks completed in this commit:"
+    task-master list | grep "done"
+fi
+```
+
+### With Make
+
+```makefile
+# Makefile
+
+.PHONY: tasks next status
+
+tasks:
+	@task-master list
+
+next:
+	@task-master next
+
+status:
+	@echo "=== Task Status ==="
+	@task-master list | grep -E "(in-progress|blocked)"
+	@echo ""
+	@echo "=== Next Task ==="
+	@task-master next
+```
+
+---
+
+<div className="bg-cyan-50 dark:bg-cyan-900/20 p-4 rounded-lg border border-cyan-200 dark:border-cyan-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-cyan-600 dark:text-cyan-400 text-lg">⚡</span>
+    <h3 className="font-semibold text-cyan-800 dark:text-cyan-200">Ready for maximum productivity!</h3>
+  </div>
+  <p className="text-cyan-700 dark:text-cyan-300">
+    You now have the full power of Task Master at your fingertips. Create your first project with our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a>.
+  </p>
+</div>

apps/docs/getting-started/agents/cursor.mdx

@@ -0,0 +1,247 @@
+---
+title: Cursor Setup
+sidebarTitle: "Cursor"
+---
+
+<div className="flex items-center space-x-4 mb-6">
+  <img src="/logo/cursor-logo.svg" className="w-12 h-12" alt="Cursor" />
+  <div>
+    <h1 className="text-2xl font-bold">Cursor AI Editor</h1>
+    <p className="text-gray-600">AI-powered VS Code fork with built-in MCP support</p>
+  </div>
+</div>
+
+Cursor offers the smoothest Task Master experience with one-click installation and native MCP integration.
+
+## 🚀 One-Click Install (Recommended)
+
+<div className="bg-blue-50 dark:bg-blue-900/20 p-4 rounded-lg border border-blue-200 dark:border-blue-800 mb-6">
+  <div className="flex items-center space-x-2 mb-3">
+    <span className="text-blue-600 dark:text-blue-400 text-lg">⚡</span>
+    <h3 className="font-semibold text-blue-800 dark:text-blue-200">Fastest Setup</h3>
+  </div>
+  
+  <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=task-master-ai&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi0tcGFja2FnZT10YXNrLW1hc3Rlci1haSIsInRhc2stbWFzdGVyLWFpIl0sImVudiI6eyJBTlRIUk9QSUNfQVBJX0tFWSI6IllPVVJfQU5USFJPUElDX0FQSV9LRVlfSEVSRSIsIlBFUlBMRVhJVFlfQVBJX0tFWSI6IllPVVJfUEVSUExFWElUWV9BUElfS0VZX0hFUkUiLCJPUEVOQUlfQVBJX0tFWSI6IllPVVJfT1BFTkFJX0tFWV9IRVJFIiwiR09PR0xFX0FQSV9LRVkiOiJZT1VSX0dPT0dMRV9LRVlfSEVSRSIsIk1JU1RSQUxfQVBJX0tFWSI6IllPVVJfTUlTVFJBTF9LRVlfSEVSRSIsIk9QRU5ST1VURVJfQVBJX0tFWSI6IllPVVJfT1BFTlJPVVRFUl9LRVlfSEVSRSIsIlhBSV9BUElfS0VZIjoiWU9VUl9YQUlfS0VZX0hFUkUiLCJBWlVSRV9PUEVOQUJFX0FQSV9LRVkiOiJZT1VSX0FaVVJFX0tFWV9IRVJFIiwiT0xMQU1BX0FQSV9LRVkiOiJZT1VSX09MTEFNQV9BUElfS0VZX0hFUkUifX0%3D">
+    <img 
+      className="block dark:hidden hover:opacity-80 transition-opacity cursor-pointer" 
+      src="https://cursor.com/deeplink/mcp-install-light.png" 
+      alt="Add Task Master MCP server to Cursor" 
+      noZoom
+    />
+    <img 
+      className="hidden dark:block hover:opacity-80 transition-opacity cursor-pointer" 
+      src="https://cursor.com/deeplink/mcp-install-dark.png" 
+      alt="Add Task Master MCP server to Cursor" 
+      noZoom
+    />
+  </a>
+</div>
+
+<Warning>
+**After one-click install**: You still need to add your actual API keys! The installer uses placeholder keys that must be replaced.
+</Warning>
+
+## 📋 Manual Setup
+
+If you prefer manual configuration or the one-click install doesn't work:
+
+### Step 1: Create MCP Configuration
+
+Choose your configuration scope:
+
+<Tabs>
+  <Tab title="Global Config">
+    Create or edit `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "npx",
+          "args": ["-y", "task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+            "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
+            "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
+            "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
+            "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
+            "XAI_API_KEY": "YOUR_XAI_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  
+  <Tab title="Project Config">
+    Create `.cursor/mcp.json` in your project root:
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "npx",
+          "args": ["-y", "task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  
+  <Tab title="Windows Native">
+    For Windows users without WSL:
+
+    ```json
+    {
+      "mcpServers": {
+        "task-master-ai": {
+          "command": "cmd",
+          "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+          "env": {
+            "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+            "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+            "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+
+    <Note>
+    **Alternative Windows Setup**: Use Claude Code's project-level installation:
+    ```bash
+    claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+    ```
+    </Note>
+  </Tab>
+</Tabs>
+
+### Step 2: Enable MCP Server
+
+1. Open Cursor Settings (`Ctrl+Shift+J` or `Cmd+Shift+J`)
+2. Click the **MCP** tab in the left sidebar
+3. Find `task-master-ai` and toggle it **ON**
+4. Restart Cursor if needed
+
+### Step 3: Verify Installation
+
+In Cursor's chat panel, type:
+```
+help
+```
+
+You should see Task Master commands available. If you see "0 tools enabled", check your API keys and restart Cursor.
+
+## 🔧 Configuration
+
+### Add Your API Keys
+
+<Tabs>
+  <Tab title="Required Keys">
+    You need **at least one** of these:
+    - `ANTHROPIC_API_KEY` - For Claude models (recommended)
+    - `OPENAI_API_KEY` - For GPT models  
+    - `GOOGLE_API_KEY` - For Gemini models
+  </Tab>
+  
+  <Tab title="Recommended Keys">
+    For the best experience, also add:
+    - `PERPLEXITY_API_KEY` - Enables research features
+    - `OPENAI_API_KEY` - Fallback option
+  </Tab>
+  
+  <Tab title="All Supported Keys">
+    Full list of supported API keys:
+    - `ANTHROPIC_API_KEY`
+    - `PERPLEXITY_API_KEY` 
+    - `OPENAI_API_KEY`
+    - `GOOGLE_API_KEY`
+    - `MISTRAL_API_KEY`
+    - `OPENROUTER_API_KEY`
+    - `XAI_API_KEY`
+    - `AZURE_OPENAI_API_KEY`
+    - `OLLAMA_API_KEY`
+  </Tab>
+</Tabs>
+
+### Configure Models (Optional)
+
+In Cursor's chat, set your preferred models:
+
+```
+Change the main, research and fallback models to claude-3-5-sonnet-20241022, perplexity-llama-3.1-sonar-large-128k-online and gpt-4o-mini respectively.
+```
+
+## 🎯 Getting Started
+
+### 1. Initialize Task Master
+
+In Cursor's chat panel:
+```
+Initialize taskmaster-ai in my project
+```
+
+### 2. Create Your First Task
+
+```
+Can you help me implement user authentication for my web app?
+```
+
+### 3. Start Working
+
+```
+What's the next task I should work on?
+```
+
+## 🔍 Troubleshooting
+
+<Accordion title="0 tools enabled in MCP settings">
+- **Check API keys**: Ensure at least one API key is correctly set
+- **Restart Cursor**: Close and reopen Cursor completely  
+- **Check file paths**: Verify your `mcp.json` is in the correct location
+- **Test manually**: Run `npx task-master-ai` in terminal to test
+</Accordion>
+
+<Accordion title="MCP server fails to start">
+- **Update Node.js**: Ensure you have Node.js 16+ installed
+- **Clear npm cache**: Run `npm cache clean --force`
+- **Try global install**: Run `npm install -g task-master-ai`
+- **Check permissions**: Ensure npm has permission to install packages
+</Accordion>
+
+<Accordion title="Commands not working">
+- **Verify installation**: Type `help` in chat to see available commands
+- **Check project initialization**: Run `Initialize taskmaster-ai in my project`
+- **Review logs**: Check Cursor's developer console for error messages
+</Accordion>
+
+## 💡 Pro Tips
+
+<Tip>
+**Use project-specific configs** for different API keys per project, especially when working with team projects that have shared API limits.
+</Tip>
+
+<Tip>
+**Enable research mode** with a Perplexity API key to get AI-powered task suggestions based on the latest best practices.
+</Tip>
+
+<Tip>
+**Set up keyboard shortcuts** in Cursor for common Task Master commands like "What's next?" or "Show task status".
+</Tip>
+
+---
+
+<div className="bg-green-50 dark:bg-green-900/20 p-4 rounded-lg border border-green-200 dark:border-green-800">
+  <div className="flex items-center space-x-2 mb-2">
+    <span className="text-green-600 dark:text-green-400 text-lg">✅</span>
+    <h3 className="font-semibold text-green-800 dark:text-green-200">Ready to go!</h3>
+  </div>
+  <p className="text-green-700 dark:text-green-300">
+    You're all set with Cursor! Head over to our <a href="/getting-started/quick-start/prd-quick" className="underline">PRD guide</a> to create your first project.
+  </p>
+</div>

apps/docs/getting-started/ai-agents.mdx

@@ -0,0 +1,118 @@
+---
+title: Choose Your AI Agent
+sidebarTitle: "AI Agents"
+---
+
+Task Master works seamlessly with various AI agents. Choose your preferred agent to get customized setup instructions.
+
+<CardGroup cols={2}>
+  <Card 
+    title="Cursor" 
+    icon="cursor" 
+    href="/getting-started/agents/cursor"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/cursor-logo.svg" className="w-8 h-8" alt="Cursor" />
+      <span>AI-powered VS Code fork with built-in MCP support</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Claude Code" 
+    icon="claude" 
+    href="/getting-started/agents/claude-code"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/claude-logo.svg" className="w-8 h-8" alt="Claude Code" />
+      <span>Anthropic's official CLI for Claude</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Windsurf" 
+    icon="windsurf" 
+    href="/getting-started/agents/windsurf"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/windsurf-logo.svg" className="w-8 h-8" alt="Windsurf" />
+      <span>Codeium's AI-native IDE</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="VS Code" 
+    icon="vscode" 
+    href="/getting-started/agents/vscode"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/vscode-logo.svg" className="w-8 h-8" alt="VS Code" />
+      <span>Microsoft's editor with MCP extensions</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Command Line" 
+    icon="terminal" 
+    href="/getting-started/agents/cli"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/terminal-logo.svg" className="w-8 h-8" alt="Terminal" />
+      <span>Direct CLI usage without IDE integration</span>
+    </div>
+  </Card>
+
+  <Card 
+    title="Other Agents" 
+    icon="question" 
+    href="/getting-started/agents/other"
+  >
+    <div className="flex items-center space-x-3">
+      <img src="/logo/generic-logo.svg" className="w-8 h-8" alt="Other" />
+      <span>Generic setup for other AI agents</span>
+    </div>
+  </Card>
+</CardGroup>
+
+## Quick Recommendations
+
+<Accordion title="🎯 Which agent should I choose?">
+**For beginners**: Start with **Cursor** - it has the most seamless MCP integration and one-click install.
+
+**For Claude users**: Use **Claude Code** - it's Anthropic's official CLI with no API key required.
+
+**For existing VS Code users**: Stick with **VS Code** if you're already comfortable with your setup.
+
+**For advanced users**: Try **Windsurf** for its AI-native features or use **Command Line** for maximum flexibility.
+</Accordion>
+
+<Accordion title="💡 What's MCP and why does it matter?">
+MCP (Model Control Protocol) allows Task Master to run directly inside your AI agent, giving you:
+- 🔥 **Seamless integration** - No switching between tools
+- ⚡ **Real-time task management** - Tasks update as you work  
+- 🧠 **Context awareness** - Your AI knows about your tasks
+- 🎯 **Smart suggestions** - AI can recommend next tasks
+</Accordion>
+
+## Platform-Specific Notes
+
+<Tabs>
+  <Tab title="Windows">
+    **Important**: Windows users may need special configuration for some agents. We'll provide Windows-specific instructions for each agent.
+    
+    Some agents work better with WSL (Windows Subsystem for Linux), while others have native Windows support.
+  </Tab>
+  
+  <Tab title="macOS">
+    Most agents work seamlessly on macOS. Claude Code and Cursor have the best native macOS integration.
+  </Tab>
+  
+  <Tab title="Linux">
+    All agents have excellent Linux support. Command Line interface works particularly well in Linux environments.
+  </Tab>
+</Tabs>
+
+---
+
+<Note>
+**Need help choosing?** Check our [comparison table](/getting-started/agent-comparison) or join our [Discord community](https://discord.gg/taskmasterai) for personalized recommendations.
+</Note>

apps/docs/getting-started/quick-start/configuration-quick.mdx

@@ -108,5 +108,5 @@ You don’t need to configure everything up front. Most settings can be left as
 </Accordion>
 
 <Note>
-For advanced configuration options and detailed customization, see our [Advanced Configuration Guide](/best-practices/configuration-advanced) page.
+For advanced configuration options and detailed customization, see our [Advanced Configuration Guide](/docs/best-practices/configuration-advanced) page.
 </Note>

apps/docs/getting-started/quick-start/execute-quick.mdx

@@ -56,4 +56,4 @@ If you ran into problems and had to debug errors you can create new rules as you
 
 By now you have all you need to get started executing code faster and smarter with Task Master.
 
-If you have any questions please check out [Frequently Asked Questions](/getting-started/faq)
+If you have any questions please check out [Frequently Asked Questions](/docs/getting-started/faq)

apps/docs/getting-started/quick-start/installation.mdx

@@ -30,19 +30,6 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=taskmaster-ai&config=eyJjb21
 ```
 
 > **Note:** After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.
-
-### Claude Code Quick Install
-
-For Claude Code users:
-
-```bash
-claude mcp add taskmaster-ai -- npx -y task-master-ai
-```
-
-Don't forget to add your API keys to the configuration:
-- in the root .env of your Project
-- in the "env" section of your mcp config for taskmaster-ai
-
 </Accordion>
 ## Installation Options
 
@@ -90,6 +77,36 @@ MCP (Model Control Protocol) lets you run Task Master directly from your editor.
 
 > **Note**: If you see `0 tools enabled` in the MCP settings, restart your editor and check that your API keys are correctly configured.
 
+### Windows-specific Configuration
+
+For Windows users without WSL, you may need to use `cmd` to run the MCP server:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "cmd",
+      "args": ["/c", "npx -y --package=task-master-ai task-master-ai"],
+      "env": {
+        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
+        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
+        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
+        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
+        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
+        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Alternatively, you can install at the project level with Claude Code:
+```bash
+claude mcp add task-master-mcp -s project -- cmd /c "npx -y --package=task-master-ai task-master-ai"
+```
+
 ### VS Code (`servers` + `type`)
 
 ```json

apps/docs/getting-started/quick-start/quick-start.mdx

@@ -5,14 +5,34 @@ sidebarTitle: "Quick Start"
 
 This guide is for new users who want to start using Task Master with minimal setup time.
 
-It covers:
-- [Requirements](/getting-started/quick-start/requirements): You will need Node.js and an AI model API Key.
-- [Installation](/getting-started/quick-start/installation): How to Install Task Master.
-- [Configuration](/getting-started/quick-start/configuration-quick): Setting up your API Key, MCP, and more.
-- [PRD](/getting-started/quick-start/prd-quick): Writing and parsing your first PRD.
-- [Task Setup](/getting-started/quick-start/tasks-quick): Preparing your tasks for execution.
-- [Executing Tasks](/getting-started/quick-start/execute-quick): Using Task Master to execute tasks.
-- [Rules & Context](/getting-started/quick-start/rules-quick): Learn how and why to build context in your project over time.
+## 🎯 Choose Your AI Agent
+
+First, pick your preferred AI development environment:
+
+<CardGroup cols={3}>
+  <Card title="Cursor" icon="cursor" href="/getting-started/agents/cursor">
+    One-click install with native MCP support
+  </Card>
+  <Card title="Claude Code" icon="claude" href="/getting-started/agents/claude-code">
+    No API keys needed - uses your Claude subscription
+  </Card>
+  <Card title="Command Line" icon="terminal" href="/getting-started/agents/cli">
+    Maximum control and scriptability
+  </Card>
+</CardGroup>
+
+[View all AI agents →](/getting-started/ai-agents)
+
+## 📋 Quick Start Steps
+
+After setting up your AI agent, this guide covers:
+- [Requirements](/docs/getting-started/quick-start/requirements): You will need Node.js and an AI model API Key.
+- [Installation](/docs/getting-started/quick-start/installation): How to Install Task Master.
+- [Configuration](/docs/getting-started/quick-start/configuration-quick): Setting up your API Key, MCP, and more.
+- [PRD](/docs/getting-started/quick-start/prd-quick): Writing and parsing your first PRD.
+- [Task Setup](/docs/getting-started/quick-start/tasks-quick): Preparing your tasks for execution.
+- [Executing Tasks](/docs/getting-started/quick-start/execute-quick): Using Task Master to execute tasks.
+- [Rules & Context](/docs/getting-started/quick-start/rules-quick): Learn how and why to build context in your project over time.
 
 <Tip>
 By the end of this guide, you'll have everything you need to begin working productively with Task Master.

apps/docs/getting-started/quick-start/tasks-quick.mdx

@@ -61,25 +61,9 @@ Task Master can provide a complexity report which can be helpful to read before
 Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
 ```
 
-The agent will use the `analyze_project_complexity` MCP tool, or you can run it directly with the CLI command:
-```bash
-task-master analyze-complexity
-```
-
-For more comprehensive analysis using your configured research model, you can use:
-```bash
-task-master analyze-complexity --research
-```
-
-<Tip>
-The `--research` flag uses whatever research model you have configured in `.taskmaster/config.json` (configurable via `task-master models --setup`) for research-backed complexity analysis, providing more informed recommendations.
-</Tip>
-
 You can view the report in a friendly table using:
 ```
 Can you show me the complexity report in a more readable format?
 ```
 
-For more detailed CLI options, see the [Analyze Task Complexity](/capabilities/cli-root-commands#analyze-task-complexity) section.
-
-<Check>Now you are ready to begin [executing tasks](/getting-started/quick-start/execute-quick)</Check>
+<Check>Now you are ready to begin [executing tasks](/docs/getting-started/quick-start/execute-quick)</Check>

apps/docs/introduction.mdx

@@ -4,7 +4,7 @@ Welcome to v1 of the Task Master Docs. Expect weekly updates as we expand and re
 
 We've organized the docs into three sections depending on your experience level and goals:
 
-### Getting Started - Jump in to [Quick Start](/getting-started/quick-start)
+### Getting Started - Jump in to [Quick Start](/docs/getting-started/quick-start)
 Designed for first-time users. Get set up, create your first PRD, and run your first task.
 
 ### Best Practices

apps/extension/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## 0.25.4
+
+### Patch Changes
+
+- Updated dependencies [[`af53525`](https://github.com/eyaltoledano/claude-task-master/commit/af53525cbc660a595b67d4bb90d906911c71f45d)]:
+  - task-master-ai@0.27.3
+
 ## 0.25.3
 
 ### Patch Changes

apps/extension/package.json

@@ -3,7 +3,7 @@
 	"private": true,
 	"displayName": "TaskMaster",
 	"description": "A visual Kanban board interface for TaskMaster projects in VS Code",
-	"version": "0.25.3",
+	"version": "0.25.4",
 	"publisher": "Hamster",
 	"icon": "assets/icon.png",
 	"engines": {
@@ -240,7 +240,7 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"task-master-ai": "0.27.2"
+		"task-master-ai": "0.27.3"
 	},
 	"devDependencies": {
 		"@dnd-kit/core": "^6.3.1",

docs/configuration.md

@@ -235,60 +235,6 @@ node scripts/init.js
    - "MCP provider requires session context" → Ensure running in MCP environment
    - See the [MCP Provider Guide](./mcp-provider-guide.md) for detailed troubleshooting
 
-### MCP Timeout Configuration
-
-Long-running AI operations in taskmaster-ai can exceed the default 60-second MCP timeout. Operations like `parse_prd`, `expand_task`, `research`, and `analyze_project_complexity` may take 2-5 minutes to complete.
-
-#### Adding Timeout Configuration
-
-Add a `timeout` parameter to your MCP configuration to extend the timeout limit. The timeout configuration works identically across MCP clients including Cursor, Windsurf, and RooCode:
-
-```json
-{
-  "mcpServers": {
-    "task-master-ai": {
-      "command": "npx",
-      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
-      "timeout": 300,
-      "env": {
-        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
-      }
-    }
-  }
-}
-```
-
-**Configuration Details:**
-- **`timeout: 300`** - Sets timeout to 300 seconds (5 minutes)
-- **Value range**: 1-3600 seconds (1 second to 1 hour)
-- **Recommended**: 300 seconds provides sufficient time for most AI operations
-- **Format**: Integer value in seconds (not milliseconds)
-
-#### Automatic Setup
-
-When adding taskmaster rules for supported editors, the timeout configuration is automatically included:
-
-```bash
-# Automatically includes timeout configuration
-task-master rules add cursor
-task-master rules add roo
-task-master rules add windsurf
-task-master rules add vscode
-```
-
-#### Troubleshooting Timeouts
-
-If you're still experiencing timeout errors:
-
-1. **Verify configuration**: Check that `timeout: 300` is present in your MCP config
-2. **Restart editor**: Restart your editor after making configuration changes
-3. **Increase timeout**: For very complex operations, try `timeout: 600` (10 minutes)
-4. **Check API keys**: Ensure required API keys are properly configured
-
-**Expected behavior:**
-- **Before fix**: Operations fail after 60 seconds with `MCP request timed out after 60000ms`
-- **After fix**: Operations complete successfully within the configured timeout limit
-
 ### Google Vertex AI Configuration
 
 Google Vertex AI is Google Cloud's enterprise AI platform and requires specific configuration:

docs/models.md

@@ -1,4 +1,4 @@
-# Available Models as of September 23, 2025
+# Available Models as of September 19, 2025
 
 ## Main Models
 
@@ -119,7 +119,7 @@
 | groq        | deepseek-r1-distill-llama-70b                | 0.52      | 0.75       | 0.99        |
 | perplexity  | sonar-pro                                    | —         | 3          | 15          |
 | perplexity  | sonar                                        | —         | 1          | 1           |
-| perplexity  | sonar-deep-research                          | 0.211     | 2          | 8           |
+| perplexity  | deep-research                                | 0.211     | 2          | 8           |
 | perplexity  | sonar-reasoning-pro                          | 0.211     | 2          | 8           |
 | perplexity  | sonar-reasoning                              | 0.211     | 1          | 5           |
 | bedrock     | us.anthropic.claude-3-opus-20240229-v1:0     | 0.725     | 15         | 75          |

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.2",
+	"version": "0.27.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "task-master-ai",
-			"version": "0.27.2",
+			"version": "0.27.3",
 			"license": "MIT WITH Commons-Clause",
 			"workspaces": [
 				"apps/*",
@@ -357,9 +357,9 @@
 			}
 		},
 		"apps/extension": {
-			"version": "0.25.3",
+			"version": "0.25.4",
 			"dependencies": {
-				"task-master-ai": "0.27.2"
+				"task-master-ai": "0.27.3"
 			},
 			"devDependencies": {
 				"@dnd-kit/core": "^6.3.1",

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.2",
+	"version": "0.27.3",
 	"description": "A task management system for ambitious AI-driven development that doesn't overwhelm and confuse Cursor.",
 	"main": "index.js",
 	"type": "module",

packages/tm-core/src/services/task-service.ts

@@ -135,15 +135,28 @@ export class TaskService {
 	}
 
 	/**
-	 * Get a single task by ID
+	 * Get a single task by ID - delegates to storage layer
 	 */
 	async getTask(taskId: string, tag?: string): Promise<Task | null> {
-		const result = await this.getTaskList({
-			tag,
-			includeSubtasks: true
-		});
+		// Use provided tag or get active tag
+		const activeTag = tag || this.getActiveTag();
 
-		return result.tasks.find((t) => t.id === taskId) || null;
+		try {
+			// Delegate to storage layer which handles the specific logic for tasks vs subtasks
+			return await this.storage.loadTask(String(taskId), activeTag);
+		} catch (error) {
+			throw new TaskMasterError(
+				`Failed to get task ${taskId}`,
+				ERROR_CODES.STORAGE_ERROR,
+				{
+					operation: 'getTask',
+					resource: 'task',
+					taskId: String(taskId),
+					tag: activeTag
+				},
+				error as Error
+			);
+		}
 	}
 
 	/**

packages/tm-core/src/storage/file-storage/file-storage.ts

@@ -105,9 +105,65 @@ export class FileStorage implements IStorage {
 
 	/**
 	 * Load a single task by ID from the tasks.json file
+	 * Handles both regular tasks and subtasks (with dotted notation like "1.2")
 	 */
 	async loadTask(taskId: string, tag?: string): Promise<Task | null> {
 		const tasks = await this.loadTasks(tag);
+
+		// Check if this is a subtask (contains a dot)
+		if (taskId.includes('.')) {
+			const [parentId, subtaskId] = taskId.split('.');
+			const parentTask = tasks.find((t) => String(t.id) === parentId);
+
+			if (!parentTask || !parentTask.subtasks) {
+				return null;
+			}
+
+			const subtask = parentTask.subtasks.find(
+				(st) => String(st.id) === subtaskId
+			);
+			if (!subtask) {
+				return null;
+			}
+
+			const toFullSubId = (maybeDotId: string | number): string => {
+				const depId = String(maybeDotId);
+				return depId.includes('.') ? depId : `${parentTask.id}.${depId}`;
+			};
+			const resolvedDependencies =
+				subtask.dependencies?.map((dep) => toFullSubId(dep)) ?? [];
+
+			// Return a Task-like object for the subtask with the full dotted ID
+			// Following the same pattern as findTaskById in utils.js
+			const subtaskResult = {
+				...subtask,
+				id: taskId, // Use the full dotted ID
+				title: subtask.title || `Subtask ${subtaskId}`,
+				description: subtask.description || '',
+				status: subtask.status || 'pending',
+				priority: subtask.priority || parentTask.priority || 'medium',
+				dependencies: resolvedDependencies,
+				details: subtask.details || '',
+				testStrategy: subtask.testStrategy || '',
+				subtasks: [],
+				tags: parentTask.tags || [],
+				assignee: subtask.assignee || parentTask.assignee,
+				complexity: subtask.complexity || parentTask.complexity,
+				createdAt: subtask.createdAt || parentTask.createdAt,
+				updatedAt: subtask.updatedAt || parentTask.updatedAt,
+				// Add reference to parent task for context (like utils.js does)
+				parentTask: {
+					id: parentTask.id,
+					title: parentTask.title,
+					status: parentTask.status
+				},
+				isSubtask: true
+			};
+
+			return subtaskResult;
+		}
+
+		// Handle regular task lookup
 		return tasks.find((task) => String(task.id) === String(taskId)) || null;
 	}
 
@@ -409,11 +465,8 @@ export class FileStorage implements IStorage {
 			const allDone = subs.every(isDoneLike);
 			const anyInProgress = subs.some((s) => norm(s) === 'in-progress');
 			const anyDone = subs.some(isDoneLike);
-			const allPending = subs.every((s) => norm(s) === 'pending');
-
 			if (allDone) parentNewStatus = 'done';
 			else if (anyInProgress || anyDone) parentNewStatus = 'in-progress';
-			else if (allPending) parentNewStatus = 'pending';
 		}
 
 		// Always bump updatedAt; update status only if changed

scripts/modules/commands.js

@@ -1847,7 +1847,7 @@ function registerCommands(programInstance) {
 		)
 		.option(
 			'-r, --research',
-			'Use configured research model for research-backed complexity analysis'
+			'Use Perplexity AI for research-backed complexity analysis'
 		)
 		.option(
 			'-i, --id <ids>',

scripts/modules/config-manager.js

@@ -310,7 +310,6 @@ function validateProviderModelCombination(providerName, modelId) {
 function validateClaudeCodeSettings(settings) {
 	// Define the base settings schema without commandSpecific first
 	const BaseSettingsSchema = z.object({
-		pathToClaudeCodeExecutable: z.string().optional(),
 		maxTurns: z.number().int().positive().optional(),
 		customSystemPrompt: z.string().optional(),
 		appendSystemPrompt: z.string().optional(),

scripts/modules/supported-models.json

@@ -522,7 +522,7 @@
 			"supported": true
 		},
 		{
-			"id": "sonar-deep-research",
+			"id": "deep-research",
 			"swe_score": 0.211,
 			"cost_per_1m_tokens": {
 				"input": 2,

src/profiles/roo.js

@@ -5,40 +5,6 @@ import { isSilentMode, log } from '../../scripts/modules/utils.js';
 import { createProfile, COMMON_TOOL_MAPPINGS } from './base-profile.js';
 import { ROO_MODES } from '../constants/profiles.js';
 
-// Import the shared MCP configuration helper
-import { formatJSONWithTabs } from '../utils/create-mcp-config.js';
-
-// Roo-specific MCP configuration enhancements
-function enhanceRooMCPConfiguration(mcpPath) {
-	if (!fs.existsSync(mcpPath)) {
-		log('warn', `[Roo] MCP configuration file not found at ${mcpPath}`);
-		return;
-	}
-
-	try {
-		// Read the existing configuration
-		const mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-
-		if (mcpConfig.mcpServers && mcpConfig.mcpServers['task-master-ai']) {
-			const server = mcpConfig.mcpServers['task-master-ai'];
-
-			// Add Roo-specific timeout enhancement for long-running AI operations
-			server.timeout = 300;
-
-			// Write the enhanced configuration back
-			fs.writeFileSync(mcpPath, formatJSONWithTabs(mcpConfig) + '\n');
-			log(
-				'debug',
-				`[Roo] Enhanced MCP configuration with timeout at ${mcpPath}`
-			);
-		} else {
-			log('warn', `[Roo] task-master-ai server not found in MCP configuration`);
-		}
-	} catch (error) {
-		log('error', `[Roo] Failed to enhance MCP configuration: ${error.message}`);
-	}
-}
-
 // Lifecycle functions for Roo profile
 function onAddRulesProfile(targetDir, assetsDir) {
 	// Use the provided assets directory to find the roocode directory
@@ -66,9 +32,6 @@ function onAddRulesProfile(targetDir, assetsDir) {
 		}
 	}
 
-	// Note: MCP configuration is now handled by the base profile system
-	// The base profile will call setupMCPConfiguration, and we enhance it in onPostConvert
-
 	for (const mode of ROO_MODES) {
 		const src = path.join(rooModesDir, `rules-${mode}`, `${mode}-rules`);
 		const dest = path.join(targetDir, '.roo', `rules-${mode}`, `${mode}-rules`);
@@ -115,15 +78,6 @@ function onRemoveRulesProfile(targetDir) {
 
 	const rooDir = path.join(targetDir, '.roo');
 	if (fs.existsSync(rooDir)) {
-		// Remove MCP configuration
-		const mcpPath = path.join(rooDir, 'mcp.json');
-		try {
-			fs.rmSync(mcpPath, { force: true });
-			log('debug', `[Roo] Removed MCP configuration from ${mcpPath}`);
-		} catch (err) {
-			log('error', `[Roo] Failed to remove MCP configuration: ${err.message}`);
-		}
-
 		fs.readdirSync(rooDir).forEach((entry) => {
 			if (entry.startsWith('rules-')) {
 				const modeDir = path.join(rooDir, entry);
@@ -147,13 +101,7 @@ function onRemoveRulesProfile(targetDir) {
 }
 
 function onPostConvertRulesProfile(targetDir, assetsDir) {
-	// Enhance the MCP configuration with Roo-specific features after base setup
-	const mcpPath = path.join(targetDir, '.roo', 'mcp.json');
-	try {
-		enhanceRooMCPConfiguration(mcpPath);
-	} catch (err) {
-		log('error', `[Roo] Failed to enhance MCP configuration: ${err.message}`);
-	}
+	onAddRulesProfile(targetDir, assetsDir);
 }
 
 // Create and export roo profile using the base factory
@@ -163,7 +111,6 @@ export const rooProfile = createProfile({
 	url: 'roocode.com',
 	docsUrl: 'docs.roocode.com',
 	toolMappings: COMMON_TOOL_MAPPINGS.ROO_STYLE,
-	mcpConfig: true, // Enable MCP config - we enhance it with Roo-specific features
 	onAdd: onAddRulesProfile,
 	onRemove: onRemoveRulesProfile,
 	onPostConvert: onPostConvertRulesProfile

src/utils/create-mcp-config.js

@@ -262,6 +262,3 @@ export function removeTaskMasterMCPConfiguration(projectRoot, mcpConfigPath) {
 
 	return result;
 }
-
-// Export the formatting function for use by other modules
-export { formatJSONWithTabs };

tests/integration/profiles/roo-init-functionality.test.js

@@ -26,7 +26,7 @@ describe('Roo Profile Initialization Functionality', () => {
 		expect(rooProfile.displayName).toBe('Roo Code');
 		expect(rooProfile.profileDir).toBe('.roo'); // default
 		expect(rooProfile.rulesDir).toBe('.roo/rules'); // default
-		expect(rooProfile.mcpConfig).toBe(true); // now uses standard MCP configuration with Roo enhancements
+		expect(rooProfile.mcpConfig).toBe(true); // default
 	});
 
 	test('roo.js uses custom ROO_STYLE tool mappings', () => {

tests/unit/profiles/mcp-config-validation.test.js

@@ -266,10 +266,10 @@ describe('MCP Configuration Validation', () => {
 			expect(mcpEnabledProfiles).toContain('cursor');
 			expect(mcpEnabledProfiles).toContain('gemini');
 			expect(mcpEnabledProfiles).toContain('opencode');
+			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).toContain('vscode');
 			expect(mcpEnabledProfiles).toContain('windsurf');
 			expect(mcpEnabledProfiles).toContain('zed');
-			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).not.toContain('cline');
 			expect(mcpEnabledProfiles).not.toContain('codex');
 			expect(mcpEnabledProfiles).not.toContain('trae');
@@ -384,7 +384,6 @@ describe('MCP Configuration Validation', () => {
 			'claude',
 			'cursor',
 			'gemini',
-			'kiro',
 			'opencode',
 			'roo',
 			'windsurf',