@jackwener/opencli 1.6.0 → 1.6.2

package/extension/src/cdp.ts

@@ -8,6 +8,27 @@
 
 const attached = new Set<number>();
 
+type NetworkCaptureEntry = {
+  kind: 'cdp';
+  url: string;
+  method: string;
+  requestHeaders?: Record<string, string>;
+  requestBodyKind?: string;
+  requestBodyPreview?: string;
+  responseStatus?: number;
+  responseContentType?: string;
+  responseHeaders?: Record<string, string>;
+  responsePreview?: string;
+  timestamp: number;
+};
+
+type NetworkCaptureState = {
+  patterns: string[];
+  entries: NetworkCaptureEntry[];
+  requestToIndex: Map<string, number>;
+};
+
+const networkCaptures = new Map<number, NetworkCaptureState>();
 /** Check if a URL can be attached via CDP — only allow http(s) and blank pages. */
 function isDebuggableUrl(url?: string): boolean {
   if (!url) return true;  // empty/undefined = tab still loading, allow it
@@ -79,6 +100,16 @@ export async function ensureAttached(tabId: number, aggressiveRetry: boolean = f
   }
 
   if (lastError) {
+    // Log detailed diagnostics for debugging extension conflicts
+    let finalUrl = 'unknown';
+    let finalWindowId = 'unknown';
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      finalUrl = tab.url ?? 'undefined';
+      finalWindowId = String(tab.windowId);
+    } catch { /* tab gone */ }
+    console.warn(`[opencli] attach failed for tab ${tabId}: url=${finalUrl}, windowId=${finalWindowId}, error=${lastError}`);
+
     const hint = lastError.includes('chrome-extension://')
       ? '. Tip: another Chrome extension may be interfering — try disabling other extensions'
       : '';
@@ -121,11 +152,14 @@ export async function evaluate(tabId: number, expression: string, aggressiveRetr
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
       // Only retry on attach/debugger errors, not on JS eval errors
-      const isAttachError = msg.includes('attach failed') || msg.includes('Debugger is not attached')
-        || msg.includes('chrome-extension://') || msg.includes('Target closed');
+      const isNavigateError = msg.includes('Inspected target navigated') || msg.includes('Target closed');
+      const isAttachError = isNavigateError || msg.includes('attach failed') || msg.includes('Debugger is not attached')
+        || msg.includes('chrome-extension://');
       if (isAttachError && attempt < MAX_EVAL_RETRIES) {
         attached.delete(tabId); // Force re-attach on next attempt
-        await new Promise(resolve => setTimeout(resolve, 1000));
+        // SPA navigations recover quickly; debugger detach needs longer
+        const retryMs = isNavigateError ? 200 : 500;
+        await new Promise(resolve => setTimeout(resolve, retryMs));
         continue;
       }
       throw e;
@@ -228,18 +262,100 @@ export async function setFileInputFiles(
   });
 }
 
