feat(docs): add MCP and Agent CLI documentation sections

agent-cli/capabilities.mdx

@@ -0,0 +1,99 @@
+---
+title: "Capabilities"
+---
+
+# Capabilities
+
+The CLI and MCP share the same underlying Playwright tools, organized into capability groups. In the CLI all capabilities are always available — there's no gating. This page maps commands to their capability groups for reference.
+
+## Core
+
+Always available. Basic browser automation.
+
+| Command | Description |
+|---------|-------------|
+| `open`, `goto`, `close` | Open, navigate, close browser |
+| `go-back`, `go-forward`, `reload` | History navigation |
+| `click`, `dblclick`, `hover`, `drag` | Element interaction |
+| `type`, `fill`, `select` | Text input and dropdowns |
+| `check`, `uncheck` | Checkboxes and radio buttons |
+| `press`, `keydown`, `keyup` | Keyboard input |
+| `snapshot` | Capture accessibility tree |
+| `screenshot` | Take screenshot |
+| `upload` | Upload files |
+| `dialog-accept`, `dialog-dismiss` | Handle dialogs |
+| `resize` | Resize browser window |
+| `eval`, `run-code` | Execute JavaScript / Playwright code |
+
+## Network
+
+Network inspection and mocking.
+
+| Command | Description |
+|---------|-------------|
+| `network` | List network requests since page load |
+| `route` | Mock requests matching a URL pattern |
+| `route-list` | List active mocked routes |
+| `unroute` | Remove mocked routes |
+| `network-state-set` | Set online/offline state |
+
+See [Network & Mocking](./commands/network-routing.mdx) for usage.
+
+## Storage
+
+Cookie, localStorage, and sessionStorage management plus state persistence.
+
+| Command | Description |
+|---------|-------------|
+| `state-save`, `state-load` | Save/restore full browser state |
+| `cookie-list/get/set/delete/clear` | Manage cookies |
+| `localstorage-list/get/set/delete/clear` | Manage localStorage |
+| `sessionstorage-list/get/set/delete/clear` | Manage sessionStorage |
+
+See [Storage & Authentication](./commands/storage.mdx) for usage.
+
+## Vision
+
+Coordinate-based mouse interaction using pixel positions from screenshots. Useful for canvas apps, maps, and custom widgets without accessible elements.
+
+| Command | Description |
+|---------|-------------|
+| `mousemove <x> <y>` | Move mouse to coordinates |
+| `mousedown [button]` | Press mouse button |
+| `mouseup [button]` | Release mouse button |
+| `mousewheel <dx> <dy>` | Scroll with mouse wheel |
+| `screenshot` | Capture viewport for coordinate reference |
+
+See [Vision Mode](./vision-mode.mdx) for when and how to use coordinate-based interaction.
+
+## DevTools
+
+Tracing, video recording, and test debugging.
+
+| Command | Description |
+|---------|-------------|
+| `console` | View console messages |
+| `tracing-start`, `tracing-stop` | Record execution traces |
+| `video-start`, `video-stop`, `video-chapter` | Record session videos |
+| `show` | Open visual dashboard |
+| `pause-at`, `resume`, `step-over` | Test debugging |
+
+## PDF
+
+PDF generation.
+
+| Command | Description |
+|---------|-------------|
+| `pdf` | Export page as PDF |
+
+## Testing
+
+Assertions and test generation tools.
+
+| Command | Description |
+|---------|-------------|
+| `verify-element-visible` | Assert element is visible by role and name |
+| `verify-text-visible` | Assert text is visible |
+| `verify-list-visible` | Assert list with items is visible |
+| `verify-value` | Assert form field value |
+| `generate-locator` | Generate Playwright locator for test code |

agent-cli/commands/attach.mdx

