docs: standardize Playwright MCP headed/headless runbook across AI CLI harnesses (#1438)

Author: atxtechbro

docs/playwright-headed-headless-cheatsheet.md

@@ -0,0 +1,45 @@
+# Playwright MCP Headed vs Headless Cheat Sheet
+
+Quick operational reference for AI-first CLI sessions.
+
+## 60-Second Triage
+
+1. Decide task mode:
+   - Login/demo/visual verification -> `headed`
+   - CI/batch/non-interactive -> `headless`
+2. Check harness MCP config (not only shell env).
+3. If `headed` on Linux, verify display prerequisites are present.
+4. Restart harness session after config/env changes.
+5. Validate with a minimal post-login authenticated-page check.
+
+## Decision Table
+
+| Situation | Mode |
+|-----------|------|
+| Login/MFA needed | Headed |
+| Live demo or walkthrough | Headed |
+| Visual bug investigation | Headed |
+| CI or nightly automation | Headless |
+| Fast non-interactive extraction | Headless |
+
+## Top Failure Signatures
+
+1. Missing display/X server launch errors
+2. Browser does not appear despite headed intent
+3. Transport/session closed unexpectedly
+4. Login redirect succeeds but auth state is missing
+5. Works once, fails after restart
+
+## Fix Direction (One Line Each)
+
+- Display/X errors -> Ensure headed prerequisites are passed in harness MCP env.
+- No browser window -> Confirm harness is actually launching in headed mode.
+- Transport closed -> Restart harness and re-launch MCP with validated config.
+- Missing auth state -> Verify with authenticated route check after login.
+- Restart regression -> Persist config in harness file, not temporary shell only.
+
+## Canonical Runbook
+
+Use full procedure for detailed diagnostics and recovery:
+- `../knowledge/procedures/playwright-headed-vs-headless.md`
+

knowledge/ai-index.md

@@ -34,6 +34,7 @@ Your starting point for understanding and working with this dotfiles repository.
 ### Debug or Fix Issues
 - Use [MCP Protocol Smoke Test](procedures/mcp-protocol-smoke-test.md) for MCP issues
 - Follow [MCP Error Reporting](procedures/mcp-error-reporting.md) when MCP tools fail
+- Use [Playwright Headed vs Headless](procedures/playwright-headed-vs-headless.md) for deterministic browser mode behavior
 - Apply [Systems Stewardship](principles/systems-stewardship.md) - Document fixes
 
 ### Improve Documentation
@@ -53,6 +54,7 @@ Your starting point for understanding and working with this dotfiles repository.
 
 ### When MCP Tools Don't Work
 - Follow [MCP Error Reporting](procedures/mcp-error-reporting.md) - We control these servers, we'll fix them!
+- Use [Playwright Headed vs Headless](procedures/playwright-headed-vs-headless.md) for browser mode triage and recovery
 - Creates self-healing systems through proper issue tracking
 - Remember: 80% core work, 20% documenting issues
 

knowledge/procedures/README.md

@@ -32,6 +32,7 @@ This is THE workflow. Everything else supports this core process.
 - `mcp-tool-logging.md` - MCP server tool-level logging
 - `mcp-protocol-smoke-test.md` - Testing MCP protocol directly
 - `mcp-prompts.md` - Adding prompts to MCP servers
+- `playwright-headed-vs-headless.md` - Deterministic mode selection and recovery for AI CLI sessions
 
 ### Tips & Setup
 - `claude-code-tips.md` - Tips and shortcuts for Claude Code

knowledge/procedures/playwright-headed-vs-headless.md

@@ -0,0 +1,88 @@
+# Playwright MCP: Headed vs Headless
+
+Cross-harness runbook for deterministic browser mode selection in AI-first CLI workflows.
+
+## Why This Exists
+
+In CLI harnesses, Playwright MCP mode can appear to "mysteriously" switch to headless because:
+- Harness-level config differs from shell-level env.
+- MCP subprocesses inherit only what the harness passes.
+- Display stack prerequisites are missing even when config requests headed mode.
+
+This runbook makes headed and headless behavior predictable across:
+- Claude Code
+- OpenAI Codex
+- GitHub Copilot CLI
+
+## Mode Selection
+
+Choose `headed` when you need:
+- Login and MFA flows.
+- Live demos and walkthroughs.
+- Visual verification of UI states.
+- Debugging anti-bot/captcha interactions.
+
+Choose `headless` when you need:
+- CI or batch automation.
+- Non-interactive extraction or checks.
+- Faster, repeatable automation without UI.
+
+## Common Failure Signatures
+
+- Launch error about missing X server or `$DISPLAY`.
+- Session dies with transport-closed style errors.
+- Login appears successful but follow-up page is unauthenticated.
+- Browser window never appears despite headed intent.
+
+## Deterministic Diagnostics
+
+Run this sequence in order:
+
+1. Verify harness config source of truth.
+   - Confirm the active config file for your harness and session.
+2. Verify MCP subprocess environment.
+   - Ensure headed prerequisites are passed in harness config env, not only in shell.
+3. Verify display stack prerequisites.
+   - Linux/X11: `DISPLAY` and `XAUTHORITY` must be valid for the session user.
+   - Wayland environments may require Xwayland compatibility for specific setups.
+4. Verify restart boundary.
+   - If config changed, restart the harness session so MCP launches with new env.
+5. Verify with a neutral authenticated-page check.
+   - Confirm post-login access to a known authenticated route/view, not just a login redirect.
+
+## Cross-Harness Notes
+
+### Claude Code
+- Keep MCP server config aligned with `mcp/mcp.json` and enabled server settings.
+- If MCP env changes, restart the CLI session to relaunch subprocesses.
+
+### OpenAI Codex
+- Configure Playwright MCP env under `.codex/config.toml` `[mcp_servers.playwright]`.
+- Treat shell exports as insufficient unless reflected in Codex MCP server env.
+
+### GitHub Copilot CLI
+- Use the CLI's MCP config/env mechanism as the runtime source of truth.
+- Ensure session restarts occur after env/config updates.
+
+## Recovery Playbook
+
+Use smallest-safe-change-first:
+
+1. Confirm intended mode for task (`headed` or `headless`).
+2. Align harness MCP env to that mode.
+3. Restart harness session.
+4. Re-run minimal navigation check.
+5. Re-run login or demo flow.
+6. Validate with an authenticated-page check.
+
+Stop and escalate when:
+- Same failure repeats after two config-correct restarts.
+- Mode appears correct but auth state is unstable across immediate retries.
+
+## Definition Of Done
+
+- Intended mode is explicitly confirmed by behavior.
+- Target flow completes in that mode.
+- Follow-up authenticated-page verification passes.
+- Behavior remains stable after one full harness restart.
+

mcp/README.md

@@ -37,6 +37,10 @@ Wrapper scripts and configuration for MCP clients (Claude Code, Amazon Q, Cursor
 
 When an MCP server shows as "failed" in Claude Code:
 
+For browser mode selection and stability in AI CLI sessions, use:
+- `knowledge/procedures/playwright-headed-vs-headless.md`
+- `docs/playwright-headed-headless-cheatsheet.md`
+
 ### 1. Quick Health Check
 ```bash
 # Check individual server logs if needed
@@ -91,4 +95,4 @@ check-mcp-logs --follow # Real-time logs
 ```bash
 # Test MCP handshake for npm-based servers
 echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "smoke-test", "version": "1.0.0"}}}' | npx @playwright/mcp
-```
+```