@browserbridge/bbx 1.0.0 → 1.1.0

package/docs/mcp-vs-cli.md

@@ -1,258 +0,0 @@
-# MCP vs CLI
-
-This document compares the two Browser Bridge integration paths:
-**MCP (Model Context Protocol)** and the **CLI skill**.
-
-Short version:
-
-- Choose MCP when your agent supports it.
-- Choose the CLI skill when shell-native `bbx` control is the point.
-- Do not install both by default unless you have a clear reason.
-
-## Overview
-
-| Aspect | MCP | CLI Skill |
-|--------|-----|-----------|
-| **Integration Type** | Native tool protocol | Shell command execution |
-| **Primary Use Case** | Agents with MCP support | Shell-capable agents |
-| **Discovery** | Auto-discovered tools | Skill documentation |
-| **Invocation** | Tool calls | `bbx` commands |
-| **Sandbox Compatibility** | Excellent (no shell required) | Variable (requires shell access) |
-
-## Capability Matrix
-
-### Core Bridge Operations
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Health check | `browser_status`, `browser_health` | `bbx status`, `bbx doctor` | CLI has separate status/doctor |
-| Request access | `browser_access` | `bbx access-request` | Surfaces Enable prompt in extension UI |
-| Setup status | `browser_setup` | `bbx doctor` | Check MCP/skill installation |
-| Request logs | `browser_logs` | `bbx logs` | Equivalent |
-| Runtime presets | `browser_skill` | `bbx skill` | Equivalent |
-| Heuristic investigation | `browser_investigate` | `bbx batch` / `bbx call` sequence | MCP has a dedicated read-only tool; CLI uses scripted structured reads |
-
-### Tab Management
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| List tabs | `browser_tabs` (list) | `bbx tabs` | Equivalent |
-| Create tab | `browser_tabs` (create) | `bbx tab-create [url]` | CLI shortcut |
-| Close tab | `browser_tabs` (close) | `bbx tab-close <tabId>` | CLI shortcut |
-| Tab activation | `browser_tabs` (active param) | `bbx call tabs.create` | CLI needs raw call for `active` param |
-
-### DOM Inspection
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Query DOM | `browser_dom` (query) | `bbx dom-query [selector]` | Equivalent |
-| Describe element | `browser_dom` (describe) | `bbx describe <ref>` | Equivalent |
-| Get text content | `browser_dom` (text) | `bbx text <ref>` | Equivalent |
-| Get HTML | `browser_dom` (html) | `bbx html <ref>` | Equivalent |
-| Get attributes | `browser_dom` (attributes) | `bbx attrs <ref> [attr1,...]` | CLI shortcut |
-| Wait for element | `browser_dom` (wait) | `bbx wait <selector>` | Equivalent |
-| Find by text | `browser_dom` (find_text) | `bbx find <text>` | Equivalent |
-| Find by ARIA role | `browser_dom` (find_role) | `bbx find-role <role>` | Equivalent |
-| Accessibility tree | `browser_dom` (accessibility_tree) | `bbx a11y-tree` | Equivalent |
-
-### Styles & Layout
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Computed styles | `browser_styles_layout` (computed) | `bbx styles <ref> [props]` | Equivalent |
-| Matched CSS rules | `browser_styles_layout` (matched_rules) | `bbx matched-rules <ref>` | CLI shortcut |
-| Box model | `browser_styles_layout` (box_model) | `bbx box <ref>` | Equivalent |
-| Hit test | `browser_styles_layout` (hit_test) | `bbx call layout.hit_test` | CLI uses raw call |
-
-### Page State
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Page state | `browser_page` (state) | `bbx call page.get_state` | CLI uses raw call |
-| JavaScript evaluate | `browser_page` (evaluate) | `bbx eval <expression>` | Equivalent |
-| Console output | `browser_page` (console) | `bbx console [level]` | Equivalent |
-| Wait for load | `browser_page` (wait_for_load) | `bbx call page.wait_for_load_state` | CLI uses raw call |
-| Browser storage | `browser_page` (storage) | `bbx storage [type] [keys]` | Equivalent |
-| Page text | `browser_page` (text) | `bbx page-text [budget]` | Equivalent |
-| Network requests | `browser_page` (network) | `bbx network [limit]` | Equivalent |
-| Performance metrics | `browser_page` (performance) | `bbx perf` | Equivalent |
-
-### Navigation
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Navigate to URL | `browser_navigation` (navigate) | `bbx navigate <url>` | Equivalent |
-| Reload page | `browser_navigation` (reload) | `bbx reload` | CLI shortcut |
-| Go back | `browser_navigation` (go_back) | `bbx back` | CLI shortcut |
-| Go forward | `browser_navigation` (go_forward) | `bbx forward` | CLI shortcut |
-| Scroll viewport | `browser_navigation` (scroll) | `bbx scroll <top> [left]` | CLI shortcut |
-| Resize viewport | `browser_navigation` (resize) | `bbx resize <w> <h>` | Equivalent |
-
-### Input & Interaction
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Click element | `browser_input` (click) | `bbx click <ref> [button]` | Equivalent |
-| Focus element | `browser_input` (focus) | `bbx focus <ref>` | Equivalent |
-| Type text | `browser_input` (type) | `bbx type <ref> <text>` | Equivalent |
-| Press key | `browser_input` (press_key) | `bbx press-key <key> [ref]` | Equivalent |
-| Set checked | `browser_input` (set_checked) | `bbx call input.set_checked` | CLI uses raw call |
-| Select option | `browser_input` (select_option) | `bbx call input.select_option` | CLI uses raw call |
-| Hover | `browser_input` (hover) | `bbx hover <ref>` | Equivalent |
-| Drag | `browser_input` (drag) | `bbx call input.drag` | CLI uses raw call |
-| Scroll target into view | `browser_input` (scroll_into_view) | `bbx call input.scroll_into_view` | CLI uses raw call |
-
-### Patching
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Apply style patch | `browser_patch` (apply_styles) | `bbx patch-style <ref> prop=val...` | Equivalent |
-| Apply DOM patch | `browser_patch` (apply_dom) | `bbx patch-text <ref> <text>` | CLI has text-specific shortcut |
-| List patches | `browser_patch` (list) | `bbx patches` | Equivalent |
-| Rollback patch | `browser_patch` (rollback) | `bbx rollback <patchId>` | Equivalent |
-| Commit baseline | `browser_patch` (commit_baseline) | `bbx call patch.commit_baseline` | CLI uses raw call |
-
-### Capture & Screenshots
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Element screenshot | `browser_capture` (element) | `bbx screenshot <ref> [outPath]` | Equivalent |
-| Region screenshot | `browser_capture` (region) | `bbx call screenshot.capture_region` | CLI uses raw call |
-| Full-page screenshot | `browser_capture` (full_page) | `bbx call screenshot.capture_full_page` | CLI uses raw call |
-| CDP document | `browser_capture` (cdp_document) | `bbx call cdp.get_document` | CLI uses raw call |
-| CDP DOM snapshot | `browser_capture` (cdp_dom_snapshot) | `bbx call cdp.get_dom_snapshot` | CLI uses raw call |
-| CDP box model | `browser_capture` (cdp_box_model) | `bbx call cdp.get_box_model` | CLI uses raw call |
-| CDP computed styles | `browser_capture` (cdp_computed_styles) | `bbx call cdp.get_computed_styles_for_node` | CLI uses raw call |
-
-### Advanced & Raw Protocol
-
-| Capability | MCP Tool | CLI Command | Notes |
-|------------|----------|-------------|-------|
-| Raw protocol call | `browser_call` | `bbx call <method> '{...}'` | Equivalent |
-| Ordered batch calls | `browser_batch` | `bbx batch '[{...}]'` | Both preserve request order and return per-call `durationMs` / `approxTokens` |
-| Batch parallel reads | N/A (multiple tool calls) | `bbx batch '[{...}]'` | CLI has explicit batch |
-| Install manifest | N/A | `bbx install <ext-id>` | CLI-only (setup) |
-| Install MCP config | N/A | `bbx install-mcp [client]` | CLI-only (setup) |
-| Install skill | N/A | `bbx install-skill [client]` | CLI-only (setup) |
-| Uninstall | N/A | `bbx uninstall` | CLI-only (setup) |
-
-## Feature Comparison
-
-### MCP Advantages
-
-| Feature | Description |
-|---------|-------------|
-| **Auto-discovery** | Tools are automatically registered and discovered by MCP clients |
-| **Schema validation** | Input parameters validated via Zod schemas before execution |
-| **Structured responses** | Consistent tool result format with content blocks |
-| **No shell dependency** | Works in sandboxed environments without shell access |
-| **Tool grouping** | Related actions grouped logically (e.g., `browser_dom` with multiple actions) |
-| **Type safety** | Strong typing via input schemas |
-| **Client-native** | Integrated into agent's tool system natively |
-| **Delegation hints** | `browser_investigate` can tell orchestrators to use a smaller, cheaper subagent first |
-
-### CLI Advantages
-
-| Feature | Description |
-|---------|-------------|
-| **Batch execution** | `bbx batch` executes multiple calls concurrently via Promise.all and reports per-call duration/token estimates |
-| **Request logging** | `bbx logs` shows recent bridge request history |
-| **Setup commands** | Built-in install, uninstall, doctor commands |
-| **Shell scripting** | Can be used in scripts, pipes, and CI workflows |
-| **Direct output** | JSON output can be piped to other tools |
-| **Shortcut commands** | Convenient aliases for common operations |
-| **Raw protocol access** | Direct `bbx call` for any method with full parameter control |
-| **Interactive flows** | `bbx doctor` for guided troubleshooting |
-| **Stdin support** | `bbx eval -` reads expression from stdin |
-| **Manual investigation loops** | `bbx batch` makes the same structured-first investigation pattern easy to script |
-
-## Ergonomics Comparison
-
-### MCP Tool Invocation
-
-```
-Tool: browser_dom
-Parameters: { "action": "query", "selector": ".sidebar", "maxNodes": 20 }
-```
-
-### CLI Command Invocation
-
-```bash
-bbx dom-query .sidebar
-# or with full control:
-bbx call dom.query '{"selector": ".sidebar", "maxNodes": 20}'
-```
-
-### Open-Ended Investigation
-
-MCP has a dedicated `browser_investigate` tool for "find out why this is broken" style requests. It is read-only and can carry delegation metadata for a smaller, cheaper subagent.
-
-CLI does not have a separate `bbx investigate` command. The equivalent is a structured-first sequence, usually via one `bbx batch` call:
-
-```bash
-bbx batch '[
-  {"method":"page.get_state"},
-  {"method":"dom.query","params":{"selector":"main","maxNodes":20,"maxDepth":4,"textBudget":600}},
-  {"method":"page.get_text","params":{"textBudget":4000}}
-]'
-```
-
-Escalate to `bbx screenshot`, `screenshot.capture_region`, or `screenshot.capture_full_page` only when those structured reads are insufficient.
-
-### Key Differences
-
-| Aspect | MCP | CLI |
-|--------|-----|-----|
-| Parameter format | JSON object | CLI args or JSON string |
-| Output format | Tool result content | `{ok, summary, evidence}` JSON |
-| Error handling | Tool error response | JSON with `ok: false` |
-| Version drift warnings | Returned in health/status output and surfaced automatically after connect | Returned in summaries and raw response metadata after connect |
-| Access routing | Follows active tab in enabled window by default | Follows active tab in enabled window by default |
-| Explicit targeting | `tabId` on grouped tools | `bbx call --tab <tabId> ...` |
-| Concurrency | Multiple tool calls | `batch` command or parallel shells |
-
-## Use Case Recommendations
-
-### Prefer MCP When:
-
-- Your agent has native MCP support (Claude Code, Cursor, Copilot, etc.)
-- Running in sandboxed environments (GitHub Copilot, containerized agents)
-- You want automatic tool discovery and schema validation
-- You prefer grouped, semantic tool interfaces
-- Integration with IDE tool systems is important
-
-### Prefer CLI When:
-
-- Your agent runs shell commands reliably
-- You need batch execution of multiple reads
-- You want access to setup/install commands
-- You're debugging the bridge itself (`bbx logs`, `bbx doctor`)
-- You're writing scripts or CI workflows
-- You need stdin/stdout piping
-- You prefer direct protocol access
-
-## Client Compatibility Matrix
-
-| Client | MCP Support | CLI Skill Support | Recommended Path |
-|--------|-------------|-------------------|------------------|
-| OpenAI Codex | Yes (TOML config) | Yes | MCP preferred |
-| Claude Code | Yes | Yes | MCP preferred |
-| Cursor | Yes | Yes | MCP preferred |
-| GitHub Copilot | Yes (VS Code) | Limited (sandbox) | **MCP required** |
-| OpenCode | Yes (local type) | Yes | MCP preferred |
-| Antigravity | Yes | Yes | MCP preferred |
-| Windsurf | Yes | Yes | MCP preferred |
-| Generic agents | Yes (`.agents/mcp.json`) | `.agents/skills/` | MCP preferred when available |
-
-## Summary
-
-Both MCP and CLI paths provide full access to Browser Bridge capabilities. The choice depends primarily on your agent's architecture:
-
-1. **MCP** is the recommended path for agents with native MCP support, offering better integration, validation, and sandbox compatibility.
-
-2. **CLI Skill** is ideal for shell-capable agents, scripting scenarios, and when you need batch operations or setup commands.
-
-The underlying protocol is identical: both paths communicate with the same
-native host and extension. Use `browser_call` (MCP) or `bbx call` (CLI) when
-you need method-specific fields not exposed by the grouped tools or shortcut
-commands.

