surf-cli 2.7.2 → 2.9.0

package/scripts/uninstall-native-host.cjs

@@ -2,7 +2,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execSync } = require("child_process");
+const { execFileSync, execSync } = require("child_process");
 
 const HOST_NAME = "surf.browser.host";
 
@@ -12,43 +12,80 @@ const BROWSERS = {
     darwin: "Library/Application Support/Google/Chrome/NativeMessagingHosts",
     linux: ".config/google-chrome/NativeMessagingHosts",
     win32: "Google\\Chrome",
+    wsl: "Google/Chrome/User Data/NativeMessagingHosts",
   },
   chromium: {
     name: "Chromium",
     darwin: "Library/Application Support/Chromium/NativeMessagingHosts",
     linux: ".config/chromium/NativeMessagingHosts",
     win32: "Chromium",
+    wsl: "Chromium/User Data/NativeMessagingHosts",
   },
   brave: {
     name: "Brave",
     darwin: "Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts",
     linux: ".config/BraveSoftware/Brave-Browser/NativeMessagingHosts",
     win32: "BraveSoftware\\Brave-Browser",
+    wsl: "BraveSoftware/Brave-Browser/User Data/NativeMessagingHosts",
   },
   edge: {
     name: "Microsoft Edge",
     darwin: "Library/Application Support/Microsoft Edge/NativeMessagingHosts",
     linux: ".config/microsoft-edge/NativeMessagingHosts",
     win32: "Microsoft\\Edge",
+    wsl: "Microsoft/Edge/User Data/NativeMessagingHosts",
   },
   arc: {
     name: "Arc",
     darwin: "Library/Application Support/Arc/User Data/NativeMessagingHosts",
     linux: null,
     win32: null,
+    wsl: null,
   },
   helium: {
     name: "Helium",
     darwin: "Library/Application Support/net.imput.helium/NativeMessagingHosts",
     linux: null,
     win32: null,
+    wsl: null,
   },
 };
 