@@ -0,0 +1,128 @@
+---
+title: "Attach"
+---
+
+# Attach
+
+Connect to an existing browser instead of launching a new one.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `attach --cdp=<channel>` | Connect to a running browser by channel name |
+| `attach --cdp=<url>` | Connect via Chrome DevTools Protocol endpoint |
+| `attach --endpoint=<url>` | Connect to a Playwright server endpoint |
+| `attach --extension` | Connect via Playwright MCP Bridge extension |
+
+## Attach by channel name
+
+Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
+
+<img src="/img/mcp/chrome-remote-debugging.png" width="752" height="426" alt="Chrome remote debugging settings at chrome://inspect/#remote-debugging" />
+
+```bash
+# Attach to Chrome
+playwright-cli attach --cdp=chrome
+
+# Attach to Chrome Canary
+playwright-cli attach --cdp=chrome-canary
+
+# Attach to Microsoft Edge
+playwright-cli attach --cdp=msedge
+
+# Attach to Edge Dev
+playwright-cli attach --cdp=msedge-dev
+```
+
+Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.
+
+This is the simplest way to connect — no need to start Chrome with special flags or know the debugging port.
+
+## CDP endpoint
+
+Connect to any Chromium-based browser with a Chrome DevTools Protocol endpoint:
+
+```bash
+# Start Chrome with remote debugging
+google-chrome --remote-debugging-port=9222
+
+# Connect from the CLI
+playwright-cli attach --cdp=http://localhost:9222
+playwright-cli snapshot
+playwright-cli click e5
+```
+
+Works with:
+- Chrome / Chromium with `--remote-debugging-port`
+- Edge with remote debugging
+- Electron apps exposing CDP
+- Cloud browser services (Browserbase, etc.)
+
+## Playwright server endpoint
+
+Connect to a remote Playwright server:
+
+```bash
+playwright-cli attach --endpoint=ws://localhost:3000
+playwright-cli snapshot
+```
+
+## Browser extension
+
+Connect to your existing browser tabs using the [Playwright MCP Bridge extension](https://github.com/microsoft/playwright-mcp/blob/main/packages/extension/README.md). This lets you reuse your logged-in sessions, cookies, and installed extensions.
+
+<img src="/img/mcp/chrome-bridge-extension.png" width="662" height="427" alt="Playwright MCP Bridge extension in Chrome Web Store" />
+
+```bash
+playwright-cli attach --extension
+```
+
+### When to use extension mode
+
+- **SSO / 2FA** — skip complex login flows by reusing your authenticated session
+- **Browser extensions** — interact with pages that depend on installed extensions
+- **Existing tabs** — automate pages you already have open
+
+## Named sessions
+
+Attach creates a session. Use `-s` to name it:
+
+```bash
+playwright-cli attach --cdp=chrome -s=debug-session
+playwright-cli -s=debug-session snapshot
+playwright-cli -s=debug-session click e5
+```
+
+## Workflow: connect to your running Chrome
+
+```bash
+# 1. In Chrome, go to chrome://inspect/#remote-debugging
+#    and enable "Allow remote debugging for this browser instance"
+
+# 2. Attach by channel name
+playwright-cli attach --cdp=chrome
+
+# 3. Interact with your existing tabs
+playwright-cli snapshot
+playwright-cli screenshot --filename=current-state.png
+
+# 4. Save state for future headless sessions
+playwright-cli state-save auth.json
+```
+
+## Workflow: debugging a remote browser
+
+```bash
+# On the remote machine: start Chrome with debugging
+google-chrome --remote-debugging-port=9222
+
+# On your machine: connect via SSH tunnel
+ssh -L 9222:localhost:9222 user@remote-host
+
+# Attach and inspect
+playwright-cli attach --cdp=http://localhost:9222
+playwright-cli snapshot
+playwright-cli screenshot --filename=remote-state.png
+playwright-cli console error
+```

agent-cli/commands/console-eval.mdx

@@ -0,0 +1,104 @@
+---
+title: "Console & Eval"
+---
+
+# Console & Eval
+
+## Console messages
+
+```bash
+playwright-cli console                  # all messages (info and above)
+playwright-cli console error            # errors only
+playwright-cli console warning          # warnings and errors
+playwright-cli console debug            # everything
+playwright-cli console --clear          # clear the message buffer
+```
+
+```bash
+$ playwright-cli console error
+# [error] Uncaught TypeError: Cannot read property 'map' of undefined
+#   at app.js:42:15
+# [error] Failed to fetch: GET /api/users 404
+```
+
+### Workflow: debugging a broken page
+
+```bash
+# Check the console for errors
+playwright-cli console error
+# [error] Failed to fetch: GET https://api.example.com/data 404
+# [error] Uncaught Error: API returned 404
+
+# Now you know the API endpoint is returning 404
+# Mock the route or investigate further
+playwright-cli route "**/api/data" \
+  --body='{"items":[]}' --content-type=application/json
+playwright-cli reload
+```
+
+## JavaScript evaluation
+
+```bash
+playwright-cli eval <expression> [ref]
+```
+
+### Page-level evaluation
+
+```bash
+$ playwright-cli eval "() => document.title"
+# React - TodoMVC
+
+$ playwright-cli eval "() => window.innerWidth + 'x' + window.innerHeight"
+# 1280x720
+```
+
+### Element evaluation
+
+```bash
+$ playwright-cli eval "(el) => el.getAttribute('data-id')" e15
+# item-42
+
+$ playwright-cli eval "(el) => getComputedStyle(el).color" e5
+# rgb(255, 0, 0)
+```
+
+## Running Playwright code
+
+Execute arbitrary Playwright scripts with full API access:
+
+```bash
+playwright-cli run-code <code>
+playwright-cli run-code --filename=script.js
+```
+
+### Set geolocation
+
+```bash
+playwright-cli run-code "async (page) => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({latitude: 37.77, longitude: -122.42});
+}"
+```
+
+### Wait for specific condition
+
+```bash
+playwright-cli run-code "async (page) => {
+  await page.waitForSelector('.data-loaded');
+  return 'Data loaded successfully';
+}"
+```
+
+### Scrape structured data
+
+```bash
+playwright-cli run-code "async (page) => {
+  const items = await page.$$eval('.product', els =>
+    els.map(el => ({
+      name: el.querySelector('.name').textContent,
+      price: el.querySelector('.price').textContent
+    }))
+  );
+  return JSON.stringify(items, null, 2);
+}"
+```

agent-cli/commands/dialogs.mdx

@@ -0,0 +1,63 @@
+---
+title: "Dialogs"
+---
+
+# Dialogs
+
+Handle browser dialogs (alert, confirm, prompt) that block page interaction.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `dialog-accept [prompt]` | Accept a dialog, optionally providing prompt text |
+| `dialog-dismiss` | Dismiss (cancel) a dialog |
+
+## Alert dialogs
+
+```bash
+$ playwright-cli click e5
+# ⚠ Dialog appeared: [alert] "Item has been deleted."
+
+$ playwright-cli dialog-accept
+```
+
+## Confirm dialogs
+
+```bash
+$ playwright-cli click e10
+# ⚠ Dialog appeared: [confirm] "Are you sure you want to delete this?"
+
+# Accept (OK)
+$ playwright-cli dialog-accept
+
+# Or dismiss (Cancel)
+$ playwright-cli dialog-dismiss
+```
+
+## Prompt dialogs
+
+```bash
+$ playwright-cli click e8
+# ⚠ Dialog appeared: [prompt] "Enter your name:"
+
+# Accept with text
+$ playwright-cli dialog-accept "Alice"
+
+# Or dismiss (cancels the prompt)
+$ playwright-cli dialog-dismiss
+```
+
+## Workflow
+
+When a dialog appears, other commands will report it. Handle the dialog before continuing:
+
+```bash
+$ playwright-cli click e12
+# ⚠ Dialog appeared: [confirm] "Discard unsaved changes?"
+
+$ playwright-cli dialog-accept
+
+$ playwright-cli snapshot
+# Page now shows updated state after dialog was accepted
+```