Merge pull request #83 from woocommerce/26-04/ai-recommended-tools

Add AI Recommended Tools page and agent-agnostic framing

Author: Luc45

docs/ai/getting-started.md

@@ -10,9 +10,9 @@ This page assumes your AI agent already has QIT context. If not, see [Getting St
 
 Once set up, your AI agent can handle any QIT task autonomously. This page covers what's possible and how to get the most out of it.
 
-## What Claude Can Do
+## What Your AI Agent Can Do
 
-With the QIT plugin, Claude can:
+With QIT documentation context, your AI agent can:
 
 - **Run any QIT test**: managed tests, test packages, or both
 - **Create test packages**: follows a [structured methodology](./test-packages/writing-with-agents.md) that includes user research, UI observation, and persona-based test design
@@ -23,10 +23,20 @@ With the QIT plugin, Claude can:
 
 ## How It Works
 
-The plugin uses **progressive disclosure** from QIT's live documentation:
+### Claude Code (Recommended)
 
-1. Claude fetches the [documentation index](https://qit.woo.com/docs/llms.txt) to find relevant pages
+The QIT plugin uses **progressive disclosure** from live documentation:
+
+1. The agent fetches the [documentation index](https://qit.woo.com/docs/llms.txt) to find relevant pages
 2. It reads the specific docs needed for your task
 3. It acts on what it learned: running commands, writing code, interpreting results
 
-This means Claude always has current information, even as QIT evolves. You don't need to paste docs or explain QIT concepts — the agent discovers what it needs on-demand.
+This happens automatically. You don't need to paste docs or explain QIT concepts.
+
+### Other AI Agents
+
+Provide your agent with the documentation URL once:
+
+> Read https://qit.woo.com/docs/llms.txt — I want to test my WooCommerce extension with QIT.
+
+Your agent reads the index, fetches the pages it needs, and has the same capabilities from there. The llms.txt index follows the [llmstxt.org](https://llmstxt.org) standard and stays current as QIT evolves.

docs/ai/recommended-tools.md

@@ -0,0 +1,50 @@
+---
+description: "The recommended MCP servers and tools for using QIT with AI coding agents. Covers Playwright MCP for browser observation, Xdebug MCP for PHP debugging, and how they work together in a typical test development workflow."
+---
+
+# Recommended Tools
+
+These MCP servers give your AI agent direct access to the browser and PHP runtime, making it significantly more effective at writing tests, debugging failures, and investigating issues.
+
+## Playwright MCP
+
+[Playwright MCP](https://github.com/anthropics/playwright-mcp) lets your agent control a real browser: navigate pages, read the accessibility tree, take screenshots, fill forms, and click elements. Essential for writing test packages and debugging test failures.
+
+Your agent uses it to:
+- Explore your extension's admin and frontend UI before writing tests
+- Observe exact accessible names and page structure for reliable selectors
+- Debug failing tests by navigating to the failing page and inspecting what's actually there
+
+See [Browser Observation](./test-packages/browser-observation.md) for the detailed workflow.
+
+## Xdebug MCP
+
+[Xdebug MCP](https://github.com/kpanuragh/xdebug-mcp) lets your agent do PHP step debugging conversationally: set breakpoints, step through code, inspect variables, and evaluate expressions. No IDE needed.
+
+Your agent uses it to:
+- Set breakpoints in plugin code and step through execution
+- Inspect variable state at runtime to understand behavior
+- Trace function calls to find where things go wrong
+
+Pair it with QIT's built-in Xdebug support:
+
+```qitbash
+qit env:up --xdebug --plugin=your-extension
+```
+
+See [Xdebug Debugging](../environment/xdebug.md) for environment setup and configuration.
+
+## How They Work Together
+
+A typical AI-driven test development workflow uses all three tools:
+
+1. **QIT CLI** starts the environment and runs tests
+2. **Playwright MCP** observes the UI to discover selectors and verify behavior
+3. **Xdebug MCP** debugs PHP when something unexpected happens server-side
+
+For example, when a test fails because checkout doesn't complete:
+- Your agent uses Playwright MCP to navigate to checkout and see the current UI state
+- If the UI looks correct but the order still fails, it uses Xdebug MCP to set a breakpoint in the payment processing code and step through it
+- Once it finds the issue, it fixes the code and uses QIT CLI to re-run the test
+
+This is the workflow described in detail in [Writing Test Packages with AI](./test-packages/writing-with-agents.md).

docs/environment/xdebug.md

@@ -12,6 +12,10 @@ QIT environments include Xdebug pre-installed but disabled by default. The `--xd
 - **Profiling** — generate cachegrind files to find performance bottlenecks
 - **Tracing** — log every function call for execution flow analysis
 
+:::tip AI-agent debugging
+Using an AI coding agent? It can drive Xdebug directly via [Xdebug MCP](https://github.com/kpanuragh/xdebug-mcp), setting breakpoints and inspecting variables conversationally with no IDE needed. See [Recommended Tools](/ai/recommended-tools) for the full AI toolkit.
+:::
+
 ## Quick start
 
 ```qitbash

sidebars.js

@@ -114,6 +114,7 @@ const sidebars = {
             collapsed: true,
             items: [
                 'ai/getting-started',
+                'ai/recommended-tools',
                 {
                     type: 'category',
                     label: 'Test Packages',