@vibebrowser/mcp 0.2.5 → 0.2.7

package/docs/eval.md

@@ -7,7 +7,7 @@ This document tracks the current validation matrix for the `vibebrowser-mcp` and
 - published npm validation (`@vibebrowser/mcp@latest`)
 - real-extension browser evals versus fake-extension protocol evals
 
-Evaluation date: **March 25, 2026 (America/Los_Angeles)**.
+Evaluation date: **March 26, 2026 (America/Los_Angeles)**.
 
 ## Coverage Matrix
 
@@ -16,6 +16,7 @@ Evaluation date: **March 25, 2026 (America/Los_Angeles)**.
 | Relay race regression | `npm run test:e2e:relay-race` | local | fake extension socket | relay preserves in-flight tool calls across extension reconnects |
 | HTTP MCP transport | `npm run test:e2e:http` | local | fake extension socket | streamable HTTP MCP path works end to end |
 | OpenClaw-compatible browser CLI | `npm run test:e2e:browser-cli` | `local`, `pack`, `npm` | fake extension socket | `vibebrowser-cli` command shape, JSON output, and tool routing work end to end |
+| Live browser CLI regression | `npm run test:e2e:browser-cli-live` | local | real extension session | validates `open`/`snapshot` behavior on a real URL against the connected Vibe extension |
 | Codex + OpenCode MCP bridge | `npm run test:e2e:agents` | `local`, `pack`, `npm` | real extension session | packaged `vibebrowser-mcp` can be launched by Codex/OpenCode tooling and route MCP traffic to a real Vibe-connected browser |
 | OpenCode financial eval (`../vibe`) | `node tests/mcp-eval.test.js --skip-build --model github-copilot/gpt-4.1 --mcp-source ...` | `auto`, `local`, `pack`, `npm` | harness-managed browser + extension | full OpenCode browser task execution against the Vibe extension |
 
@@ -119,7 +120,22 @@ Pass signal:
 - `vibebrowser-mcp --help` prints the branded CLI
 - `vibebrowser-cli --help` prints the standalone OpenClaw-compatible CLI
 
-### 4. Real-extension agent eval
+### 4. Published npm CLI validation
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --version
+npx -y --package @vibebrowser/mcp@latest vibe-mcp --version
+npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --version
+E2E_BROWSER_CLI_SOURCE=npm node scripts/e2e-browser-cli.mjs
+```
+
+Pass signal:
+
+- all three binaries print the published version
+- `browser cli e2e ok` proves `vibebrowser-cli` works from the npm registry package, not only from a local tarball
+
+### 5. Real-extension agent eval
 
 ```bash
 cd /Users/engineer/workspace/vibebrowser/vibe-mcp
@@ -136,8 +152,69 @@ Hard requirement:
 
 - a live Vibe extension session must already be connected or connectable on the relay path
 - this harness does **not** prove anything if the extension is absent
+- default Codex settings are tuned for current CLI compatibility:
+  - `E2E_CODEX_MODEL=gpt-5`
+  - `E2E_CODEX_REASONING_EFFORT=low`
+  - `E2E_CODEX_TIMEOUT_MS=480000`
+
+### 5a. Live browser CLI regression (real extension)
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+npm run test:e2e:browser-cli-live
+```
+
+Optional env overrides:
+
+- `BROWSER_LIVE_URL` (default: X search URL from issue repro)
+- `BROWSER_LIVE_TIMEOUT_MS` (default: `60000`)
+- `BROWSER_LIVE_MIN_CONTENT_CHARS` (default: `200`)
+
+Pass signal:
+
+- output contains `live browser cli e2e ok`
+- output prints measured `open latency`, content lengths, and matched `pageId`
+- test proves real-extension `open` + page-content + `snapshot --page-id` flow (not mocked)
+
+### 5b. Latest built extension eval via Chrome for Testing
+
+Build the dev extension first:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe
+npm run build:extension:dev
+```
+
+Use the direct script form when debugging the isolated path, especially from a detached worktree where `../vibe` discovery may not point at the intended sibling repo:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_DEBUG=1 \
+E2E_TEST_BROWSER=1 \
+E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe \
+E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev \
+E2E_MCP_SOURCE=npm \
+node scripts/e2e-mcp-agents.mjs
+```
+
+Use the package-script entrypoint for the canonical repo-level check:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_TEST_BROWSER=1 \
+E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe \
+E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev \
+E2E_MCP_SOURCE=npm \
+npm run test:e2e:agents
+```
+
+Pass signal:
+
+- output contains `e2e ok`
+- the eval launches a separate Chrome for Testing instance
+- the loaded extension comes from `../vibe/dist/extension/dev`, not the user’s daily Chrome profile
 