-function getWrapperDir() {
-  const platform = process.platform;
+function isWsl() {
+  if (process.platform !== "linux") return false;
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+function getWindowsEnv(name) {
+  try {
+    return execFileSync("cmd.exe", ["/c", "echo", `%${name}%`], { encoding: "utf8" })
+      .trim()
+      .replace(/\r/g, "");
+  } catch {
+    return null;
+  }
+}
+
+function windowsPathToWslPath(winPath) {
+  const normalized = winPath.replace(/\\/g, "/");
+  const match = normalized.match(/^([A-Za-z]):\/(.*)$/);
+  if (!match) return normalized;
+  return `/mnt/${match[1].toLowerCase()}/${match[2]}`;
+}
+
+function getWrapperDir(target = process.platform) {
   const home = os.homedir();
-  switch (platform) {
+  if (target === "wsl-windows") {
+    const localAppData = getWindowsEnv("LOCALAPPDATA");
+    if (!localAppData) return null;
+    return path.join(windowsPathToWslPath(localAppData), "surf-cli");
+  }
+  switch (process.platform) {
     case "darwin":
       return path.join(home, "Library/Application Support/surf-cli");
     case "linux":
@@ -60,14 +97,31 @@ function getWrapperDir() {
   }
 }
 
-function removeManifest(browser) {
-  const platform = process.platform;
+function getWslWindowsManifestPath(browserConfig) {
+  const localAppData = getWindowsEnv("LOCALAPPDATA");
+  if (!localAppData || !browserConfig.wsl) return null;
+  return path.join(windowsPathToWslPath(localAppData), browserConfig.wsl, `${HOST_NAME}.json`);
+}
+
+function removeManifest(browser, target) {
   const browserConfig = BROWSERS[browser];
 
-  if (!browserConfig || !browserConfig[platform]) {
-    return null;
+  if (!browserConfig) return null;
+
+  if (target === "wsl-windows") {
+    const manifestPath = getWslWindowsManifestPath(browserConfig);
+    if (!manifestPath) return null;
+    try {
+      fs.unlinkSync(manifestPath);
+      return manifestPath;
+    } catch {
+      return null;
+    }
   }
 
+  const platform = process.platform;
+  if (!browserConfig[platform]) return null;
+
   if (platform === "win32") {
     return removeWindowsRegistry(browser);
   }
@@ -98,8 +152,8 @@ function removeWindowsRegistry(browser) {
   }
 }
 
-function removeWrapperDir() {
-  const wrapperDir = getWrapperDir();
+function removeWrapperDir(target) {
+  const wrapperDir = getWrapperDir(target);
   if (!wrapperDir) return null;
 
   try {
@@ -112,7 +166,7 @@ function removeWrapperDir() {
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const result = { browsers: ["chrome"], all: false };
+  const result = { browsers: ["chrome"], all: false, target: "auto" };
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -127,6 +181,8 @@ function parseArgs() {
     } else if (arg === "--all" || arg === "-a") {
       result.browsers = Object.keys(BROWSERS);
       result.all = true;
+    } else if (arg === "--target") {
+      result.target = args[++i];
     } else if (arg === "--help" || arg === "-h") {
       printHelp();
       process.exit(0);
@@ -145,18 +201,40 @@ Options:
   -b, --browser   Browser(s) to uninstall from (default: chrome)
                   Values: chrome, chromium, brave, edge, arc, helium, all
   -a, --all       Uninstall from all browsers and remove wrapper
+  --target        Install target to remove: auto, linux, windows
+                  On WSL2, auto removes Windows-browser manifests. Use linux for WSLg/Linux browsers.
 
 Examples:
   node uninstall-native-host.cjs
   node uninstall-native-host.cjs --browser brave
   node uninstall-native-host.cjs --all
+  node uninstall-native-host.cjs --target linux
 `);
 }
 
 function main() {
-  const { browsers, all } = parseArgs();
+  const { browsers, all, target } = parseArgs();
+
+  if (!["auto", "linux", "windows"].includes(target)) {
+    console.error("Error: Invalid --target value. Expected auto, linux, or windows");
+    process.exit(1);
+  }
+
+  const runningInWsl = isWsl();
+  if (target === "windows" && !runningInWsl && process.platform !== "win32") {
+    console.error("Error: --target windows is only supported on Windows or WSL2");
+    process.exit(1);
+  }
+
+  if (target === "linux" && process.platform !== "linux") {
+    console.error("Error: --target linux is only supported on Linux or WSL2");
+    process.exit(1);
+  }
+
+  const effectiveTarget = runningInWsl && target !== "linux" ? "wsl-windows" : process.platform;
 
-  console.log(`Platform: ${process.platform}`);
+  console.log(`Platform: ${process.platform}${runningInWsl ? " (WSL2 detected)" : ""}`);
+  console.log(`Target: ${effectiveTarget === "wsl-windows" ? "Windows browser from WSL2" : effectiveTarget}`);
   console.log("");
 
   const removed = [];
@@ -168,7 +246,7 @@ function main() {
       continue;
     }
 
-    const result = removeManifest(browser);
+    const result = removeManifest(browser, effectiveTarget);
     if (result) {
       removed.push({ browser: BROWSERS[browser].name, path: result });
     } else {
@@ -188,7 +266,7 @@ function main() {
   }
 
   if (all) {
-    const wrapperDir = removeWrapperDir();
+    const wrapperDir = removeWrapperDir(effectiveTarget);
     if (wrapperDir) {
       console.log(`\nRemoved wrapper directory: ${wrapperDir}`);
     }

package/skills/README.md

@@ -1,21 +1,27 @@
 # Surf Skills
 
-This directory contains skill files for AI coding agents.
+This directory contains skill files for AI coding agents:
+
+- **`surf/`** — the core browser-automation reference: every surf command, workflows, AI assistants, troubleshooting.
+- **`deep-x-research/`** — a research procedure built on surf: exhaustive, multi-angle X (Twitter) research with categorized findings and full post-URL traceability. Requires x.com login in Chrome.
+
+Install each skill folder the same way (symlink or copy).
 
 ## Pi Agent
 
-To use the surf skill with [Pi coding agent](https://github.com/badlogic/pi-mono):
+To use a skill with [Pi coding agent](https://github.com/badlogic/pi-mono):
 
 ```bash
 # Option 1: Symlink (auto-updates)
 ln -s "$(pwd)/skills/surf" ~/.agents/skills/surf
+ln -s "$(pwd)/skills/deep-x-research" ~/.agents/skills/deep-x-research
 
 # Option 2: Copy
-cp -r skills/surf ~/.agents/skills/
+cp -r skills/surf skills/deep-x-research ~/.agents/skills/
 ```
 
-The skill will be available when pi detects browser automation tasks.
+The skills will be available when pi detects browser automation or X research tasks.
 
 ## Other Agents
 
-The `SKILL.md` file is a comprehensive reference that can be adapted for other AI coding agents or used as documentation for LLM prompts.
+Each `SKILL.md` file can be adapted for other AI coding agents (Claude Code, Codex) or used as documentation for LLM prompts — copy the skill folder into the agent's skills directory (e.g. `~/.claude/skills/`, `~/.agents/skills/`).

package/skills/deep-x-research/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: deep-x-research
+description: Deep, exhaustive research on a topic across X (Twitter) by driving Grok (x.com/i/grok) through surf. Use when the user wants comprehensive X research on a concept, technique, trend, tool, or creator scene; needs categorized findings with every claim traceable to post URLs; or when a single Grok query is not enough.
+---
+
+# Deep X Research
+
+Research a topic across X by putting Grok to work from multiple angles — it runs keyword and semantic X searches and watches videos natively — then deliver categorized findings where every claim is traceable to a post URL.
+
+Requires: surf installed and connected (`surf doctor`), Chrome logged into x.com. Command reference: the `surf` skill or `surf --help`.
+
+**Quota:** X caps Grok requests (typically 15 per 20 hours on a standard plan). Every `surf grok` call spends one. Budget the session before the first query and make each query do multi-angle work — never spend a request on what a quota-free step can answer.
+
+## Steps
+
+### 1. Decompose the topic and budget the queries
+
+Break the topic into angles: showcases/examples, techniques & tutorials, tools, notable creators, community discussion — adapt to the topic. Plan a Grok budget of **4-8 queries** covering every angle (combine related angles into one query rather than spending two). Done when each angle is assigned to a budgeted query.
+
+### 2. Grok sweep
+
+Run the budgeted queries sequentially. Engineer each so Grok does the fan-out internally and returns traceable sources:
+
+```bash
+# Broad pass — force multi-angle search and URLs
+surf grok "Do deep research on TOPIC on X. Search both latest and top posts, keyword and semantic. Return the most relevant posts with full post URLs (x.com/user/status/ID) and a one-line description of each."
+
+# Focused passes — one per remaining angle group
+surf grok "TOPIC on X: tutorials, techniques, and the tools people use. Include post URLs for every example."
+
+# Deepest pass — spend DeepSearch on the highest-value angle
+surf grok "TOPIC: notable creators, how the trend is evolving, and the standout posts of the last 6 months. Post URLs required." --deep-search
+```
+
+Record every post Grok cites: author, one-line gist, full `https://x.com/USER/status/ID` URL. If a response gives claims without URLs, the *next* query in the budget re-asks for sources — never leave an angle sourceless. Done when every planned angle has been queried and the final response adds no new relevant posts, or the budget is spent.
+
+### 3. Video pass (visual topics)
+
+When the topic involves video, editing, or visual style, spend 1-3 budgeted queries having Grok analyze the strongest video posts — it can watch X videos natively:
+
+```bash
+surf grok "Analyze the videos in these posts: URL1 URL2 URL3 — for each, describe the techniques, pacing, and style, and why it works."
+```
+
+Batch several URLs per query to conserve budget. Done when each analyzed video has notes on what it shows and why it matters for the topic.
+
+### 4. Enrich and verify — quota-free
+
+For each cited post, open it directly with surf (no Grok spend) to verify the URL resolves and harvest detail Grok didn't give:
+
+```bash
+surf navigate "https://x.com/USER/status/ID" && surf wait 2
+surf page.read --compact          # engagement numbers, thread context
+surf network | grep video.twimg   # direct video URL after playback
+```
+
+Done when every URL destined for the References section has been resolved (dead or hallucinated links dropped or replaced).
+
+### 5. Categorize and analyze
+
+Group findings into categories that fit the topic. Extract trends: momentum on X, recurring techniques, notable creators, how the topic is evolving. Done when every recorded post is either placed in a category or deliberately dropped as irrelevant.
+
+### 6. Report with full traceability
+
+```md
+# Deep Research on [Topic]
+
+## Summary
+[2-4 paragraphs: state of the topic on X]
+
+## Key Trends
+- ...
+
+## Categorized Findings
+### [Category]
+- [Finding with inline post reference]
+
+## Notable Creators & Techniques
+- ...
+
+## References
+1. [Author — one-line description]
+   https://x.com/USER/status/ID
+   Video: https://video.twimg.com/... (when captured)
+```
+
+The report is done when **every post mentioned anywhere in it appears in References with its full, verified URL** — no bare @handles, no "a viral post showed…" without a link.
+
+## Fallback: direct search when the Grok quota is exhausted
+
+The x.com search UI costs no Grok requests. Slower and keyword-only, but it keeps the sweep going:
+
+```bash
+surf navigate "https://x.com/search?q=QUERY&f=live" && surf wait 3   # Latest
+surf page.read --compact
+surf scroll down 2000    # then page.read again — repeat to load more
+```
+
+Modes via the `f=` param: **Top is the default (no `f` param)** — there is no `f=top`; `f=live` = Latest, `f=user` = People, `f=media` = Media. Operators compose into the URL-encoded `q=`: `"exact phrase"`, `filter:videos`, `min_faves:100`, `min_retweets:50`, `from:user`, `since:2026-01-01`, `until:2026-06-01`.
+
+## Troubleshooting
+
+- Grok replies with a rate-limit message → quota exhausted; switch to the fallback sweep and tell the user when the quota resets.
+- Grok queries fail outright → `surf grok --validate`, then retry with a model from the validation output (see the `surf` skill's AI troubleshooting section).
+- Grok cites posts without URLs → re-ask in the next budgeted query; do not invent URLs.
+- Search page shows a login wall → Chrome isn't logged into x.com; ask the user to log in.

package/skills/surf/SKILL.md

@@ -7,6 +7,36 @@ description: Control Chrome browser via CLI for testing, automation, and debuggi
 
 Control Chrome browser via CLI or Unix socket.
 
+## Native Host / Socket Notes
+
+For WSL2 with Windows Chrome, run `surf install <extension-id>` inside WSL2. Surf detects WSL2 and writes the Windows-side native messaging manifest plus a wrapper that launches the WSL host. Use `surf install <extension-id> --target linux` only for Linux browsers running inside WSLg.
+
+On macOS, Chrome reads the native messaging manifest at `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/surf.browser.host.json`. If native messaging fails, confirm that file exists, its `allowed_origins` extension ID matches `chrome://extensions`, then rerun `surf install <extension-id>`, restart Chrome, reload the extension, and inspect the extension service-worker console.
+
+If a command reports `Socket connect failed`, run `surf doctor` first, then check the `Attempted socket:` line. Default sockets are `/tmp/surf.sock` on macOS/Linux/WSL2 and `//./pipe/surf` on Windows. If `SURF_SOCKET` is set, the browser-launched host and the shell running `surf` must use the same value.
+
+## Remote Surf
+
+Remote clients require a per-client credential; Tailnet reachability alone is not authorization. On the POSIX browser host, authorize the client before installing the listener:
+
+```bash
+surf remote authorize agent-macbook --output ~/agent-macbook.surf-credential.json
+surf install <extension-id> --listen 100.101.102.103:4321
+surf remote list
+```
+
+Move the mode-0600 credential to the client through a secure channel. It grants full trusted Surf authority. Use it explicitly or through `SURF_REMOTE` and `SURF_REMOTE_CREDENTIAL`:
+
+```bash
+surf --remote 100.101.102.103:4321 \
+  --remote-credential ~/.config/surf/agent-macbook.json \
+  page.read
+
+surf remote revoke agent-macbook  # Run on the browser host
+```
+
+Remote paths are client-local by default. `local:./file` is explicit client-local syntax; only `remote:/absolute/path` accesses the browser host directly. Remote transfer supports one upload or ChatGPT/Gemini input and one screenshot, network-export, or Gemini image output. Limits are 256 MiB per file, 512 MiB and 32 files per connection, and 256 KiB decoded chunks. `record`, `aistudio.build`, smoke screenshot directories, directories, and multi-file inputs are not supported remotely. Successful action screenshots and failure `--auto-capture` diagnostics are transferred back to client-local paths.
+
 ## CLI Quick Reference
 
 ```bash
@@ -35,6 +65,9 @@ surf type --text "hello"
 
 # 5. Screenshot
 surf screenshot --output /tmp/shot.png
+
+# Inspect animation/style changes as JSON
+surf animate-audit --selector ".thing" --duration 2000 --fps 10
 ```
 
 ## AI Assistants (No API Keys)
@@ -57,7 +90,7 @@ surf gemini "analyze" --file data.csv             # Attach file
 surf gemini "a robot surfing" --generate-image /tmp/robot.png
 surf gemini "add sunglasses" --edit-image photo.jpg --output out.jpg
 surf gemini "summarize" --youtube "https://youtube.com/..."
-surf gemini "hello" --model gemini-2.5-flash      # Models: gemini-3-pro (default), gemini-2.5-pro, gemini-2.5-flash
+surf gemini "hello" --model gemini-3.5-flash      # Models: gemini-3.1-pro (default), gemini-3.5-flash, gemini-3.1-flash-lite
 surf gemini "wide banner" --generate-image /tmp/banner.png --aspect-ratio 16:9
 ```
 
@@ -75,9 +108,11 @@ surf grok "what are the latest AI trends on X"    # Search X posts
 surf grok "analyze @username recent activity"     # Profile analysis  
 surf grok "summarize this page" --with-page       # Include page context
 surf grok "find viral AI posts" --deep-search     # DeepSearch mode
-surf grok "quick question" --model fast           # Models: auto, fast, expert, thinking (default)
+surf grok "quick question" --model fast           # Models: auto, fast, expert, grok-4.20-beta
 ```
 
+For exhaustive, multi-angle X research with categorized findings and full post-URL traceability, use the `deep-x-research` skill (`skills/deep-x-research/`) instead of a single Grok query.
+
 **Grok Validation & Troubleshooting:**
 ```bash
 # Validate Grok UI and check available models (no query sent)
@@ -122,7 +157,7 @@ When AI queries fail, check these common issues:
 
 1. **Not logged in**: The error "login required" means you need to log into the service in Chrome (chatgpt.com, gemini.google.com, perplexity.ai, x.com, or aistudio.google.com)
 2. **Model selection failed**: The UI may have changed. Run `surf grok --validate` to check
-3. **Response timeout**: Thinking models (ChatGPT o1, Grok thinking) can take 45+ seconds. AI Studio builds can take several minutes.
+3. **Response timeout**: Reasoning-heavy models (ChatGPT o1, Grok Expert) can take 45+ seconds. AI Studio builds can take several minutes.
 4. **Element not found**: The service's UI changed. Check for surf-cli updates
 
 **Debugging workflow for agents:**
@@ -147,6 +182,7 @@ surf tab.list
 surf tab.new "https://google.com"
 surf tab.switch 12345
 surf tab.close 12345
+surf tab.move 12345 --to-window 67890
 surf tab.reload                # Reload current tab
 
 # Named tabs (aliases)
@@ -165,6 +201,8 @@ surf tab.groups                # List all tab groups
 
 ```bash
 surf window.list                              # List all windows
+surf resize 1280 720                         # Resize current browser window
+surf resize 1280                             # Set current window width only
 surf window.list --tabs                       # Include tab details
 surf window.new                               # New window
 surf window.new --url "https://example.com"   # New window with URL
@@ -176,24 +214,31 @@ surf window.resize --id 123 --width 1920 --height 1080
 surf window.resize --id 123 --state maximized # States: normal, minimized, maximized, fullscreen
 ```
 
-**Window isolation for agents:**
+**Multi-agent isolation:**
 ```bash
-# Create isolated window for agent work
+# Create a separate window for one agent and keep using its ID
 surf window.new "https://example.com"
-# Returns window ID, use with subsequent commands:
 surf --window-id 123 tab.list
 surf --window-id 123 go "https://other.com"
+
+# Pin work to a specific tab, or name it for easier handoff
+surf read --tab-id 456
+surf tab.name agent-a --tab-id 456
+surf tab.switch agent-a
 ```
 
+Use `window.new`, `--window-id`, `--tab-id`, and named tabs to keep parallel agents on separate targets. Surf serializes non-streaming browser CLI requests per socket with a file-based lock, so agents sharing one native host wait instead of interleaving commands. Use `--no-lock` only for intentional bypasses. For hard isolation, run separate browser/profile instances with separate native hosts and `SURF_SOCKET` values; each socket gets its own lock. Surf does not yet have `session.new`, session IDs, or independent per-agent CDP sessions.
+
 ## Input Methods
 
 ```bash
-# CDP method (real events) - default
+# CDP method (real events) types at the current focus
 surf type --text "hello"
 surf click --x 100 --y 200
 
-# JS method (DOM manipulation) - for contenteditable
-surf type --text "hello" --selector "#input" --method js
+# Selector/ref targets use frame-aware DOM input
+surf type "hello" --into "#input"
+surf type "hello" --ref e5
 
 # Keys
 surf key Enter
@@ -210,9 +255,11 @@ surf drag --from-x 100 --from-y 100 --to-x 200 --to-y 200
 ```bash
 surf page.read                 # Accessibility tree with refs + page text
 surf page.read --no-text       # Interactive elements only (no text content)
+surf animate-audit --selector ".thing" --duration 2000 --fps 10  # JSON animation timeline
 surf page.read --ref e5        # Get specific element details
 surf page.read --depth 3       # Limit tree depth
 surf page.read --compact       # Minimal output for LLM efficiency
+surf page.read --max-bytes 2000 # Cap visible text at a UTF-8 byte boundary
 surf page.text                 # Plain text content only
 surf page.state                # Modals, loading state, scroll info
 ```
@@ -258,11 +305,13 @@ surf element.styles ".card"            # Or by CSS selector
 ## Scrolling
 
 ```bash
-surf scroll.bottom
-surf scroll.top  
-surf scroll.to --y 500         # Scroll to Y position
+surf scroll down 800           # Scroll down 800px
+surf scroll up 400             # Scroll up 400px
+surf scroll bottom             # Scroll to bottom
+surf scroll top                # Scroll to top
+surf scroll.bottom             # Dot command form also works
+surf scroll.top
 surf scroll.to --ref e5        # Scroll element into view
-surf scroll.by --y 200         # Scroll by amount
 surf scroll.info               # Get scroll position
 ```
 
@@ -395,6 +444,7 @@ surf screenshot                           # Auto-saves to /tmp/surf-snap-*.png
 surf screenshot --output /tmp/shot.png    # Save to specific file
 surf screenshot --selector ".card"        # Element only
 surf screenshot --full-page               # Full page scroll capture
+surf screenshot --full-page /tmp/full.png # Full page saved to path
 surf screenshot --no-save                 # Return base64 only, don't save file
 ```
 
@@ -409,11 +459,12 @@ surf zoom 1                    # Reset to 100%
 ## Cookies & Storage
 
 ```bash
-surf cookie.list               # List cookies for current page
-surf cookie.list --domain .google.com
-surf cookie.set --name "token" --value "abc123"
-surf cookie.get --name "token"
-surf cookie.clear              # Clear all cookies
+surf cookie list               # List cookies for current page
+surf cookie list --domain .google.com
+surf cookie set --name "token" --value "abc123"
+surf cookie get "token"
+surf cookie clear --all        # Clear all cookies
+surf cookie delete "token"     # Clear one cookie
 ```
 
 ## History & Bookmarks
@@ -558,13 +609,17 @@ surf wait.element ".missing" --auto-capture --timeout 2000
 5. **Auto-capture for debugging** - `--auto-capture` saves diagnostics on failure
 6. **AI tools use browser session** - Must be logged into the service (ChatGPT, Gemini, Perplexity, Grok, AI Studio), no API keys needed
 7. **Grok validation** - Run `surf grok --validate` if queries fail to check UI changes
-8. **Long timeouts for thinking models** - ChatGPT o1, Grok thinking can take 60+ seconds. AI Studio builds default to 600s.
+8. **Long timeouts for reasoning-heavy models** - ChatGPT o1 and Grok Expert can take 60+ seconds. AI Studio builds default to 600s.
 9. **AI Studio for unrestricted Gemini** - `surf aistudio` gives less filtered responses than `surf gemini` for the same models
 10. **Use `surf do` for multi-step tasks** - Reduces token overhead and improves reliability
 11. **Dry-run workflows first** - `surf do '...' --dry-run` validates without executing
-12. **Window isolation** - Use `window.new` + `--window-id` to keep agent work separate from your browsing
-13. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
-14. **Frame context** - Use `frame.switch` before interacting with iframe content
+12. **Window isolation** - Use `window.new` + `--window-id` or `--tab-id` to keep agent work separate from your browsing
+13. **Request lock** - Non-streaming browser CLI requests serialize per socket; use `--no-lock` only when you intentionally want to bypass it
+14. **Native host diagnostics** - If commands fail with socket/native-host errors, run `surf doctor` or `surf doctor --browser all` before guessing at reinstall steps
+15. **Animation capture** - Use `surf record --duration 2000 --fps 10 --output /tmp/anim.gif` when the agent needs to see motion; use `animate-audit` for numeric timelines and `perf-audit` for jank/layout-shift snapshots
+16. **Hard isolation** - Use separate browser/profile instances plus separate `SURF_SOCKET` values when agents must not share a host or target
+17. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
+18. **Frame context** - Use `frame.switch` before interacting with iframe content
 
 ## Socket API