@caiqy/browser-skill-dsh-plugin 0.3.3-dsh.2 → 0.3.3-dsh.3

package/skill/references/debugging.md

@@ -1,119 +1,119 @@
-# Website debugging
-
-Use `bsk_inspect` with `action: "debug"` to record and investigate a website
-problem. Keep ordinary browsing capture-free. All examples use the owning
-`session`; use returned IDs and the owned `tabId` when targeting a specific tab.
-Read loaded schemas for parameters; `debugAction: "capabilities"` reports supported
-actions, limits, filters and build information.
-
-## Capture, reproduce, inspect, save
-
-1. Record the problem and expected result. Start a session or borrow the user's tab
-   following [tabs and profiles](tabs-and-profiles.md). Start capture **before**
-   navigating or reproducing; earlier traffic cannot be recovered.
-
-   ```text
-   bsk_inspect({ action: "debug", debugAction: "start", session: "<id>", name: "Nickname does not persist" })
-   bsk_page({ action: "navigate", session: "<id>", url: "https://example.com/profile" })
-   bsk_inspect({ action: "observe", session: "<id>" })
-   ```
-
-2. Retain the returned run ID; pass it as `runId` for subsequent reads. Reproduce
-   with ordinary interaction tools, or let the user act (manual capture covers the
-   main frame). Observe the outcome; allow expected delayed work to finish.
-3. Read `operations`, then `operation` with its `id` to inspect associated requests,
-   console messages, field values and later page changes. Use `requests`, then
-   `request` with its `id` and `part: "request"` or `"response"` for body text;
-   metadata is the default. `console` and `pages` expose other retained context.
-4. Use `stop` to save the final record, then export before stopping the session:
-
-   ```text
-   bsk_inspect({ action: "debug", debugAction: "stop", session: "<id>" })
-   bsk_inspect({ action: "debug", debugAction: "export", session: "<id>", runId: "<run-id>", output: "<new-file.json>" })
-   bsk_session({ action: "stop", session: "<id>" })
-   ```
-
-`export` writes a new file without overwriting and returns its path/size. Exporting
-while capturing gives a point-in-time record. Browser-local history survives task
-completion within retention limits; inspect/export it through the extension after
-session teardown. A new session cannot read another task's history. Give exported
-JSON to an agent for analysis/comparison; there is no repair or comparison action.
-`pin`/`unpin` with a completed request `id` protect it from capacity eviction,
-not record expiry.
-
-## Decide whether the evidence supports a conclusion
-
-Operation links are time associations, not proof of causation. Distinguish original,
-submitted, response and later page values only where recorded; do not invent missing
-steps. HTTP 200 is not business success. Console source labels distinguish website,
-extension, browser and unknown errors.
-`payload_partial` means a field scan was incomplete; inspect the body directly
-rather than assuming a unique field match.
-
-Check `run.coverage`, `run.storage`, body states/reasons and `output.omitted`.
-Late start, unsupported capture, pending work, truncation, eviction and storage
-failure can leave gaps: missing evidence does not mean an event did not happen.
-State the supported finding and the specific gap preventing a stronger conclusion.
-Evidence may be redacted; never treat displayable text as an exact original request.
-
-## Read within a budget; wait without repeating commands
-
-Default output budget is 64 KiB; `budget` accepts 4096..262144 bytes, export exempt.
-For `requests`, filter with `url`, `method`, `resourceType`, `status`, `state` or
-`kind`; `kind: "business"` reduces resource noise. Use a comma-separated `fields`
-string from capabilities for optional projections. `limit` is 1..100. Requests/operations return `next_since`:
-pass it as `since` and merge updates by ID. Body slices return the body's
-`next_offset`; console/pages, performance and analysis return top-level `next_offset`. Pass it
-as `offset`. Body reads also accept `maxChars` and a JSON `pointer` for complete bodies.
-Pagination does not imply completeness: inspect omissions and availability flags.
-
-When busy, read `activity`; use `wait` with `commandId` from activity or
-`session_busy`, and optional `waitMs` up to 60000. Omitting `commandId` waits for
-idle. Waiting neither resends nor cancels a command; completion is not success.
-Inspect the result/page before retrying an operation with uncertain effects.
-
-## Performance and request summaries
-
-`performance` reports main-frame navigation/paint, CLS and long tasks, not INP or
-CPU profiles. Read each metric's state/reason and visibility history; hidden-page
-or late-start metrics may be invalid.
-`aggregate` groups method/path with latency percentiles, errors and slow counts
-(`slowMs`). `duplicates` reports suspected equal URL/body/document bursts
-(`windowMs`); valid retries or polling can look repetitive. Both default to business
-traffic and exclude rule/replay experiments; `includeControlled: true` includes them.
-Follow linked request IDs and coverage gaps. Stop capture for stable summary
-pagination, using `offset`/`next_offset`, not `since`.
-
-## Explicit network experiments
-
-Capture alone does not alter traffic. Use rules/replay only within the user's
-requested experiment: they can block or change live requests and server data.
-They require active capture in the original owning task; history never reactivates controls.
-
-`rule_add` takes a **JSON-string** `rule` containing `match`, `effect` and optional
-`times`. Match an absolute URL; `*` matches path/query. Effects are `block`,
-`modify` (same-origin URL, method, headers, text body or top-level JSON edits) and
-`mock` (status, text body, optional headers/delay). Default: one Fetch/XHR match;
-first matching rule wins. `times: 0` lasts until disabled/capture ends. Read `rules`
-for IDs, hits and failures; `rule_enable`, `rule_disable`, `rule_remove` take `id`.
-Capture end clears execution. Check recorded `intervention`; a mock is not a server
-response. Active rules also apply to matching replays.
-
-`replay` takes the source request `id` and a **JSON-string** `replay`, for example
-`"{\"key\":\"attempt-1\"}"`; add explicit `url`/`body` replacements when needed.
-It sends a new request using current cookies. Source, destination and current page
-must share an HTTP(S) origin; redirects, cross-origin and binary/multipart replay
-are unsupported. Reuse the **same key** after an uncertain result to avoid sending
-again; a new key deliberately creates a new attempt. Inspect the linked request
-for outcome; replay does not invoke the original page handler or guarantee UI updates.
-
-Reusing retained values requires `integrity.url: "complete"`, complete request metadata
-and `request_body.replay_safe: true`. Body `available` only means displayable.
-`integrity.metadata` covers the request; `integrity.response_headers` is independent
-and does not restrict replay.
-Changed, truncated or unverified URL/body require explicit complete replacements;
-old records without these markers do too. Never copy a truncated evidence draft as
-its replacement. Replacing URL/body cannot fix incomplete metadata. Replace known
-redacted headers with authorized values or remove them with `null`; never send
-redacted placeholders or guess secrets. Preserve exact numeric tokens when supplying
-text bodies; JSON edits must not round large numeric IDs.
+# Website debugging
+
+Use `bsk_inspect` with `action: "debug"` to record and investigate a website
+problem. Keep ordinary browsing capture-free. All examples use the owning
+`session`; use returned IDs and the owned `tabId` when targeting a specific tab.
+Read loaded schemas for parameters; `debugAction: "capabilities"` reports supported
+actions, limits, filters and build information.
+
+## Capture, reproduce, inspect, save
+
+1. Record the problem and expected result. Start a session or borrow the user's tab
+   following [tabs and profiles](tabs-and-profiles.md). Start capture **before**
+   navigating or reproducing; earlier traffic cannot be recovered.
+
+   ```text
+   bsk_inspect({ action: "debug", debugAction: "start", session: "<id>", name: "Nickname does not persist" })
+   bsk_page({ action: "navigate", session: "<id>", url: "https://example.com/profile" })
+   bsk_inspect({ action: "observe", session: "<id>" })
+   ```
+
+2. Retain the returned run ID; pass it as `runId` for subsequent reads. Reproduce
+   with ordinary interaction tools, or let the user act (manual capture covers the
+   main frame). Observe the outcome; allow expected delayed work to finish.
+3. Read `operations`, then `operation` with its `id` to inspect associated requests,
+   console messages, field values and later page changes. Use `requests`, then
+   `request` with its `id` and `part: "request"` or `"response"` for body text;
+   metadata is the default. `console` and `pages` expose other retained context.
+4. Use `stop` to save the final record, then export before stopping the session:
+
+   ```text
+   bsk_inspect({ action: "debug", debugAction: "stop", session: "<id>" })
+   bsk_inspect({ action: "debug", debugAction: "export", session: "<id>", runId: "<run-id>", output: "<new-file.json>" })
+   bsk_session({ action: "stop", session: "<id>" })
+   ```
+
+`export` writes a new file without overwriting and returns its path/size. Exporting
+while capturing gives a point-in-time record. Browser-local history survives task
+completion within retention limits; inspect/export it through the extension after
+session teardown. A new session cannot read another task's history. Give exported
+JSON to an agent for analysis/comparison; there is no repair or comparison action.
+`pin`/`unpin` with a completed request `id` protect it from capacity eviction,
+not record expiry.
+
+## Decide whether the evidence supports a conclusion
+
+Operation links are time associations, not proof of causation. Distinguish original,
+submitted, response and later page values only where recorded; do not invent missing
+steps. HTTP 200 is not business success. Console source labels distinguish website,
+extension, browser and unknown errors.
+`payload_partial` means a field scan was incomplete; inspect the body directly
+rather than assuming a unique field match.
+
+Check `run.coverage`, `run.storage`, body states/reasons and `output.omitted`.
+Late start, unsupported capture, pending work, truncation, eviction and storage
+failure can leave gaps: missing evidence does not mean an event did not happen.
+State the supported finding and the specific gap preventing a stronger conclusion.
+Evidence may be redacted; never treat displayable text as an exact original request.
+
+## Read within a budget; wait without repeating commands
+
+Default output budget is 64 KiB; `budget` accepts 4096..262144 bytes, export exempt.
+For `requests`, filter with `url`, `method`, `resourceType`, `status`, `state` or
+`kind`; `kind: "business"` reduces resource noise. Use a comma-separated `fields`
+string from capabilities for optional projections. `limit` is 1..100. Requests/operations return `next_since`:
+pass it as `since` and merge updates by ID. Body slices return the body's
+`next_offset`; console/pages, performance and analysis return top-level `next_offset`. Pass it
+as `offset`. Body reads also accept `maxChars` and a JSON `pointer` for complete bodies.
+Pagination does not imply completeness: inspect omissions and availability flags.
+
+When busy, read `activity`; use `wait` with `commandId` from activity or
+`session_busy`, and optional `waitMs` up to 60000. Omitting `commandId` waits for
+idle. Waiting neither resends nor cancels a command; completion is not success.
+Inspect the result/page before retrying an operation with uncertain effects.
+
+## Performance and request summaries
+
+`performance` reports main-frame navigation/paint, CLS and long tasks, not INP or
+CPU profiles. Read each metric's state/reason and visibility history; hidden-page
+or late-start metrics may be invalid.
+`aggregate` groups method/path with latency percentiles, errors and slow counts
+(`slowMs`). `duplicates` reports suspected equal URL/body/document bursts
+(`windowMs`); valid retries or polling can look repetitive. Both default to business
+traffic and exclude rule/replay experiments; `includeControlled: true` includes them.
+Follow linked request IDs and coverage gaps. Stop capture for stable summary
+pagination, using `offset`/`next_offset`, not `since`.
+
+## Explicit network experiments
+
+Capture alone does not alter traffic. Use rules/replay only within the user's
+requested experiment: they can block or change live requests and server data.
+They require active capture in the original owning task; history never reactivates controls.
+
+`rule_add` takes a **JSON-string** `rule` containing `match`, `effect` and optional
+`times`. Match an absolute URL; `*` matches path/query. Effects are `block`,
+`modify` (same-origin URL, method, headers, text body or top-level JSON edits) and
+`mock` (status, text body, optional headers/delay). Default: one Fetch/XHR match;
+first matching rule wins. `times: 0` lasts until disabled/capture ends. Read `rules`
+for IDs, hits and failures; `rule_enable`, `rule_disable`, `rule_remove` take `id`.
+Capture end clears execution. Check recorded `intervention`; a mock is not a server
+response. Active rules also apply to matching replays.
+
+`replay` takes the source request `id` and a **JSON-string** `replay`, for example
+`"{\"key\":\"attempt-1\"}"`; add explicit `url`/`body` replacements when needed.
+It sends a new request using current cookies. Source, destination and current page
+must share an HTTP(S) origin; redirects, cross-origin and binary/multipart replay
+are unsupported. Reuse the **same key** after an uncertain result to avoid sending
+again; a new key deliberately creates a new attempt. Inspect the linked request
+for outcome; replay does not invoke the original page handler or guarantee UI updates.
+
+Reusing retained values requires `integrity.url: "complete"`, complete request metadata
+and `request_body.replay_safe: true`. Body `available` only means displayable.
+`integrity.metadata` covers the request; `integrity.response_headers` is independent
+and does not restrict replay.
+Changed, truncated or unverified URL/body require explicit complete replacements;
+old records without these markers do too. Never copy a truncated evidence draft as
+its replacement. Replacing URL/body cannot fix incomplete metadata. Replace known
+redacted headers with authorized values or remove them with `null`; never send
+redacted placeholders or guess secrets. Preserve exact numeric tokens when supplying
+text bodies; JSON edits must not round large numeric IDs.

