fix(workflow): resolve Multi-Device Docs Tester max-turns exhaustion due to Playwright/localhost networking mismatch

.github/workflows/daily-multi-device-docs-tester.md

@@ -16,7 +16,7 @@ permissions:
 tracker-id: daily-multi-device-docs-tester
 engine:
   id: claude
-  max-turns: 30  # Prevent runaway token usage
+  max-turns: 50  # Prevent runaway token usage (10 devices × ~3 turns + build/setup/report)
 strict: true
 timeout-minutes: 30
 tools:
@@ -106,19 +106,28 @@ Playwright is provided through an MCP server interface, **NOT** as an npm packag
 
 **Example Usage:**
 
+```bash
+# First, get the container's bridge IP (needed for Playwright - see shared lifecycle instructions)
+SERVER_IP=$(ip -4 route get 1.1.1.1 2>/dev/null | awk '{print $7; exit}')
+if [ -z "$SERVER_IP" ]; then SERVER_IP=$(hostname -I | awk '{print $1}'); fi
+echo "Playwright server URL: http://${SERVER_IP}:4321/gh-aw/"
+```
+
 ```javascript
-// Use browser_run_code to execute Playwright commands
+// Use browser_run_code to execute Playwright commands.
+// IMPORTANT: Replace 172.30.0.20 below with the actual SERVER_IP from the bash command above.
+// Do NOT use "localhost" — Playwright runs with --network host so its localhost differs.
 mcp__playwright__browser_run_code({
   code: `async (page) => {
     await page.setViewportSize({ width: 390, height: 844 });
-    await page.goto('http://localhost:4321/gh-aw/');
+    await page.goto('http://172.30.0.20:4321/gh-aw/');  // substitute actual SERVER_IP
     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/
+- Set viewport size and navigate to `http://${SERVER_IP}:4321/gh-aw/` (substitute the bridge IP you obtained above, NOT localhost)
 - Take screenshots and run accessibility audits
 - Test interactions (navigation, search, buttons)
 - Check for layout issues (overflow, truncation, broken layouts)

.github/workflows/shared/docs-server-lifecycle.md

@@ -14,19 +14,22 @@
 
 **Context**: The documentation has been pre-built using `npm run build`. Use the preview server to serve the static build.
 
-Navigate to the docs directory and start the preview server in the background:
+Navigate to the docs directory and start the preview server in the background, binding to all network interfaces on a fixed port:
 
 ```bash
 cd docs
-npm run preview > /tmp/preview.log 2>&1 &
+npm run preview -- --host 0.0.0.0 --port 4321 > /tmp/preview.log 2>&1 &
 echo $! > /tmp/server.pid
 ```
 
 This will:
-- Start the preview server on port 4321
+- Start the preview server on port 4321, bound to all interfaces (`0.0.0.0`)
 - Redirect output to `/tmp/preview.log`
 - Save the process ID to `/tmp/server.pid` for later cleanup
 
+**Why `--host 0.0.0.0 --port 4321` is required:**
+The agent runs inside a Docker container. Playwright also runs in its own container with `--network host`, meaning its `localhost` is the Docker host — not the agent container. Binding to `0.0.0.0` makes the server accessible on the agent container's bridge IP (e.g. `172.30.x.x`). The `--port 4321` flag prevents port conflicts if a previous server instance is still shutting down.
+
 ## Waiting for Server Readiness
 
 Poll the server with curl to ensure it's ready before use:
@@ -43,6 +46,25 @@ This will:
 - Wait 2 seconds between attempts
 - Exit successfully when server responds
 
+## Playwright Browser Access
+
+**Important**: Playwright runs in a container with `--network host`, so its `localhost` is the Docker host's localhost — not the agent container. To access the docs server from Playwright browser tools, use the agent container's bridge network IP instead of `localhost`.
+
+Get the container's bridge IP (this uses route lookup — `1.1.1.1` is never actually contacted, it only determines which interface handles outbound traffic):
+
+```bash
+SERVER_IP=$(ip -4 route get 1.1.1.1 2>/dev/null | awk '{print $7; exit}')
+# Fallback if route lookup fails
+if [ -z "$SERVER_IP" ]; then
+  SERVER_IP=$(hostname -I | awk '{print $1}')
+fi
+echo "Playwright server URL: http://${SERVER_IP}:4321/gh-aw/"
+```
+
+Then use `http://${SERVER_IP}:4321/gh-aw/` (not `http://localhost:4321/gh-aw/`) when navigating with Playwright tools.
+
+The `curl` readiness check and bash commands still use `localhost:4321` since they run inside the agent container where the server is local.
+
 ## Verifying Server Accessibility (Optional)
 
 Optionally verify the server is serving content:
@@ -67,7 +89,8 @@ This will:
 
 ## Usage Notes
 
-- The server runs on `http://localhost:4321`
-- Documentation is accessible at `http://localhost:4321/gh-aw/`
+- The server runs on `http://localhost:4321` (agent container's localhost)
+- Documentation is accessible at `http://localhost:4321/gh-aw/` for curl/bash
+- For Playwright browser tools, use the container bridge IP (see "Playwright Browser Access" section above)
 - Always clean up the server when done to avoid orphan processes
 - If the server fails to start, check `/tmp/preview.log` for errors