pi-lean-dimension 0.1.0 → 0.2.1

package/README.md

@@ -1,57 +1,117 @@
 # pi-lean-dimension
 
-The full web-tools suite for Pi — interactive web browsing and SearXNG search,
-unified under `/web`.
+> Web browsing and search tools for [Pi](https://github.com/earendil-works/pi-coding-agent), the AI coding agent.
 
-**This is an umbrella meta-package.** It bundles
-[`pi-lean-portal`](https://www.npmjs.com/package/pi-lean-portal) (browser) and
-[`pi-lean-search`](https://www.npmjs.com/package/pi-lean-search) (SearXNG search)
-into a single `pi install` command.
+A monorepo housing three Pi extension packages that give your AI agent the
+ability to browse the web interactively, fetch static pages as Markdown, and
+search via SearXNG — all toggled from a single `/web` command. When the toggle
+is off, the tools are removed from the agent's context entirely, so web browsing
+doesn't consume tokens or attention on sessions that aren't doing web work.
+The same surfaces are user-extensible: author navigation guides that resurface
+by domain, or drop in a stealth browser backend like [Camoufox](https://github.com/daijro/camoufox)
+when a site blocks the shipped Chromium/Firefox.
 
-## Install
+## Quick start (recommended)
 
 ```bash
-pi install npm:pi-lean-dimension
+pi install npm:pi-lean-portal
+npx playwright install chromium firefox
 ```
 
-### Prerequisites
+That's it — the tools are registered and start enabled by default. Control
+them with `/web on|off|learn` (`on` = browser tools, `learn` = browser tools
+plus guide-saving via `web-learn`, `off` = everything off). The state persists
+per session. To set a different default for **new** sessions, add this to your
+Pi settings (`~/.pi/agent/settings.json` or `.pi/settings.json`):
 
-- **Playwright browsers** (for browsing):
+```json
+{ "browserToggle": { "defaultEnabled": false } }
+```
 
-  ```bash
-  npx playwright install chromium firefox
-  ```
+---
+
+## Install options
 
-- **SearXNG instance** (for search, optional): configure the URL in settings:
+| Mode | Command | What you get | Requires |
+|---|---|---|---|
+| **A — Browser** (recommended) | `pi install npm:pi-lean-portal` | 12 browser tools + `/web` command | `npx playwright install chromium firefox` |
+| **B — Full suite** | `pi install npm:pi-lean-dimension` | 13 tools (browser + search) + `/web` | Playwright browsers + SearXNG server |
+| **B-search — Search only** | `pi install npm:pi-lean-search` | `web-search` tool only | SearXNG server |
+
+Notes the table doesn't carry:
+
+- **Browser binaries aren't downloaded during `npm install`** (configured via `.npmrc`). The first `browser-navigate` call prompts you to run `npx playwright install chromium firefox` if they're missing.
+- **SearXNG is optional for Mode B.** The browser works immediately without it; `web-search` returns a clear setup message on first call. When you do run it, point the suite at your instance in Pi settings:
 
   ```json
-  { "searxng": { "url": "https://searxng.example.com" } }
+  { "searxng": { "url": "http://localhost:8888" } }
   ```
 
-The browser works immediately after `npx playwright install`. The search tool
-self-documents its setup on first call if SearXNG isn't configured.
-
-## What you get
-
-| Tool | Purpose |
-|---|---|
-| `browser-navigate` | Navigate to a URL, get an accessibility tree with `@e` element refs |
-| `browser-snapshot` | Re-extract the current page's accessibility tree (`@e` refs) and capture a screenshot to a temp file |
-| `browser-click` | Click an element by `@e` ref |
-| `browser-type` | Type text into an input by `@e` ref |
-| `browser-scroll` | Scroll the page |
-| `browser-back` | Navigate back |
-| `browser-press` | Press a key |
-| `browser-console` | Read console messages from the page |
-| `browser-inspect` | Query and extract text from elements |
-| `web-fetch` | Stateless fetch → Markdown (no JS) |
-| `web-guide` | Navigation guidance for a site or pattern |
-| `web-learn` | Save/update navigation guidance |
-| `web-search` | Web search via SearXNG |
+- **Search-only has no `/web` command** — a single tiny tool has nothing to toggle.
+
+---
+
+## What's included
+
+### Packages
+
+| Package | Type | Description |
+|---|---|---|
+| `pi-lean-portal` | Extension | Interactive browser + `/web` command owner. **12 tools + 1 command.** |
+| `pi-lean-search` | Extension | SearXNG search tool (`web-search`). **1 tool + 1 command** (`/searxng-status`). |
+| `pi-lean-dimension` | Umbrella meta-package | Bundles portal + search for one-command install. |
+
+### Tools (13 total with search)
+
+| Tool | Package | Purpose |
+|---|---|---|
+| `browser-navigate` | portal | Navigate to a URL, get an accessibility tree with `@e` element refs |
+| `browser-snapshot` | portal | Re-extract the current page's accessibility tree (`@e` refs) and capture a screenshot to a temp file |
+| `browser-click` | portal | Click an element by `@e` ref |
+| `browser-type` | portal | Type text into an input by `@e` ref |
+| `browser-scroll` | portal | Scroll the page |
+| `browser-back` | portal | Navigate back |
+| `browser-press` | portal | Press a key |
+| `browser-console` | portal | Read console messages from the page |
+| `browser-inspect` | portal | Query and extract text from elements |
+| `web-fetch` | portal | Stateless fetch → Markdown (no JS) |
+| `web-guide` | portal | Navigation guidance for a site or pattern |
+| `web-learn` | portal | Save/update navigation guidance |
+| `web-search` | search | Web search via SearXNG |
 
 ### Commands
 
-- `/web on|off|learn|cookies|profile|status` — unified toggle and management
+| Command | Owner | Description |
+|---|---|---|
+| `/web on\|off\|learn\|cookies\|profile\|status` | portal | Unified toggle and management |
+| `/searxng-status` | search | Test SearXNG connection and update status glyph |
+
+### Status bar
+
+When search is installed, two independent glyphs appear:
+
+- `● idle` (browser) — browser tools enabled
+- `● searxng` (search) — SearXNG health (accent=healthy, yellow=degraded, red=unreachable)
+
+---
+
+## Extending it
+
+Beyond the `/web` toggle, two surfaces are user-driven rather than hardcoded:
+
+- **Navigation guides** — `web-learn` saves site-specific playbooks that auto-match by domain and resurface in later sessions.
+- **Custom browser backends** — if a site blocks the shipped Chromium/Firefox, drop a `bridge.py` subclass into `~/.pi/agent/pi-lean-portal/user-backends/` and drive a patched engine like [Camoufox](https://github.com/daijro/camoufox) yourself. A quirks schema declares how the engine diverges from base Playwright, and `launch` options flow from `settings.json` to the subprocess at runtime. This is user-authored, user-audited code that the extension never auto-downloads — and as far as we're aware, no other Pi web plugin lets you run a browser backend you wrote yourself. Most installs never need it; the [portal README](packages/pi-lean-portal/README.md#stealth--custom-browser-backends) and [`contributed/README.md`](packages/pi-lean-portal/contributed/README.md) cover the full flow when you do.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/coreyryanhanson/pi-lean-dimension.git
+cd pi-lean-dimension
+npm install
+npm test                    # vitest run — all workspace tests
+```
 
 ## License
 

package/node_modules/pi-lean-portal/AGENTS.md

@@ -32,10 +32,146 @@ getCookies, addCookies, clearCookies  — cookie operations
 getStorageState     — profile storage for session restore
 ```
 
-The 12 registered tools map to 12 tool-facing plugin methods. The cookie/storage methods (`getCookies`, `addCookies`, `clearCookies`, `getStorageState`) are router-facing, not tool-mapped. Element cache access (`getElementCache`) is used internally by `browser-inspect`. The lifecycle methods (`init`, `cleanupAll`) are framework-facing. Total interface: 19 methods.
+The 12 registered tools map to 12 tool-facing plugin methods. The cookie/storage methods (`getCookies`, `addCookies`, `clearCookies`, `getStorageState`) are router-facing, not tool-mapped. Element cache access (`getElementCache`) is used internally by `browser-inspect`. The lifecycle methods (`init`, `cleanupAll`) are framework-facing. Total interface: 19 methods (18 required + 1 optional).
 
 Capabilities (`PluginCapabilities`) advertise quirks. The router checks them at dispatch time.
 
+## Browser launch hook
+
+The portal's own backends launch their browser directly and drive
+their own page — there is **no external-attach path**. The
+`getAttachEndpoint()` interface method, the `AttachEndpoint` union,
+`core/shared/cdp-endpoint.ts`, the `launchServer()` / `connect()`
+hop, and the `_cdpEndpoint` / `_wsEndpoint` / `_browserServer` /
+`_reconnectBrowser()` scaffolding were all removed (see
+[`docs/decisions/miniwob-and-host-setup.md`](../../docs/decisions/miniwob-and-host-setup.md)).
+There is no post-launch hook for third-party subclasses and no
+`connectOverCDP?` interface hook — a host-owns-browser ("Mode B")
+path was considered and dropped as YAGNI; either will be re-added
+alongside a real consumer that needs it.
+
+## Stealth backends (user-managed)
+
+Stealth backends are **user-installed plugins** that drive
+patched/fingerprint-managed browser binaries (e.g. Camoufox) for sites
+that block the shipped Chromium/Firefox. They are never shipped in the
+npm tarball and the extension never downloads or executes them
+automatically — there is no plugin marketplace. For the install flow
+and the choosing decision, see
+[`contributed/README.md`](contributed/README.md) and
+[`contributed/CHOOSING.md`](contributed/CHOOSING.md).
+
+### Deployment: user-writable data tree, not the npm tarball
+
+Stealth backends live under the user-writable data tree:
+
+```
+~/.pi/agent/pi-lean-portal/
+├── web-guides/              (existing)
+├── browser-state/           (existing)
+└── user-backends/           ← stealth backends go here
+    └── camoufox-py/
+        ├── bridge.py        (user copies from contributed/)
+        └── .venv/           (user-created: engine pip pkg + playwright)
+```
+
+This is **trusted user code** — the user wrote or audited the bridge,
+created the venv, and fetched the binary. The extension spawns it as a
+subprocess; it never auto-downloads stealth backends. `user-backends/`
+is a **different tree from any in-repo test fixtures** (which live
+gitignored under `bench/miniwob/fixtures/` for the evaluation
+harness). The `~/.pi/agent/pi-lean-portal/user-backends/` tree is what
+the pi agent's production `detectPluginType` reads at runtime.
+
+Stealth backends are **never in the default fallback list**. When
+`browser.plugins` is absent, only the four shipped backends
+(`chromium`, `firefox`, `chromium-py`, `firefox-py`) are loaded. A
+fresh install must not emit validation errors for plugins the user
+never asked for. Tested in `__tests__/plugin-config-browser.test.ts`.
+
+### Discovery: multi-root, absolute short-circuit
+
+`detectPluginType(dir, roots)` (in `core/plugin-config.ts`) resolves
+`dir` in order:
+
+1. **Absolute path** — used directly (dev/power-user escape hatch).
+2. **`DEFAULT_BACKEND_ROOTS[0]`** = package `backends/` (shipped
+   backends).
+3. **`DEFAULT_BACKEND_ROOTS[1]`** = `USER_BACKENDS_DIR` (user stealth).
+
+First root with an unambiguous entry point (`index.ts` XOR `bridge.py`)
+wins. Missing from all roots throws an error naming every root
+searched. Tested in `__tests__/plugin-loading.test.ts`.
+
+The `pythonPath` in `config` must be **absolute** — a relative
+`pythonPath` is not resolved against `USER_BACKENDS_DIR` (that nicety
+is intentionally out of scope). Point it at
+`<user-backends>/<name>-py/.venv/bin/python`.
+
+### Config channel: `browser.init` RPC
+
+After the `ping` handshake, `python-adapter.ts` sends a single
+`browser.init` RPC with `{ config: <user config dict> }`. The bridge
+stores it as `self._plugin_config`; subclasses read
+`self.plugin_config.get("launch", {})`. A bridge that does not
+recognize `browser.init` rejects with a "bridge too old" message so
+upgrades fail loudly. Re-sent after crash-recovery restarts. Tested in
+`__tests__/python-adapter.test.ts` ("browser.init RPC").
+
+### Importability: `PYTHONPATH` injection
+
+`python-adapter.ts` `_buildPythonPath()` appends the package's
+`backends/python-base/` to any existing `PYTHONPATH` in the spawn env,
+so a user bridge in its own venv can
+`from pi_browser_bridge.playwright_base import PlaywrightBridge`
+without a `pip install` of `pi-browser-bridge` (which is not on PyPI).
+Append (not prepend) so the editable install in `python-base/.venv`
+keeps precedence for the shipped `chromium-py` / `firefox-py` bridges.
+Tested in `__tests__/python-adapter.test.ts` ("PYTHONPATH injection").
+
+### Quirks schema (`PlaywrightBridge` class attrs)
+
+The contract for a stealth backend is a set of class attributes on
+`PlaywrightBridge` in
+`backends/python-base/pi_browser_bridge/playwright_base.py`. Set them
+as class attributes on your subclass:
+
+| Flag | Default | Effect when set |
+|------|---------|-----------------|
+| `_fingerprint_managed_context` | `False` | `create_browser_context()` skips hardcoded `viewport`/`user_agent`; lets the fingerprint package set them. |
+| `_eval_prefix` | `""` | Prepended to every `page.evaluate` expression in `do_evaluate` (e.g. Camoufox's `"mw:"` routes writes to the main world). |
+| `_scroll_via_wheel` | `False` | `do_scroll` uses `page.mouse.wheel` instead of `page.evaluate("window.scrollBy")` (avoids eval-write under isolated-world stealth). |
+| `_skip_default_viewport` | `False` | Skips Playwright's `Browser.setDefaultViewport` CDP call (Camoufox binary rejects its `isMobile` prop). |
+| `_skip_networkidle` | `False` | Nav-settle uses `load` instead of `networkidle` (patched binaries don't fire `networkidle` reliably). |
+| `_wrap_mw_eval_in_eval` | `False` | `do_evaluate` rewrites the expression as `eval(<JSON-string of expression>)` before prepending `_eval_prefix`, so multi-statement scripts survive Camoufox's `let _s = (${script})` main-world wrapper (see prose below). |
+| `_csp_safe_readonly_via_init_script` | `False` | `do_evaluate(read_only=True)` (the EXTRACTOR_SCRIPT) reads its JSON result from a `<meta id="__pi-extract">` tag that `create_browser_context` registers as a `context.add_init_script` (isolated world, CSP-free) at `DOMContentLoaded`, instead of `page.evaluate`. For patched-Firefox stealth binaries that route `page.evaluate` through `eval()` in the page's main world (CSP-subject) — Camoufox is NOT affected (its binary keeps Juggler's CSP-free isolated-world). The adapter plumbs the script via the `browser.init` config key `readOnlyExtractorScript`. Stale across SPA route changes (no new load) — fine for navigate→inspect. |
+
+All flags default off → `chromium-py` / `firefox-py` behavior is
+bit-identical to a pre-stealth install. A dropped v2 `_context_factory`
+flag (dispatching to a `_camoufox_new_context` helper) was removed
+when `camoufox.NewContext` turned out to be broken on the current
+binary (`Protocol error (Browser.setDefaultViewport)` from the same
+`isMobile` rejection `_skip_default_viewport` handles). Camoufox
+injects the fingerprint at **browser launch** via `camoufox.NewBrowser`,
+so standard `browser.new_context()` with
+`_fingerprint_managed_context = True` is correct — do not re-attempt
+`NewContext`.
+
+### Camoufox: the shipped example template
+
+Camoufox is the **shipped, tested template** — a reference `bridge.py`
+lives at `contributed/camoufox-py/` (source repo only; **not in the
+npm tarball** because `docs/` is excluded from `package.json` `files`).
+Pointer:
+`packages/pi-lean-portal/contributed/camoufox-py/bridge.py`.
+Generic test suites (contract + persistence + MiniWoB parity + quirks
+introspection) run via the discovery runner at
+`__tests__/run-contributed-suites.test.ts`, which auto-discovers
+any `<name>-py/` user backend at runtime — there is no per-backend
+contract file for Camoufox. Backend-specific behavioural tests
+(beyond the quirks flags) are optional hand-authored files under
+`__tests__/contributed/<name>-py/`
+
 ## Router (`core/router.ts`)
 
 All tool calls dispatch through the router. Key responsibilities:
@@ -68,12 +204,12 @@ All tool calls dispatch through the router. Key responsibilities:
 
 ## Known Constraints & Debt
 
-- **Console capture in Python backends** — Both `chromium-py` and `firefox-py` inherit console capture (500-entry ring buffer) and dialog auto-dismissal from `PlaywrightBridge._setup_page_session()` in `python-base`. The base `BrowserBridge` does not install handlers; future Python plugins must override `_setup_page_session`.
+- **Console capture in Python backends** — Both `chromium-py` and `firefox-py` inherit console capture (500-entry ring buffer) and dialog auto-dismissal from `PlaywrightBridge._setup_page_session()` in `python-base`. The base `BrowserBridge` (an `abc.ABC`) does not define `_setup_page_session`; future Python plugins that subclass `BrowserBridge` directly must supply their own session setup (subclasses of `PlaywrightBridge` inherit it).
 - **AbortSignal not supported on Python bridge** — the router passes `signal` through unconditionally (no capability check). The Python adapter accepts and silently ignores the signal. `supportsAbortSignal` is advertised but unenforced.
 - **Sessions are per taskId** — mapped to `browser-NNN` keys via `_sessionKeys`/`_sessionCounter` in `core/shared/task-id.ts`. Created on first navigate, cleaned up on `session_shutdown`.
 - **Python shared-context machinery removed (B1)** — the `browser.newPage`/`browser.closePage` RPC routes, `_profile_contexts` ref-counting, and `ensure_profile_session`/`remove_profile_session` methods were removed from both the base `BrowserBridge` and `ChromiumPyBridge`. Named profiles now use disk persistence (load-on-navigate via `storageState`) matching the TS Chromium plugin. Both backends use `ensure_session(task_id, config)` for all sessions.
 - **Python bridge reuses BrowserContexts across navigations** — `ensure_session()` returns the existing session on re-navigate (unlike the TS Chromium plugin which creates a fresh context per navigate). This means in-process cookies survive re-navigation without explicit save, but also means `storageState` from the router is ignored on re-navigate (the context already exists). The Python adapter's `_persistState()` saves current cookies to disk before the navigate RPC for cross-process persistence.
-- **`_persistState()` helper in both backends** — extracted from `cleanup()`, this method checks `session?.persistState`, snapshots the BrowserContext's storage state, persists it to disk, and returns the raw state for optional in-memory reuse (Chromium uses the return as fallback for the new context; Python returns it for API consistency). Called both from `cleanup()` and — on re-navigate — from `getOrCreateContext()` (Chromium) or `navigate()` (Python) before the old context is closed/reused.
+- **`_persistState()` helper in both backends** — both `PlaywrightPluginBase._persistState` (direct `context.storageState()` call) and `PythonPluginAdapter._persistState` (JSON-RPC `browser.getStorageState` retrieval) delegate to the shared `persistSessionState()` helper in `core/shared/storage-state.ts`, which owns the `session?.persistState` gate, the `saveStorageState()` call, and the warn-and-swallow error path. Called both from `cleanup()` and — on re-navigate — from `getOrCreateContext()` (Chromium) or `navigate()` (Python) before the old context is closed/reused.
 - **Role-based locators only**: never XPath/CSS — always `getByRole()` via `buildLocator()` with positional `.nth()` for duplicates. The `INTERACTIVE_ROLES` set defines which roles get @e refs.
 - **All URLs go through `url-safety.ts`** — blocks localhost, private IPs (10.x, 172.16-31.x, 192.168.x, 169.254.169.254), dangerous schemes (file:, ftp:, data:, javascript:, vbscript:), and heuristically detects secrets in URLs.
 - **Screenshot**: JPEG 80% quality, viewport constrained to 1280px wide, returns data URI.
@@ -87,10 +223,16 @@ All tool calls dispatch through the router. Key responsibilities:
 - **Guide staleness**: no builtin site guides shipped — entirely user-authored via `~/.pi/agent/pi-lean-portal/web-guides/*.md`. Guides carry `updated` date and `currentDate` timestamp in output.
 - **Learn mode toggle**: `/web learn` enables `web-learn` tool; `/web on` removes it. Agent never calls `web-learn` unprompted. Default is off on fresh sessions.
 - **Navigation settle** (`core/shared/nav-settle.ts`): after click or press, detects page navigation via a `framenavigated` listener and waits for `load + networkidle` (capped, errors swallowed) before reading URL/title/snapshot. Replaces the old fixed `waitForTimeout(300)` pattern that caused URL/DOM mismatches. Framework-agnostic via a lightweight `NavigationSettlePage` interface for testability.
+- **Stealth backends are user-managed, not shipped** — they live under `~/.pi/agent/pi-lean-portal/user-backends/`, are never in the npm tarball, and the extension never auto-downloads them. The user-side install burden is real: a per-engine venv, a ~100 MB patched-binary fetch, and an explicit `settings.json` entry with an **absolute** `pythonPath`. See `contributed/README.md` for the install flow.
+- **Fingerprint-managed context** — a stealth backend sets `_fingerprint_managed_context = True` so `create_browser_context()` skips the hardcoded `viewport`/`user_agent` and lets the fingerprint package set them. Camoufox injects the fingerprint at **browser launch** via `camoufox.NewBrowser`, so standard `browser.new_context()` is correct (a `_context_factory` / `NewContext` path was attempted and dropped — `camoufox.NewContext` is broken on the current binary).
+- **Camoufox `mw:` prefix + `main_world_eval`** — Camoufox sets `_eval_prefix = "mw:"` so `do_evaluate` writes route to the main world (isolated-world stealth otherwise blocks them), and forwards `main_world_eval=True` to `NewBrowser`. Contract tests assert `do_evaluate("() => 1 + 1")` returns `2`.
+- **`isMobile` / `_skip_default_viewport` binary quirk** — Camoufox's patched Firefox binary rejects the `isMobile` prop in Playwright's `Browser.setDefaultViewport` CDP call, so the template sets `_skip_default_viewport = True`. If a future binary version fixes the rejection, the flag degrades gracefully (default off) — re-validate on Camoufox releases.
+- **`_wrap_mw_eval_in_eval` main-world statement support** — Camoufox's patched Juggler main-world eval path (`MainWorldContext.executeInGlobal` in the binary's `omni.ja`) wraps every `mw:`-prefixed script as `(() => { let _s = (${script}); ... })()`. That wrapper requires `${script}` to be a single *expression*; any *statement* — `let` / `var` / multiple `;`-separated statements (the exact shape of the MiniWoB setup scripts `REMOVE_DISPLAY_JS` / `SETUP_JS`) — is a `SyntaxError` (`missing ) in parenthetical`) that surfaces through Playwright as `"Execution context was destroyed, most likely because of a navigation."`. That error is **not** a navigation race (the previous `_retry_eval_on_context_destroyed` quirk retried it and could never succeed — a SyntaxError is deterministic). The template sets `_wrap_mw_eval_in_eval = True`, making `do_evaluate` rewrite the script as `mw:eval(<JSON-string of script>)`: a single expression (valid inside `let _s = (...)`) where `eval` runs the script verbatim and returns its completion value, handling both expressions and multi-statement scripts. When a future Camoufox driver release fixes the wrapper, flip the flag back to `False`.
+- **`xvfb` for `headless='virtual'`** — on Linux, Camoufox's `headless='virtual'` mode needs the `xvfb` system package; true headless (`headless=True`, the template's default) works without it.
 - **`BROWSER_DEBUG=1`** — enables structured `[browser]` log lines on stderr (navigate, snapshot, click). Checked in both ChromiumPlugin and the Python bridge.
 
 ## Debugging
 
 ```bash
-BROWSER_DEBUG=1 npx vitest run __tests__/reddit-dialog.test.ts
+BROWSER_DEBUG=1 npx vitest run __tests__/chromium.test.ts
 ```

package/node_modules/pi-lean-portal/README.md

@@ -1,10 +1,14 @@
 # pi-lean-portal User Guide
 
-> **pi-lean-portal** is a plugin-based web browsing extension for the Pi coding
-> agent. It gives the AI agent the ability to fetch web pages, interact with
-> dynamic sites, inspect page structure, take screenshots, run JavaScript,
-> and save/recall navigation guides — all through a set of tools and the `/web`
-> command.
+> **pi-lean-portal** gives the Pi coding agent interactive web browsing —
+> Playwright Chromium/Firefox, accessibility-tree snapshots with `@e` element
+> refs, persistent profiles, cookies, and navigation guides that resurface by
+> domain. A `/web` toggle removes the tools from the agent's context when
+> switched off, so web browsing doesn't consume tokens on sessions that aren't
+> doing web work. If a site blocks the shipped browsers, drop in your own
+> backend (e.g. [Camoufox](https://github.com/daijro/camoufox)) - as far as
+> we're aware, no other Pi web plugin lets you run a browser backend you wrote
+> yourself.
 >
 > Part of the [pi-lean-dimension](https://github.com/coreyryanhanson/pi-lean-dimension)
 > web-tools suite. For SearXNG search support, install
@@ -15,16 +19,17 @@
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [`/web` Command — Browser Toggle & Profiles](#web-command--browser-toggle--profiles)
-3. [All 12 Tools](#all-12-tools)
-4. [Stateless Fetching (web-fetch)](#stateless-fetching-web-fetch)
-5. [Navigation Guides (web-guide & web-learn)](#navigation-guides-web-guide--web-learn)
-6. [`/web status` — Detailed Runtime Status](#web-status--detailed-runtime-status)
-7. [Profiles — Persistent Sessions](#profiles--persistent-sessions)
-8. [Cookie Management](#cookie-management)
-9. [Backend Architecture](#backend-architecture)
-10. [Configuration (settings.json)](#configuration-settingsjson)
-11. [Tips & Best Practices](#tips--best-practices)
+2. [Extending it](#extending-it)
+3. [`/web` Command — Browser Toggle & Profiles](#web-command--browser-toggle--profiles)
+4. [All 12 Tools](#all-12-tools)
+5. [Stateless Fetching (web-fetch)](#stateless-fetching-web-fetch)
+6. [Navigation Guides (web-guide & web-learn)](#navigation-guides-web-guide--web-learn)
+7. [`/web status` — Detailed Runtime Status](#web-status--detailed-runtime-status)
+8. [Profiles — Persistent Sessions](#profiles--persistent-sessions)
+9. [Cookie Management](#cookie-management)
+10. [Backend Architecture](#backend-architecture)
+11. [Configuration (settings.json)](#configuration-settingsjson)
+12. [Tips & Best Practices](#tips--best-practices)
 
 ---
 
@@ -56,6 +61,21 @@ The browser tools are **enabled by default**. You can:
 
 ---
 
+## Extending it
+
+Beyond the toggle, two surfaces are user-extensible rather than hardcoded:
+
+- **Navigation guides** — `web-learn` saves site-specific playbooks that
+  auto-match by domain and resurface in later sessions. See
+  [Navigation Guides](#navigation-guides-web-guide--web-learn).
+- **Custom browser backends** — if a site blocks the shipped Chromium/Firefox,
+  drop a `bridge.py` subclass into `~/.pi/agent/pi-lean-portal/user-backends/`
+  and drive a patched engine like [Camoufox](https://github.com/daijro/camoufox)
+  yourself. The full flow lives in [Backend Architecture](#backend-architecture)
+  and [`contributed/README.md`](./contributed/README.md).
+
+---
+
 ## `/web` Command — Browser Toggle & Profiles
 
 The `/web` command controls whether web tools are visible to the AI agent,
@@ -414,39 +434,76 @@ capability advertisement:
 - The extension auto-detects whether a plugin is Node-based (`index.ts`)
   or Python-based (`bridge.py`) by inspecting the directory.
 
-### Stealth & Custom Browser Backends (Planned)
+### Stealth & Custom Browser Backends
 
 This package ships four backends — `chromium`, `firefox`, `chromium-py`,
 and `firefox-py` — all built on Playwright. Additional browser support
 (including stealth engines like **Camoufox**) is intentionally **left
 to users** to author and drop in, rather than being bundled with the
-package.
-
-Most of the building blocks are already in place: the `BrowserPlugin`
-interface, the Python bridge base class (`PlaywrightBridge`), and
-config-driven plugin loading that auto-detects `index.ts` (Node) or
-`bridge.py` (Python) entry points. Two pieces of infrastructure are still
-needed before user-authored stealth backends are practical:
-
-1. **A quirks system** — so a backend can declare things like a custom
-   context factory (e.g. Camoufox's `NewContext` for fingerprint
-   injection), an eval-script prefix, or a fingerprint-managed viewport,
-   instead of being clobbered by the base class's hardcoded defaults.
-2. **A config channel** from the TypeScript adapter to the Python bridge
-   subprocess — so launch options like `headless`, target OS, proxy, and
-   binary path can reach the bridge.
-
-Once those land, the plan is for users to author additional backends the
-same way they author site guides today — by dropping files into a
-user-owned directory (e.g. `~/.pi/agent/pi-lean-portal/backends/`,
-analogous to the `web-guides/` directory) and registering them in
-`browser.plugins`. The shipped backends live inside the package's own
-`backends/` directory; that directory should not be edited after install
-(modifications would be lost on the next package update), which is exactly
-why a separate user-owned directory is the supported path for custom and
-stealth backends.
-
-The shape a custom backend's config entry will take looks like:
+package. The infrastructure for this is now in place: a **quirks system**
+lets a backend declare how it diverges from the base Playwright behavior,
+and a **config channel** (`browser.init` RPC) forwards launch options
+from `settings.json` to the Python bridge subprocess.
+
+Most users will never need a stealth backend (see
+[`contributed/CHOOSING.md`](./contributed/CHOOSING.md) for when to reach
+for one at all). When you do, the flow is:
+
+1. **Drop a `bridge.py` into the user-backends tree.** The convention is
+   `~/.pi/agent/pi-lean-portal/user-backends/<name>-py/bridge.py` (the
+   `-py` suffix mirrors the shipped `chromium-py` / `firefox-py`). This is
+   a separate tree from the package's own `backends/` directory, which is
+   not edited after install — exactly so custom backends survive updates.
+2. **Create a venv and fetch the engine binary** (e.g.
+   `python -m camoufox fetch`). The shared `pi_browser_bridge` library is
+   injected onto `PYTHONPATH` automatically at spawn time, so you do not
+   need to `pip install` it.
+3. **Register it in `browser.plugins`** with an **absolute** `pythonPath`
+   and a `launch` object whose keys are forwarded to the bridge.
+4. **Verify with `/web status`** and a `browser-navigate`.
+
+The shipped **Camoufox template** at
+[`contributed/camoufox-py/bridge.py`](./contributed/camoufox-py/bridge.py)
+is a worked example — copy it as a starting point. The full install flow,
+the quirks schema reference, and the security model (user-backends are
+**trusted user code** — never auto-downloaded, no plugin marketplace) live
+in [`contributed/README.md`](./contributed/README.md). The decision doc at
+[`contributed/CHOOSING.md`](./contributed/CHOOSING.md) covers when to use
+a stealth backend at all and the two lifecycle patterns for implementing
+your own.
+
+#### Writing your own backend (high level)
+
+A custom Python backend is a subclass of `PlaywrightBridge`
+(`backends/python-base/pi_browser_bridge/playwright_base.py`) that sets
+the **quirks flags** its engine needs as class attributes and overrides
+the launch hook matching how the engine owns Playwright. The flags
+(`_fingerprint_managed_context`, `_eval_prefix`, `_scroll_via_wheel`,
+`_skip_default_viewport`, `_skip_networkidle`, `_wrap_mw_eval_in_eval`)
+all default off, so a subclass that sets none of them is bit-identical to
+the shipped `chromium-py` / `firefox-py`. The full table with effects is
+in [`contributed/README.md`](./contributed/README.md#quirks-schema-reference).
+
+Node-based custom backends follow the same shape via the
+`PlaywrightPluginBase` class — the auto-detection in `plugin-loading`
+picks up `index.ts` (Node) or `bridge.py` (Python) entry points from the
+user-backends directory.
+
+#### Tests are auto-discovered
+
+You usually do **not** need to write your own tests. The contributed
+runner at `__tests__/run-contributed-suites.test.ts` discovers every
+backend under `user-backends/*-py/`, loads config from the test-local
+`settings.json`, and runs the shared contract + persistence + parity +
+quirks-introspection suites against it — forwarding your configured
+`launch` options. Opt in with `CONTRIB_RUN=1`:
+
+```bash
+npm run setup:miniwob   # one-time: clone MiniWoB++ content
+CONTRIB_RUN=1 npx vitest run packages/pi-lean-portal/__tests__/run-contributed-suites.test.ts
+```
+
+A custom backend's config entry looks like:
 
 ```jsonc
 {
@@ -454,8 +511,9 @@ The shape a custom backend's config entry will take looks like:
     "plugins": [
       { "name": "chromium", "dir": "chromium", "enabled": true, "config": {} },
       { "name": "firefox", "dir": "firefox", "enabled": true, "config": {} },
-      { "name": "camoufox-py", "dir": "camoufox-py", "enabled": false, "config": {
-          "pythonPath": "/path/to/camoufox-py/.venv/bin/python"
+      { "name": "camoufox-py", "dir": "camoufox-py", "enabled": true, "config": {
+          "pythonPath": "/home/me/.pi/agent/pi-lean-portal/user-backends/camoufox-py/.venv/bin/python",
+          "launch": { "headless": true, "os": "windows", "humanize": true }
         }
       }
     ]
@@ -463,8 +521,12 @@ The shape a custom backend's config entry will take looks like:
 }
 ```
 
-This support will arrive in a future update. Until then, the four shipped
-backends can be toggled via the `enabled` field below.
+`pythonPath` must be **absolute**; `dir` resolves against the user-backends
+root (multi-root discovery: package `backends/` → `USER_BACKENDS_DIR` →
+absolute). `launch` keys are forwarded to the bridge as
+`plugin_config.launch` via the `browser.init` RPC. Stealth backends are
+never in the default fallback list — a fresh install with no
+`browser.plugins` loads only the four shipped backends.
 
 ---
 
@@ -495,9 +557,9 @@ Controls which browser backends are loaded. Entries are processed in order
 
 Each entry requires only a unique name, a backend directory path, and an
 optional `config` object passed to the plugin's `init()`. For the Python
-backends, `config` carries options like `pythonPath` (the shape shown for
-`camoufox-py` above is representative of how a user-authored Python
-backend will be configured).
+backends, `config` carries `pythonPath` and a `launch` object (the shape
+shown for `camoufox-py` in the [Stealth & Custom Browser Backends](#stealth--custom-browser-backends)
+section above is the reference for a user-authored Python backend).
 
 ### `browser.defaultProfile`