-### 5. Full OpenCode browser eval in sibling repo
+### 6. Full OpenCode browser eval in sibling repo
 
 ```bash
 cd /Users/engineer/workspace/vibebrowser/vibe
@@ -169,10 +246,18 @@ Commands executed in this session:
 | `npm pack --json --pack-destination <tmp>` | PASS | tarball includes both `dist/cli.js` and `dist/browser-main.js` plus docs/openclaw skill files |
 | `npx -y --package <local-tarball> vibebrowser-mcp --help` | PASS | branded `vibebrowser-mcp` binary available from package artifact |
 | `npx -y --package <local-tarball> vibebrowser-cli --help` | PASS | standalone `vibebrowser-cli` binary available from package artifact |
+| `gh workflow run "Publish to npm" --ref release/vibebrowser-cli-0.2.5` | PASS | GitHub publish workflow completed successfully |
+| `npm view @vibebrowser/mcp version dist-tags.latest bin --json` | PASS | npm `latest` is now `0.2.5` and includes `vibebrowser-mcp`, `vibe-mcp`, and `vibebrowser-cli` |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --version` | PASS | published npm binary resolves to `0.2.5` |
+| `npx -y --package @vibebrowser/mcp@latest vibe-mcp --version` | PASS | legacy alias still resolves to `0.2.5` |
+| `npm run test:e2e:agents` | PASS | local `dist/cli.js` path completed all three MiniWoB tasks with Codex + OpenCode against the live extension session |
+| `E2E_MCP_SOURCE=npm npm run test:e2e:agents` | PASS | published npm binary path completed the same three MiniWoB tasks end to end |
+| `E2E_DEBUG=1 E2E_TEST_BROWSER=1 E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev E2E_MCP_SOURCE=npm node scripts/e2e-mcp-agents.mjs` | PASS | debug run against a separate Chrome for Testing instance with the unpacked extension build |
+| `E2E_TEST_BROWSER=1 E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev E2E_MCP_SOURCE=npm npm run test:e2e:agents` | PASS | canonical repo entrypoint passed against the latest built extension in isolated browser mode |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --version` | PASS | standalone CLI is now available from npm `latest` |
+| `E2E_BROWSER_CLI_SOURCE=npm node scripts/e2e-browser-cli.mjs` | PASS | npm-installed `vibebrowser-cli` passed end to end |
+| `npm run test:e2e:browser-cli-live` | PASS | real extension run against X search URL; reported open latency `60718ms`, open content `9119` chars, snapshot content `9564` chars |
 | `E2E_MCP_SOURCE=pack node scripts/e2e-mcp-agents.mjs` | FAIL (environment) | timed out waiting for a live Vibe extension connection on the relay path |
-| `npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --help` | PASS, but stale | published npm has the `vibebrowser-mcp` alias, but not the full new standalone CLI release shape |
-| `npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --help` | FAIL | `vibebrowser-cli` is not present in the current npm `latest` release |
-| `npm whoami` | FAIL | `ENEEDAUTH`; publish from this machine is currently blocked |
 
 Observed real-extension agent failure:
 
@@ -184,26 +269,26 @@ Interpretation:
 
 - packaged artifacts are valid locally
 - the standalone CLI branding and binaries are correct in the tarball
-- published npm `latest` is **not yet** updated to the new branded binaries
+- published npm `latest` is now updated to `0.2.5` with all intended binaries
 - real-agent validation currently depends on a live extension session and was not satisfiable in this shell session
 
 ## Publish Reality
 
 Current npm state:
 
-- `npm view @vibebrowser/mcp version dist-tags.latest --json` returned `0.2.4`
-- `@latest` still resolves to a partial older package surface
-- `npm whoami` failed with `ENEEDAUTH`
+- `npm view @vibebrowser/mcp version dist-tags.latest bin --json` returns `0.2.5`
+- `@latest` now includes:
+  - `vibebrowser-mcp`
+  - `vibe-mcp`
+  - `vibebrowser-cli`
+- publish succeeded via GitHub Actions workflow `Publish to npm`
 
 Consequences:
 
-- the new `vibebrowser-mcp` / `vibebrowser-cli` binaries are verified in a local tarball artifact
-- they are **not yet published** to npm from this machine
-- do not claim npm end-to-end availability until:
-  - a new version is cut
-  - publish auth is configured
-  - `npx -y --package @vibebrowser/mcp@<new-version> vibebrowser-cli --help` succeeds
+- the new `vibebrowser-mcp` / `vibebrowser-cli` binaries are published to npm and verified from the registry
+- the remaining non-green item is the real-extension agent eval, which still requires a live Vibe extension session on the relay path
 
 ## Tracking
 
 - Tracking issue: `VibeTechnologies/vibe-mcp#22`
