devharness 0.8.0

package/docs/debugging.md

@@ -0,0 +1,229 @@
+# Runtime Debugging
+
+## Setting Breakpoints
+
+**Regular breakpoints:**
+```javascript
+breakpoint({
+  action: 'set',
+  url: 'http://localhost:3000/app.js',
+  lineNumber: 42,
+  connectionReason: 'my-debug-session'
+})
+```
+
+**Conditional breakpoints:**
+```javascript
+breakpoint({
+  action: 'set',
+  url: 'http://localhost:3000/app.js',
+  lineNumber: 42,
+  condition: 'userId === "123"',
+  connectionReason: 'my-debug-session'
+})
+```
+
+**Logpoints** (non-breaking):
+```javascript
+breakpoint({
+  action: 'setLogpoint',
+  url: 'http://localhost:3000/app.js',
+  lineNumber: 42,
+  logMessage: 'User {userId} with role {userRole}',
+  includeCallStack: true,
+  maxExecutions: 50,
+  connectionReason: 'my-debug-session'
+})
+```
+
+## Execution Control
+
+When paused at a breakpoint:
+
+```javascript
+// Get call stack
+inspect({ action: 'getCallStack', connectionReason: 'my-debug-session' })
+
+// Get variables in current scope
+inspect({ action: 'getVariables', callFrameId: '0', connectionReason: 'my-debug-session' })
+
+// Filter variables by name pattern
+inspect({ action: 'getVariables', callFrameId: '0', filter: 'user|config', connectionReason: 'my-debug-session' })
+
+// Evaluate expression
+inspect({ action: 'evaluateExpression', expression: 'user.email', connectionReason: 'my-debug-session' })
+
+// Step over
+execution({ action: 'stepOver', connectionReason: 'my-debug-session' })
+
+// Step into
+execution({ action: 'stepInto', connectionReason: 'my-debug-session' })
+
+// Step out
+execution({ action: 'stepOut', connectionReason: 'my-debug-session' })
+
+// Resume
+execution({ action: 'resume', connectionReason: 'my-debug-session' })
+```
+
+## Source Maps
+
+TypeScript debugging works automatically:
+
+1. Source maps are auto-detected and registered for lazy loading
+2. Breakpoints map to original TypeScript files
+3. Variable names match your source code
+4. Call stacks show TypeScript file paths
+
+**Lazy Loading**: Source maps are loaded on-demand when needed (e.g., when mapping positions), not eagerly at startup. This improves performance with large codebases.
+
+**Size Limits**: To prevent performance issues:
+- Inline source maps (data URIs): 1MB max
+- File-based source maps: 10MB max
+
+**Manual Loading**:
+```javascript
+// Register source maps from a directory (lazy - does not load immediately)
+loadSourceMaps({ directory: './dist' })
+
+// Source maps load automatically when you:
+// - Set a breakpoint that needs mapping
+// - Get original position from generated code
+```
+
+## Code Search
+
+Search for patterns in loaded scripts:
+
+```javascript
+// Search for code patterns
+inspect({
+  action: 'searchCode',
+  pattern: 'fetchUser',
+  urlFilter: 'localhost',
+  connectionReason: 'my-debug-session'
+})
+
+// Find function definitions
+inspect({
+  action: 'searchFunctions',
+  functionName: 'handleSubmit',
+  connectionReason: 'my-debug-session'
+})
+
+// Get source code at specific lines
+getSourceCode({
+  url: 'http://localhost:3000/app.js',
+  startLine: 40,
+  endLine: 60,
+  connectionReason: 'my-debug-session'
+})
+```
+
+**Webpack Support**: When using webpack with eval-based source maps, code search automatically extracts the actual source code from webpack's eval wrappers.
+
+## Node.js Debugging
+
+Debug backend applications:
+
+```bash
+# Start Node with debugging
+node --inspect=9229 server.js
+```
+
+```javascript
+// Connect to Node.js debugger
+connectDebugger({ reference: 'backend debug', port: 9229 })
+
+// Set breakpoints
+breakpoint({
+  action: 'set',
+  url: 'file:///app/server.js',
+  lineNumber: 50,
+  connectionReason: 'backend-debug'
+})
+```
+
+## Multi-Runtime Debugging
+
+Debug Chrome and Node.js simultaneously:
+
+**Chrome:**
+```javascript
+launchChrome({ reference: 'frontend debug' })
+navigate({ action: 'goto', url: 'http://localhost:3000', connectionReason: 'frontend-debug' })
+```
+
+**Node.js (separate connection):**
+```javascript
+connectDebugger({ reference: 'backend debug', port: 9229 })
+breakpoint({ action: 'set', url: 'file:///app/server.js', lineNumber: 50, connectionReason: 'backend-debug' })
+```
+
+## Logpoint Expressions
+
+Logpoints support variable interpolation:
+
+```javascript
+// Simple variables
+logMessage: 'User ID: {userId}'
+
+// Object properties
+logMessage: 'User: {user.email}, Role: {user.role}'
+
+// Function calls
+logMessage: 'Timestamp: {Date.now()}'
+
+// Complex expressions
+logMessage: 'Cart total: {cart.items.reduce((sum, item) => sum + item.price, 0)}'
+```
+
+## Variable Inspection Fallbacks
+
+When debugging code with many variables or deeply nested objects, `getVariables` automatically degrades gracefully to fit within token limits:
+
+1. **Full data** at requested depth (ideal case)
+2. **Depth reduced** - automatically reduce expansion depth
+3. **Names only** - variable names grouped by scope
+4. **Counts only** - scope counts as last resort
+
+To inspect specific variables at full depth, use `filter` or `evaluateExpression`:
+
+```javascript
+// Filter to specific variable
+inspect({ action: 'getVariables', callFrameId: '0', filter: '^myVar$', connectionReason: 'my-debug-session' })
+
+// Or evaluate directly
+inspect({ action: 'evaluateExpression', expression: 'myVar', connectionReason: 'my-debug-session' })
+```
+
+## Bug Hunting Pattern
+
+1. **Launch and navigate**
+```javascript
+launchChrome({ reference: 'bug hunt' })
+navigate({ action: 'goto', url: 'http://localhost:3000/problematic-page', connectionReason: 'bug-hunt' })
+```
+
+2. **Monitor console errors**
+```javascript
+console({ action: 'list', type: 'error', connectionReason: 'bug-hunt' })
+```
+
+3. **Set breakpoints**
+```javascript
+breakpoint({
+  action: 'set',
+  url: 'http://localhost:3000/app.js',
+  lineNumber: 150,
+  connectionReason: 'bug-hunt'
+})
+```
+
+4. **Trigger the bug and inspect**
+```javascript
+input({ action: 'click', selector: '#trigger-button', connectionReason: 'bug-hunt' })
+// Pauses at breakpoint
+inspect({ action: 'getCallStack', connectionReason: 'bug-hunt' })
+inspect({ action: 'getVariables', callFrameId: '0', connectionReason: 'bug-hunt' })
+```

