High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: refresh pinchtab skill command and profile references
Bosch3aedea7a555f
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex 7a0640a6..03aabdd9 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -35,7 +35,7 @@ CLI-first browser skill. Use `pinchtab` commands.- `--mode` and `--humanize` are mutually exclusive.4. For read-only observation: `pinchtab text` when you won't act on refs.-**Key optimization**: Use `--snap-diff` on `click`, `fill`, `select`, `back`, `forward`, `reload` to get only added/changed/removed elements — most token-efficient for multi-step flows. Use `--snap` when you need the full snapshot (e.g., first navigation, or after major page changes). Use `--text` when you need prose content for verification (skips snap, returns page text directly).+**Key optimization**: Use `--snap-diff` on `nav`, `click`, `fill`, `select`, `press`, `scroll`, `back`, `forward`, `reload` to get only added/changed/removed elements — most token-efficient for multi-step flows. Use `--snap` when you need the full snapshot (e.g., first navigation, or after major page changes). `--text` is available on `click`, `fill`, `select`, `press`, `back`, `forward`, `reload` (but NOT on `nav` or `scroll`) when you need prose content for verification (skips snap, returns page text directly). `dblclick` does not support any observation flag — run a separate `snap` after.`--snap-diff` returns the same compact format as `snap`, but with change markers and a header showing counts:```@@ -64,7 +64,7 @@ Rules: only `nav <url>` auto-starts the default local server; `snap`, `text`, `h- Do not save screenshots, PDFs, or downloads to arbitrary paths — use a user-specified path or a safe temporary/workspace directory.- Do not use PinchTab to inspect unrelated local files, browser secrets, stored credentials, or system configuration outside the task.- Cookie access is disabled by default; do not inspect, change, or clear cookies without explicit user approval.-- Network exports (`pinchtab network-export`) may contain private URLs, auth tokens, and response bodies. Omit `--body` for sensitive sessions. Delete or redact export files after use.+- Network captures (`pinchtab network`, optionally `pinchtab network <requestId> --body`) may contain private URLs, auth tokens, and response bodies. Omit `--body` for sensitive sessions. Delete or redact exported data after use.## Selectors@@ -105,7 +105,7 @@ Key settings agents may need to change:- `security.allowEvaluate`: enable `eval` command (`true`/`false`)- `security.allowScreencast`: enable `record` commands (`true`/`false`)- `security.allowedDomains`: list of allowed hostnames (e.g. `["localhost", "127.0.0.1"]`)-- `instanceDefaults.headless`: run Chrome headless (`true`) or headed (`false`)+- `instanceDefaults.mode`: `"headless"` or `"headed"` (string, not boolean)After changing config with the server running, restart to apply: `pinchtab server restart`.@@ -188,12 +188,29 @@ pinchtab press <key> # Enter, Tab, Escape, ...pinchtab hover <selector>pinchtab select <selector> <value|text> # flags: --snap, --snap-diff, --text; matches value attr, falls back to visible textpinchtab scroll <pixels|direction|selector> # `scroll 1500`, `scroll down`, `scroll '#footer'`+pinchtab check <selector> | uncheck <selector> # toggle checkboxes / radios+pinchtab focus <selector> # move keyboard focus+pinchtab scrollintoview <selector> # scroll element into view+pinchtab dialog accept | dismiss [--text "..."] # standalone dialog handling (besides click --dialog-action)+pinchtab keyboard type <text> | inserttext <text> # low-level keystroke text entry+pinchtab keydown <key> | keyup <key> # individual key events+```++DOM inspection helpers (skip a snap when you only need one value):++```bash+pinchtab title | url | html # page metadata / serialized HTML+pinchtab value <selector> # form-field value+pinchtab attr <selector> <name> # arbitrary attribute+pinchtab count <selector> # querySelectorAll length+pinchtab box <selector> # getBoundingClientRect+pinchtab visible <selector> | enabled <selector> | checked <selector>```Rules:- Default output is `OK`; use `--json` for recovery metadata. Errors go to stderr as `ERROR: <cmd>: <reason>`.-- **Prefer `--snap-diff`** with `click`, `fill`, `select`, `back`, `forward`, `reload` — returns `OK` + only changed elements. Use `--snap` when you need the full snapshot (first nav, major page change).+- **Prefer `--snap-diff`** with `click`, `fill`, `select`, `press`, `scroll`, `back`, `forward`, `reload` — returns `OK` + only changed elements. Use `--snap` when you need the full snapshot (first nav, major page change). `dblclick` has no observation flags — chain a separate `snap` after.- Prefer `fill` for form entry; `type` only when the site depends on keystroke events.- Click behavior: omit `--mode` for the normal click path, use `click --mode dom` for `element.click()`, or `click --mode dispatch` for synthetic click events.- Treat `click --mode dom` and `click --mode dispatch` as broad low-level escape hatches; bypassing occlusion is the common case.@@ -211,14 +228,14 @@ Use for async DOM settling (spinners, toasts, XHR).```bashpinchtab wait <selector> # default: visible; --state hidden to wait for disappear-pinchtab wait --text "..." | --not-text "..." # text appear / disappear+pinchtab wait --text "..." | --not-text "..." # text appear / disappear (polls document.body.innerText)pinchtab wait --url "**/dashboard" # glob: **, *, ?-pinchtab wait --load ready-state|content-loaded|network-idle-pinchtab wait --fn "window.dataReady === true" # requires security.allowEvaluate+pinchtab wait --load ready-state|content-loaded|network-idle [--idleFor <ms>]+pinchtab wait --fn "window.dataReady === true" # requires security.allowEvaluate: true (else 403 evaluate_disabled)pinchtab wait 500 # fixed ms delay (last resort, max 30000ms)```-Timeout 10s default, 30s max via `--timeout <ms>`. Prefer `--not-text`/`--state hidden` over polling.+Timeout 10s default, 30s max via `--timeout <ms>`. All non-`ms` wait modes poll internally every ~250ms. For dynamic SPA content (iframes, shadow DOM, virtualized lists) where `document.body.innerText` is unreliable, prefer `wait <selector> --state hidden|visible` over `--text`/`--not-text`. `--idleFor <ms>` tunes the quiet-period for `--load network-idle` (default 500ms, max 10000).### Export, debug, verificationdiff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.mdindex d2b4cfb1..dab48751 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -135,13 +135,16 @@ pinchtab drag e5 400,320Use these for drag handles, canvas controls, precise hover choreography, or sites that require exact pointer sequencing.-### `pinchtab scroll [ref]`-Scroll the page or a specific element.+### `pinchtab scroll <pixels|direction|selector>`+Scroll the page or a specific element. Argument is positional — there is no `--pixels` flag.```bash-pinchtab scroll # scroll page down 300px-pinchtab scroll --pixels -300 # scroll up-pinchtab scroll e20 --pixels 500+pinchtab scroll 800 # scroll page down 800px+pinchtab scroll -300 # scroll page up 300px+pinchtab scroll down # named direction (also up, top, bottom)+pinchtab scroll '#footer' # scroll a CSS selector into view+pinchtab scroll e20 # scroll an element ref into view+pinchtab scroll 800 --snap-diff```### `pinchtab select <ref> <value>`diff --git a/skills/pinchtab/references/profiles.md b/skills/pinchtab/references/profiles.mdindex 15961c3a..70bf9022 100644--- a/skills/pinchtab/references/profiles.md+++ b/skills/pinchtab/references/profiles.md@@ -20,9 +20,6 @@ curl -X POST http://localhost:9867/profiles/<ID>/startcurl -X POST http://localhost:9867/profiles/<ID>/start \-H 'Content-Type: application/json' \-d '{"port": "9868", "headless": true}'--# Short alias-curl -X POST http://localhost:9867/start/<ID>```Returns instance info including allocated `port`. Use that port for all subsequent API calls.@@ -31,9 +28,6 @@ Returns instance info including allocated `port`. Use that port for all subseque```bashcurl -X POST http://localhost:9867/profiles/<ID>/stop--# Short alias-curl -X POST http://localhost:9867/stop/<ID>```## Check instance status@@ -60,11 +54,20 @@ curl -X POST http://localhost:9867/instances/start \## CLI usage with profiles-The CLI doesn't have profile subcommands yet — use `curl` for profile management.-Once a profile instance is running, point the CLI at it using the `--server` flag:+CLI subcommands are available — use these instead of `curl` when possible:++```bash+pinchtab profiles # list profiles+pinchtab instance start --profile <name> # start (auto-allocates port)+pinchtab instance navigate <id> <url>+pinchtab instance stop <id>+pinchtab instance restart <id>+pinchtab instance logs <id>+```++Once a profile instance is running, the CLI auto-routes to it; you can also target it explicitly:```bash-# Get the instance port, then use CLIpinchtab --server http://localhost:9868 snap -i```