package/skill/references/help-and-recovery.md

@@ -1,47 +1,47 @@
-# Human help and recovery
-
-With help enabled, use `bsk_assist` action `request-help` for login, CAPTCHA,
-OTP, payment confirmation, consent, or after two attempts without progress. Supply
-a precise prompt and fresh targets; completion criteria need a stable success signal.
-`all` and `any` support at most eight conditions in total. `urlMatches` accepts
-RE2-compatible regular expressions of at most 128 characters. A compiled pattern
-may contain at most 4096 instructions, and all URL-regex conditions together at most
-8192, counting repeated patterns each time. Invalid or over-budget patterns return
-`invalid_params` before help starts.
-URL conditions do not auto-complete on URLs longer than 8192 characters; the user
-can still finish manually. The protocol treats empty, null, and omitted
-`url_matches` values as no URL-regex condition.
-
-RE2 rejects JavaScript patterns such as `\u0061`, `a{1001}`, `[^]`, lookahead,
-lookbehind, and backreferences. Some accepted patterns differ in meaning: `\a`
-is a control character in RE2 rather than `a`, and RE2's `\s` does not include
-Unicode whitespace. Rewrite patterns in RE2 syntax; use `urlContains` when a
-substring is enough.
-Resume only on `continued` / `completed`, then observe. Cancellation/timeout blocks
-the step; do not repeat the request. Navigation alone is not success.
-
-With help disabled, neither request help nor re-enable it. `disabled` grants no human
-action or permission. Re-observe; use existing logins, authorized inputs and alternatives
-within task/host rules. Vision models may try authorized graphical verification.
-Phone-only QR scans, face verification, missing SMS codes and image-only tasks for
-text-only models may stay blocked. Report missing inputs/capabilities or exhausted
-alternatives; continue independent work. Never repeat unknown effects or switch
-backends to bypass limits. Borrow confirmation still applies.
-
-## Recover
-
-- Unknown browser tool after plugin reload: invoke `skill` with `name: "browser-skill"`
-  again (users can enter `/browser-skill`), then retry the intended browser tool once
-  after its schema appears. If it remains unavailable, report the failure.
-- Stale ref: observe, then retry the intended action once.
-- Unknown tab/session: list owned resources or start a session with the required
-  browser selector, if any; never guess IDs.
-- Failed/interrupted stop: accepted cleanup continues in the background. Retry the
-  same stop; completed cleanup returns `alreadyClosed: true`. For multiple pending
-  stops, specify `session` or the owned `requestId` from the result/list/error,
-  never both. The request ID identifies the original operation even if its short
-  session ID is reused. Never switch sessions to retry cleanup.
-- Timeout/unknown effect: inspect before retrying; the action may have happened.
-- Unconfirmed fill: read the field. Formatting may satisfy the goal; correct only a
-  remaining difference instead of blindly refilling or requesting help.
-- Other errors: follow the hint; on unrecoverable failure, report and stop the owned session.
+# Human help and recovery
+
+With help enabled, use `bsk_assist` action `request-help` for login, CAPTCHA,
+OTP, payment confirmation, consent, or after two attempts without progress. Supply
+a precise prompt and fresh targets; completion criteria need a stable success signal.
+`all` and `any` support at most eight conditions in total. `urlMatches` accepts
+RE2-compatible regular expressions of at most 128 characters. A compiled pattern
+may contain at most 4096 instructions, and all URL-regex conditions together at most
+8192, counting repeated patterns each time. Invalid or over-budget patterns return
+`invalid_params` before help starts.
+URL conditions do not auto-complete on URLs longer than 8192 characters; the user
+can still finish manually. The protocol treats empty, null, and omitted
+`url_matches` values as no URL-regex condition.
+
+RE2 rejects JavaScript patterns such as `\u0061`, `a{1001}`, `[^]`, lookahead,
+lookbehind, and backreferences. Some accepted patterns differ in meaning: `\a`
+is a control character in RE2 rather than `a`, and RE2's `\s` does not include
+Unicode whitespace. Rewrite patterns in RE2 syntax; use `urlContains` when a
+substring is enough.
+Resume only on `continued` / `completed`, then observe. Cancellation/timeout blocks
+the step; do not repeat the request. Navigation alone is not success.
+
+With help disabled, neither request help nor re-enable it. `disabled` grants no human
+action or permission. Re-observe; use existing logins, authorized inputs and alternatives
+within task/host rules. Vision models may try authorized graphical verification.
+Phone-only QR scans, face verification, missing SMS codes and image-only tasks for
+text-only models may stay blocked. Report missing inputs/capabilities or exhausted
+alternatives; continue independent work. Never repeat unknown effects or switch
+backends to bypass limits. Borrow confirmation still applies.
+
+## Recover
+
+- Unknown browser tool after plugin reload: invoke `skill` with `name: "browser-skill"`
+  again (users can enter `/browser-skill`), then retry the intended browser tool once
+  after its schema appears. If it remains unavailable, report the failure.
+- Stale ref: observe, then retry the intended action once.
+- Unknown tab/session: list owned resources or start a session with the required
+  browser selector, if any; never guess IDs.
+- Failed/interrupted stop: accepted cleanup continues in the background. Retry the
+  same stop; completed cleanup returns `alreadyClosed: true`. For multiple pending
+  stops, specify `session` or the owned `requestId` from the result/list/error,
+  never both. The request ID identifies the original operation even if its short
+  session ID is reused. Never switch sessions to retry cleanup.
+- Timeout/unknown effect: inspect before retrying; the action may have happened.
+- Unconfirmed fill: read the field. Formatting may satisfy the goal; correct only a
+  remaining difference instead of blindly refilling or requesting help.
+- Other errors: follow the hint; on unrecoverable failure, report and stop the owned session.

