pi-lean-portal 0.3.3 → 0.5.0

package/README.md

@@ -1,9 +1,7 @@
 # pi-lean-portal User Guide
 
-> **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
+> **pi-lean-portal** gives the Pi coding agent interactive web browsing via Playwright Chromium/Firefox, accessibility-tree snapshots with `@e` element
+> refs, persistent profiles, cookies, and domain-aware navigation guides. 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)).
@@ -14,23 +12,6 @@
 
 ---
 
-## Table of Contents
-
-1. [Quick Start](#quick-start)
-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)
-
----
-
 ## Quick Start
 
 ```bash
@@ -42,46 +23,16 @@ Once loaded, you'll see a notification like:
 
 > 🌐 Browser extension loaded (plugins: chromium, firefox). Try: web-fetch for static pages or browser-navigate for interactive browsing.
 
-The browser tools are **enabled by default**. You can:
+The browser tools are **enabled by default**: `web-fetch` for static pages,
+`browser-navigate` (plus click/type/scroll/screenshots via `@e` refs) for
+interactive browsing.
 
-- **Fetch a static page**: The agent uses `web-fetch` for quick, stateless
-  content retrieval (no JavaScript, no session).
-- **Browse interactively**: The agent uses `browser-navigate` to visit a page,
-  then clicks, types, scrolls, and screenshots using `@e1`/`@e2` element
-  references from the accessibility tree.
-
-> **Tip:** If you only need Markdown content from a static page, `web-fetch`
-> is faster and lighter than launching a full browser session.
->
 > **Playwright browser binaries are not downloaded during `npm install`.**
 > Run `npx playwright install chromium firefox` separately. On first
 > `browser-navigate` without them, you'll be prompted with the exact command.
 
 ---
 
-## Extending it
-
-Beyond the toggle, three surfaces are extensible or shared 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).
-- **Toolset toggles** — the `/web` toggle is powered by the shared
-  [`pi-tool-masking`](https://github.com/coreyryanhanson/pi-tool-masking/) peer dep,
-  which handles active-set masking, sibling-tool union math, and the
-  `TOOLSET_EVENTS` protocol that keeps the `browser`/`search` status-bar
-  glyphs in sync across extensions. It's published as a general toggle
-  mechanism — any extension that hides/shows its own tools can build on the
-  same scheme so masking and glyph events stay consistent across the whole
-  agent, rather than each toggle reinventing its own.
-
----
-
 ## `/web` Command — Browser Toggle & Profiles
 
 The `/web` command controls whether web tools are visible to the AI agent,
@@ -90,202 +41,132 @@ toggles guide-saving mode, and manages browser profiles.
 ### Three-State Toggle
 
 | Command | Effect |
-|---------|--------|
-| `/web on` | **Browsing only** — all interactive browser tools + `web-fetch` are available. `web-learn` is hidden. If `pi-lean-search` is also installed, `web-search` is enabled too. |
-| `/web learn` | **Browsing + guide-saving** — same as `on`, plus the `web-learn` tool is available so the AI can save/update navigation guides on request. |
-| `/web off` | **All web tools hidden** — saves ~1500–2000 tokens per turn by removing tool schemas from the prompt. `web-fetch` and `web-search` are also hidden. |
+| ------- | ------ |
+| `/web on` | **Browsing only**: all interactive browser tools + `web-fetch` are available. `web-learn` is hidden. If `pi-lean-search` is also installed, `web-search` is enabled too. |
+| `/web learn` | **Browsing + guide-saving**: same as `on`, plus the `web-learn` tool is available so the AI can save/update navigation guides on request. |
+| `/web off` | **All web tools hidden**: saves ~1500–2000 tokens per turn by removing tool schemas from the prompt. `web-fetch` and `web-search` are also hidden. |
 
 ### Check Current State
 
 | Command | Effect |
-|---------|--------|
+| ------- | ------ |
 | `/web` | Show current toggle status and available sub-commands. |
-| `/web status` | **Detailed runtime status** — toggle state, plugin health, active sessions, and profiles on disk. |
-
-### Why Toggle?
-
-- **`/web off`**: When you're done browsing, turning tools off reduces context
-  usage and keeps the agent focused on coding.
-- **`/web learn`**: Only enable this when you want the agent to save navigation
-  guidance for a site. The agent never calls `web-learn` unprompted — it must
-  be in learn mode.
-- **State persists** across `/reload`, `/resume`, `/fork`, and `/tree`
-  navigation — the toggle remembers what you chose.
-
-### Persistence
-
-The toggle state is stored in the conversation's branch history. A fresh
-conversation starts with the default from `settings.json` (`browserToggle.defaultEnabled`,
-which defaults to `true`).
-
-> ⚠️ `browserToggle.defaultEnabled` is still read today but is scheduled to be
-> replaced by the `pi-tool-masking` library's `toolsetDefaults` block in an
-> upcoming release — **that block is not read yet**, so keep the legacy key
-> until the replacement ships. See
-> [Configuration (`settings.json`)](#configuration-settingsjson) for the
-> future shape and how to pre-add it harmlessly. A migration warning fires on
-> session start once the legacy key is present and the web default hasn't yet
-> been mirrored into `toolsetDefaults`.
-
----
-
-## All 12 Tools
-
-`pi-lean-portal` registers 12 tools. The first 9 require a **browser session**
-(created by `browser-navigate`). `web-fetch`, `web-guide`, and `web-learn` are stateless.
-
-**Auto-captured screenshots:** `browser-navigate` and `browser-snapshot` automatically
-capture a screenshot to a temp file (`/tmp/pi-lean-portal/screenshot-<taskId>.jpg`).
-Use the `read` tool to visually inspect the page when the accessibility tree isn't enough.
-Screenshots capture the 1280×720 viewport (not full-page) — the same viewport the
-browser uses for navigation.
-
-### 1. `browser-navigate` — Visit a Page
-
-Navigates to a URL using a browser plugin (default: Chromium). Returns an
-accessibility tree annotated with **@e1, @e2, …** element references.
-
-```text
-Title: Example Domain
-URL: https://example.com
-Backend: chromium
-Interactive elements: 3
-
-  link "More information..." [@e1]
-    → https://www.iana.org/domains/example
-  …
-```
-
-**Parameters:**
-
-- `url` — the target URL
-- `strategy` (optional) — `"auto"` (default) or a plugin name like `"chromium"` or `"firefox"`
-- `timeout` (optional) — seconds, default 30, max 120
-- `profile` (optional) — `"none"`, `"session"`, or a named profile (see
-  [Profiles](#profiles--persistent-sessions))
-
-**Output includes:**
-
-- Page title, URL, backend name, element count
-- Profile info when using profiles
-- Bot detection warning when applicable
-- Screenshot file path for visual inspection
-- Guide footer appended when relevant guides apply
-
-### 2. `browser-snapshot` — Refresh the Accessibility Tree
-
-Returns the current page's accessibility tree with up-to-date `@e` refs. Also
-captures a screenshot to a temp file (path in output). Use after clicking, typing,
-or scrolling to get fresh element references.
-
-- `full=true` — returns the complete tree (by default it's compacted to
-  ~2500 characters for LLM efficiency)
-
-### 3. `browser-click` — Click an Element
+| `/web status` | **Detailed runtime status** including toggle state, plugin health, active sessions, and profiles on disk. |
 
 ```text