+- Release PR: `VibeTechnologies/vibe-mcp#23`

package/docs/openclaw-local-browser.md

@@ -59,56 +59,91 @@ So the missing piece was a streamable HTTP MCP transport.
 
 That is what `vibebrowser-mcp start --transport http` now provides.
 
-## What to install
+## Prerequisites
+
+You need:
+
+1. **Node.js 18+** - `vibebrowser-mcp` requires Node.js
+2. **Chrome/Brave/Chromium** with the Vibe extension installed
+3. **OpenClaw** configured with an MCP server URL
+
+## What gets installed
 
 The user needs three pieces:
 
 1. the Vibe Co-Pilot browser extension
 2. `vibebrowser-mcp` on the same machine as the browser
-3. an OpenClaw MCP server entry pointing at the local `vibebrowser-mcp` HTTP endpoint
-
-## Step 1: install the Vibe extension
+3. an OpenClaw MCP server entry pointing to the local `vibebrowser-mcp` HTTP endpoint
 
-Install the Vibe Co-Pilot extension from `https://vibebrowser.app`.
+## Step 1: Install the Vibe extension
 
-Then open the extension settings and enable `MCP External`.
+1. Install the Vibe Co-Pilot extension from [Chrome Web Store](https://chromewebstore.google.com/detail/vibe-ai-browser-co-pilot/djodpgokbmobeclicaicnnidccoinado)
+2. Open Chrome and click the Vibe extension icon
+3. Go to **Settings** (gear icon)
+4. Find **MCP External** (or "MCP External Control")
+5. Enable it and select **Remote** mode
+6. Copy the **Extension UUID** shown - you'll need this for the next step
 
-For cloud OpenClaw, choose **Remote** mode and copy the **Extension UUID**.
+> **Note**: The Extension UUID is a unique identifier that allows `vibebrowser-mcp` to connect to your specific browser session through the Vibe relay.
 
-## Step 2: start the local HTTP bridge
+## Step 2: Start the local HTTP bridge
 
 On the same machine where the browser extension is installed, run:
 
+**Option A: Using the helper command (recommended)**
+
 ```bash
-npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remote <extension-uuid>
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
 ```
 
-By default this starts a local MCP endpoint at:
+This prints the exact commands and MCP URL you need.
 
-```text
-http://127.0.0.1:8788/mcp
+If OpenClaw is running on another machine (for example in the cloud), provide a reachable URL:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid> --public-url https://<reachable-host>/mcp
 ```
 
-If you want the exact OpenClaw-friendly snippet, you can also run:
+**Option B: Manual command**
 
 ```bash
-npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remote <extension-uuid>
 ```
 
-That prints:
+By default this starts a local MCP endpoint at:
 
-- the bridge command
-- the MCP URL to register in OpenClaw
-- a JSON snippet you can paste into config
+```
+http://127.0.0.1:8788/mcp
+```
+
+That loopback URL only works when OpenClaw can reach the same machine. For cloud OpenClaw, register a reachable URL (`--public-url`) instead.
+
+Keep this terminal open - the bridge must stay running for OpenClaw to connect.
 
 For operator workflows and OpenClaw skills, you can also use the OpenClaw-compatible browser CLI surface directly:
 
 ```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli sessions
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> status
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> tabs
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> snapshot --json
 ```
 
+`snapshot` in `vibebrowser-cli` is tool-only and maps directly to extension snapshot tools:
+
+- default (`--format ai`) -> `take_md_snapshot`
+- ARIA (`--format aria`) -> `take_a11y_snapshot`
+
+Use `--page-id <id>` (or `--pageId <id>`) to target a specific tab without switching user focus.
+
+For local relay mode with multiple connected browsers/profiles:
+
+- run `vibebrowser-cli sessions` to list available local session IDs
+- pass `--session <id>` to target one explicitly
+- if omitted, the CLI uses the first connected local session
+
+`open` and `navigate` responses include extracted page content in JSON output (`pageContent`) when page state is modified, so agents can continue without an immediate extra snapshot call.
+
 That CLI accepts the same style of verbs and flags OpenClaw operators expect, but it still targets the Vibe real-browser path rather than an isolated OpenClaw-managed browser profile.
 
 ## Step 3: add the MCP server to OpenClaw
@@ -125,8 +160,47 @@ Register the bridge URL in OpenClaw:
 }
 ```
 
+Use that loopback URL only for same-machine setups. For cloud OpenClaw, set `"url"` to the reachable value you passed through `--public-url`.
+
 Once that is configured, the cloud OpenClaw agent can use the Vibe browser tools through the local bridge.
 
+## Optional: Use the OpenClaw skill for local agents
+
+For OpenClaw agents running locally (not in the cloud) that need access to your real browser, you can use the Vibe skill instead of configuring an MCP server URL.
+
+### Install the skill
+
+Copy `openclaw/vibebrowser/SKILL.md` from this package to your OpenClaw skills directory. The skill provides OpenClaw-compatible CLI commands that target your Vibe-connected browser.
+
+### Configure environment
+
+Set the extension UUID in your shell:
+
+```bash
+export VIBE_EXTENSION_UUID="<your-extension-uuid>"
+```
+
+### Available commands
+
+```bash
+# Check status
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json status
+
+# List tabs
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json tabs
+
+# Open a page
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json open https://example.com
+
+# Click element by index
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json click 12
+
+# Type into element
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json type 23 "hello"
+```
+
+See [`openclaw/vibebrowser/SKILL.md`](../openclaw/vibebrowser/SKILL.md) for the full command reference.
+
 ## When to use this setup
 
 This architecture is the right fit when the agent needs the **user's own browser context**, for example:
@@ -171,3 +245,30 @@ That is a much better fit than asking users to move their life into a fresh clou
 The end result is simple:
 
 **OpenClaw stays in the cloud. The browser stays local. Vibe MCP connects them cleanly.**
+
+## Troubleshooting
+
+### "Extension UUID not found"
+
+Make sure you've enabled **Remote** mode in the Vibe extension settings. The UUID only appears when Remote mode is active.
+
+### "Connection refused" errors
+
+1. Ensure the `vibebrowser-mcp` process is still running
+2. Check the terminal for error messages
+3. Verify the MCP URL matches exactly (including the `/mcp` path) and is reachable from OpenClaw (not `127.0.0.1` for cloud-hosted OpenClaw)
+
+### "No extension connected"
+
+1. Open Chrome and click the Vibe extension icon
+2. Verify MCP External is enabled in Settings
+3. Check the extension shows "Connected" status
+
+### MCP URL format
+
+The correct format is:
+```
+http://127.0.0.1:8788/mcp
+```
+
+Not `http://127.0.0.1:8788` (missing `/mcp` path).

