surf-cli 2.19.0 → 2.20.0

package/skills/surf/SKILL.md

@@ -13,7 +13,7 @@ Ordinary socket-backed CLI commands report top-level host tool-response errors o
 
 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.
+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, and reload the extension. Open Surf's service-worker console from `chrome://extensions`; in **Details > Extension options**, enable **Debug Mode**, reproduce the failure, then disable it when finished.
 
 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.
 
@@ -94,6 +94,83 @@ surf screenshot --full-page --output /tmp/shot.png
 surf animate-audit --selector ".thing" --duration 2000 --fps 10
 ```
 
+## Optional semantic decisions
+
+`semantic.act` is a bounded, goal-driven website controller. It repeatedly
+observes the page, lets Jev select the next action from Surf's allowed menu,
+validates and executes that action, and checks the overall goal:
+
+```text
+goal -> observe -> choose -> validate + act -> verify
+           ^                              |
+           +-------- incomplete ----------+
+```
+
+It returns when the goal is complete, a decision is uncertain, or a configured
+budget is exhausted. Use `semantic.find` for one control, `semantic.filter` for
+relevant page regions, and
+`semantic.verify` for one outcome. Use Jev when the page or happy path is
+unfamiliar; once the path is stable, prefer deterministic Surf commands for
+repeated runs. The agent owns the goal and final confirmation, while Surf retains
+execution authority. Only `semantic.*` sends bounded, value-free page text to
+TypeSafe.
+
+```bash
+surf semantic.find "the settings control"
+surf semantic.verify "Settings were saved" --json
+surf semantic.filter "settings"
+surf semantic.act "Open settings" --max-steps 5
+surf semantic.act "Fill email" --input email="$EMAIL" --allow-write --allow-ref e3
+surf semantic.act 'Add the selected item to the cart' --allow-write --threshold write=0.85
+printf '%s\n' "$TYPESAFE_KEY" | surf semantic auth set
+surf semantic auth status
+surf semantic auth clear
+```
+
+For reusable bounded recipes, put only linear `semantic.step` operations in a
+workflow with `"semantic":{"version":1}`. Check it offline with
+`surf workflow.validate flow.json` or `surf do --file flow.json --dry-run`, then
+run with `--allow-semantic`; declared fill/check/click operations also require
+`--allow-write`. Supply private fill slots as a bounded JSON object on stdin:
+
+```bash
+printf '%s' '{"quantity":"2"}' | SURF_SESSION=shopping surf do --file flow.json \
+  --inputs-stdin --allow-semantic --allow-write --json
+```
+
+The closed operations are `find`, same-origin direct `open`, `ensureChecked`,
+`fill`, one-shot `click` with an explicit expectation, and `assert`. Search is
+bounded overlapping coverage, not global ranking. Unknown write outcomes stop
+without replay; a later new run can still repeat an external effect. Input
+values never enter provider state, workflow variables, events, or checkpoints.
+
+Required argument shapes:
+
+```text
+find           target (+ optional search), usually save with "as"
+open           target
+ensureChecked  target + checked
+fill           target + input
+click          target + expect
+assert         mode + claim (semantic) or predicate (local)
+```
+
+The complete valid six-operation example in the README uses these shapes; start
+from it instead of inventing fields.
+
+Every click/fill requires `--allow-write`; repeat `--allow-ref` to narrow it.
+Broad writes use threshold `0.95`; exactly one allowed ref with one applicable
+write uses `0.65`. The applied threshold is included in decision/trace output.
+Repeatable `--threshold name=value` overrides applicable confidence thresholds
+for one run only; defaults remain safer, and overrides never grant write authority.
+`TYPESAFE_API_KEY` is the ephemeral/CI override.
+The shared credential schema is `{"version":1,"apiKey":"..."}` at
+`${XDG_CONFIG_HOME:-~/.config}/typesafe/credentials.json` (Unix/macOS) or
+`%APPDATA%\TypeSafe\credentials.json` (Windows), independent of Surf state and
+the project. POSIX directories/files use `0700`/`0600`; Windows relies on the
+current user's profile ACL. `TYPESAFE_API_KEY` wins. Status reveals only source
+and fingerprint; clear affects all clients using the shared file.
+
 ## AI Assistants (No API Keys)
 
 Query AI models using your browser's logged-in session. Must be logged into the respective service in Chrome.