-browser-click ref="@e5"
+🌐 Browser tools: ✅ on  |  📖 Learn mode: ❌ off
+────────────────────────────────────────
+Status: idle
+Plugins: chromium, firefox, chromium-py (disabled), firefox-py (disabled)
+Use web-fetch for stateless HTTP fetches.
+Active sessions: 1
+  PW [chromium] https://example.com — Example Domain [profile: session]
+Profiles: 1 on disk (named)
+  shopping  (0.3 KB) ← active
+Session profiles: 1 (manage with /web profile)
 ```
 
-Clicks the element identified by its `@e` reference. Returns a fresh snapshot
-of the page after the click.
-
-### 4. `browser-type` — Type Into a Field
-
-```text
-browser-type ref="@e3" text="hello world"
-```
+### Persistence
 
-Clears the input, then types the given text. Works on textboxes, searchboxes,
-and comboboxes.
+Toggle state persists across `/reload`, `/resume`, `/fork`, and `/tree` — it's
+stored in the conversation's branch history. Fresh conversations start from
+the `toolsetDefaults` block in `settings.json`
+([Configuration](#configuration-settingsjson)).
 
-### 5. `browser-scroll` — Scroll the Page
+---
 
-```text
-browser-scroll direction="down"
-```
+## Profiles — Persistent Sessions
 
-Scrolls approximately one viewport height. Returns a fresh snapshot.
+Profiles let the AI agent maintain persistent browser state (cookies,
+localStorage) across calls, conversations, and even across different subagents.
 
-### 6. `browser-back` — Go Back
+### Profile Modes
 
-Navigates back in browser history. Returns the previous page's snapshot.
+| Mode | `browser-navigate profile=` | Behavior |
+| ---- | --------------------------- | -------- |
+| None | `"none"` | Clean slate every time (no cookies or state) |
+| Session | `"session"` (default) | Persists state for the current conversation; survives `/reload` and `/resume` |
+| Named | `"shopping"`, `"work"`, etc. | Shared across conversations and subagents, similar to browser tabs sharing a profile |
 
-### 7. `browser-press` — Press a Keyboard Key
+### Managing Profiles with `/web profile`
 
-```text
-browser-press key="Enter"
-```
+| Sub-command | Effect |
+| ----------- | ------ |
+| `/web profile list` | List all profiles on disk with their state size |
+| `/web profile create shopping` | Create a new named profile |
+| `/web profile session` | Set conversation-scoped default to session mode |
+| `/web profile none` | Reset default to ephemeral (no persistence) |
+| `/web profile shopping` | Switch default profile to an existing named profile |
+| `/web profile clear shopping` | Delete the saved state for a profile (keeps the directory) |
+| `/web profile clear-all --confirm` | Clear ALL profile states |
+| `/web profile prune --confirm` | Remove stale session profiles for ended conversations |
 
-Useful keys: `Enter`, `Tab`, `Escape`, `ArrowDown`, `ArrowUp`, `Backspace`.
+> **How it works:** Profile state is stored at
+> `~/.pi/agent/pi-lean-portal/browser-state/<profile-name>/storage-state.json`.
+> Session-scoped profiles are auto-cleaned when the pi conversation ends.
 
-### 8. `browser-console` — Read Console / Run JS
+---
 
-Three modes:
+## Cookie Management
 
-| Usage | Effect |
-|-------|--------|
-| `browser-console expression="document.title"` | Evaluates JS and returns the result |
-| `browser-console` (no params) | Returns captured console messages (log, warn, error, info) |
-| `browser-console clear=true` | Clears the captured console log |
+The `/web cookies` command lets you inspect and clear session cookies:
 
-### 9. `browser-inspect` — Targeted Element Discovery
+| Sub-command | Effect |
+| ----------- | ------ |
+| `/web cookies list` | List all cookies in the current session (name, value, domain, expiry, flags) |
+| `/web cookies clear --confirm` | Clear ALL cookies for the current session |
 
-A lighter alternative to loading a full snapshot. Queries the page for specific
-elements or extracts text content.
+> Cookies are saved as part of profile state. When you switch profiles,
+> the cookies from the old profile are preserved and the new profile's
+> cookies are loaded.
 
-| Parameter | Example | Effect |
-|-----------|---------|--------|
-| `role` | `"link,button"` | Filter by ARIA role(s) |
-| `name` | `"Submit"` | Filter by accessible name (case-insensitive) |
-| `ref` | `"e5"` | Look up a specific `@e` ref |
-| `subtree` | `"dialog"` | Scope to elements inside a container |
-| `text` | `true` | Run DOM text extractor with `@e` annotations |
-| `maxChars` | `500` | Limit output length; `0` for full content |
-| `query` | `"pricing"` | Keyword filter (only active with `text=true`) |
+---
 
-> **Tip:** Use `browser-inspect role="dialog"` to quickly check for consent
-> dialogs without loading the full tree.
+## All 12 Tools
 
----
+`pi-lean-portal` registers 12 tools. Three are **stateless**; the rest require
+a **browser session** (created by `browser-navigate`).
 
-## Stateless Fetching (`web-fetch`)
+| Tool | What it does | State |
+| ---- | ------------ | ----- |
+| `web-fetch` | Fetch a URL → Markdown, no browser session | stateless |
+| `web-guide` / `web-learn` | Read / save navigation guides (learn mode via `/web learn`) | stateless |
+| `browser-navigate` | Open a page → accessibility tree with `@e` element refs | session |
+| `browser-snapshot` | Refresh the tree (`full=true` returns the uncompacted tree) | session |
+| `browser-click` / `browser-type` / `browser-scroll` / `browser-back` / `browser-press` | Interact via `@e` refs (click, type, scroll, history, keyboard) | session |
+| `browser-console` | Read captured console messages; also evaluates JS in the page | session |
+| `browser-inspect` | Targeted element/text queries without loading a full snapshot | session |
 
-`web-fetch` is a lightweight, stateless tool that fetches a URL and converts
-HTML to Markdown. It does **not** create a browser session.
+### Automatic Artifacts
 
-**When to use:**
+Session tools save their full output to disk so the agent never needs a second call:
 
-- Static pages, API docs, READMEs, articles
-- Quick lookups where JavaScript isn't needed
-- When the interactive browser is blocked by bot detection — `web-fetch`
-  sometimes succeeds where the browser triggers a challenge
+- **Screenshots**: `browser-navigate` and `browser-snapshot` auto-capture a viewport-sized (1280×720) JPEG to `/tmp/pi-lean-portal/screenshot-<taskId>.jpg`[^1].
+- **Full Snapshots**: Any snapshot compacted for size is cached in full at `/tmp/pi-lean-portal/snapshot-*.txt` (last 2 per task).
 
-**Output handling:**
+Both file paths are surfaced as hints in the tool output, which the agent can follow up with the `read` tool.
 
-- Content is truncated to ~4000 characters inline
-- Larger content is spilled to a temp file in `/tmp/pi-lean-portal/` — the agent can `read` the file with offset/limit for specific sections. This cache ensures that the agent can access the full page content even when it exceeds the LLM's immediate context window.
-- Bot detection and JS-only shells are detected heuristically
+[^1]: Not full-page.
 
 ---
 
-## Navigation Guides (`web-guide` & `web-learn`)
+## Navigation Guides
 
 ### Built-in Pattern Guides
 
 `pi-lean-portal` ships with four built-in pattern guides that appear in the guide footer when relevant:
 
 | Guide | Trigger | What It Covers |
-|-------|---------|----------------|
-| `bot-detection` | When bot blocking is detected | Cloudflare, challenge pages, what NOT to do |
-| `cookie-consent` | When a dialog is detected in the snapshot | Accept/Reject buttons, Escape key, verification |
+| ----- | ------- | -------------- |
+| `bot-detection` | Bot blocking detected (`botDetected`) | Cloudflare, challenge pages, what NOT to do |
+| `cookie-consent` | Dialog detected (`dialogDetected`) | Accept/Reject buttons, Escape key, verification |
 | `pagination` | On-demand | Next buttons, infinite scroll, pages |
 | `search` | On-demand | Search boxes, comboboxes, result lists |
 
 ### Overriding Built-in Guides
 
 A same-named `.md` file in `~/.pi/agent/pi-lean-portal/web-guides/` (e.g.
-`bot-detection.md`) **shadows the builtin entirely** — the whole guide is
+`bot-detection.md`) **shadows the builtin entirely**; the whole guide is
 replaced, not field-merged. To keep a pattern guide firing, include
 `trigger.signal: botDetected` (or `dialogDetected`) in the frontmatter;
 omitting it disables the trigger.
@@ -304,133 +185,41 @@ Site guides and pattern guides live in **disjoint namespaces** — a site guide
 for `www.botdetection.com` does not collide with the `bot-detection` pattern
 guide; both fire when applicable.
 
-### Viewing Guides
-
-```text
-web-guide                           → lists all available guides
-web-guide guide="cookie-consent"    → shows guidance text
-```
-
-The output includes the guide's last updated date and source (`builtin` or
-`user`).
-
-### Creating Your Own Site Guides (`web-learn`)
-
-When the agent is in **learn mode** (`/web learn`), it can save or update
-navigation guidance for specific sites using `web-learn`.
-
-```text
-web-learn domain="reddit.com" content="…guidance text…"
-```
-
-This creates a `.md` file with YAML frontmatter in `~/.pi/agent/pi-lean-portal/web-guides/`.
-The guide becomes available immediately via `web-guide` and appears in the guide footer on
-future navigations to that domain.
-
-**Learn mode is off by default** — the agent never saves guides unprompted.
-You must explicitly enable it with `/web learn`.
-
----
-
-## `/web status` — Detailed Runtime Status
-
-```text
-/web status
-```
-
-Shows everything about the browser runtime in one notification:
-
-```text
-🌐 Browser tools: ✅ on  |  📖 Learn mode: ❌ off
-────────────────────────────────────────
-Status: idle
-Plugins: chromium, firefox, chromium-py (disabled), firefox-py (disabled)
-Use web-fetch for stateless HTTP fetches.
-Active sessions: 1
-  PW [chromium] https://example.com — Example Domain [profile: session]
-Profiles: 1 on disk (named)
-  shopping  (0.3 KB) ← active
-Session profiles: 1 (manage with /web profile)
-```
-
-Covers:
-
-- **Toggle state** — whether browser/learn tools are active in the agent's context
-- **Backend health** — idle, busy, or error state
-- **All registered plugins** — enabled/disabled status
-- **Active sessions** — current URL, title, profile name per session
-- **Profiles on disk** — named profiles with state size and which is
-  currently active; session profiles are collapsed into a single count line
-  (inspect individually with `/web profile list`)
-
-When `pi-lean-search` is also installed, the status bar shows two independent
-glyphs: `● idle` (browser state) and `● searxng` (search health/state).
-
----
-
-## Profiles — Persistent Sessions
-
-Profiles let the AI agent maintain persistent browser state (cookies,
-localStorage) across calls, conversations, and even across different subagents.
-
-### Profile Modes
-
-| Mode | `browser-navigate profile=` | Behavior |
-|------|-----------------------------|----------|
-| None | `"none"` | Clean slate every time — no cookies, no state |
-| Session | `"session"` (default) | Persists state for the current conversation; survives `/reload` and `/resume` |
-| Named | `"shopping"`, `"work"`, etc. | Shared across conversations and subagents — like browser tabs sharing a profile |
-
-### Managing Profiles with `/web profile`
-
-All profile management happens through the `/web profile` command:
-
-| Sub-command | Effect |
-|-------------|--------|
-| `/web profile list` | List all profiles on disk with their state size |
-| `/web profile create shopping` | Create a new named profile |
-| `/web profile session` | Set conversation-scoped default to session mode |
-| `/web profile none` | Reset default to ephemeral (no persistence) |
-| `/web profile shopping` | Switch default profile to an existing named profile |
-| `/web profile clear shopping` | Delete the saved state for a profile (keeps the directory) |
-| `/web profile clear-all --confirm` | Clear ALL profile states |
-| `/web profile prune --confirm` | Remove stale session profiles for ended conversations |
-
-> **How it works:** Profile state is stored at
-> `~/.pi/agent/pi-lean-portal/browser-state/<profile-name>/storage-state.json`.
-> Session-scoped profiles use names like `_session-<piSessionId>` and are
-> auto-cleaned when the pi conversation ends.
+### Domain Matching
 
----
+A guide's declared domain matches the **exact hostname or any subdomain of
+it**. Declaring `reddit.com` covers `www.reddit.com`, `old.reddit.com`, and
+any other subdomain, so a guide saved once resurfaces across a site's URL
+variations. This is what makes guides cheap to author: you rarely need more
+than the apex domain. A domain may match multiple guides (a web guide plus
+one or more API guides) — all matching guides surface together, sorted
+host-first (API guides before web guides).
 
-## Cookie Management
+### API guides from `pi-lean-host` (co-install)
 
-The `/web cookies` command lets you inspect and clear session cookies:
-
-| Sub-command | Effect |
-|-------------|--------|
-| `/web cookies list` | List all cookies in the current session (name, value, domain, expiry, flags) |
-| `/web cookies clear --confirm` | Clear ALL cookies for the current session |
-
-> Cookies are saved as part of profile state. When you switch profiles,
-> the cookies from the old profile are preserved and the new profile's
-> cookies are loaded.
+When `pi-lean-host` is installed alongside portal and `/api` is on, its
+user-authored API guides also **surface in the navigate footer** alongside
+your web guides using the same reactive mechanism, with no extra setup. API guides sort
+first (API access is cheaper than browsing) but both always appear, so a
+partial-coverage API keeps its web guide for the gaps the API doesn't cover.
+The footer routes API guides to `api-guide({domain, guide})` rather than
+`web-guide`. See the
+[host README](https://github.com/coreyryanhanson/pi-lean-dimension/blob/main/packages/pi-lean-host/README.md#co-installing-with-pi-lean-portal)
+for the host side of the contract.
 
 ---
 
 ## Backend Architecture
 
 `pi-lean-portal` uses a **plugin-based architecture**. The core framework is
-backend-agnostic — plugins implement a standard `BrowserPlugin` interface,
+backend-agnostic; plugins implement a standard `BrowserPlugin` interface,
 and the router dispatches tool calls to the right plugin based on a
 `strategy` parameter.
 
 ### Four Shipped Backends
 
-The extension ships with **four browser backends** out of the box:
-
 | Backend | Engine | Type | Default |
-|---------|--------|------|---------|
+| ------- | ------ | ---- | ------- |
 | `chromium` | Chromium | Node/Playwright | **Enabled** (auto strategy) |
 | `firefox` | Firefox | Node/Playwright | **Enabled** |
 | `chromium-py` | Chromium | Python/Playwright | Disabled |
@@ -440,134 +229,43 @@ The extension ships with **four browser backends** out of the box:
 > `firefox` backend. For the Python parity backends, install Playwright
 > inside `backends/python-base/.venv`.
 
-### Plugin Capabilities
-
-All four shipped backends share the same capability set (they all use
-Playwright under the hood). The router adapts based on each plugin's
-capability advertisement:
-
-| Capability | Chromium / Firefox (Node) | `-py` backends (Python) |
-|------------|--------------------------|------------------------|
-| Full-page screenshots | ✅ | ✅ |
-| Console message capture | ✅ | ✅ |
-| JavaScript evaluation | ✅ | ✅ |
-| Bot detection | ✅ | ✅ |
-| Dialog auto-dismissal | ✅ | ✅ |
-| AbortSignal support | ✅ | Advertised, silently ignored |
+All four shipped backends support screenshots (viewport-sized, not
+full-page), console capture, JS evaluation, bot detection, and dialog
+auto-dismissal. The one divergence:
+`AbortSignal` is advertised but silently ignored on the Python `-py` backends.
 
-> The `-py` Python backends are disabled by default. They ship as parity
-> references for the Python bridge contract and as templates for users
-> authoring their own Python-based backends (see the custom backends
-> section below). Keep `chromium-py` as a reference when reading the
-> bridge code.
+> The `-py` backends are disabled by default, as they ship as parity references
+> for the Python bridge contract and as templates for authoring your own
+> Python-based backends.
 
 ### How Plugin Selection Works
 
-- The **order** of plugins in the config array determines priority — the
+- The **order** of plugins in the config array determines priority; the
   first enabled plugin is the "auto" default (typically Chromium).
 - The **AI agent explicitly selects** which backend to use via the
   `strategy` parameter in `browser-navigate`:
   - `strategy="auto"` → uses the first enabled plugin (typically Chromium)
   - `strategy="firefox"` → uses the Firefox Node backend
   - `strategy="chromium-py"` → uses the Python Chromium backend
-- **No automatic fallbacks** and **no mid-session transitions** — if a
+- **No automatic fallbacks** and **no mid-session transitions**. If a
   plugin fails, the agent decides what to do next.
-- 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
 
-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. 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
-{
-  "browser": {
-    "plugins": [
-      { "name": "chromium", "dir": "chromium", "enabled": true, "config": {} },
-      { "name": "firefox", "dir": "firefox", "enabled": true, "config": {} },
-      { "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 }
-        }
-      }
-    ]
-  }
-}
-```
-
-`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.
+Stealth engines like **Camoufox** are intentionally **left to users** to
+author: drop a `bridge.py` into
+`~/.pi/agent/pi-lean-portal/user-backends/<name>-py/` — a separate tree
+from the package's `backends/` directory (never edited after install,
+so custom backends survive updates) and never in the default fallback list.
+Register one in `browser.plugins` with an **absolute** `pythonPath` (see
+[Configuration](#configuration-settingsjson)).
+
+The full install flow, the quirks schema, and the worked Camoufox template
+live in
+[`contributed/README.md`](https://github.com/coreyryanhanson/pi-lean-dimension/blob/main/packages/pi-lean-portal/contributed/README.md);
+[`contributed/CHOOSING.md`](https://github.com/coreyryanhanson/pi-lean-dimension/blob/main/packages/pi-lean-portal/contributed/CHOOSING.md)
+covers when to reach for one at all (most users never need one).
+Node-based custom backends follow the same shape via `PlaywrightPluginBase`.
 
 ---
 
@@ -587,7 +285,7 @@ Controls which browser backends are loaded. Entries are processed in order
     "plugins": [
       {
         "name": "chromium",    // Required: unique plugin identifier
-        "dir": "chromium",     // Required: directory under backends/
+        "dir": "chromium",     // Required: backend directory
         "enabled": true,       // Optional, defaults to true
         "config": {}           // Optional, passed to the plugin's init()
       }
@@ -596,11 +294,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 `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).
+A user-installed stealth backend additionally puts an **absolute** `pythonPath`
+and a `launch` object into `config` — see
+[`contributed/README.md`](https://github.com/coreyryanhanson/pi-lean-dimension/blob/main/packages/pi-lean-portal/contributed/README.md#6-register-in-settingsjson).
 
 ### `browser.defaultProfile`
 
@@ -615,48 +311,28 @@ a `profile` parameter:
 }
 ```
 
-### `browserToggle.defaultEnabled` *(deprecated — not yet replaced)*
+### `toolsetDefaults`
 
-Whether browser tools are enabled on fresh conversations. **This key is still
-read today and works as shown.** It is *scheduled* to be replaced by the
-`pi-tool-masking` library's `toolsetDefaults` block in an upcoming release —
-**that block is not read yet**, so keep this key until the replacement ships.
+Whether browser tools are enabled on fresh conversations. Read by the
+`pi-tool-masking` library at restore time, between the chat-branch tier and
+the toolset's packaged default:
 
 ```jsonc
 {
-  "browserToggle": {
-    "defaultEnabled": true
+  "toolsetDefaults": {
+    "toolset-state:pi-lean-dimension.web": { "enabled": true },
+    "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
+    "toolset-state:pi-lean-dimension.search": { "enabled": true }
   }
 }
 ```
 
-> ⚠️ **Preparing for the offload.** Settings-based toolset defaults are being
-> offloaded to the `pi-tool-masking` library, which will read a new
-> `toolsetDefaults` block keyed by persist key. **The new block is not read
-> by the current release** — it's harmless to add now and will take effect
-> automatically once the offload ships, at which point the legacy key stops
-> being read. To pre-stage the migration, set both:
->
-> ```jsonc
-> {
->   "browserToggle": { "defaultEnabled": true },
->   "toolsetDefaults": {
->     "toolset-state:pi-lean-dimension.web": { "enabled": true },
->     "toolset-state:pi-lean-dimension.web-learn": { "enabled": false },
->     "toolset-state:pi-lean-dimension.search": { "enabled": true }
->   }
-> }
-> ```
->
-> - Keys are the toolsets' `persistKey` values (`toolset-state:<id>`).
-> - Omit a `toolsetDefaults` key to use the toolset's packaged default (`web`
->   and `search` default `true`; `web-learn` defaults `false`).
-> - The `search` key only applies when `pi-lean-search` is installed.
->
-> Once the offload ships and the legacy read is removed, delete the
-> `browserToggle` block. Until then, a migration warning fires on session
-> start when the legacy key is present and the web default hasn't yet been
-> mirrored into `toolsetDefaults`; mirroring it suppresses the warning.
+- Keys are the toolsets' `persistKey` values (`toolset-state:<id>`).
+- Omit a `toolsetDefaults` key to use the toolset's packaged default (`web`
+  and `search` default `true`; `web-learn` defaults `false`).
+- The `search` key only applies when `pi-lean-search` is installed.
+- Pins do not apply in spawned subagent children (see pi-tool-masking
+  1.3.0's `piToolMasking.childPolicy` for the opt-out).
 
 ### `browser.maxStorageStateSize`
 
@@ -677,61 +353,30 @@ Size threshold for profile state warnings (default: 10 MB):
 ### When to use `web-fetch` vs `browser-navigate`
 
 | Use `web-fetch` | Use `browser-navigate` |
-|-----------------|----------------------|
+| --------------- | ---------------------- |
 | Static content, docs, READMEs | Interactive pages, JS-heavy SPAs |
 | Quick lookups, no session needed | Form filling, clicking, authentication |
-| Bot-detected pages (fallback) | Visual inspection (auto-captured screenshots) |
-| Content you want as clean Markdown | Pages where you need the accessibility tree |
-
-### Working with `@e` Element References
-
-- `@e1`, `@e2`, etc. are assigned based on the accessibility tree order
-- `browser-click`/`type`/`scroll` already return a fresh snapshot and cache
-  the full tree to disk — no separate `browser-snapshot` needed unless you
-  want the uncompacted tree (`full=true`) or a screenshot
-- `browser-inspect` is cheaper than `browser-snapshot full=true` for finding
-  specific elements
+| Content you want as clean Markdown | Visual inspection (auto-captured screenshots), pages where you need the accessibility tree |
 
-### Navigating Large Pages
+### Working with `@e` Element References & Large Pages
 
-- Snapshots are automatically compacted to ~2500 characters
-- Very large pages (>8000 chars) preserve the top ~2000 chars
-- The **full tree is cached to disk** at `/tmp/pi-lean-portal/snapshot-*.txt`
-  when it would otherwise be truncated — use `read` on the cache file with
-  offset/limit to retrieve the complete tree
-- `browser-inspect text=true query="keyword"` finds specific content without
-  loading the full tree
+The agent interacts via `@e1`, `@e2` refs from the accessibility tree —
+no CSS selectors or XPath. Snapshots are auto-compacted to ~2500 chars;
+full trees and screenshots spill to `/tmp/pi-lean-portal/` (paths are
+surfaced in tool output).
 
 ### Bot Detection
 
-When a page triggers anti-automation:
-
-1. The agent sees a warning in the navigate output
-2. The **bot-detection guide** footer appears with strategies available via `web-guide`
-3. If very few elements are detected (<5), the navigation is treated as
-   a hard failure — the agent won't try to interact with a challenge page
-4. Retry with a stealth backend — the `browser-navigate` `strategy`
-   parameter lists registered backend names; a stealth backend (e.g.
-   `strategy="camoufox"`) can pass challenges the default `chromium`/
-   `firefox` triggers. Only names listed in the `strategy` description
-   are valid — there is no `"stealth"` alias
-5. Try `web-fetch` on the same URL — it skips JS execution, so it can
-   retrieve raw HTML on pages that block the interactive browser via
-   client-side fingerprinting (it won't help against server-side WAFs)
-
-### Guide Creation Discipline
-
-When creating navigation guides with `web-learn`:
-
-- Keep guidance **concise** (≤800 chars recommended)
-- Focus on: page structure, consent dialogs, known quirks, and useful
-  selector patterns
-- Include domains so the guide appears in the footer on future navigations
-- No runtime enforcement on guide length, but brevity helps the LLM
+When a page triggers anti-automation, the agent sees a warning plus a
+bot-detection guide footer, and challenge pages with <5 visible elements
+fail hard rather than being interacted with. If a site consistently blocks
+the shipped Chromium/Firefox, that's the trigger to install a stealth
+backend (see [Stealth & Custom Browser Backends](#stealth--custom-browser-backends)) —
+not something to configure up front.
 
 ### Security
 
-- URLs are parsed with `new URL()` as input validation — malformed
+- URLs are parsed with `new URL()` as input validation. Malformed
   URLs are rejected, but no SSRF boundary is enforced (a coding agent
   already has filesystem and shell access, so blocking localhost or
   private IPs would be theater)
@@ -740,9 +385,4 @@ When creating navigation guides with `web-learn`:
 
 ---
 
-> `pi-lean-portal` is part of the
-> [pi-lean-dimension](https://github.com/coreyryanhanson/pi-lean-dimension)
-> web-tools suite. For questions, issues, or feature requests, check the
-> project's documentation or open an issue.
->
 > License: AGPL-3.0-only