FEAT: Implement Playwright-Python Bridge for high-fidelity browsing

docs/rca/rca-playwright-bridge.org

@@ -0,0 +1,39 @@
+#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
+#+DATE: 2026-04-11
+#+FILETAGS: :rca:intelligence:browsing:automation:psf:
+
+* Executive Summary
+Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `org-agent` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
+
+* 1. Architectural Strategy: The I/O Bridge
+** Problem
+Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
+** Resolution
+Implemented a **JSON-over-STDIO Bridge**. 
+- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
+- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.
+
+* 2. Environment & Dependency Management
+** Issue
+Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
+** Resolution
+Updated the `Dockerfile` to:
+1. Install Python3, pip, and venv.
+2. Create a virtual environment for isolated dependency management.
+3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.
+
+* 3. Cognitive Tooling
+Created the `:browser` cognitive tool, which exposes three primary capabilities to System 1:
+- **Navigation:** Full JS rendering and waiting for network idle.
+- **Extraction:** Targeted text retrieval via CSS selectors.
+- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
+
+* 4. PSF Mandate Alignment
+** Zero-Bloat (Managed)
+While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
+** Literate Granularity
+The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.
+
+* 5. Permanent Learnings
+- **Inter-Process JSON:** JSON is the ideal lingua franca for Lisp-Python bridges.
+- **Path Portability:** Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.