+export async function insertText(
+  tabId: number,
+  text: string,
+): Promise<void> {
+  await ensureAttached(tabId);
+  await chrome.debugger.sendCommand({ tabId }, 'Input.insertText', { text });
+}
+
+function normalizeCapturePatterns(pattern?: string): string[] {
+  return String(pattern || '')
+    .split('|')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function shouldCaptureUrl(url: string | undefined, patterns: string[]): boolean {
+  if (!url) return false;
+  if (!patterns.length) return true;
+  return patterns.some((pattern) => url.includes(pattern));
+}
+
+function normalizeHeaders(headers: unknown): Record<string, string> {
+  if (!headers || typeof headers !== 'object') return {};
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
+    out[String(key)] = String(value);
+  }
+  return out;
+}
+
+function getOrCreateNetworkCaptureEntry(tabId: number, requestId: string, fallback?: {
+  url?: string;
+  method?: string;
+  requestHeaders?: Record<string, string>;
+}): NetworkCaptureEntry | null {
+  const state = networkCaptures.get(tabId);
+  if (!state) return null;
+  const existingIndex = state.requestToIndex.get(requestId);
+  if (existingIndex !== undefined) {
+    return state.entries[existingIndex] || null;
+  }
+  const url = fallback?.url || '';
+  if (!shouldCaptureUrl(url, state.patterns)) return null;
+  const entry: NetworkCaptureEntry = {
+    kind: 'cdp',
+    url,
+    method: fallback?.method || 'GET',
+    requestHeaders: fallback?.requestHeaders || {},
+    timestamp: Date.now(),
+  };
+  state.entries.push(entry);
+  state.requestToIndex.set(requestId, state.entries.length - 1);
+  return entry;
+}
+
+export async function startNetworkCapture(
+  tabId: number,
+  pattern?: string,
+): Promise<void> {
+  await ensureAttached(tabId);
+  await chrome.debugger.sendCommand({ tabId }, 'Network.enable');
+  networkCaptures.set(tabId, {
+    patterns: normalizeCapturePatterns(pattern),
+    entries: [],
+    requestToIndex: new Map(),
+  });
+}
+
+export async function readNetworkCapture(tabId: number): Promise<NetworkCaptureEntry[]> {
+  const state = networkCaptures.get(tabId);
+  if (!state) return [];
+  const entries = state.entries.slice();
+  state.entries = [];
+  state.requestToIndex.clear();
+  return entries;
+}
+
 export async function detach(tabId: number): Promise<void> {
   if (!attached.has(tabId)) return;
   attached.delete(tabId);
+  networkCaptures.delete(tabId);
   try { await chrome.debugger.detach({ tabId }); } catch { /* ignore */ }
 }
 
 export function registerListeners(): void {
   chrome.tabs.onRemoved.addListener((tabId) => {
     attached.delete(tabId);
+    networkCaptures.delete(tabId);
   });
   chrome.debugger.onDetach.addListener((source) => {
-    if (source.tabId) attached.delete(source.tabId);
+    if (source.tabId) {
+      attached.delete(source.tabId);
+      networkCaptures.delete(source.tabId);
+    }
   });
   // Invalidate attached cache when tab URL changes to non-debuggable
   chrome.tabs.onUpdated.addListener(async (tabId, info) => {
@@ -247,4 +363,78 @@ export function registerListeners(): void {
       await detach(tabId);
     }
   });
+  chrome.debugger.onEvent.addListener(async (source, method, params) => {
+    const tabId = source.tabId;
+    if (!tabId) return;
+    const state = networkCaptures.get(tabId);
+    if (!state) return;
+
+    if (method === 'Network.requestWillBeSent') {
+      const requestId = String(params?.requestId || '');
+      const request = params?.request as {
+        url?: string;
+        method?: string;
+        headers?: Record<string, unknown>;
+        postData?: string;
+        hasPostData?: boolean;
+      } | undefined;
+      const entry = getOrCreateNetworkCaptureEntry(tabId, requestId, {
+        url: request?.url,
+        method: request?.method,
+        requestHeaders: normalizeHeaders(request?.headers),
+      });
+      if (!entry) return;
+      entry.requestBodyKind = request?.hasPostData ? 'string' : 'empty';
+      entry.requestBodyPreview = String(request?.postData || '').slice(0, 4000);
+      try {
+        const postData = await chrome.debugger.sendCommand({ tabId }, 'Network.getRequestPostData', { requestId }) as { postData?: string };
+        if (postData?.postData) {
+          entry.requestBodyKind = 'string';
+          entry.requestBodyPreview = postData.postData.slice(0, 4000);
+        }
+      } catch {
+        // Optional; some requests do not expose postData.
+      }
+      return;
+    }
+
+    if (method === 'Network.responseReceived') {
+      const requestId = String(params?.requestId || '');
+      const response = params?.response as {
+        url?: string;
+        mimeType?: string;
+        status?: number;
+        headers?: Record<string, unknown>;
+      } | undefined;
+      const entry = getOrCreateNetworkCaptureEntry(tabId, requestId, {
+        url: response?.url,
+      });
+      if (!entry) return;
+      entry.responseStatus = response?.status;
+      entry.responseContentType = response?.mimeType || '';
+      entry.responseHeaders = normalizeHeaders(response?.headers);
+      return;
+    }
+
+    if (method === 'Network.loadingFinished') {
+      const requestId = String(params?.requestId || '');
+      const stateEntryIndex = state.requestToIndex.get(requestId);
+      if (stateEntryIndex === undefined) return;
+      const entry = state.entries[stateEntryIndex];
+      if (!entry) return;
+      try {
+        const body = await chrome.debugger.sendCommand({ tabId }, 'Network.getResponseBody', { requestId }) as {
+          body?: string;
+          base64Encoded?: boolean;
+        };
+        if (typeof body?.body === 'string') {
+          entry.responsePreview = body.base64Encoded
+            ? `base64:${body.body.slice(0, 4000)}`
+            : body.body.slice(0, 4000);
+        }
+      } catch {
+        // Optional; bodies are unavailable for some requests (e.g. uploads).
+      }
+    }
+  });
 }

