eyaltoledano · Crunchyman-ralph · Dec 18, 2025 · Dec 19, 2025 · Dec 28, 2025 · Dec 28, 2025
diff --git a/.changeset/afraid-rocks-add.md b/.changeset/afraid-rocks-add.md
diff --git a/.changeset/hip-pots-study.md b/.changeset/hip-pots-study.md
diff --git a/.changeset/lazy-lies-argue.md b/.changeset/lazy-lies-argue.md
diff --git a/.changeset/new-grapes-accept.md b/.changeset/new-grapes-accept.md
diff --git a/.changeset/violet-colts-sip.md b/.changeset/violet-colts-sip.md
diff --git a/.claude/TM_COMMANDS_GUIDE.md b/.claude/TM_COMMANDS_GUIDE.md
@@ -1,5 +1,9 @@
 # Task Master Commands for Claude Code
 
+> 📖 **New to Claude Code + Task Master?** See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for installation options.
+
+This guide is specifically for users who have installed the **Task Master plugin** and want to use slash commands.
+
 Complete guide to using Task Master through Claude Code's slash commands.
 
 ## Overview

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # task-master-ai
 
+## 0.40.1
+
+### Patch Changes
+
+- [#1523](https://github.com/eyaltoledano/claude-task-master/pull/1523) [`fc1a79f`](https://github.com/eyaltoledano/claude-task-master/commit/fc1a79f2565b0d8c24f009aec2c473a335262ae2) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Codex cli Validate reasoning effort against model capabilities
+  - Add provider-level reasoning effort validation for OpenAI models
+  - Automatically cap unsupported effort levels (e.g., 'xhigh' on gpt-5.1 and gpt-5 becomes 'high')
+
+- [#1549](https://github.com/eyaltoledano/claude-task-master/pull/1549) [`98087ac`](https://github.com/eyaltoledano/claude-task-master/commit/98087acae91fad7345bdb4c253d4dfd0d584f81e) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Improve CLI startup speed by 2x
+
+- [#1545](https://github.com/eyaltoledano/claude-task-master/pull/1545) [`a0007a3`](https://github.com/eyaltoledano/claude-task-master/commit/a0007a3575305c367c8561584aa0dbd181f5e1cc) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Smarter project root detection with boundary markers
+  - Prevents Task Master from incorrectly detecting `.taskmaster` folders in your home directory when working inside a different project
+  - Now stops at project boundaries (`.git`, `package.json`, lock files) instead of searching all the way up to the filesystem root
+  - Adds support for monorepo markers (`lerna.json`, `nx.json`, `turbo.json`) and additional lock files (`bun.lockb`, `deno.lock`)
+
+- [#1523](https://github.com/eyaltoledano/claude-task-master/pull/1523) [`fc1a79f`](https://github.com/eyaltoledano/claude-task-master/commit/fc1a79f2565b0d8c24f009aec2c473a335262ae2) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Improve json schemas for ai-related commands making it more compatible with openai models
+  - Fixes #1541 #1542
+
+- [#1542](https://github.com/eyaltoledano/claude-task-master/pull/1542) [`b817d6f`](https://github.com/eyaltoledano/claude-task-master/commit/b817d6f9f278c84785ec468f9b305e70c47266f6) Thanks [@mdimitrovg](https://github.com/mdimitrovg)! - Fixed vertex-ai authentication when using service account and vertex location env variable.
+
 ## 0.40.0
 
 ### Minor Changes

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,5 +1,9 @@
 # Claude Code Instructions
 
+> **What is this file?** This file is auto-loaded by Claude Code to provide context about this project's development guidelines.
+>
+> 📖 **Setting up Claude Code + Task Master?** See the [Complete Setup Guide](https://docs.task-master.dev/integrations/claude-code)
+
 ## Task Master AI Instructions
 
 **Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.**

diff --git a/CLAUDE_CODE_PLUGIN.md b/CLAUDE_CODE_PLUGIN.md
@@ -1,6 +1,8 @@
-# Taskmaster AI - Claude Code Marketplace
+# Taskmaster AI - Claude Code Plugin Marketplace
 
-This repository includes a Claude Code plugin marketplace in `.claude-plugin/marketplace.json`.
+> 📖 **Looking for Claude Code setup?** See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for all integration options (MCP, Plugin, Provider).
+
+This document is specifically for **plugin marketplace** installation. The repository includes a Claude Code plugin marketplace in `.claude-plugin/marketplace.json`.
 
 ## Installation
 

diff --git a/README.md b/README.md
@@ -60,17 +60,18 @@ 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
+#### Claude Code Setup
 
-For Claude Code users:
+For Claude Code users, we offer multiple integration options:
 
 ```bash
+# Quick MCP install
 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
+📖 **[Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code)** - Learn about MCP server, plugin marketplace, and Claude Code provider options.
+
+> **Note:** `task-master-ai` is the MCP server package name. The CLI command is `task-master`.
 
 
 ## Requirements
@@ -320,20 +321,15 @@ Add `TASK_MASTER_TOOLS` to your MCP configuration file's `env` section:
 }
 ```
 
-#### Method 2: Claude Code CLI (One-Time Setup)
+#### Method 2: Claude Code CLI
 
-For Claude Code users, you can set the mode during installation:
+For Claude Code users, you can set the mode during installation. See the [Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code) for details.
 
 ```bash
 # Core mode example (~70% token reduction)
 claude mcp add task-master-ai --scope user \
   --env TASK_MASTER_TOOLS="core" \
   -- npx -y task-master-ai@latest
-
-# Custom tools example
-claude mcp add task-master-ai --scope user \
-  --env TASK_MASTER_TOOLS="get_tasks,next_task,set_task_status" \
-  -- npx -y task-master-ai@latest
 ```
 
 ### Tool Sets Details
@@ -353,13 +349,13 @@ claude mcp add task-master-ai --scope user \
 
 ## Claude Code Support
 
-Task Master now supports Claude models through the Claude Code CLI, which requires no API key:
+Task Master offers comprehensive Claude Code integration:
 
-- **Models**: `claude-code/opus` and `claude-code/sonnet`
-- **Requirements**: Claude Code CLI installed
-- **Benefits**: No API key needed, uses your local Claude instance
+- **MCP Server**: Natural language task management in chat
+- **Plugin**: 49 slash commands for quick workflows
+- **Provider**: Use Claude Code models (no API key required)
 
-[Learn more about Claude Code setup](docs/examples/claude-code-usage.md)
+📖 **[Complete Claude Code Setup Guide](https://docs.task-master.dev/integrations/claude-code)** - Choose the best option for your workflow.
 
 ## Troubleshooting
 

diff --git a/apps/docs/docs.json b/apps/docs/docs.json
@@ -53,6 +53,10 @@
 							"capabilities/task-structure"
 						]
 					},
+					{
+						"group": "Integrations",
+						"pages": ["integrations/claude-code"]
+					},
 					{
 						"group": "AI Providers",
 						"pages": ["providers/azure"]