package/openclaw/vibebrowser/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: vibebrowser
+description: Control the user's local browser through the Vibe Browser CLI bridge. Use this when the task must run against the user's real Vibe-connected browser session, tabs, cookies, or installed extensions.
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🌐",
+        "requires":
+          {
+            "bins": ["npx"],
+            "env": ["VIBE_EXTENSION_UUID"],
+          },
+      },
+  }
+---
+
+# Vibe Local Browser
+
+## Installation
+
+1. **Get the Extension UUID**:
+   - Install the Vibe extension in Chrome
+   - Open extension Settings → MCP External
+   - Enable Remote mode and copy the Extension UUID
+
+2. **Set environment variable**:
+   ```bash
+   export VIBE_EXTENSION_UUID="<your-extension-uuid>"
+   ```
+
+3. **Install the skill**:
+   Copy this file to your OpenClaw skills directory (typically `~/.openclaw/skills/` or your project's `openclaw/skills/` folder).
+
+Use the `vibebrowser-cli` command when the user wants OpenClaw to drive their real local browser through the Vibe extension.
+
+Prefer this skill when the task depends on:
+
+- the user's real browser profile
+- existing logged-in sessions
+- local tabs already open on the user's machine
+- browser extensions or stored site state
+
+Do not use this skill for OpenClaw tenant cloud browsing.
+
+## Required environment
+
+The shell running OpenClaw must have:
+
+```bash
+export VIBE_EXTENSION_UUID="<extension-uuid>"
+
+# Optional if you use a custom relay URL.
+# export VIBE_REMOTE_RELAY_URL="wss://relay.api.vibebrowser.app"
+# export VIBE_RELAY_URL="wss://relay.api.vibebrowser.app"  # legacy alias
+
+# Optional compatibility label. Vibe always targets the real local browser path.
+# export VIBE_BROWSER_PROFILE="user"
+```
+
+## Command form
+
+Prefer this exact command pattern:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json <subcommand> ...
+```
+
+If the package is already installed locally, you can use:
+
+```bash
+vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json <subcommand> ...
+```
+
+If you set `VIBE_RELAY_URL`, append:
+
+```bash
+--relay-url "$VIBE_RELAY_URL"
+```
+
+If you set `VIBE_REMOTE_RELAY_URL`, use:
+
+```bash
+--relay-url "$VIBE_REMOTE_RELAY_URL"
+```
+
+## Deterministic runbook (default)
+
+Use this sequence when the task needs reliable, repeatable control:
+
+1. Verify connection:
+   ```bash
+   npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json status --wait-for-extension --wait-timeout 10000
+   ```
+2. Resolve a target page id without changing focus:
+   ```bash
+   PAGE_ID="$(
+     npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json tabs \
+     | jq -r '.pages[] | select(.active == true) | .id' \
+     | head -n1
+   )"
+   ```
+3. Snapshot that page before acting:
+   ```bash
+   npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id "$PAGE_ID" snapshot --format aria --interactive
+   ```
+   If the aria snapshot is too verbose, try the default first and fall back:
+   ```bash
+   npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id "$PAGE_ID" snapshot
+   # If empty or only title returned, retry with aria:
+   npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id "$PAGE_ID" snapshot --format aria --interactive
+   ```
+4. Perform action on the same page id:
+   ```bash
+   npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id "$PAGE_ID" click 12
+   ```
+
+If `jq` is unavailable, parse `.pages` from `tabs --json` directly and still pass `--page-id <id>` on every action.
+
+## Safe operating rules
+
+- **Never use `focus` or `tab select` unless explicitly asked.** The user may be actively working in the browser — switching their active tab is disruptive. Instead, pass `--page-id <id>` (or `--pageId <id>`) to target a specific tab without switching focus. Get the page ID from `tabs` output, then use it on any command:
+  ```bash
+  vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id 2 snapshot
+  vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id 2 click 7
+  ```
+- Prefer `tabs` or `snapshot` before acting.
+- `snapshot` is tool-only and maps to extension snapshot tools (`take_md_snapshot` by default, `take_a11y_snapshot` for `--format aria`).
+- Use `open <url>` to create a fresh page when possible.
+- Use `evaluate --fn ...` only for simple compatibility-safe expressions such as:
+  - `() => 21 + 21`
+  - `() => document.title`
+  - `() => location.href`
+  - `() => location.hostname`
+  - `() => location.origin`
+- Avoid destructive actions unless the user explicitly asks.
+- If the CLI returns a connection error, report it clearly and stop guessing.
+- The OpenClaw-compatible `--browser-profile` flag is accepted by the CLI, but Vibe always targets the user's real browser path rather than an isolated managed browser.
+
+## Common commands
+
+Status:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json status
+```
+
+List pages:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json tabs
+```
+
+Open a new page:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json open https://example.com
+```
+
+Take the default AI snapshot:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json snapshot
+```
+
+Take the ARIA / interactive snapshot:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json snapshot --format aria --interactive
+```
+
+Click and type using OpenClaw-style refs:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json click 12
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json type 23 "hello" --submit
+```
+
+Evaluate JavaScript:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json evaluate --fn '() => document.title'
+```
+
+## Snapshot format: `ai` vs `aria`
+
+The `snapshot` command supports two extraction formats:
+
+| Format | Flag | Engine | Best for |
+|--------|------|--------|----------|
+| `ai` (default) | `--format ai` | Content script (in-page JS) | Simple pages, articles, search results |
+| `aria` | `--format aria` | CDP accessibility tree | **SPAs, background tabs, Notion, Gmail, complex apps** |
+
+**When the default `--format ai` returns only the page title or empty content**, switch to `--format aria`:
+
+```bash
+# Default — may return empty for background tabs or SPAs like Notion
+vibebrowser-cli ... snapshot
+
+# Reliable fallback — uses Chrome DevTools Protocol directly, works on background tabs
+vibebrowser-cli ... snapshot --format aria --interactive
+```
+
+**Known limitations of `--format ai`:**
+- Returns empty for **background tabs** (content script not injected or `getBoundingClientRect` returns 0x0)
+- Returns `"Could not establish connection"` when the content script is unreachable
+- May miss content behind `aria-hidden` containers in SPAs like Notion
+
+**Rule of thumb:** If `snapshot` returns suspiciously little content, retry with `--format aria --interactive` before reporting failure.
+
+## Success criteria
+
+A successful run usually looks like:
+
+1. confirm the relay is reachable
+2. list current tabs or create a fresh one
+3. navigate or snapshot if needed
+4. evaluate `document.title` or `location.href` to verify the result
+5. summarize what happened for the user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibebrowser/mcp",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "description": "MCP server for browser automation - the only solution supporting multiple AI agents (Claude, Cursor, VS Code) simultaneously controlling your Chrome browser",
   "main": "dist/index.js",