package/skill/references/interaction-details.md

@@ -1,139 +1,139 @@
-# Interaction details
-
-## Element waits
-
-`bsk_page` supports `action: "wait-for-element"` for an explicit element
-condition. For example, if
-`@e2` is an observed loading indicator after the triggering action, use
-`bsk_page({ action: "wait-for-element", target: "@e2", state: "hidden" })`,
-then check `satisfied` and observe the result. Replace the example ref with the
-actual one. Skip waiting when the page is already ready.
-
-Prefer a fresh ref for an existing node, including frame/shadow-root targets; do
-not fetch HTML just to replace a usable ref with a selector. A known
-CSS selector can find a node that will appear or be replaced; it checks only the
-first match in the main document, so scope it to the intended component. Do not
-invent selectors: inspect bounded HTML if the current observation lacks one.
-Only CSS selectors are supported, not `text=...`, XPath, or Playwright locators.
-
-States are `visible` (default), `hidden` (absent or not visible), `attached`, and
-`detached` (absent). Visibility does not guarantee enabled state or actionability.
-An already absent loading mask satisfies `hidden` immediately, possibly before
-loading starts; prefer a result marker when that race is possible. Invalid refs
-remain errors, even for `hidden`/`detached`. Navigation invalidates refs.
-
-The default timeout is 10000 ms (range 1..300000); `pollMs` is optional, defaults
-to 100, and accepts 16..2000. The wait stops as soon as the condition matches.
-Always check `satisfied`: false means timeout, not success. `attached`/`visible`
-describe the last completed probe and are unknown if no probe completed.
-Waiting does not refresh refs: observe before choosing a new action. For a
-timeout, stale ref, or an older installation without this command, observe the
-current page and continue with supported single actions when possible. Do not
-repeat the triggering action without checking its effects or keep retrying an
-unsupported wait. If blocked, follow [help and recovery](help-and-recovery.md).
-
-## Page-script evaluation
-
-Use `bsk_interact` with `action: "evaluate"` and a nonempty JavaScript `expression`
-for authorized page work. Use an IIFE for statements. `awaitPromise` and
-`returnByValue` default to true; explicit false is preserved. `timeoutMs` controls
-execution. All page actions here accept an owned `session` and optional `tabId`.
-
-```text
-bsk_interact({ action: "evaluate", session: "<id>", expression: "document.title" })
-bsk_interact({ action: "evaluate", session: "<id>", tabId: 123, expression: "Promise.resolve({ ready: true })", awaitPromise: true, returnByValue: true, timeoutMs: 10000 })
-bsk_interact({ action: "evaluate", session: "<id>", expression: "window", awaitPromise: false, returnByValue: false })
-```
-
-Replace example IDs with actual results. Scripts may mutate the page or send
-requests; use the same authorization and ownership limits as other interactions.
-Never extract secrets. Page exceptions (`ok:false`) are failures even if the
-underlying process exits successfully; retain their details. Timeout/cancellation
-is not success and may leave effects: inspect before retrying. Observe after changes.
-
-## Upload and download
-
-`upload` requires an observed `target` and nonempty `files` array of readable local
-paths. `mode` defaults to `input` for a file input/chooser; `drop` targets a drop zone.
-Multiple paths use the existing transfer pipeline, including staging and cleanup.
-
-```text
-bsk_interact({ action: "upload", session: "<id>", target: "@e3", files: ["C:/task/sample.txt"] })
-bsk_interact({ action: "upload", session: "<id>", target: "@e4", files: ["C:/task/a.txt", "C:/task/b.txt"], mode: "drop", timeoutMs: 120000 })
-bsk_interact({ action: "download", session: "<id>", target: "@e5", output: "C:/task/report.csv", overwrite: false, timeoutMs: 120000 })
-```
-
-`download` clicks the target and requires `output`. Existing destinations are
-refused by default; use `overwrite:true` only when replacement is authorized.
-Downloads use temporary files, atomic commit and transfer release. Paths refer to
-the computer running the plugin/CLI, not a remote browser; remote browser file
-transfer is unsupported. Empty lists, unreadable files, invalid modes, failed
-transfers and cancellation must be reported as failures. Inspect uncertain browser
-effects before repeating a click/upload. Verify the actual upload/download result.
-
-## Fixed delays
-
-`wait` waits for navigation lifecycle events; `wait-for-element` checks a DOM
-condition. Use `wait-ms` only when a fixed delay is needed, then observe the result:
-
-```text
-bsk_page({ action: "wait-ms", durationMs: 250 })
-```
-
-`durationMs` must be an integer in 0..300000. This is a cancellable daemon-level
-delay and needs no session or tab. Completion means elapsed time, not page readiness;
-cancellation must not be reported as completion. Prefer an element condition when available.
-
-## Interactions
-
-- Hover markers like `[hover first: Shoes | Bags]` list labels, not refs. Hover the
-  trigger, observe, then use the item's ref. Click the trigger only if its action is wanted.
-- `scroll-to` returns ancestor-clipped bounds in top-level viewport CSS pixels.
-  Partial visibility suffices; hidden/fully clipped targets fail. It does not test occlusion.
-- `wheel` uses signed `deltaX`/`deltaY`, at least one nonzero. Optional `target` is
-  scrolled into view first; otherwise it uses the viewport centre. It reports input,
-  not scrolling success: observe afterwards. Focus/blur change focus states.
-
-## Observation continuation
-
-No default token cap. With `maxTokens`, pass `nextCursor` as observe's `cursor` to
-continue. Each page replaces refs; use them before continuing, never reuse old ones.
-Continuation uses the same capture without refresh/depth changes. New
-observe/snapshot or changed page identity invalidates it.
-
-`probeHover` and `debugSurfaces` default to false. If static observation misses
-hover content, explicitly request a probe:
-
-```text
-bsk_inspect({ action: "observe", session: "<id>", probeHover: true, debugSurfaces: true, maxTokens: 3000 })
-```
-
-Active probing moves the real cursor and can trigger page events; it uses the
-session queue and must not run concurrently with page operations. Read returned
-`hoverProbe`, `debug` and `dialogs` when present; missing fields are not evidence
-of a successful probe. `debugSurfaces` requests diagnostics without enabling active
-hover by itself. Do not combine `cursor` with `maxDepth` or enabled probe flags;
-continue the captured observation or start a new one. Console/network remain bounded
-read-only diagnostics; follow sequence cursors.
-
-## Window and device emulation
-
-`bsk_assist` with `action:"resize"` changes the window; `emulate` applies per-tab
-overrides, not inherited by new tabs. Device presets supply viewport, DPR, UA and
-touch defaults; explicit values override the preset, including false.
-
-```text
-bsk_assist({ action: "emulate", session: "<id>", device: "iphone-14", width: 420, dpr: 2, mobile: false, touch: false })
-bsk_assist({ action: "emulate", session: "<id>", tabId: 123, width: 800, height: 600, dpr: 1.5, mobile: false, ua: "Mozilla/5.0 task-test", acceptLanguage: "zh-CN,en;q=0.8", touch: true, maxTouchPoints: 5 })
-bsk_assist({ action: "emulate", session: "<id>", off: true })
-```
-
-Dimensions are integers 1..7680; without a preset give width and height together.
-`dpr` must be positive and finite; `dpr`/`mobile` require dimensions or a preset.
-UA and touch can be set alone; `acceptLanguage` requires `ua` or a device preset.
-`maxTouchPoints` is a positive integer (official unsigned 32-bit range) and implies
-touch unless explicit `touch:false` overrides it. `mobile:false` and `touch:false`
-explicitly disable those features; `touch:false` takes priority over both preset
-touch defaults and `maxTouchPoints`. `off:true` clears emulation and must be used
-without any preset or override, including false values. Invalid values/combinations
-fail before execution. Inspect the page after applying or clearing emulation.
+# Interaction details
+
+## Element waits
+
+`bsk_page` supports `action: "wait-for-element"` for an explicit element
+condition. For example, if
+`@e2` is an observed loading indicator after the triggering action, use
+`bsk_page({ action: "wait-for-element", target: "@e2", state: "hidden" })`,
+then check `satisfied` and observe the result. Replace the example ref with the
+actual one. Skip waiting when the page is already ready.
+
+Prefer a fresh ref for an existing node, including frame/shadow-root targets; do
+not fetch HTML just to replace a usable ref with a selector. A known
+CSS selector can find a node that will appear or be replaced; it checks only the
+first match in the main document, so scope it to the intended component. Do not
+invent selectors: inspect bounded HTML if the current observation lacks one.
+Only CSS selectors are supported, not `text=...`, XPath, or Playwright locators.
+
+States are `visible` (default), `hidden` (absent or not visible), `attached`, and
+`detached` (absent). Visibility does not guarantee enabled state or actionability.
+An already absent loading mask satisfies `hidden` immediately, possibly before
+loading starts; prefer a result marker when that race is possible. Invalid refs
+remain errors, even for `hidden`/`detached`. Navigation invalidates refs.
+
+The default timeout is 10000 ms (range 1..300000); `pollMs` is optional, defaults
+to 100, and accepts 16..2000. The wait stops as soon as the condition matches.
+Always check `satisfied`: false means timeout, not success. `attached`/`visible`
+describe the last completed probe and are unknown if no probe completed.
+Waiting does not refresh refs: observe before choosing a new action. For a
+timeout, stale ref, or an older installation without this command, observe the
+current page and continue with supported single actions when possible. Do not
+repeat the triggering action without checking its effects or keep retrying an
+unsupported wait. If blocked, follow [help and recovery](help-and-recovery.md).
+
+## Page-script evaluation
+
+Use `bsk_interact` with `action: "evaluate"` and a nonempty JavaScript `expression`
+for authorized page work. Use an IIFE for statements. `awaitPromise` and
+`returnByValue` default to true; explicit false is preserved. `timeoutMs` controls
+execution. All page actions here accept an owned `session` and optional `tabId`.
+
+```text
+bsk_interact({ action: "evaluate", session: "<id>", expression: "document.title" })
+bsk_interact({ action: "evaluate", session: "<id>", tabId: 123, expression: "Promise.resolve({ ready: true })", awaitPromise: true, returnByValue: true, timeoutMs: 10000 })
+bsk_interact({ action: "evaluate", session: "<id>", expression: "window", awaitPromise: false, returnByValue: false })
+```
+
+Replace example IDs with actual results. Scripts may mutate the page or send
+requests; use the same authorization and ownership limits as other interactions.
+Never extract secrets. Page exceptions (`ok:false`) are failures even if the
+underlying process exits successfully; retain their details. Timeout/cancellation
+is not success and may leave effects: inspect before retrying. Observe after changes.
+
+## Upload and download
+
+`upload` requires an observed `target` and nonempty `files` array of readable local
+paths. `mode` defaults to `input` for a file input/chooser; `drop` targets a drop zone.
+Multiple paths use the existing transfer pipeline, including staging and cleanup.
+
+```text
+bsk_interact({ action: "upload", session: "<id>", target: "@e3", files: ["C:/task/sample.txt"] })
+bsk_interact({ action: "upload", session: "<id>", target: "@e4", files: ["C:/task/a.txt", "C:/task/b.txt"], mode: "drop", timeoutMs: 120000 })
+bsk_interact({ action: "download", session: "<id>", target: "@e5", output: "C:/task/report.csv", overwrite: false, timeoutMs: 120000 })
+```
+
+`download` clicks the target and requires `output`. Existing destinations are
+refused by default; use `overwrite:true` only when replacement is authorized.
+Downloads use temporary files, atomic commit and transfer release. Paths refer to
+the computer running the plugin/CLI, not a remote browser; remote browser file
+transfer is unsupported. Empty lists, unreadable files, invalid modes, failed
+transfers and cancellation must be reported as failures. Inspect uncertain browser
+effects before repeating a click/upload. Verify the actual upload/download result.
+
+## Fixed delays
+
+`wait` waits for navigation lifecycle events; `wait-for-element` checks a DOM
+condition. Use `wait-ms` only when a fixed delay is needed, then observe the result:
+
+```text
+bsk_page({ action: "wait-ms", durationMs: 250 })
+```
+
+`durationMs` must be an integer in 0..300000. This is a cancellable daemon-level
+delay and needs no session or tab. Completion means elapsed time, not page readiness;
+cancellation must not be reported as completion. Prefer an element condition when available.
+
+## Interactions
+
+- Hover markers like `[hover first: Shoes | Bags]` list labels, not refs. Hover the
+  trigger, observe, then use the item's ref. Click the trigger only if its action is wanted.
+- `scroll-to` returns ancestor-clipped bounds in top-level viewport CSS pixels.
+  Partial visibility suffices; hidden/fully clipped targets fail. It does not test occlusion.
+- `wheel` uses signed `deltaX`/`deltaY`, at least one nonzero. Optional `target` is
+  scrolled into view first; otherwise it uses the viewport centre. It reports input,
+  not scrolling success: observe afterwards. Focus/blur change focus states.
+
+## Observation continuation
+
+No default token cap. With `maxTokens`, pass `nextCursor` as observe's `cursor` to
+continue. Each page replaces refs; use them before continuing, never reuse old ones.
+Continuation uses the same capture without refresh/depth changes. New
+observe/snapshot or changed page identity invalidates it.
+
+`probeHover` and `debugSurfaces` default to false. If static observation misses
+hover content, explicitly request a probe:
+
+```text
+bsk_inspect({ action: "observe", session: "<id>", probeHover: true, debugSurfaces: true, maxTokens: 3000 })
+```
+
+Active probing moves the real cursor and can trigger page events; it uses the
+session queue and must not run concurrently with page operations. Read returned
+`hoverProbe`, `debug` and `dialogs` when present; missing fields are not evidence
+of a successful probe. `debugSurfaces` requests diagnostics without enabling active
+hover by itself. Do not combine `cursor` with `maxDepth` or enabled probe flags;
+continue the captured observation or start a new one. Console/network remain bounded
+read-only diagnostics; follow sequence cursors.
+
+## Window and device emulation
+
+`bsk_assist` with `action:"resize"` changes the window; `emulate` applies per-tab
+overrides, not inherited by new tabs. Device presets supply viewport, DPR, UA and
+touch defaults; explicit values override the preset, including false.
+
+```text
+bsk_assist({ action: "emulate", session: "<id>", device: "iphone-14", width: 420, dpr: 2, mobile: false, touch: false })
+bsk_assist({ action: "emulate", session: "<id>", tabId: 123, width: 800, height: 600, dpr: 1.5, mobile: false, ua: "Mozilla/5.0 task-test", acceptLanguage: "zh-CN,en;q=0.8", touch: true, maxTouchPoints: 5 })
+bsk_assist({ action: "emulate", session: "<id>", off: true })
+```
+
+Dimensions are integers 1..7680; without a preset give width and height together.
+`dpr` must be positive and finite; `dpr`/`mobile` require dimensions or a preset.
+UA and touch can be set alone; `acceptLanguage` requires `ua` or a device preset.
+`maxTouchPoints` is a positive integer (official unsigned 32-bit range) and implies
+touch unless explicit `touch:false` overrides it. `mobile:false` and `touch:false`
+explicitly disable those features; `touch:false` takes priority over both preset
+touch defaults and `maxTouchPoints`. `off:true` clears emulation and must be used
+without any preset or override, including false values. Invalid values/combinations
+fail before execution. Inspect the page after applying or clearing emulation.