docs: Update documentation for new AI/config architecture and finalize cleanup

This commit updates all relevant documentation (READMEs, docs/*, .cursor/rules) to accurately reflect the finalized unified AI service architecture and the new configuration system (.taskmasterconfig + .env/mcp.json). It also includes the final code cleanup steps related to the refactoring.

Key Changes:

1.  **Documentation Updates:**

    *   Revised `README.md`, `README-task-master.md`, `assets/scripts_README.md`, `docs/configuration.md`, and `docs/tutorial.md` to explain the new configuration split (.taskmasterconfig vs .env/mcp.json).

    *   Updated MCP configuration examples in READMEs and tutorials to only include API keys in the `env` block.

    *   Added/updated examples for using the `--research` flag in `docs/command-reference.md`, `docs/examples.md`, and `docs/tutorial.md`.

    *   Updated `.cursor/rules/ai_services.mdc`, `.cursor/rules/architecture.mdc`, `.cursor/rules/dev_workflow.mdc`, `.cursor/rules/mcp.mdc`, `.cursor/rules/taskmaster.mdc`, `.cursor/rules/utilities.mdc`, and `.cursor/rules/new_features.mdc` to align with the new architecture, removing references to old patterns/files.

    *   Removed internal rule links from user-facing rules (`taskmaster.mdc`, `dev_workflow.mdc`, `self_improve.mdc`).

    *   Deleted outdated example file `docs/ai-client-utils-example.md`.

2.  **Final Code Refactor & Cleanup:**

    *   Corrected `update-task-by-id.js` by removing the last import from the old `ai-services.js`.

    *   Refactored `update-subtask-by-id.js` to correctly use the unified service and logger patterns.

    *   Removed the obsolete export block from `mcp-server/src/core/task-master-core.js`.

    *   Corrected logger implementation in `update-tasks.js` for CLI context.

    *   Updated API key mapping in `config-manager.js` and `ai-services-unified.js`.

3.  **Configuration Files:**

    *   Updated API keys in `.cursor/mcp.json`, replacing `GROK_API_KEY` with `XAI_API_KEY`.

    *   Updated `.env.example` with current API key names.

    *   Added `azureOpenaiBaseUrl` to `.taskmasterconfig` example.

4.  **Task Management:**

    *   Marked documentation subtask 61.10 as 'done'.

    *   Includes various other task content/status updates from the diff summary.

5.  **Changeset:**

    *   Added `.changeset/cuddly-zebras-matter.md` for user-facing `expand`/`expand-all` improvements.

This commit concludes the major architectural refactoring (Task 61) and ensures the documentation accurately reflects the current system.

assets/.taskmasterconfig

@@ -25,6 +25,7 @@
 		"defaultSubtasks": 5,
 		"defaultPriority": "medium",
 		"projectName": "Taskmaster",
-		"ollamaBaseUrl": "http://localhost:11434/api"
+		"ollamaBaseUrl": "http://localhost:11434/api",
+		"azureOpenaiBaseUrl": "https://your-endpoint.openai.azure.com/"
 	}
 }

assets/env.example

@@ -3,8 +3,7 @@ ANTHROPIC_API_KEY=your_anthropic_api_key_here       # Required: Format: sk-ant-a
 PERPLEXITY_API_KEY=your_perplexity_api_key_here     # Optional: Format: pplx-...
 OPENAI_API_KEY=your_openai_api_key_here             # Optional, for OpenAI/OpenRouter models. Format: sk-proj-...
 GOOGLE_API_KEY=your_google_api_key_here             # Optional, for Google Gemini models.
-GROK_API_KEY=your_grok_api_key_here                 # Optional, for XAI Grok models.
 MISTRAL_API_KEY=your_mistral_key_here               # Optional, for Mistral AI models.
-AZURE_OPENAI_API_KEY=your_azure_key_here            # Optional, for Azure OpenAI models.
-AZURE_OPENAI_ENDPOINT=your_azure_endpoint_here      # Optional, for Azure OpenAI.
-OLLAMA_BASE_URL=http://localhost:11434/api          # Base URL for local Ollama instance (Optional)
+XAI_API_KEY=YOUR_XAI_KEY_HERE                       # Optional, for xAI AI models.
+AZURE_OPENAI_API_KEY=your_azure_key_here            # Optional, for Azure OpenAI models (requires endpoint in .taskmasterconfig).
+OLLAMA_API_KEY=YOUR_OLLAMA_KEY_HERE                 # Optional, for local Ollama AI models (requires endpoint in .taskmasterconfig).

assets/scripts_README.md

@@ -16,27 +16,22 @@ In an AI-driven development process—particularly with tools like [Cursor](http
 8. **Clear subtasks**—remove subtasks from specified tasks to allow regeneration or restructuring.
 9. **Show task details**—display detailed information about a specific task and its subtasks.
 
-## Configuration
+## Configuration (Updated)
 
-The script can be configured through environment variables in a `.env` file at the root of the project:
+Task Master configuration is now managed through two primary methods:
 
-### Required Configuration
+1.  **`.taskmasterconfig` File (Project Root - Primary)**
 
-- `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude
+    - Stores AI model selections (`main`, `research`, `fallback`), model parameters (`maxTokens`, `temperature`), `logLevel`, `defaultSubtasks`, `defaultPriority`, `projectName`, etc.
+    - Managed using the `task-master models --setup` command or the `models` MCP tool.
+    - This is the main configuration file for most settings.
 
-### Optional Configuration
+2.  **Environment Variables (`.env` File - API Keys Only)**
+    - Used **only** for sensitive **API Keys** (e.g., `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`).
+    - Create a `.env` file in your project root for CLI usage.
+    - See `assets/env.example` for required key names.
 
-- `MODEL`: Specify which Claude model to use (default: "claude-3-7-sonnet-20250219")
-- `MAX_TOKENS`: Maximum tokens for model responses (default: 4000)
-- `TEMPERATURE`: Temperature for model responses (default: 0.7)
-- `PERPLEXITY_API_KEY`: Your Perplexity API key for research-backed subtask generation
-- `PERPLEXITY_MODEL`: Specify which Perplexity model to use (default: "sonar-medium-online")
-- `DEBUG`: Enable debug logging (default: false)
-- `LOG_LEVEL`: Log level - debug, info, warn, error (default: info)
-- `DEFAULT_SUBTASKS`: Default number of subtasks when expanding (default: 3)
-- `DEFAULT_PRIORITY`: Default priority for generated tasks (default: medium)
-- `PROJECT_NAME`: Override default project name in tasks.json
-- `PROJECT_VERSION`: Override default version in tasks.json
+**Important:** Settings like `MODEL`, `MAX_TOKENS`, `TEMPERATURE`, `LOG_LEVEL`, etc., are **no longer set via `.env`**. Use `task-master models --setup` instead.
 
 ## How It Works
 
@@ -194,21 +189,14 @@ Notes:
 - Can be combined with the `expand` command to immediately generate new subtasks
 - Works with both parent tasks and individual subtasks
 
-## AI Integration
+## AI Integration (Updated)
 
-The script integrates with two AI services:
-
-1. **Anthropic Claude**: Used for parsing PRDs, generating tasks, and creating subtasks.
-2. **Perplexity AI**: Used for research-backed subtask generation when the `--research` flag is specified.
-
-The Perplexity integration uses the OpenAI client to connect to Perplexity's API, which provides enhanced research capabilities for generating more informed subtasks. If the Perplexity API is unavailable or encounters an error, the script will automatically fall back to using Anthropic's Claude.
-
-To use the Perplexity integration:
-
-1. Obtain a Perplexity API key
-2. Add `PERPLEXITY_API_KEY` to your `.env` file
-3. Optionally specify `PERPLEXITY_MODEL` in your `.env` file (default: "sonar-medium-online")
-4. Use the `--research` flag with the `expand` command
+- The script now uses a unified AI service layer (`ai-services-unified.js`).
+- Model selection (e.g., Claude vs. Perplexity for `--research`) is determined by the configuration in `.taskmasterconfig` based on the requested `role` (`main` or `research`).
+- API keys are automatically resolved from your `.env` file (for CLI) or MCP session environment.
+- To use the research capabilities (e.g., `expand --research`), ensure you have:
+  1.  Configured a model for the `research` role using `task-master models --setup` (Perplexity models are recommended).
+  2.  Added the corresponding API key (e.g., `PERPLEXITY_API_KEY`) to your `.env` file.
 
 ## Logging