package/extension/src/protocol.ts

@@ -5,7 +5,20 @@
  * Everything else is just JS code sent via 'exec'.
  */
 
-export type Action = 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'cdp';
+export type Action =
+  | 'exec'
+  | 'navigate'
+  | 'tabs'
+  | 'cookies'
+  | 'screenshot'
+  | 'close-window'
+  | 'sessions'
+  | 'set-file-input'
+  | 'insert-text'
+  | 'bind-current'
+  | 'network-capture-start'
+  | 'network-capture-read'
+  | 'cdp';
 
 export interface Command {
   /** Unique request ID */
@@ -26,6 +39,10 @@ export interface Command {
   index?: number;
   /** Cookie domain filter */
   domain?: string;
+  /** Optional hostname/domain to require for current-tab binding */
+  matchDomain?: string;
+  /** Optional pathname prefix to require for current-tab binding */
+  matchPathPrefix?: string;
   /** Screenshot format: png (default) or jpeg */
   format?: 'png' | 'jpeg';
   /** JPEG quality (0-100), only for jpeg format */
@@ -36,6 +53,10 @@ export interface Command {
   files?: string[];
   /** CSS selector for file input element (set-file-input action) */
   selector?: string;
+  /** Raw text payload for insert-text action */
+  text?: string;
+  /** URL substring filter pattern for network capture actions */
+  pattern?: string;
   /** CDP method name for 'cdp' action (e.g. 'Accessibility.getFullAXTree') */
   cdpMethod?: string;
   /** CDP method params for 'cdp' action */

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Make any website your CLI. AI-powered.",
+  "description": "Make any website or Electron App your CLI. AI-powered.",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -30,6 +30,7 @@
     "postinstall": "node scripts/postinstall.js || true",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
+    "prepare": "[ -d src ] && npm run build || true",
     "prepublishOnly": "npm run build",
     "test": "vitest run --project unit",
     "test:bun": "bun vitest run --project unit",

package/scripts/postinstall.js

@@ -217,7 +217,7 @@ function main() {
   console.log('  \x1b[1mNext step — Browser Bridge setup\x1b[0m');
   console.log('  Browser commands (bilibili, zhihu, twitter...) require the extension:');
   console.log('  1. Download: https://github.com/jackwener/opencli/releases');
-  console.log('  2. Open chrome://extensions → enable Developer Mode → Load unpacked');
+  console.log('  2. In Chrome or Chromium, open chrome://extensions → enable Developer Mode → Load unpacked');
   console.log('');
   console.log('  Then run \x1b[36mopencli doctor\x1b[0m to verify.');
   console.log('');

package/skills/opencli-explorer/SKILL.md

@@ -10,7 +10,7 @@ tags: [opencli, adapter, browser, api-discovery, cli, web-scraping, automation]
 > 从零到发布，覆盖 API 发现、方案选择、适配器编写、测试验证全流程。
 
 > [!TIP]
-> **只想为一个具体页面快速生成一个命令？** 看 [CLI-ONESHOT.md](./CLI-ONESHOT.md)（~150 行，4 步搞定）。
+> **只想为一个具体页面快速生成一个命令？** 看 [opencli-oneshot skill](../opencli-oneshot/SKILL.md)（~150 行，4 步搞定）。
 > 本文档适合从零探索一个新站点的完整流程。
 
 ---

package/skills/opencli-oneshot/SKILL.md

@@ -7,7 +7,7 @@ tags: [opencli, adapter, quick-start, yaml, cli, one-shot, automation]
 # CLI-ONESHOT — 单点快速 CLI 生成
 
 > 给一个 URL + 一句话描述，4 步生成一个 CLI 命令。
-> 完整探索式开发请看 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。
+> 完整探索式开发请看 [opencli-explorer skill](../opencli-explorer/SKILL.md)。
 
 ---
 
@@ -219,4 +219,4 @@ opencli mysite mycommand --limit 3 -v      # 实际运行
 
 ## 就这样，没了
 
-写完文件 → build → run → 提交。有问题再看 [CLI-EXPLORER.md](./CLI-EXPLORER.md)。
+写完文件 → build → run → 提交。有问题再看 [opencli-explorer skill](../opencli-explorer/SKILL.md)。

package/skills/opencli-operate/SKILL.md

@@ -4,7 +4,7 @@ description: Make websites accessible for AI agents. Navigate, click, type, extr
 allowed-tools: Bash(opencli:*), Read, Edit, Write
 ---
 
-# OpenCLI — Make Websites Accessible for AI Agents
+# OpenCLI Operate — Browser Automation for AI Agents
 
 Control Chrome step-by-step via CLI. Reuses existing login sessions — no passwords needed.
 
@@ -16,25 +16,61 @@ opencli doctor    # Verify extension + daemon connectivity
 
 Requires: Chrome running + OpenCLI Browser Bridge extension installed.
 
-## Quickstart for AI Agents (1 step)
+## Critical Rules
 
-Point your AI agent to this file. It contains everything needed to operate browsers.
+1. **ALWAYS use `state` to inspect the page, NEVER use `screenshot`** — `state` returns structured DOM with `[N]` element indices, is instant and costs zero tokens. `screenshot` requires vision processing and is slow. Only use `screenshot` when the user explicitly asks to save a visual.
+2. **ALWAYS use `click`/`type`/`select` for interaction, NEVER use `eval` to click or type** — `eval "el.click()"` bypasses scrollIntoView and CDP click pipeline, causing failures on off-screen elements. Use `state` to find the `[N]` index, then `click <N>`.
+3. **Verify inputs with `get value`, not screenshots** — after `type`, run `get value <index>` to confirm.
+4. **Run `state` after every page change** — after `open`, `click` (on links), `scroll`, always run `state` to see the new elements and their indices. Never guess indices.
+5. **Chain commands aggressively with `&&`** — combine `open + state`, multiple `type` calls, and `type + get value` into single `&&` chains. Each tool call has overhead; chaining cuts it.
+6. **`eval` is read-only** — use `eval` ONLY for data extraction (`JSON.stringify(...)`), never for clicking, typing, or navigating. Always wrap in IIFE to avoid variable conflicts: `eval "(function(){ const x = ...; return JSON.stringify(x); })()"`.
+7. **Minimize total tool calls** — plan your sequence before acting. A good task completion uses 3-5 tool calls, not 15-20. Combine `open + state` as one call. Combine `type + type + click` as one call. Only run `state` separately when you need to discover new indices.
+8. **Prefer `network` to discover APIs** — most sites have JSON APIs. API-based adapters are more reliable than DOM scraping.
 
-## Quickstart for Humans (3 steps)
+## Command Cost Guide
 
+| Cost | Commands | When to use |
+|------|----------|-------------|
+| **Free & instant** | `state`, `get *`, `eval`, `network`, `scroll`, `keys` | Default — use these |
+| **Free but changes page** | `open`, `click`, `type`, `select`, `back` | Interaction — run `state` after |
+| **Expensive (vision tokens)** | `screenshot` | ONLY when user needs a saved image |
+
+## Action Chaining Rules
+
+Commands can be chained with `&&`. The browser persists via daemon, so chaining is safe.
+
+**Always chain when possible** — fewer tool calls = faster completion:
 ```bash
-npm install -g @jackwener/opencli          # 1. Install
-# Install extension from chrome://extensions  # 2. Load extension
-opencli operate open https://example.com    # 3. Go!
+# GOOD: open + inspect in one call (saves 1 round trip)
+opencli operate open https://example.com && opencli operate state
+
+# GOOD: fill form in one call (saves 2 round trips)
+opencli operate type 3 "hello" && opencli operate type 4 "world" && opencli operate click 7
+
+# GOOD: type + verify in one call
+opencli operate type 5 "test@example.com" && opencli operate get value 5
+
+# GOOD: click + wait + state in one call (for page-changing clicks)
+opencli operate click 12 && opencli operate wait time 1 && opencli operate state
+
+# BAD: separate calls for each action (wasteful)
+opencli operate type 3 "hello"    # Don't do this
+opencli operate type 4 "world"    # when you can chain
+opencli operate click 7            # all three together
 ```
 
+**Page-changing — always put last** in a chain (subsequent commands see stale indices):
+- `open <url>`, `back`, `click <link/button that navigates>`
+
+**Rule**: Chain when you already know the indices. Run `state` separately when you need to discover indices first.
+
 ## Core Workflow
 
 1. **Navigate**: `opencli operate open <url>`
-2. **Inspect**: `opencli operate state` → see elements with `[N]` indices
+2. **Inspect**: `opencli operate state` → elements with `[N]` indices
 3. **Interact**: use indices — `click`, `type`, `select`, `keys`
-4. **Wait**: `opencli operate wait selector ".loaded"` or `wait text "Success"`
-5. **Verify**: `opencli operate get title` or `opencli operate screenshot`
+4. **Wait** (if needed): `opencli operate wait selector ".loaded"` or `wait text "Success"`
+5. **Verify**: `opencli operate state` or `opencli operate get value <N>`
 6. **Repeat**: browser stays open between commands
 7. **Save**: write a TS adapter to `~/.opencli/clis/<site>/<command>.ts`
 
@@ -43,26 +79,26 @@ opencli operate open https://example.com    # 3. Go!
 ### Navigation
 
 ```bash
-opencli operate open <url>              # Open URL
-opencli operate back                    # Go back
+opencli operate open <url>              # Open URL (page-changing)
+opencli operate back                    # Go back (page-changing)
 opencli operate scroll down             # Scroll (up/down, --amount N)
 opencli operate scroll up --amount 1000
 ```
 
-### Inspect
+### Inspect (free & instant)
 
 ```bash
-opencli operate state                   # Elements with [N] indices
-opencli operate screenshot [path.png]   # Screenshot
+opencli operate state                   # Structured DOM with [N] indices — PRIMARY tool
+opencli operate screenshot [path.png]   # Save visual to file — ONLY for user deliverables
 ```
 
-### Get (structured data)
+### Get (free & instant)
 
 ```bash
 opencli operate get title               # Page title
 opencli operate get url                 # Current URL
 opencli operate get text <index>        # Element text content
-opencli operate get value <index>       # Input/textarea value
+opencli operate get value <index>       # Input/textarea value (use to verify after type)
 opencli operate get html                # Full page HTML
 opencli operate get html --selector "h1" # Scoped HTML
 opencli operate get attributes <index>  # Element attributes
@@ -79,18 +115,37 @@ opencli operate keys "Enter"            # Press key (Enter, Escape, Tab, Control
 
 ### Wait
 
+Three variants — use the right one for the situation:
+
 ```bash
-opencli operate wait selector ".loaded"           # Wait for element
-opencli operate wait selector ".spinner" --timeout 5000  # With timeout
-opencli operate wait text "Success"               # Wait for text
-opencli operate wait time 3                       # Wait N seconds
+opencli operate wait time 3                       # Wait N seconds (fixed delay)
+opencli operate wait selector ".loaded"            # Wait until element appears in DOM
+opencli operate wait selector ".spinner" --timeout 5000  # With timeout (default 30s)
+opencli operate wait text "Success"                # Wait until text appears on page
 ```
 
-### Extract
+**When to wait**: After `open` on SPAs, after `click` that triggers async loading, before `eval` on dynamically rendered content.
+
+### Extract (free & instant, read-only)
+
+Use `eval` ONLY for reading data. Never use it to click, type, or navigate.
 
 ```bash
 opencli operate eval "document.title"
 opencli operate eval "JSON.stringify([...document.querySelectorAll('h2')].map(e => e.textContent))"
+
+# IMPORTANT: wrap complex logic in IIFE to avoid "already declared" errors
+opencli operate eval "(function(){ const items = [...document.querySelectorAll('.item')]; return JSON.stringify(items.map(e => e.textContent)); })()"
+```
+
+**Selector safety**: Always use fallback selectors — `querySelector` returns `null` on miss:
+```bash
+# BAD: crashes if selector misses
+opencli operate eval "document.querySelector('.title').textContent"
+
+# GOOD: fallback with || or ?.
+opencli operate eval "(document.querySelector('.title') || document.querySelector('h1') || {textContent:''}).textContent"
+opencli operate eval "document.querySelector('.title')?.textContent ?? 'not found'"
 ```
 
 ### Network (API Discovery)
@@ -104,10 +159,14 @@ opencli operate network --all            # Include static resources
 ### Sedimentation (Save as CLI)
 
 ```bash
-opencli operate init hn/top              # Generate adapter scaffold
-opencli operate verify hn/top            # Test the adapter
+opencli operate init hn/top              # Generate adapter scaffold at ~/.opencli/clis/hn/top.ts
+opencli operate verify hn/top            # Test the adapter (adds --limit 3 only if `limit` arg is defined)
 ```
 
+- `init` auto-detects the domain from the active browser session (no need to specify it)
+- `init` creates the file + populates `site`, `name`, `domain`, and `columns` from current page
+- `verify` runs the adapter end-to-end and prints output; if no `limit` arg exists in the adapter, it won't pass `--limit 3`
+
 ### Session
 
 ```bash
@@ -128,8 +187,7 @@ opencli operate close
 ```bash
 opencli operate open https://httpbin.org/forms/post
 opencli operate state                   # See [3] input "Customer Name", [4] input "Telephone"
-opencli operate type 3 "OpenCLI"
-opencli operate type 4 "555-0100"
+opencli operate type 3 "OpenCLI" && opencli operate type 4 "555-0100"
 opencli operate get value 3             # Verify: "OpenCLI"
 opencli operate close
 ```
@@ -204,10 +262,45 @@ Save to `~/.opencli/clis/<site>/<command>.ts` → immediately available as `open
 
 **Always prefer API over UI** — if you discovered an API during browsing, use `fetch()` directly.
 
+## Tips
+
+1. **Always `state` first** — never guess element indices, always inspect first
+2. **Sessions persist** — browser stays open between commands, no need to re-open
+3. **Use `eval` for data extraction** — `eval "JSON.stringify(...)"` is faster than multiple `get` calls
+4. **Use `network` to find APIs** — JSON APIs are more reliable than DOM scraping
+5. **Alias**: `opencli op` is shorthand for `opencli operate`
+
+## Common Pitfalls
+
+1. **`form.submit()` fails in automation** — Don't use `form.submit()` or `eval` to submit forms. Navigate directly to the search URL instead:
+   ```bash
+   # BAD: form.submit() often silently fails
+   opencli operate eval "document.querySelector('form').submit()"
+   # GOOD: construct the URL and navigate
+   opencli operate open "https://github.com/search?q=opencli&type=repositories"
+   ```
+
+2. **GitHub DOM changes frequently** — Prefer `data-testid` attributes when available; they are more stable than class names or tag structure.
+
+3. **SPA pages need `wait` before extraction** — After `open` or `click` on single-page apps, the DOM isn't ready immediately. Always `wait selector` or `wait text` before `eval`.
+
+4. **Use `state` before clicking** — Run `opencli operate state` to inspect available interactive elements and their indices. Never guess indices from memory.
+
+5. **`evaluate` runs in browser context** — `page.evaluate()` in adapters executes inside the browser. Node.js APIs (`fs`, `path`, `process`) are NOT available. Use `fetch()` for network calls, DOM APIs for page data.
+
+6. **Backticks in `page.evaluate` break JSON storage** — When writing adapters that will be stored/transported as JSON, avoid template literals inside `page.evaluate`. Use string concatenation or function-style evaluate:
+   ```typescript
+   // BAD: template literal backticks break when adapter is in JSON
+   page.evaluate(`document.querySelector("${selector}")`)
+   // GOOD: function-style evaluate
+   page.evaluate((sel) => document.querySelector(sel), selector)
+   ```
+
 ## Troubleshooting
 
 | Error | Fix |
 |-------|-----|
 | "Browser not connected" | Run `opencli doctor` |
 | "attach failed: chrome-extension://" | Disable 1Password temporarily |
-| Element not found | `opencli operate scroll down` then `opencli operate state` |
+| Element not found | `opencli operate scroll down && opencli operate state` |
+| Stale indices after page change | Run `opencli operate state` again to get fresh indices |