package/docs/installation.md

@@ -0,0 +1,133 @@
+# Installation
+
+## Claude Code CLI
+
+```bash
+claude mcp add cdp-tools -- npx -y devharness
+```
+
+## Claude Desktop
+
+Add to your config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "cdp-tools": {
+      "command": "npx",
+      "args": ["-y", "devharness"]
+    }
+  }
+}
+```
+
+Restart and ask Claude to debug your application.
+
+## From Source
+
+```bash
+git clone https://github.com/InDate/devharness.git
+cd devharness
+npm install
+npm run build
+npm start
+```
+
+## Configuration
+
+### Multi-Session Support
+
+Each MCP server instance automatically uses a unique debugging port to prevent conflicts when running multiple LLM sessions simultaneously.
+
+**Port Configuration:**
+- **Auto-assigned**: Ports auto-assigned starting from 9222
+- **Manual override**: Set `MCP_DEBUG_PORT` environment variable or configure in config file
+- **Valid range**: 1024-65535
+
+### Environment Variables
+
+```bash
+# Set specific debug port
+export MCP_DEBUG_PORT=9223
+```
+
+### Config File
+
+Create `.cdp-tools/config.json` to customize settings:
+
+```json
+{
+  "chrome": {
+    "defaultDebugPort": 9222
+  }
+}
+```
+
+The `defaultDebugPort` sets the starting port for Chrome debugging. If the port is in use, the next available port is used automatically.
+
+### Idle Sessions
+
+An editor window left open for days keeps its cdp-tools server alive, holding
+Chrome instances, dev servers and monitor buffers nobody is using. Two things
+stop that:
+
+- **Idle suspend.** After two hours with no request from the client, the server
+  releases what it holds - connections, the Chrome instances it launched,
+  monitor buffers, and the dev servers it owns - and exits. The supervisor
+  stays connected, so the MCP connection itself survives: the next tool call
+  starts a fresh server. You will need to relaunch Chrome (`launchChrome`) and
+  restart dev servers (`server({ action: 'start', serverId: '...' })`); their
+  config is kept.
+- **Shared dev servers are protected.** A dev server is only stopped when no
+  other live session claims it or is working in its directory, so a window that
+  goes idle never takes down a server another window is using. Ownership is
+  tracked in `.cdp-tools/server-claims/`, keyed by the supervisor process that
+  owns each session.
+- **Abandoned dev servers are collected.** A window closed for good used to
+  leave its dev servers running until reboot. The next session in that
+  directory now stops any whose owning sessions are all gone.
+- **Orphan reaping.** When the client that launched cdp-tools is gone, the
+  server tree shuts itself down, rather than waiting for a stdin EOF that never
+  arrives when an `npm exec` wrapper is holding the pipe open.
+
+```json
+{
+  "session": {
+    "idleSuspendMinutes": 120,
+    "clientPollSeconds": 60
+  }
+}
+```
+
+Set `idleSuspendMinutes` to `0` to never suspend. Both values can also be set
+via `CDP_TOOLS_IDLE_SUSPEND_MINUTES` and `CDP_TOOLS_CLIENT_POLL_SECONDS`, which
+take precedence over the config file. Unlike most settings these are read by the
+supervisor at startup, so a change takes effect on the next reconnect rather
+than hot-reloading.
+
+### Debug Logging
+
+Enable debug logging to track server operations:
+
+```javascript
+// Enable debug logging
+setDebugLogging({ enabled: true })
+
+// Check status
+getDebugLoggingStatus()
+// Logs written to: .cdp-tools/logs/debug.log
+```
+
+### Password Popup Prevention
+
+Chrome is automatically configured to prevent password-related popups that can block automation:
+
+- Password save prompts disabled
+- Password leak detection disabled
+- Mock keychain used on macOS
+
+No configuration needed - this is enabled by default.

package/docs/instructions.md

@@ -0,0 +1,227 @@
+# cdp-tools Debugger Usage
+
+Chrome DevTools Protocol debugging for JavaScript/TypeScript in Chrome, Node.js, or CDP-compatible environments.
+
+## Quick Start
+
+**Web apps (most common):**
+```
+1. launchChrome({ reference: "your-descriptive-name" })  # Auto-connects, ready immediately
+2. navigate({ action: 'goto', connectionReason: "your-descriptive-name", url: "..." })
+   # Navigation automatically caches interactive elements (links, buttons, inputs) for the page
+3. content({ action: 'findInteractive', connectionReason: "your-descriptive-name" })
+   # Shows summary of all interactive elements. Use search/types to filter
+4. content({ action: 'extractText', mode: 'outline' })  # Read page content (preferred over screenshot)
+5. Use other tools as needed with connectionReason parameter
+```
+
+**Alternative (rename later):**
+```
+1. launchChrome()                                  # Uses default "unnamed-connection-default"
+2. tab({ action: 'rename', reference: "unnamed-connection-default", newReference: "your-name" })
+3. Use other tools with connectionReason: "your-name"
+```
+
+**Node.js debugging:**
+```
+1. Start app: node --inspect=9229 app.js
+2. connectDebugger({ reference: "my-app-debug", port: 9229 })
+3. breakpoint({ action: 'set', connectionReason: "my-app-debug", ... })
+```
+
+## Basic Workflow
+
+1. **Connect**:
+   - `launchChrome({ reference: "name" })` - Launches AND auto-connects (ready immediately, don't call connectDebugger)
+   - `connectDebugger({ reference: "name" })` - Only for existing Node.js/remote debuggers
+2. **Navigate & interact**: Use connectionReason in all tool calls
+   - `navigate({ action: 'goto', connectionReason: "name", url: "..." })`
+   - `input({ action: 'click', connectionReason: "name", selector: "..." })`
+3. **Debug**: `breakpoint({ action: 'set', connectionReason: "name", ... })`
+4. **Inspect when paused**: `inspect({ action: 'getCallStack', ... })` → `inspect({ action: 'getVariables', ... })`
+5. **Monitor**: `console({ action: 'list', connectionReason: "name" })`, `network({ action: 'list', connectionReason: "name" })`
+
+## Key Practices
+
+**Breakpoints:**
+- Use conditional: `breakpoint({ action: 'set', condition: "userId === '123'" })`
+- Prefer `breakpoint({ action: 'setLogpoint' })` for loops/high-frequency code
+- Clean up with `breakpoint({ action: 'remove' })` or check `breakpoint({ action: 'list' })`
+
+**DOM/Event/XHR Breakpoints (Chrome only):**
+- `breakpoint({ action: 'setDOMBreakpoint' })`: Pause when element changes
+  - `subtree-modified`: Children added/removed
+  - `attribute-modified`: Attributes changed (class, style, etc.)
+  - `node-removed`: Element deleted from DOM
+- `breakpoint({ action: 'setEventBreakpoint' })`: Pause when events fire (click, submit, input, keydown, etc.)
+- `breakpoint({ action: 'setXHRBreakpoint' })`: Pause when XHR/Fetch URL contains pattern
+- Example: `breakpoint({ action: 'setDOMBreakpoint', selector: '.todo-list', domBreakpointType: 'subtree-modified' })`
+- Note: DOM breakpoints use nodeIds which are invalidated on page reload
+
+**Code search:**
+- `inspect({ action: 'searchCode' })`: Find patterns
+- `inspect({ action: 'searchFunctions' })`: Locate definitions
+- `getSourceCode`: View context
+
+**Modal handling:**
+- Use `handleModals: true` on `input({ action: 'click' | 'type' | 'hover' })`
+- Strategies: `auto` (smart), `accept`, `reject`, `close`, `remove`
+- Example: `input({ action: 'click', selector: '.btn', handleModals: true, dismissStrategy: 'auto' })`
+- Limitation: English-only, no Shadow DOM/iframes
+
+**Multiple connections:**
+- `listConnections` → `switchConnection`
+- Each connection = separate tab/process
+
+## Common Patterns
+
+**Bug debugging:**
+1. `launchChrome` → `navigate({ action: 'goto' })`
+2. `inspect({ action: 'searchCode' | 'searchFunctions' })`
+3. `breakpoint({ action: 'set' | 'setLogpoint' })`
+4. Trigger bug
+5. `inspect({ action: 'getCallStack' })` + `inspect({ action: 'getVariables' })`
+6. `inspect({ action: 'evaluateExpression' })`
+
+**Performance:**
+1. `network({ action: 'enable' })`
+2. `navigate({ action: 'goto' })`
+3. `network({ action: 'search' })` (find slow)
+4. `network({ action: 'get' })` (timing)
+5. `breakpoint({ action: 'setLogpoint' })` in slow paths
+
+**Frontend state:**
+1. `dom({ action: 'querySelector' })` + `dom({ action: 'getProperties' })`
+2. `storage({ action: 'getLocalStorage' })` + `storage({ action: 'getCookies' })`
+3. `inspect({ action: 'evaluateExpression' })`
+4. `dom({ action: 'snapshot' })`
+
+**UI verification:**
+1. `content({ action: 'verify' })` - Run all default checks
+2. Reports: dead buttons, small touch targets, overflow clipping, dead links, viewport issues
+3. Filter checks: `checks: ['handlers', 'touch']` for specific issues
+4. Available checks: `handlers`, `viewport`, `touch`, `overflow`, `clickability`, `links`, `scroll`
+
+## Important Notes
+
+- **After `launchChrome()`**: You are ALREADY connected. Do NOT call `connectDebugger()`. Use the `reference` parameter when launching, or rename later with `tab({ action: 'rename' })`
+- **Interactive elements cache**: Navigation (goto, reload, back, forward) automatically caches all interactive elements. Cache expires after 5 minutes. `findInteractive` shows a summary by default; use `search` or `types` parameters to filter elements
+- **Logpoint limits**: Default 20 executions. Use `breakpoint({ action: 'resetCounter' })` or adjust `maxExecutions`
+- **Expression failures**: Wrapped in try-catch, shows `[Error: message]`. Search: `console({ action: 'search', pattern: "Logpoint Error" })`
+- **CDP line mapping**: May map to nearest valid line. Use `breakpoint({ action: 'validate' })` first
+- **Source maps**: Auto-handled. Use `loadSourceMaps` for manual
+- **File paths**: Full URLs (`http://localhost:3000/app.js`) or `file://`
+- **Network monitoring**: Must enable with `network({ action: 'enable' })`
+- **Working an issue**: `comment` on it as you go - once when you start (what you're about to change and why) and once when you finish (what you actually changed, files touched, tests added, and anything that contradicts the issue as written). The issue is the durable record; someone reviewing later reads the timeline, not your diff
+- **Closing an issue**: `issues({ action: 'resolve' })` waits on a browser overlay only a human can click - don't call it unattended, use `issues({ action: 'comment' })` to record findings instead
+
+## Recovering from a failed tool call
+
+- **Missing/invalid parameters**: the error includes a `continuationToken` and `missingParameters` (name/type/description/enum). Retry with just `{ continuationToken, <missing/bad field(s)> }` - don't resend everything. Expires after 5 min.
+- **A validated call gets blocked by a guard** (port failure, dead server, breakpoint pause): the response footer shows `**Repeat:** replay({ action: 'repeat', indices: [N] })`. Acknowledge the guard (e.g. `server({ action: 'acknowledgePort' })`), then use that hint to resume the exact call. Don't reuse a `continuationToken` here - that's for fixing bad input, not for retrying an already-valid call.
+
+## Restarting cdp-tools
+
+If cdp-tools itself seems stuck or broken (not the target app), restart it yourself rather than asking the user to reconnect: `config({ action: 'restart' })`. Falls back to `kill -USR2 $(cat .cdp-tools/mcp-supervisor.pid)` via Bash if that action reports `CONFIG_RESTART_NOT_SUPERVISED` (e.g. a bare `node build/index.js`, not through the supervisor). Editing devharness's own source and running `npm run build` triggers the same restart automatically via its postbuild hook - `config({ action: 'status' })` reports which build is actually answering (entry file, its timestamp, server and supervisor pids), so a rebuild that signalled the wrong supervisor is visible rather than silent. Either way, this kills any Chrome instances it launched (relaunch with `launchChrome`) but managed dev servers (`server` tool) survive and reattach automatically.
+
+## Tool Categories
+
+Most tools are **grouped**: one tool name plus an `action` param, e.g.
+`navigate({ action: 'goto', url })`, not a separate `navigateTo` tool. The
+actions below are the complete enums accepted by each tool.
+
+Nearly every tool also takes `connectionReason` to pick which connection it
+runs against (see Quick Start).
+
+**Connection**: `launchChrome`, `killChrome`, `resetChromeLauncher`, `getChromeStatus`, `connectDebugger`, `disconnectDebugger`, `getDebuggerStatus`, `listConnections`, `switchConnection`
+- These are individual tools, not actions
+- `launchChrome` also connects - don't follow it with `connectDebugger`
+- `launchChrome({ profile: 'device-a' })` uses a **named persistent profile**: a stable user-data-dir under `~/.cdp-tools/profiles` (override per project with `chrome.persistentProfileRoot`) that survives across runs, so logins, cookies and IndexedDB persist. Naming it is what makes it persistent - there is no separate flag. It does not pin a port. Only one live Chrome may hold a profile at a time. Unnamed launches stay throwaway and are deleted on exit
+- `launchChrome({ port, forceNewInstance: true })` honours that exact port and errors if it is already taken, rather than quietly moving to another one
+
+**Tab**: `tab` (actions: list, create, rename, switch, close)
+
+**Breakpoint**: `breakpoint` (actions: set, remove, list, setLogpoint, validate, resetCounter, waitForScript, setDOMBreakpoint, setEventBreakpoint, setXHRBreakpoint, await)
+- `waitForScript`: block until a script URL loads, so you can breakpoint code that isn't parsed yet
+- `await`: wait for a breakpoint to be hit rather than polling
+- `setLogpoint`: non-pausing logging with `{expr}` interpolation, `maxExecutions` to cap noise
+
+**Execution**: `execution` (actions: pause, resume, stepOver, stepInto, stepOut, acknowledge)
+
+**Inspection**: `inspect` (actions: getCallStack, getVariables, evaluateExpression, searchCode, searchFunctions)
+- `evaluateExpression` awaits a returned Promise by default (async IIFEs resolve to their settled value; a rejection is reported as the expression's own error). Pass `awaitPromise: false` to inspect the Promise object itself. While paused at a breakpoint only already-settled promises can be resolved - a pending one fails fast because the event loop is stopped
+
+**Source**: `getSourceCode`, `loadSourceMaps`
+- Individual tools, not actions
+
+**Console**: `console` (actions: list, get, recent, search, clear, setObjectDepth)
+
+**Network**: `network` (actions: list, get, search, enable, disable, setConditions)
+
+**Page**: `navigate` (actions: goto, reload, back, forward, info)
+
+**DOM**: `dom` (actions: querySelector, getProperties, snapshot)
+
+**Content**: `content` (actions: extractText, findInteractive, verify, parse)
+
+**Screenshot**: `screenshot` (actions: fullPage, viewport, element, pdf)
+
+**Input**: `input` (actions: click, type, press, hover, focus, focusNext, focusPrevious, drag, scroll, mousemove, pinch, tap, swipe)
+- `tap` / `swipe`: real touch events via `Input.dispatchTouchEvent`. Mouse actions never produce touchstart/touchmove, so a component listening only for touch cannot be driven by `click` or `drag`. `tap` takes a selector or x/y; `swipe` takes `from`/`to` and `steps` (default 10) and emits touchstart, N touchmove, touchend
+
+**Modal**: `detectModals`, `dismissModal`
+- Individual tools, not actions
+
+**Storage**: `storage` (actions: getCookies, setCookie, getLocalStorage, setLocalStorage, removeLocalStorage, getSessionStorage, setSessionStorage, removeSessionStorage, idbListDatabases, idbListStores, idbGet, idbGetAll, idbPut, idbDelete, clear)
+- IndexedDB reads return typed descriptors for values JSON can't express - `{__type:'CryptoKey', algorithm, extractable, usages}` and analogues for Blob/ArrayBuffer/Map/Set/Date - so a non-extractable key is still observable. `idbPut` accepts JSON-expressible values only
+- A read never creates a database: `idbGet` on an unknown name errors rather than silently creating it
+- `clear` defaults to cookies + localStorage + sessionStorage. `indexedDB` is opt-in via `types` - dropping whole databases is far less recoverable
+
+**HTTP / assertions**: `request`, `assert`, `saveToDisk`
+- `request`: HTTP request as a sequence step. `destination: 'node'` sends it from the MCP server process (no browser, no CORS/cookies); `destination: 'browser'` runs `fetch()` in a connected tab (that page's cookies/session/origin). `saveAs` captures the response for later steps
+- `assert`: assert a condition as a sequence step, failing the sequence if false - use `{{var:name.path}}` templates against values captured by a prior `saveAs`
+- **Capturing values with `saveAs`**: supported on `request` and on `inspect({ action: 'evaluateExpression' })`. They store different shapes - `request` stores the whole response object (so `{{var:login.body.token}}`), `inspect` stores the evaluated value itself (so `{{var:pairingUrl}}` is the string). A `saveAs` that cannot be honoured now fails the step rather than silently capturing nothing. Async expressions work: a returned Promise is awaited and the settled value is captured exactly (JSON-serializable values are captured by value, not from display text)
+
+**Wait**: `wait` (exactly one of: selector, selectorGone, expression, ms)
+- The primitive for "the previous step kicked off async work": `wait({ selector })` until an element appears (extended `:has-text()` selectors supported), `wait({ selectorGone })` until it disappears, `wait({ expression })` until a synchronous JS predicate evaluates truthy, `wait({ ms })` fixed sleep (last resort)
+- Condition forms poll from the MCP side, so they survive a navigation mid-wait and never depend on in-page timers or promises resolving. Default timeout 15s (`timeoutMs`, `pollIntervalMs` tunable); on timeout the step fails cleanly (stopping a sequence) instead of hanging
+- For async in-page work, kick it off in one step (store its result in a global), then `wait({ expression: 'window.__result !== undefined' })`
+
+**Issues**: `issues` (actions: list, create, workOn, resolve, acknowledge, comment)
+- `create`/`comment`: track bugs and features as Markdown issues, optionally linked to a replay sequence
+- `workOn`: start on an issue, auto-replaying its linked sequence
+- `resolve` is **human-gated**: it opens a browser overlay and only a person clicking Fixed/Not Fixed can close the issue. Don't call it unattended - it will wait ~150s and then fail with `ISSUES_RESOLVE_TIMEOUT`. Record what you found with `comment` and ask the user to run `resolve` themselves
+- `acknowledge`: acknowledge pending bugs to unblock other tools
+
+**Server**: `server` (actions: start, stop, restart, list, logs, stopAll, setAutoRun, clearLogs, remove, monitorPort, unmonitorPort, listMonitored, acknowledgePort, acknowledgeStartup, extendStartup, cancelPendingRestart)
+- Use `global: true` to access servers started from a different working directory
+- `start({ watch: true, watchPaths?: [...] })`: cdp-tools watches the given paths (default: cwd) and auto-restarts the server on file changes, instead of relying on `--watch`/nodemon. Pause-aware: if a breakpoint debugger is paused on that server's inspector port, the restart queues instead of firing immediately - `cancelPendingRestart` discards a queued restart to keep debugging without it firing on resume
+
+**Replay**: `replay` (actions: history, create, list, get, delete, export, load, listSaved, deleteSaved, run, runAll, step, finish, insert, addConditional, status, cancel, repeat, runFromLog, recordInteraction)
+- `recordInteraction`: record mouse, keyboard, and navigation events with a visual overlay
+- `runAll`: run every sequence in a folder and report one line each - `replay({ action: 'runAll', folder: 'spine', connectionReason: 'my-app' })`. Sequences may live in SUBFOLDERS of the sequences dir (`spine/`, `story/`, `_helpers/`); filenames are relative to that root (`spine/spine-01.json`) and `load` still accepts the bare basename. The whole tree is LOADED before anything runs, so a sequence in one folder can still reference a helper in another by name (a conditional's `then`, a forEach's `do`) - those resolve by sequence name, not by path. Folders whose name starts with `_` are loaded but never run by a bare `runAll`, which is where preamble guards and forEach bodies belong; naming such a folder explicitly runs it anyway. A failure is recorded and the suite continues (`continueOnFailure`, default true). Scoped to one root: the project sequences dir, or the global one with `global: true`. Accepts `baseUrl`, so one call runs a suite against any deployment
+- `addConditional`: add a guarded branch step - `replay({ action: 'addConditional', name: 'flow', condition: '{{selector:.cookie-banner}}', thenSequence: 'dismiss-banner', insertAfterStep: 2 })`. `conditional` is virtual, never recorded, so this is its only authoring route. Syntax and branch target are validated up front; a sequence already on disk is rewritten in place
+- `forEach`: a second virtual step - enumerate a source and run a sequence per item: `{ tool: 'forEach', params: { in: '{{var:shares}}', as: 'share', do: 'revoke-one-share', where: 'item.name !== "Employees"', maxItems: 50 } }`. `in` is either an array a prior `saveAs` captured or `{{selectorAll:CSS}}`; `where` is JavaScript with `item`/`index` in scope, not the condition grammar. Conditions probe one named thing, so this is what expresses "for everything that is there". An empty source is a success and the count is reported
+- `teardown`: an optional command array beside a sequence's `commands`, run when the main steps reach a terminal state - success, a failed step, an abort, or the total timeout - but not when the run pauses. It has its own timeout budget and does not receive the run's abort signal, so a cancelled or timed-out run still cleans up; it shares the variable store, so it can revoke what setup minted. A failing teardown step never changes the run's verdict. Best-effort: a killed server takes pending teardown with it
+- `export`: export a sequence to file - `format: sequence | playwright | puppeteer`
+- `repeat`: instantly re-execute commands by history index - `replay({ action: 'repeat', indices: [0, 1, 2] })`. Each tool response shows its history index in the "Repeat" hint
+- `run`: does not block - returns a `runId` immediately and executes in the background; poll `status({ runId })` for progress and the final result (kept 30 min in memory), `cancel({ runId })` interrupts the step in flight where the tool allows it (`wait` and `request` are genuinely cancelled, `navigate`/`inspect`/`content` stop waiting, `input` stops dispatching further events, the rest stop at the next step boundary - table in `docs/replay.md`). `wait: true` blocks for the full result (pre-0.7 behaviour). `startUrl` overrides the stored start URL for one run; `baseUrl` retargets every absolute URL at another deployment's origin
+- Use `global: true` with `export` to save to ~/.cdp-tools/sequences/ instead of the working directory
+
+**Dashboard**: `dashboard` (actions: open, status, stop)
+
+**Debug logging**: `setDebugLogging`, `getDebugLoggingStatus`
+
+**Config**: `config` (actions: status, useLocal, useGlobal, reset, backup, cloneFromGlobal, show, listTools, reload, restart, listProfiles, resetProfile)
+- `status`: Show where config is loaded from (local vs global)
+- `useLocal`: Switch to project-local config (.cdp-tools/config.json)
+- `useGlobal`: Switch to global config (~/.cdp-tools/config.json)
+- `reset`: Reset config to defaults
+- `backup`: Create timestamped backup
+- `cloneFromGlobal`: Copy global config to local project
+- `show`: Display current configuration
+- `listTools`: List all toggleable tools with status and dependency conflicts
+- `reload`: Re-read config.json now (also happens automatically on file edits, ~250ms debounce). Doesn't apply `tools.enabled`/`tools.disabled` - those need `restart`
+- `restart`: Restart cdp-tools itself via the mcp-supervisor (see "Restarting cdp-tools" above) - use when the server seems stuck/broken, or to apply `tools.enabled`/`tools.disabled` changes
+- `listProfiles`: List named persistent Chrome profiles and the root they live under
+- `resetProfile`: Wipe and recreate a named profile (`config({ action: 'resetProfile', profile: 'device-a' })`). Refused while a live Chrome holds that profile - nothing is deleted in that case

package/docs/mcp-instructions.md

@@ -0,0 +1,15 @@
+# cdp-tools MCP Server
+
+Chrome DevTools Protocol debugging for JavaScript/TypeScript in Chrome, Node.js, or CDP-compatible environments - breakpoints, variable inspection, browser automation, dev server management, and record/replay verification.
+
+**Quick start (web apps):**
+1. `launchChrome({ reference: "name" })` - launches AND auto-connects, ready immediately (do not call `connectDebugger` after this)
+2. `navigate({ action: 'goto', connectionReason: "name", url: "..." })` - also caches interactive elements for the page
+3. `content({ action: 'findInteractive' })` / `content({ action: 'extractText', mode: 'outline' })` to read the page
+4. Use other tools with `connectionReason: "name"`
+
+**Node.js:** start with `node --inspect=9229 app.js`, then `connectDebugger({ reference: "name", port: 9229 })`.
+
+For full workflow guidance, key practices, common debugging/performance/replay patterns, and the complete tool catalog: this package ships an Agent Skills-compatible skill at `skills/cdp-tools/SKILL.md`. Clients that support Agent Skills (agentskills.io) will auto-discover it once it's placed in a scanned skills directory (e.g. `.claude/skills/` or `.agents/skills/`) and load it only when a debugging task is actually underway. If your client doesn't support Agent Skills, see `docs/instructions.md` for the same material inline, or rely on each tool's own description.
+
+If cdp-tools itself seems stuck or broken (not the target app), restart it yourself: `config({ action: 'restart' })` (falls back to `kill -USR2 $(cat .cdp-tools/mcp-supervisor.pid)` if that's unavailable). This kills any Chrome instances it launched (relaunch with `launchChrome`); managed dev servers (`server` tool) survive and reattach automatically.