devharness 0.8.0

package/docs/troubleshooting.md

@@ -0,0 +1,272 @@
+# Troubleshooting
+
+## Session Issues
+
+### Chrome and my dev server closed while I was away
+
+**Problem:** After a long break, connections are gone, Chrome is closed and a
+dev server has stopped - but the MCP connection still works.
+
+**Cause:** The session was suspended. With no request from the client for
+`session.idleSuspendMinutes` (default 120), cdp-tools releases what it holds
+and exits; the supervisor stays connected and started a fresh server for your
+next call.
+
+**Solutions:**
+- Relaunch Chrome (`launchChrome`) and restart the dev server
+  (`server({ action: 'start', serverId: '...' })`) - its config is kept.
+- Raise or disable the threshold in `.cdp-tools/config.json`:
+  `{"session": {"idleSuspendMinutes": 0}}`. Read at supervisor startup, so it
+  applies from the next reconnect.
+
+A dev server another window is using is never stopped this way: it is only
+released when no other live session claims it or is working in its directory.
+
+### A dev server stopped when I opened a new session
+
+**Problem:** Starting cdp-tools in a project stopped a dev server that was
+already running.
+
+**Cause:** Every session that had claimed it was gone, so it was collected as
+abandoned - otherwise a dev server from a window you closed days ago keeps
+running until you reboot.
+
+**Solutions:**
+- Restart it (`server({ action: 'start', serverId: '...' })`).
+- To keep a server outside this lifecycle, run it yourself rather than through
+  the `server` tool; cdp-tools only collects servers it manages, and only ones
+  it can prove nobody is left to use.
+
+## Chrome Connection Issues
+
+### "Chrome is already running on port X"
+
+**Solutions:**
+- Use `killChrome({ reason: "restart needed" })` to stop existing instance
+- Launch on different port: `launchChrome({ port: 9224, reference: 'new session' })`
+- Check if another process is using the port: `lsof -i :9222`
+
+### Chrome won't launch
+
+**Solutions:**
+- Check Chrome is installed in a standard location
+- Verify no other Chrome debugging sessions are active
+- Try `resetChromeLauncher({ reason: "stuck state" })` to reset launcher state
+
+## Breakpoint Issues
+
+### Breakpoint not hitting
+
+**Problem:** Breakpoint set but never pauses
+
+**Solutions:**
+- Verify file URL matches exactly (use `searchCode` to find the right path)
+- Check source maps are loading correctly
+- Ensure code path is actually executed (add `console.log` to verify)
+- Try setting logpoint first to confirm location is reachable
+
+**Note:** Breakpoints survive rebuilds with cache-busting query params. If your bundler outputs `app.js?v=123` and rebuilds to `app.js?v=456`, existing breakpoints will automatically match the new script.
+
+### Breakpoint shows as "pending"
+
+**Problem:** Breakpoint status shows pending, not resolved
+
+**Solutions:**
+- The script may not be loaded yet - navigate to the page first
+- Use `breakpoint({ action: 'waitForScript', url: '...' })` to wait for script to load
+- Reload the page with `navigate({ action: 'reload' })`
+
+### Wrong line number after setting breakpoint
+
+**Problem:** CDP may map breakpoints to the nearest valid line
+
+**Solutions:**
+- Use `breakpoint({ action: 'validate', ... })` to check valid locations
+- Set breakpoint on a line with executable code (not comments/whitespace)
+
+## Element Issues
+
+### Element not found
+
+**Problem:** Selector doesn't match any elements
+
+**Solutions:**
+- Use `content({ action: 'findInteractive' })` to see available elements
+- Check element is in viewport: might need to scroll first
+- Wait for dynamic content: element may load asynchronously
+- Try broader selector (class instead of ID)
+
+### Cache not working
+
+**Problem:** `findInteractive` shows "no cache" or stale data
+
+**Solutions:**
+- Cache expires after 5 minutes - navigate again to refresh
+- Cache is page-specific - each URL has separate cache
+- Clear navigation: `navigate({ action: 'goto', ... })` rebuilds cache
+
+## Node.js Connection Issues
+
+### Cannot connect to Node.js debugger
+
+**Problem:** `connectDebugger` fails
+
+**Solutions:**
+- Ensure Node started with `--inspect` flag
+- Check port number matches (default 9229)
+- Verify Node process is still running
+- Try `--inspect=0.0.0.0:9229` if connecting remotely
+
+### Connection drops during debugging
+
+**Solutions:**
+- Check if Node process crashed (look at terminal output)
+- Verify Node didn't restart (e.g., from nodemon)
+- Reconnect with same reference: `connectDebugger({ reference: 'same ref', port: 9229 })`
+
+### "Reference already in use" but no connection exists
+
+**Problem:** Chrome was killed externally or tab was closed manually, but MCP still shows reference in use
+
+**Solutions:**
+- This is now auto-handled - stale connections are automatically detected and cleaned up
+- Use `tab({ action: 'list' })` which validates and cleans up dead connections
+- Use `listConnections()` which also cleans up stale references
+- As fallback, use `killChrome({ reason: "cleanup" })` then relaunch
+
+## Replay Issues
+
+### Replay times out
+
+**Problem:** Replay hangs or times out
+
+**Solutions:**
+- Increase step timeout: `stepTimeout: 60000` (60 seconds)
+- Increase total timeout: `totalTimeout: 600000` (10 minutes)
+- Check if page is waiting for user interaction (modal blocking?)
+
+### Stale callFrameId error
+
+**Problem:** `getVariables` fails with invalid call frame
+
+**Solutions:**
+- This should be auto-fixed - replay replaces stale IDs automatically
+- If still failing, ensure debugger is actually paused
+- Check breakpoint was hit with `inspect({ action: 'getCallStack' })`
+
+### Variables not substituted
+
+**Problem:** Replay uses original values instead of substituted ones
+
+**Solutions:**
+- Variable names are generated as `var_<index>_<selector>`
+- Use `replay({ action: 'get', name: '...' })` to see variable names
+- Pass empty `variables: {}` to keep original values explicitly
+
+## Console/Network Monitoring
+
+### Console messages not appearing
+
+**Solutions:**
+- Console monitoring starts automatically on connection
+- Check message type filter: `console({ action: 'list', type: 'log' })`
+- Clear and retry: `console({ action: 'clear', reason: 'reset' })`
+
+### Network requests missing
+
+**Solutions:**
+- Enable monitoring first: `network({ action: 'enable' })`
+- Monitoring must be enabled before requests are made
+- Check resource type filter if used
+
+## Source Map Issues
+
+### Source maps not loading
+
+**Solutions:**
+- Source maps load lazily - they load when needed
+- Check file size limits: inline (1MB), file (10MB)
+- Manually load: `loadSourceMaps({ directory: './dist' })`
+
+### Wrong file shown in call stack
+
+**Solutions:**
+- Verify source map is valid (check `.map` file exists and is valid JSON)
+- Check `sourcesContent` is present in source map
+- Try rebuilding with fresh source maps
+
+## Server Management Issues
+
+### Server won't start
+
+**Problem:** `server({ action: 'start' })` fails
+
+**Solutions:**
+- Check working directory exists and is correct
+- Verify the command works when run manually
+- Check for port conflicts: `lsof -i :<port>`
+- Check server logs: `server({ action: 'logs', serverId: '...' })`
+
+### Docker server not detected
+
+**Problem:** Docker container starts but port not detected
+
+**Solutions:**
+- Ensure port mapping is in the command: `-p 3000:3000`
+- Runner may need explicit type: `runner: 'docker'`
+- Check Docker is running: `docker ps`
+
+### Port monitoring blocks all tools
+
+**Problem:** Monitoring level is `block` and port went down
+
+**Solutions:**
+- Acknowledge the failure: `server({ action: 'acknowledgePort', port: <port> })`
+- Check server status: `server({ action: 'list' })`
+- Restart the server: `server({ action: 'restart', serverId: '...' })`
+
+### Server logs not updating
+
+**Solutions:**
+- Logs are fetched incrementally (delta since last view)
+- Use `lines: 100` to fetch all recent logs
+- Clear logs: `server({ action: 'clearLogs', serverId: '...' })`
+
+## General Tips
+
+### Enable debug logging
+
+```javascript
+setDebugLogging({ enabled: true })
+// Check logs at: .cdp-tools/logs/debug.log
+```
+
+### Check connection status
+
+```javascript
+// List all connections
+listConnections()
+
+// Check specific connection
+getDebuggerStatus({ reference: 'my-session' })
+```
+
+### Check Chrome status
+
+```javascript
+getChromeStatus()
+// Shows running instances, ports, and recent close events
+```
+
+### Reset everything
+
+```javascript
+// Kill all Chrome instances
+killChrome({ reason: "full reset" })
+
+// Reset launcher state
+resetChromeLauncher({ reason: "stuck" })
+
+// Start fresh
+launchChrome({ reference: 'fresh start' })
+```

