diff --git a/.github/workflows/daily-multi-device-docs-tester.md b/.github/workflows/daily-multi-device-docs-tester.md
index 2f40ac0215..1e475cf463 100644
--- a/.github/workflows/daily-multi-device-docs-tester.md
+++ b/.github/workflows/daily-multi-device-docs-tester.md
@@ -67,6 +67,7 @@ You are a documentation testing specialist. Your task is to comprehensively test
 2. The docs folder is at: `${{ github.workspace }}/docs`
 3. Use absolute paths or change directory explicitly
 4. Keep token usage low by being efficient with your code and minimizing iterations
+5. **Playwright is available via MCP tools only** - do NOT try to `require('playwright')` or install it via npm
 
 ## Your Mission
 
@@ -96,8 +97,29 @@ Test these device types based on input `${{ inputs.devices }}`:
 
 ## Step 3: Run Playwright Tests
 
-For each device, use Playwright to:
-- Set viewport size and navigate to http://localhost:4321
+**IMPORTANT: Using Playwright in gh-aw Workflows**
+
+Playwright is provided through an MCP server interface, **NOT** as an npm package. You must use the MCP Playwright tools:
+
+- ✅ **Correct**: Use MCP tools like `mcp__playwright__browser_navigate`, `mcp__playwright__browser_run_code`, etc.
+- ❌ **Incorrect**: Do NOT try to `require('playwright')` or create standalone Node.js scripts
+- ❌ **Incorrect**: Do NOT install playwright via npm - it's already available through MCP
+
+**Example Usage:**
+
+```javascript
+// Use browser_run_code to execute Playwright commands
+mcp__playwright__browser_run_code({
+  code: `async (page) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    await page.goto('http://localhost:4321/gh-aw/');
+    return { url: page.url(), title: await page.title() };
+  }`
+})
+```
+
+For each device viewport, use Playwright MCP tools to:
+- Set viewport size and navigate to http://localhost:4321/gh-aw/
 - Take screenshots and run accessibility audits
 - Test interactions (navigation, search, buttons)
 - Check for layout issues (overflow, truncation, broken layouts)
diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
index 81514a5cf8..ed7b7cb657 100644
--- a/docs/src/content/docs/troubleshooting/common-issues.md
+++ b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -162,6 +162,53 @@ tools:
     allowed_domains: ["github.com", "*.github.io"]
 ```
 
+### Cannot Find Module 'playwright'
+
+**Error Message:**
+
+```text
+Error: Cannot find module 'playwright'
+Require stack:
+- /tmp/gh-aw/agent/script.js
+```
+
+**Cause:** The AI agent tried to use `require('playwright')` or created a standalone Node.js script expecting the playwright npm package to be installed. In gh-aw workflows, Playwright is provided through an MCP server interface, not as an npm package.
+
+**Solution:** Use Playwright through MCP tools instead of trying to require the module:
+
+```javascript
+// ❌ INCORRECT - This won't work
+const playwright = require('playwright');
+const browser = await playwright.chromium.launch();
+
+// ✅ CORRECT - Use MCP Playwright tools
+// Example: Navigate and take screenshot
+await mcp__playwright__browser_navigate({
+  url: "https://example.com"
+});
+
+await mcp__playwright__browser_snapshot();
+
+// Example: Execute custom Playwright code
+await mcp__playwright__browser_run_code({
+  code: `async (page) => {
+    await page.setViewportSize({ width: 390, height: 844 });
+    const title = await page.title();
+    return { title, url: page.url() };
+  }`
+});
+```
+
+**Available MCP Playwright Tools:**
+- `mcp__playwright__browser_navigate` - Navigate to URL
+- `mcp__playwright__browser_snapshot` - Take screenshot
+- `mcp__playwright__browser_run_code` - Execute custom Playwright code
+- `mcp__playwright__browser_click` - Click elements
+- `mcp__playwright__browser_type` - Type text
+- `mcp__playwright__browser_close` - Close browser
+
+See the [Playwright Tool documentation](/gh-aw/reference/tools/#playwright-tool-playwright) for complete details.
+
 ## Permission Issues
 
 ### Write Operations Fail