package/docs/publishing.md

@@ -1,114 +0,0 @@
-# Publishing
-
-This is a maintainer document, not an end-user setup guide. End users should
-start with [quickstart](./quickstart.md).
-
-This repo has two release artifacts:
-
-1. The Chrome extension ZIP for the Chrome Web Store
-2. The npm package for the local CLI and native host
-
-The extension is not a standalone product. A store release only becomes usable once the npm package is also published, because the extension depends on the local native host installed by `bbx install <extension-id>`.
-The published npm package now embeds the Browser Bridge store extension ID, so end-user docs for the published build should default to plain `bbx install`. Only unpacked or non-store builds should require `bbx install <extension-id>` or `BROWSER_BRIDGE_EXTENSION_ID=<extension-id>`.
-
-## Release Checklist
-
-1. Bump the version in [package.json](../package.json) and [manifest.json](../manifest.json) together.
-2. Run `npm install` if dependencies changed.
-3. Run `npm run release:check`.
-4. In npm package settings, add a GitHub Actions trusted publisher for this repository and workflow file `release.yml`.
-5. Push the release tag `v<version>` so GitHub Actions publishes the npm package and uploads the extension ZIP artifact.
-6. After the first successful trusted publish, set npm package publishing access to require 2FA and disallow tokens, then revoke any old automation token.
-7. Upload the extension ZIP from `dist/browser-bridge-extension-v<version>.zip`.
-8. Complete the Chrome Web Store listing, privacy fields, and reviewer instructions.
-9. Smoke-test the published extension against the published CLI using `bbx install`.
-
-## Build The Extension ZIP
-
-The repo now includes a reproducible packaging step:
-
-```bash
-npm run package:extension
-```
-
-That stages only the runtime extension files into `dist/browser-bridge-extension/` and writes the upload artifact to:
-
-```bash
-dist/browser-bridge-extension-v<version>.zip
-```
-
-## Publish The npm Package
-
-The package is configured for public publish:
-
-```bash
-npm pack --dry-run
-npm publish --provenance --access public
-```
-
-The release workflow on tag push now performs this publish automatically through npm trusted publishing (OIDC). Manual publish remains a valid fallback when the GitHub workflow is unavailable.
-
-Trusted publishing requires npm CLI `11.5.1+`. The release workflow upgrades npm explicitly before running `npm publish`; if publish fails with `E404` or authentication issues, verify the workflow still prints an npm version at or above that threshold.
-
-## Chrome Web Store Submission
-
-### Store assets you still need to prepare manually
-
-- At least one real product screenshot
-- One 440x280 promotional image
-- A privacy policy URL
-- Support/contact URL or support email in the developer dashboard
-
-The manifest now includes packaged extension icons, but the promo image and screenshots are store-listing assets, not files inside the extension ZIP.
-
-### Single purpose statement
-
-Use one narrow sentence. Suggested draft:
-
-`Browser Bridge lets a local developer agent inspect and patch web pages in an explicitly enabled Chrome window through a local native messaging bridge.`
-
-### Permission justifications
-
-Use reviewer-facing explanations tied to the product purpose:
-
-- `activeTab`: used to bootstrap inspection against the tab the user explicitly enables
-- `debugger`: used for Chrome DevTools Protocol reads and page-context evaluation, such as DOM snapshots, computed styles, screenshots, accessibility data, and page inspection helpers
-- `nativeMessaging`: required to communicate with the local Browser Bridge daemon
-- `scripting`: used to inject and coordinate the scoped page instrumentation flow
-- `sidePanel`: provides the side panel control surface
-- `storage`: persists window approvals, session state, and recent UI state for the current browser session
-- `tabs`: enumerates tabs and validates that a request stays inside the enabled window
-- `offscreen`: used for screenshot cropping in the offscreen document
-- `host_permissions` on `<all_urls>`: needed because the tool is designed to inspect whichever site the user explicitly approves, not a fixed site list
-
-Reviewers will likely scrutinize `debugger`, `nativeMessaging`, and `<all_urls>`. Keep the listing language narrow and explicit about user approval and local-only operation.
-
-### Privacy fields
-
-Current expected answers with the code as it exists today:
-
-- Remote code: do not default this to `No`. Browser Bridge can execute user-requested expressions in page context through the Chrome Debugger API. Answer this honestly in the dashboard and explain that the extension does not load remote-hosted extension scripts.
-- Data collection: disclose the page data the product can access for the enabled window, including browsing/page content, DOM/style/layout data, console output, network metadata, storage values when requested, and screenshots when requested
-- Data sale: `No`
-- Data handling: Browser Bridge itself routes data locally to the native host and connected local client; a connected agent or IDE may still forward data onward under its own policy
-- Privacy policy: must clearly state what data the extension can access, that approval is window-scoped, and that Browser Bridge itself does not operate a Browser Bridge cloud service
-
-If product behavior changes, update the privacy answers before submission.
-
-### Reviewer test instructions
-
-Google marks the Test Instructions tab as optional, but Browser Bridge should still provide it because the product depends on local CLI/native-host setup. Suggested draft:
-
-1. Install the published extension from the draft listing.
-2. Install Node.js 18+ on the same machine.
-3. Run `npm install -g @browserbridge/bbx`.
-4. Run `bbx install`.
-5. If needed, run `bbx-daemon`.
-6. Open any normal web page in Chrome.
-7. Open the Browser Bridge popup or side panel and enable Browser Bridge for the current browser window.
-8. In a terminal, run `bbx status`, `bbx tabs`, and `bbx page-text`.
-
-## Post-Publish Follow-Up
-
-- Update [README.md](../README.md) and [quickstart.md](./quickstart.md) with the real store listing URL.
-- Re-run a live flow with `bbx install` after the first published build is available.