package/docs/working_with_llm_notes.md

@@ -0,0 +1,5 @@
+# Notes about working with LLM's.
+
+- LLM's are optimistic about their work. I expect to be ignored when not explicit.
+- MCP tools are not directly accessible, so changes are made either by the optimistic LLM, sometimes incorrectly or we need a way to edit the config
+- Always provide a backdoor into the config that will override LLM's. That way we can force the desired behavior when needed.

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "devharness",
+  "version": "0.8.0",
+  "description": "MCP server that connects AI assistants to Chrome DevTools Protocol for runtime debugging - set breakpoints, inspect variables, monitor network traffic, and automate browser interactions",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "devharness": "build/mcp-supervisor.js"
+  },
+  "scripts": {
+    "build": "tsc && npm run build:dashboard",
+    "postbuild": "node scripts/signal-supervisor.mjs",
+    "build:dashboard": "node scripts/build-dashboard.mjs",
+    "build:verify": "npm run build && node scripts/verify-mcp.js && node scripts/measure-startup.mjs",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "startup:measure": "node scripts/measure-startup.mjs",
+    "startup:measure:verbose": "node scripts/measure-startup.mjs --verbose",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "stress:suspend": "node scripts/stress-suspend.mjs",
+    "prepublishOnly": "npm run test:run && npm run build:verify",
+    "version": "node scripts/sync-skill-version.mjs",
+    "postversion": "git push && git push --tags"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chrome-devtools-protocol",
+    "cdp",
+    "debugging",
+    "debugger",
+    "llm",
+    "ai",
+    "breakpoints",
+    "browser-automation",
+    "chrome",
+    "node-debugging",
+    "typescript"
+  ],
+  "author": "CDP Tools MCP Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InDate/devharness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/InDate/devharness/issues"
+  },
+  "homepage": "https://github.com/InDate/devharness#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "build/",
+    "docs/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "chrome-remote-interface": "^0.33.2",
+    "fp-ts": "^2.16.11",
+    "io-ts": "^2.2.22",
+    "puppeteer-core": "^23.10.4",
+    "rxjs": "^7.8.2",
+    "source-map": "^0.7.4",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/chrome-remote-interface": "^0.31.14",
+    "@types/node": "^22.10.2",
+    "@types/ws": "^8.5.13",
+    "@vitest/coverage-v8": "^3.2.7",
+    "@vitest/ui": "^3.2.4",
+    "esbuild": "^0.24.2",
+    "happy-dom": "^20.0.10",
+    "preact": "^10.25.4",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/devharness/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: devharness
+description: Drive and debug a running app via the devharness MCP server - launch or attach to Chrome and Node.js, set breakpoints and logpoints, inspect call stacks and variables, watch console and network, manage dev servers, replay any earlier tool call by its history index, and record reproduction sequences that verify a fix. Use whenever a task involves running or debugging a live app, reproducing or verifying a bug, re-driving setup you already did (relaunching, re-logging in, refilling a form), or the user mentions breakpoints, Chrome DevTools, CDP, replay sequences, or devharness tools (launchChrome, navigate, breakpoint, inspect, replay, server, issues, etc.).
+compatibility: Requires the devharness MCP server to be connected (tools such as launchChrome, breakpoint, inspect, replay, server, issues). Previously published as cdp-tools-mcp.
+version: 0.8.0
+---
+
+# devharness
+
+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
+
+**Re-running work you already did:**
+- Every tool response carries its own history index in the footer:
+  `**Repeat:** replay({ action: 'repeat', indices: [58] })`. That is not only
+  for failures - it is on every call, all the time. (The `replay` tool's own
+  responses are the exception: replay calls are not recorded into history)
+- `indices` takes a **list**, so a whole stretch of work replays in one call:
+  `replay({ action: 'repeat', indices: [58, 59, 60, 61] })` re-runs those four
+  steps in order
+- Reach for this whenever you are about to redo something you already did -
+  a browser relaunch, re-logging in, retyping a form, getting back to the
+  screen where a bug appears. Re-issuing the calls by hand is slower, and
+  retyped arguments drift from what actually ran
+- `replay({ action: 'history' })` lists the indices when they have scrolled
+  out of view
+- Each repeated call replays against the connection it was recorded with, so a
+  batch spanning two browsers stays on both. Pass `connectionReason` on every
+  call while driving multiple browsers and this holds; drive one implicitly and
+  those calls have no connection to replay against
+- If the stretch is worth keeping, turn it into a sequence:
+  `replay({ action: 'create', name: '...', indices: [58, 59, 60, 61] })`
+
+## 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
+
+Two different mechanisms fix two different failure points - don't confuse them.
+
+**1. Missing/invalid parameters -> `continuationToken` (fix and resubmit, cheaply)**
+
+If a call fails validation (`code: 'MISSING_PARAMETERS'` or `'INVALID_PARAMS'`), the error includes a `continuationToken` and a `missingParameters` list (name/type/description/enum). Don't resend the whole call - retry with just:
+```
+{ continuationToken: '<token>', <only the missing/bad field(s)> }
+```
+The server merges this with what you already sent and re-validates. Repeat (same token) until it succeeds. The token expires after 5 minutes. This only applies to calls that never passed validation in the first place - it has nothing to do with guard blocks below.
+
+**2. A validated call gets blocked by a guard (port failure, dead server, breakpoint pause, etc.) -> `replay`**
+
+Once a call passes validation, devharness records it (even if a guard then blocks it before the handler runs) and every response footer includes a hint like:
+```
+**Repeat:** `replay({ action: 'repeat', indices: [N] })`
+```
+Acknowledge whatever blocked it (e.g. `server({ action: 'acknowledgePort' })`, `server({ action: 'acknowledgeStartup' })`), then use that `replay` hint to resume the exact same call - do not reconstruct the arguments by hand, and do not try to reuse a `continuationToken` for this case (that mechanism is for fixing bad input, not for retrying a call that was already valid).
+
+Note this is only one use of `repeat`. The footer hint is on every response, not just blocked ones, and `indices` takes a list - see "Re-running work you already did" above.
+
+## Restarting devharness
+
+If devharness itself seems stuck or broken (not the target app), restart it yourself rather than asking the user to reconnect - don't wait to be told to.
+
+- **Preferred**: `config({ action: 'restart' })`. Under the hood this reads `.cdp-tools/mcp-supervisor.pid` and sends the running mcp-supervisor process a `SIGUSR2`, the same signal `npm run build`'s postbuild hook sends automatically after a rebuild. The supervisor replays the original MCP `initialize` handshake to the freshly spawned child, so the host session never needs to reconnect.
+- If that returns `CONFIG_RESTART_NOT_SUPERVISED` (this server isn't running through the supervisor - e.g. a bare `node build/index.js`), fall back to Bash: `kill -USR2 $(cat .cdp-tools/mcp-supervisor.pid)`.
+- If it returns `CONFIG_RESTART_STALE_PID`, the supervisor died without cleaning up its pidfile - ask the user to run `/mcp` to reconnect.
+
+**Expect the triggering call itself to come back as an error - that's normal, not a failure.** In practice `config({ action: 'restart' })` almost never returns its own `CONFIG_RESTART_REQUESTED` success message: the old process gets torn down before it can flush that response, so the supervisor's restart-coordinator answers with a synthesized `MCP error -32000: MCP server is restarting; this request will not receive a response from the previous process. Please retry.` instead. Just retry the next call - it'll hit the freshly restarted (and by then ready) process. Two things to expect on that next call: it runs against a new PID (visible in tool response footers), and any acknowledged monitored-port failures (`server({ action: 'acknowledgePort' })`) reset and may need re-acknowledging, since that state lived in the process that just got replaced.
+
+`config({ action: 'status' })` says which build is answering: the version, the entry file it loaded, that file's timestamp, and the server/supervisor pids. If you have just rebuilt devharness and the behaviour still looks old, check that timestamp before believing the code - a build signals the supervisor named in its own project's pidfile, which is not always the one serving this session.
+
+Either way, a restart kills any Chrome instances this session launched (relaunch with `launchChrome`), but managed dev servers (`server` tool) survive and reattach automatically. `config({ action: 'reload' })` is different and lighter-weight - it hot-applies most `config.json` edits without a restart; a restart is only needed for `tools.enabled`/`tools.disabled` changes (the tool list is frozen at server startup) or when the process itself is actually stuck.
+
+## Tool Categories
+
+The full list of tools grouped by category (connection, tab, breakpoint, execution, inspection, source, console, network, page, DOM, content, screenshot, input, modal, storage, HTTP/assertions, issues, server, replay, dashboard, config) is not needed for most tasks. Load it only when you need to look up a specific tool name or action:
+
+[references/tool-categories.md](references/tool-categories.md)
+
+## Replay Sequences
+
+Recording or replaying a sequence - to build a repro, a regression test, or a
+multi-device flow - has its own workflow: capturing values mid-run with
+`saveAs`, per-step `connectionReason`, conditionals, and verifying an issue's
+fix. Load it when the task involves sequences:
+
+[references/sequences.md](references/sequences.md)