[q] fix(docs-noob-tester): fix Playwright connection issues — use curl as primary analysis method

[github-actions]

Root Cause

Investigated run #23398559751 (the run that generated discussion #22242).

The Playwright connection issue:

• Playwright MCP server runs with --network host (Docker host network)
• The Astro dev server runs inside the agent container at 172.30.0.20:4321
• iptables firewall rules block Docker host → container bridge connections
• Both browser_navigate and browser_run_code always timeout — 30s and 60s respectively
• The agent wasted ~2 min debugging this before falling back to curl

✗ browser_run_code
  TimeoutError: page.goto: Timeout 30000ms exceeded.
  - navigating to "(172.30.0.20/redacted)

✗ browser_navigate (172.30.0.20/redacted)
  TimeoutError: page.goto: Timeout 60000ms exceeded.
  - navigating to "(172.30.0.20/redacted)

This is a structural firewall constraint — not fixable from within the workflow.

Changes Made

docs-noob-tester.md

• Removed bridge IP detection bash block from Step 1 (it was only useful for Playwright)
• Rewrote Step 2 to use curl + direct file reading as the primary analysis method
• Added explicit ⚠️ Playwright Connectivity Limitation warning — do not attempt URL navigation
• Added page.setContent(html) as an alternative way to use Playwright for optional screenshots
• Step 4 screenshots are now explicitly optional with page.setContent() instructions
• Report template marks Screenshots section as optional

shared/docs-server-lifecycle.md

• Replaced the "Playwright Browser Access" section with accurate documentation of the limitation
• Documents what Playwright CAN do (page.setContent() for rendering) and CANNOT do (URL navigation)
• Removes misleading bridge IP instructions

Expected Improvements

• Eliminates ~90s of wasted turns on Playwright timeout debugging
• Reduces token usage significantly (6.77M tokens in the last run — partly due to Playwright debugging)
• Agent now goes straight to curl analysis without detours
• Screenshots become available via page.setContent() workaround (optional)

Validation

✅ docs-noob-tester compiled successfully — no errors or warnings.

References

• Discussion: 📚 Documentation Noob Test Report - March 22, 2026 #22242
• Run analyzed: https://github.com/github/gh-aw/actions/runs/23398559751

---

Warning

🛡️ Protected Files — Push Permission Denied

This was originally intended as a pull request, but the patch modifies protected files: .github/workflows/docs-noob-tester.md, .github/workflows/shared/docs-server-lifecycle.md.

The push was rejected because GitHub Actions does not have workflows permission to push these changes, and is never allowed to make such changes, or other authorization being used does not have this permission. A human must create the pull request manually.

To create a pull request with the changes:

# Download the patch from the workflow run
gh run download 23399393310 -n agent -D /tmp/agent-23399393310

# Create a new branch
git checkout -b q/fix-playwright-connection-prompt-11e168675f7e0a48 main

# Apply the patch (--3way handles cross-repo patches)
git am --3way /tmp/agent-23399393310/aw-q-fix-playwright-connection-prompt.patch

# Push the branch and create the pull request
git push origin q/fix-playwright-connection-prompt-11e168675f7e0a48
gh pr create --title '[q] fix(docs-noob-tester): fix Playwright connection issues — use curl as primary analysis method' --base main --head q/fix-playwright-connection-prompt-11e168675f7e0a48 --repo github/gh-aw

🎩 Equipped by Q · ◷

• expires on Mar 24, 2026, 8:53 AM UTC