package/docs/quickstart.md

@@ -1,104 +0,0 @@
-# Quickstart
-
-Browser Bridge lets your coding agent inspect and patch the real Chrome tab you already have open - DOM, styles, console, network, and more - without screenshots or raw HTML dumps.
-
-> **Requires:** Google Chrome and Node.js on the same machine as your agent. Remote-only agents (e.g. GitHub.com Copilot) cannot reach a local Chrome instance.
->
-> **Privacy:** Browser Bridge itself sends extension data locally to the companion host and connected local client. Your chosen agent or IDE may still forward tool results onward under its own policy. See [`PRIVACY.md`](../PRIVACY.md).
-
-## 1. Install the extension
-
-Install [Browser Bridge from the Chrome Web Store](https://chrome.google.com/webstore/detail/jjjkmmcdkpcgamlopogicbnnhdgebhie). <!-- TODO: replace with final store link after publishing -->
-
-## 2. Install the CLI
-
-```bash
-npm install -g @browserbridge/bbx
-```
-
-This also installs the native messaging host automatically.
-
-If the extension does not connect itself during setup, run:
-
-```bash
-bbx install
-```
-
-## 3. Connect your agent
-
-There are two integration paths. Pick the one that matches how your agent works:
-
-Supported clients: `codex` (OpenAI Codex), `claude` (Claude Code), `cursor` (Cursor), `copilot` (GitHub Copilot), `opencode` (OpenCode), `antigravity` (Antigravity), `windsurf` (Windsurf), `agents` (generic `.agents` MCP/skill layout).
-
-After installing the extension and CLI, finish the rest from the extension side panel's **Host Setup** section, or use the `bbx install-mcp` / `bbx install-skill` commands below if you prefer terminal setup.
-
-> **Recommendation:** MCP and the CLI skill are not meant to be installed together by default. If your agent supports both, start with MCP. The bridge protocol and browser data are the same either way; the difference is integration style. MCP fits agent tool systems better because it is structured, validated, and does not depend on shell access. Choose the CLI skill when you specifically want direct `bbx` control for shell-driven workflows such as setup, debugging, scripting, or raw protocol calls. If CLI mode is unreliable because the agent runs in a sandboxed shell, such as GitHub Copilot, use MCP instead.
-
-**MCP** - the default path for agents with native MCP tool support. Prefer this when your agent can use either mode. It gives the agent structured tools without relying on shell execution, and it is the best fallback when CLI mode is blocked by sandboxing. Write the config directly into each client's settings file:
-
-```bash
-bbx install-mcp                  # all supported clients
-bbx install-mcp codex            # or pick one: codex, claude, cursor, copilot, opencode, antigravity, windsurf, agents
-bbx install-mcp copilot --local  # scope to current project instead of global
-```
-
-Configs are written globally by default. For GitHub Copilot, that means `~/.copilot/mcp-config.json`; project installs still use `.vscode/mcp.json`. Browser Bridge also writes the older VS Code `User/mcp.json` locations as compatibility fallbacks.
-
-**Skill + CLI** - for agents that can reliably run shell commands and where direct `bbx` control is the better fit than MCP tools. Use this path for shell-driven agent flows, setup and doctor flows, scripting, logs, or raw protocol access. Install the Browser Bridge skill so your agent knows how to drive `bbx`:
-
-```bash
-bbx install-skill                  # all supported clients
-bbx install-skill codex            # or pick one: codex, claude, cursor, copilot, opencode, antigravity, windsurf, agents
-bbx install-skill agents --project .
-```
-
-The Browser Bridge skill is a CLI path. Use `bbx install-skill` for shell-driven agent flows and generic agent runtimes.
-
-Shortcut commands cover the common cases. Advanced protocol fields stay available through `bbx call <method> '{...}'` when you need the full bridge surface, and exact bridge methods can also be invoked directly for the raw path, for example `bbx page.get_state`.
-
-If Browser Bridge does not appear immediately after `bbx install-mcp` or `bbx install-skill`, restart the agent so it reloads MCP config or skill definitions.
-
-> The paths are independent. MCP clients use MCP tools; CLI skill clients use `bbx`. You do not need both. For normal agent use, start with MCP if it is available; choose the CLI skill when shell-native control is the point.
-
-## 4. Enable a window
-
-1. Open the page you want your agent to inspect.
-2. Click the Browser Bridge toolbar icon or open the side panel.
-3. If needed, finish MCP or CLI skill setup from **Host Setup**.
-4. Enable agent communication for the current Chrome window.
-
-Your agent can now inspect and patch the active tab in that enabled window, or other tabs in the same window when explicitly targeted.
-
-## 5. Use it
-
-**MCP mode** - tools are auto-discovered by the client. Just ask naturally:
-
-You can refer to it as `BB MCP` or `Browser Bridge MCP`; both should work.
-
-> *"Why is the sidebar layout broken on this page?"*
-> *"Use BB MCP to inspect why the sidebar layout is broken."*
-> *"Check the CSS on the hero section and fix the spacing."*
-> *"Does my latest change actually render correctly in the browser?"*
-
-**Skill + CLI mode** - reference the skill explicitly so the agent knows to use `bbx`:
-
-> *"Use the browser-bridge skill to check why the sidebar layout is broken."*
-> *"Using browser-bridge skill, verify the hero section spacing and fix it."*
-
-For GitHub Copilot, invoke the skill by name, for example `/browser-bridge`.
-`bbx` is the Browser Bridge CLI command, not a guaranteed Copilot skill alias.
-
-In both cases the agent reads live DOM, styles, console, and network state from your real tab. Patches are reversible and session-scoped. When visual confirmation is still needed after structured reads, prefer a partial element screenshot or a tight region crop instead of a larger page capture before writing the fix back to source.
-
-For open-ended inspection in MCP mode, start with `browser_investigate`. It is read-only and intended to be delegated to a smaller, lower-cost subagent when the client supports delegation. The CLI-skill equivalent is to start with `bbx batch` or `bbx call` using `page.get_state`, `dom.query`, and `page.get_text` before escalating to screenshots.
-
-## 6. Need more detail?
-
-Use the focused guides instead of stretching quickstart into a manual:
-
-- [Documentation index](./index.md)
-- [Manual setup](./manual-setup.md) for custom agents, exact config locations, and project-local installs
-- [Usage scenarios](./usage-scenarios.md) for concrete debugging and patching workflows
-- [CLI guide](./cli-guide.md) for command-oriented usage
-- [MCP vs CLI](./mcp-vs-cli.md) if you are deciding between integration paths
-- [Troubleshooting](./troubleshooting.md) when setup or access fails

package/docs/troubleshooting.md

@@ -1,59 +0,0 @@
-# Troubleshooting
-
-When Browser Bridge is not working, start with local validation before blaming
-the agent integration:
-
-```bash
-bbx status
-bbx doctor
-bbx tabs
-bbx logs
-```
-
-## The extension is installed, but `bbx status` says it is disconnected
-
-- Run `bbx install` again.
-- Confirm the extension is enabled in Chrome.
-- If you are using a published store build that still needs an explicit ID, run `bbx install <extension-id>`.
-- Restart Chrome after reinstalling the native messaging manifest if the host was missing when Chrome launched.
-
-## The agent gets `ACCESS_DENIED`
-
-- The first `ACCESS_DENIED` call automatically surfaces an Enable prompt in the extension UI.
-- Alternatively, call `bbx access-request` (CLI) or use the `browser_access` MCP tool to trigger the prompt proactively.
-- Open the Browser Bridge popup or side panel in Chrome and click Enable.
-- Make sure the page you care about is in that enabled window, not a different Chrome window.
-
-## The agent keeps using the wrong tab
-
-- Browser Bridge defaults to the active tab in the enabled window.
-- Bring the intended tab to the front, then retry.
-- If your workflow needs a specific tab, target it explicitly through MCP parameters or `bbx call --tab <tabId> ...`.
-- Use `bbx tabs` to confirm the tab ID and current active tab.
-
-## The CLI works locally, but the agent cannot use it
-
-- The agent may be running inside a sandboxed shell.
-- Prefer MCP for Copilot and other sandboxed environments.
-- If you intentionally want CLI mode, confirm the agent can execute `bbx` and read the installed Browser Bridge skill.
-
-## `bbx install-skill` or `bbx install-mcp` wrote files, but the client still does not see Browser Bridge
-
-- Restart the agent or client after writing config so it reloads MCP config or skill definitions.
-- Check that you installed into the right scope: global vs project-local.
-- For project-local installs, confirm the client is opened in the same repository where the config was written.
-- For managed paths and examples, see [manual-setup.md](./manual-setup.md).
-
-## Patches disappear
-
-- Patches are session-scoped, not permanent source changes.
-- Navigation, reloads, or session resets can invalidate them.
-- Use patches to prove the fix, then move the result into the codebase.
-
-## What to include in a bug report
-
-- Output summary from `bbx status`
-- Output summary from `bbx doctor`
-- `bbx tabs` for routing context
-- `bbx logs` if the bridge is failing after connection
-- Whether you are using MCP or the CLI skill

package/docs/usage-scenarios.md

@@ -1,136 +0,0 @@
-# Usage Scenarios
-
-Browser Bridge is best when you need the state that already exists in a real Chrome tab: logged-in sessions, seeded storage, feature flags, SPA state, and whatever the page actually rendered.
-
-If you need repeatable clean-room automation for tests or CI, use Playwright or another browser automation stack instead.
-
-## 1. Debug a broken layout in the real page
-
-Use this when the bug only reproduces in your current logged-in or feature-flag state.
-
-Ask an MCP-capable agent:
-
-> Use Browser Bridge MCP to inspect why the sidebar overlaps the main content.
->
-> If your client supports subagents, delegate the investigation to a smaller low-cost worker first.
-
-Ask a CLI-skill agent:
-
-> Use the browser-bridge skill to inspect the broken sidebar layout and tell me which computed styles are causing it.
-
-Useful direct commands:
-
-```bash
-bbx batch '[{"method":"page.get_state"},{"method":"dom.query","params":{"selector":".sidebar","maxNodes":20,"maxDepth":4,"textBudget":600}}]'
-bbx dom-query .sidebar
-bbx box .sidebar
-bbx styles .sidebar display,position,width,left,right,gap
-bbx matched-rules .sidebar
-```
-
-## 2. Verify that a local code change actually rendered
-
-Use this after editing source, before assuming the fix worked.
-
-Typical prompt:
-
-> Check whether the latest navbar change rendered correctly in the browser, and compare the live spacing against the intended layout.
-
-Useful direct commands:
-
-```bash
-bbx call page.get_state
-bbx dom-query nav
-bbx styles nav gap,padding,align-items
-bbx call input.scroll_into_view '{"target":{"selector":"nav"}}'
-bbx screenshot nav ./tmp/navbar.png
-```
-
-## 3. Debug a form or interaction issue
-
-Use this when a click, keyboard interaction, or form control does not behave as expected.
-
-Typical prompt:
-
-> Use Browser Bridge to inspect the submit button, confirm whether it is disabled or covered, then try the interaction again.
-
-Useful direct commands:
-
-```bash
-bbx describe button[type="submit"]
-bbx box button[type="submit"]
-bbx call input.scroll_into_view '{"target":{"selector":"button[type=\"submit\"]"}}'
-bbx click button[type="submit"]
-bbx console error
-bbx network 20
-```
-
-## 4. Prove a live CSS or DOM fix before editing source
-
-Use this when you want to validate the fix in the page first, then port it into
-the codebase.
-
-Typical prompt:
-
-> Inspect the hero spacing, patch the live page until it looks correct, then tell me the minimal source change to make.
-
-Useful direct commands:
-
-```bash
-bbx patch-style .hero gap=24px padding=32px
-bbx patch-text .hero-title "New heading"
-bbx patches
-bbx rollback <patchId>
-```
-
-## 5. Collect compact evidence instead of taking full screenshots
-
-Use this when you want token-efficient evidence for the agent.
-
-Typical prompt:
-
-> Read the visible page state, console errors, and the box model for the checkout summary without dumping the whole DOM.
-
-Useful direct commands:
-
-```bash
-bbx call page.get_state
-bbx console all
-bbx network 20
-bbx box .checkout-summary
-bbx text .checkout-summary medium
-```
-
-If `page.get_console` or `page.get_network` returns `dropped`, the page was
-noisy enough to evict older buffered entries. Narrow the repro and re-run the
-read before assuming you saw the full history.
-
-## 6. Capture the whole document only when the page-level layout is the issue
-
-Use this when a bug spans multiple viewports and tight crops cannot express the
-problem.
-
-Typical prompt:
-
-> Capture the full page so we can verify how the header, hero, and footer line up across the whole document.
-
-Useful direct commands:
-
-```bash
-bbx call input.scroll_into_view '{"target":{"selector":"main"}}'
-bbx call screenshot.capture_full_page '{}'
-```
-
-## 7. Drop to the raw protocol when shortcuts are not enough
-
-Use this when you need a method or parameter that the higher-level commands do
-not expose.
-
-```bash
-bbx call page.get_state
-bbx call dom.query '{"selector":".card","maxNodes":10}'
-bbx batch '[{"method":"page.get_state"},{"method":"page.get_console","params":{"level":"error"}}]'
-```
-
-For a command-oriented walkthrough, see [cli-guide.md](./cli-guide.md). For
-integration choices, see [mcp-vs-cli.md](./mcp-vs-cli.md).