Fixing playright again

Signed-off-by: Cliff Hill <xlorep@darkhelm.org>

docs/CICD_MULTI_STAGE_BUILD.md

@@ -184,6 +184,40 @@ RUN export NODE_OPTIONS="--max-old-space-size=1024" && \
 - **Memory Constraints**: Monitor swap usage on Raspberry Pi workers
 - **Network Timeouts**: Retry mechanisms handle transient failures
 
+#### Base Image Optimization Issues
+
+**Missing `/opt/python-dev-tools/` (Oct 2025 Resolution)**:
+- **Symptom**: Build fails with `No virtual environment or system Python installation found for path /opt/python-dev-tools/bin/python`
+- **Cause**: Base image in registry doesn't contain pre-installed Python dev tools optimization
+- **Fix Applied**: Made complete image resilient to missing optimization
+  ```dockerfile
+  # In Dockerfile.cicd - now handles missing pre-installed tools gracefully
+  if [ -f "/opt/python-dev-tools/bin/python" ]; then
+      echo "✓ Found pre-installed Python dev tools - leveraging cache"
+  else
+      echo "⚠ Pre-installed Python dev tools not found - fresh installation"
+  fi
+  ```
+- **Impact**: Builds continue successfully but without optimization benefits (~20s longer)
+- **Long-term Solution**: Rebuild base image to restore `/opt/python-dev-tools/` optimization
+
+**Playwright E2E Test Failures (Oct 2025 Resolution)**:
+- **Symptom**: `error: unknown option '--headed=false'` during E2E test execution
+- **Cause**: Invalid Playwright CLI flag syntax in workflow and documentation
+- **Fix Applied**:
+  - Removed invalid `--headed=false` flag (Playwright defaults to headless in CI)
+  - Changed to proper `yarn test:e2e --reporter=list` command
+  - Updated documentation with correct headless examples
+- **Key Learning**: Use yarn scripts (`yarn test:e2e`) rather than direct Playwright CLI calls
+
+**Missing Playwright Browser Binaries (Nov 2025 Resolution)**:
+- **Symptom**: `Executable doesn't exist at /root/.cache/ms-playwright/chromium_headless_shell-*/` for all browsers
+- **Cause**: Base image browsers not properly cached or registry image outdated
+- **Fix Applied**: Added `yarn playwright install --with-deps` step before running E2E tests in CI
+- **Docker Enhancement**: Made Dockerfile.cicd more resilient to missing browser optimization
+- **Impact**: E2E tests now work but download ~400MB of browsers each time (slower without base image optimization)
+- **Long-term Solution**: Rebuild base image to restore Playwright browser caching
+
 ## Migration Path
 
 ### From Single-Stage Build