chore(e2e): enable Playwright UI on headless Linux

Attempt to auto-start Xvfb when `--ui` is requested locally, add a stable `npm run e2e:ui:headless-server` wrapper, and document the headed/headless workflows. Improves developer DX when running Playwright UI on headless Linux and provides actionable guidance when Xvfb is unavailable.

Author: Wikid82

docs/development/running-e2e.md

@@ -0,0 +1,58 @@
+# Running Playwright E2E (headed and headless)
+
+This document explains how to run Playwright tests using a real browser (headed) on Linux machines and in the project's Docker E2E environment.
+
+## Key points
+- Playwright's interactive Test UI (--ui) requires an X server (a display). On headless CI or servers, use Xvfb.
+- Prefer the project's E2E Docker image for integration-like runs; use the local `--ui` flow for manual debugging.
+
+## Quick commands (local Linux)
+- Headless (recommended for CI / fast runs):
+  ```bash
+  npm run e2e
+  ```
+
+- Headed UI on a headless machine (auto-starts Xvfb):
+  ```bash
+  npm run e2e:ui:headless-server
+  # or, if you prefer manual control:
+  xvfb-run --auto-servernum --server-args='-screen 0 1280x720x24' npx playwright test --ui
+  ```
+
+- Headed UI on a workstation with an X server already running:
+  ```bash
+  npx playwright test --ui
+  ```
+
+## Using the project's E2E Docker image (recommended for parity with CI)
+1. Rebuild/start the E2E container (this sets up the full test environment):
+   ```bash
+   .github/skills/scripts/skill-runner.sh docker-rebuild-e2e
+   ```
+2. Run the UI against the container (you still need an X server on your host):
+   ```bash
+   PLAYWRIGHT_BASE_URL=http://localhost:8080 npm run e2e:ui:headless-server
+   ```
+
+## CI guidance
+- Do not run Playwright `--ui` in CI. Use headless runs or the E2E Docker image and collect traces/videos for failures.
+- For coverage, use the provided skill: `.github/skills/scripts/skill-runner.sh test-e2e-playwright-coverage`
+
+## Troubleshooting
+- Playwright error: "Looks like you launched a headed browser without having a XServer running." → run `npm run e2e:ui:headless-server` or install Xvfb.
+- If `npm run e2e:ui:headless-server` fails with an exit code like `148`:
+  - Inspect Xvfb logs: `tail -n 200 /tmp/xvfb.playwright.log`
+  - Ensure no permission issues on `/tmp/.X11-unix`: `ls -la /tmp/.X11-unix`
+  - Try starting Xvfb manually: `Xvfb :99 -screen 0 1280x720x24 &` then `export DISPLAY=:99` and re-run `npx playwright test --ui`.
+- If running inside Docker, prefer the skill-runner which provisions the required services; the UI still needs host X (or use VNC).
+
+## Developer notes (what we changed)
+- Added `scripts/run-e2e-ui.sh` — wrapper that auto-starts Xvfb when DISPLAY is unset.
+- Added `npm run e2e:ui:headless-server` to run the Playwright UI on headless machines.
+- Playwright config now auto-starts Xvfb when `--ui` is requested locally and prints an actionable error if Xvfb is not available.
+
+## Security & hygiene
+- Playwright auth artifacts are ignored by git (`playwright/.auth/`). Do not commit credentials.
+
+---
+If you'd like, I can open a PR with these changes (scripts + config + docs) and add a short CI note to `.github/` workflows.