surf-cli 2.8.0 → 2.10.0

package/skills/surf/SKILL.md

@@ -15,6 +15,28 @@ On macOS, Chrome reads the native messaging manifest at `~/Library/Application S
 
 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
@@ -68,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
 ```
 
@@ -89,6 +111,8 @@ surf grok "find viral AI posts" --deep-search     # DeepSearch mode
 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)
@@ -158,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)
@@ -207,12 +232,13 @@ Use `window.new`, `--window-id`, `--tab-id`, and named tabs to keep parallel age
 ## 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
@@ -233,6 +259,7 @@ surf animate-audit --selector ".thing" --duration 2000 --fps 10  # JSON animatio
 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
 ```
@@ -383,10 +410,13 @@ surf network.body --id "req-123"  # Get response body
 surf network.curl --id "req-123"  # Generate curl command
 surf network.origins           # List origins with stats
 surf network.stats             # Capture statistics
-surf network.export            # Export all requests
+surf network -vv --body-mode text --per-body-bytes 65536
+surf network.export --har --output ./trace.har
 surf network.clear             # Clear captured requests
 ```
 
+Response-body capture supports `none`, `text`, and `all` modes plus per-body and per-tab-session byte caps. HAR exports carry body completeness metadata. Persistent network state is private under `~/.surf/state/network/` by default; configure `SURF_NETWORK_PATH` in the native host environment to change it.
+
 ## Console
 
 ```bash
@@ -555,6 +585,43 @@ surf workflow.validate workflow.json
 
 **Why use `do`?** Instead of 6-8 separate CLI calls with LLM orchestration between each, a workflow executes deterministically. Faster, cheaper, and more reliable.
 
+## Playbooks
+
+Use `surf do` for a direct command sequence. Use a playbook for a reusable site capability with provenance, browser-session network execution, workflow fallback, and write-safety policy.
+
+```bash
+surf playbook list
+surf pb show page
+surf pb ops page
+surf use page read --json
+```
+
+Resolution order is project (`./.surf/playbooks/`), user (`~/.surf/playbooks/`), then built-in. Provider compatibility commands stay on their validated command paths until provider playbooks have real login-flow validation. A write op requires `--write`; Surf records semantic intent before dispatch so a timeout or concurrent retry cannot silently double-submit.
+
+Author from redacted recent activity when it contains only read/navigation behavior, or use an explicit record for richer evidence:
+
+```bash
+surf pb suggest --since 1h
+surf pb save example --op read --from-recent 1h
+surf pb record start example --op read --network --watch
+surf pb record mark "loaded results"
+surf pb record stop --draft
+surf pb save --from-record <record-id>
+surf pb trace export --from-record <record-id> --har ./trace.har
+surf pb export example --out ./example-playbook
+surf pb import ./example-playbook
+```
+
+Records, trace slices, receipts, and the bounded activity journal are private Surf state. Inputs and authentication headers are redacted by default. Use `--include-input-values` only when the saved values are necessary and acceptable.
+
+Client projections replay a validated read endpoint and never embed captured browser credentials:
+
+```bash
+surf pb client derive example --op read --from-record <record-id> --request-id <request-id> --out ./client
+surf pb client export example --op read --out ./client
+surf pb client verify ./client
+```
+
 ## Error Diagnostics
 
 ```bash