@@ -18,10 +18,14 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build",
-    "test": "npm run test:e2e:relay-race && npm run test:e2e:http && npm run test:e2e:browser-cli",
+    "test": "npm run test:e2e:relay-race && npm run test:e2e:relay-roundtrip && npm run test:e2e:cli-relay && npm run test:e2e:http && npm run test:e2e:browser-cli",
     "test:e2e:browser-cli": "node scripts/e2e-browser-cli.mjs",
+    "test:e2e:cli-relay": "node scripts/e2e-cli-relay.mjs",
     "test:e2e:http": "node scripts/e2e-http-streamable.mjs",
+    "test:e2e:devtools-flag": "node scripts/e2e-devtools-flag.mjs",
+    "test:e2e:browser-cli-live": "node scripts/e2e-browser-cli-live.mjs",
     "test:e2e:relay-race": "node scripts/e2e-relay-fake-extension-race.mjs",
+    "test:e2e:relay-roundtrip": "node scripts/e2e-relay-roundtrip.mjs",
     "test:e2e:agents": "node scripts/e2e-mcp-agents.mjs"
   },
   "keywords": [
@@ -64,6 +68,9 @@
     "commander": "^12.0.0",
     "ws": "^8.18.0"
   },
+  "optionalDependencies": {
+    "chrome-devtools-mcp": "^0.21.0"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/ws": "^8.5.0",