@omniaibot/win-x64 1.6.6 → 1.6.8

package/bin/omnibot-windows-x64/VERSION

@@ -1 +1 @@
-1.6.6
+1.6.8 

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/SKILL.md

@@ -29,17 +29,66 @@ This skill is an execution specification for agents. It is not a human command m
 - Pattern > Command.
 - Observe -> Act -> Verify.
 - Fallback is allowed, but never first.
-- Do not use `execute-js` first.
+- Native Omnibot commands before scripts. Do not use `execute-js` first.
 - Run `omnibot <command> --help` before using uncommon or newly introduced commands, especially `batch`, `network`, `cdp`, `record`, `trace`, and `skills`.
 - If a command from memory fails with parser errors, stop using that remembered syntax and re-check `omnibot --help` plus the subcommand help.
 - Prefer semantic locators and `snapshot -i` refs before selectors.
+- When the user has explicitly requested a native Omnibot command and the terminal tool is available, execute it immediately; do not ask for confirmation or claim that it was not run. If dispatch genuinely fails, report the concrete tool error after one bounded retry and do not fabricate browser results.
+- A multi-step browser task is incomplete until its requested final verification command has actually run. After the last mutation, always issue the concrete `get`/`is`/`wait` verification, inspect its result, and only then report completion; never stop after reporting that the mutation itself succeeded.
+- For workflows with more than five meaningful browser actions, split the work into multiple bounded turns. Each turn should finish its own observe -> act -> verify cycle and report the retained tab id before the next turn; do not put a long mutation chain and all final checks into one model request.
 - Raw `cdp` calls are one-shot. Do not assume `Network.enable` alone creates readable logs. For API/request evidence, use `network clear -> network start -> one action -> network stop -> network logs/summary`.
 - After a failed click by ref, re-observe or use a higher-evidence fallback. Do not keep using stale `@eN` refs from a previous snapshot.
 - For shopping, checkout, payment, banking, or irreversible workflows: Do not click final submit/pay/place-order controls unless the user explicitly confirms that final action in the current turn.
 - Prefer condition-based `wait` over shell sleep.
+- Timeout values for commands that expose a timeout option, such as `wait`, are seconds, not milliseconds. Use `--timeout 5` for a five-second wait; never convert milliseconds into a raw CLI timeout value. `dialog logs` and `dialog clear` do not accept `--timeout`.
+- Native dialog workflows are session-token scoped: use the exact same `OMNIBOT_SESSION_TOKEN` for the triggering click, `dialog logs`, and `dialog handle`. A different token cannot observe or handle the original dialog.
 - Parse JSON output from commands that return JSON.
 - Do not claim success without verification evidence.
 
+### Runtime Provenance
+
+Before an agent-driven test in a source checkout, verify the command provenance:
+
+```bash
+command -v omnibot
+omnibot --version
+```
+
+If the current workspace contains `pyproject.toml` and the global command is not the workspace version, run the test commands as `uv run omnibot ...` (or use the workspace `.venv/bin/omnibot`) so the agent exercises the code under test. Do not infer command support from memory or from a different packaged version; run the relevant subcommand `--help` after selecting the runtime.
+
+For a source-checkout test, make this concrete before the first browser action:
+stop any existing daemon, start the workspace daemon with
+`uv run python -m omnibot --api-port 18764 --ws-port 18765 daemon run`, and
+invoke every subsequent CLI command as `uv run omnibot --no-start ...` (or the
+workspace `.venv/bin/omnibot --no-start ...`). Never use bare `omnibot` in that
+workflow, because it can auto-start the globally installed packaged daemon and
+silently test different code.
+
+## Native Command Router
+
+Before any page-state operation, choose the narrowest native command that expresses the intent. JavaScript is not a convenience shortcut; it is a fallback that requires evidence that native commands could not reach the state.
+
+| Intent | Native command path | Do not start with |
+| --- | --- | --- |
+| Current page identity | `get title`, `get url`, then `snapshot -i` or `read` if needed | `execute-js "return document.title/location.href"` |
+| Page text/content | `read --screens N`, `get text`, `get html`, `get attr`, `get count` | `execute-js "document.body.innerText"` |
+| Iframe context | `frame <iframe-id/name/title/src>`, then `snapshot`/page-state commands | Assuming host selectors reach child frames |
+| Click | `find ... --action click` -> `snapshot -i` + `click @eN` -> `click selector` -> `dom click` -> `mouse click` | `document.querySelector(...).click()` |
+| Scroll | `scroll`, `scrollintoview`, `dom scroll`, then `mouse scroll` | `window.scrollTo`, `element.scrollIntoView()` |
+| Fill/type | Text entry: `find ... --action fill`, `fill`, or `type`; key semantics: `press`/`keyboard` | setting `.value` or `innerHTML` in JS |
+| Wait | `wait` by selector/text/url/load/fn | shell sleep or JS timers |
+
+If you are about to write `document.querySelector`, `document.body.innerText`, `.click()`, `.value =`, `innerHTML`, `scrollTo`, or `scrollIntoView`, stop and identify the native command you will try first. Only use `execute-js` after documenting which native tiers failed and how you will verify the result.
+
+Text entry rule: when the user asks to enter, type, fill, or replace text, use `fill` or `type`. `keyboard` and `press` dispatch key events for shortcuts and key semantics; they are not text insertion commands and must not be substituted for text entry.
+
+Clipboard rule: both `clipboard read` and `clipboard write` require the explicit
+`--tab-id <TAB_ID>` on every invocation, even though the clipboard is shared by
+the browser extension. If no tab id is known, discover a safe target tab first;
+never omit the flag or infer a default tab.
+
+Cross-origin frame rule: snapshot visibility does not guarantee write access. After targeting a cross-origin iframe, verify `fill`/`type` focus and the resulting value; if focus fails, report the limitation explicitly and do not use JavaScript as a bypass.
+
 ## Workflow Context + Tab Target
 
 Every page-state workflow must use both controls:
@@ -71,6 +120,10 @@ The agent dispatch pattern is token + tab-id:
 4. Pass `--tab-id <TAB_ID>` on every command that touches page state.
 5. Run observe -> act -> verify on that same tab.
 
+Tab-id identity rule: use the exact `id` field returned by Omnibot `tabs`/`tab list` or by a tab-creation command. Browser-control surfaces may expose a shorter numeric `tab_id`; that value is not necessarily the Omnibot session id. When the discovery output contains both `tab_id` and `id`, pass the full namespaced `id` (for example, `edge-...:12345`) to `--tab-id`. Never reconstruct or strip the namespace.
+
+Phased workflow rule: do not bundle navigation and several page actions into one unverified sequence. After creating or navigating a tab, first run `get url` (and `snapshot -i` when controls are involved); then perform one meaningful action; then verify its concrete state before issuing the next action. For a form or multi-control task, repeat this observe -> one action -> verify cycle for each control.
+
 Examples of tab-locked page-state commands:
 
 ```bash
@@ -88,6 +141,14 @@ Targeting categories:
 | Discovery or tab creation: `tabs`, `tab list`, `tab new <URL>`, `open <URL>`, `navigate <URL>` | Return or discover the tab id; save it for later page-state commands. |
 | Read URL exception: `read <URL>` | Opens a temporary read tab and does not need `--tab-id`; reading an existing tab still requires `read --tab-id <TAB_ID>`. |
 
+Navigation safety invariant:
+
+- When the task says "open", "open a new tab", or "create a test page", use `open <URL>` or `tab new <URL>` and use the returned tab id. Do not substitute `goto`, plain `navigate`, or the currently active tab.
+- Use `goto --tab-id <TAB_ID>` or `navigate --same-tab --tab-id <TAB_ID>` only when the task explicitly asks to reuse an existing tab.
+- After creating a tab, verify `get url --tab-id <TAB_ID>` before any clipboard, upload, form, or other page-state operation. This prevents a failed or misinterpreted tab-creation result from mutating a user-owned page.
+- Tool-created tabs are temporary workflow resources and may be auto-closed by cleanup after inactivity. Complete the intended tab workflow in the same token/context, keep the returned tab id, and do not assume it will still exist after a long model pause or a separate one-shot agent process. If a later close reports `not found`, re-list tabs before retrying; the cleanup may already have closed it.
+- If `open` or `tab new` times out, loses its final response, or is retried after an agent/tool interruption, first run `tabs` or `tab list` and match the requested URL. Reuse one matching tab id instead of issuing another create command. Only create again after confirming that no matching tab from the interrupted attempt exists.
+
 ## Observe -> Act -> Verify
 
 All page operations must follow this loop:
@@ -160,6 +221,7 @@ Do not use `execute-js` first for rich text writes; `fill`/`type` on the `[richt
 | Reading pages | `references/operation-patterns.md#read` |
 | Clicking | `references/operation-patterns.md#click` |
 | Filling forms | `references/operation-patterns.md#fill` |
+| Scrolling | `references/operation-patterns.md#scroll` |
 | Select / check | `references/operation-patterns.md#select--check` |
 | Navigation | `references/operation-patterns.md#navigation` |
 | Waiting | `references/operation-patterns.md#wait` |
@@ -186,47 +248,6 @@ omnibot license status
 
 If the extension is not connected, open Chrome or Edge with the omnibot extension loaded and keep an HTTP/HTTPS tab open.
 
-## Site Memory Reuse
-
-Before operating a complex site, check whether a generated site skill is installed for the current domain.
-
-1. Run `omnibot skills list-sites` to see available generated site skills.
-2. If a matching site skill is installed (e.g., `omnibot-xhs`), read its `SKILL.md` and use it for the operation.
-3. If no matching site skill is installed, create one with:
-   ```bash
-   omnibot explore run <url> --name <site> --goal "<explicit goal>"
-   omnibot skills install --agent opencode --site <site>
-   ```
-4. Generated site skills are not auto-loaded from `~/.omnibot/skills/`; they must be installed into the current agent's skill directory.
-
-## Generated Site Skill Installation
-
-Generated site skills are stored under `~/.omnibot/skills/omnibot-<name>/` but must be installed into each agent's native skill path to be auto-loaded.
-
-List available generated site skills:
-
-```bash
-omnibot skills list-sites
-```
-
-Install one generated site skill:
-
-```bash
-omnibot skills install --agent opencode --site xhs
-omnibot skills install --agent claude --site xhs
-omnibot skills install --agent codex --site xhs
-```
-
-Install all generated site skills:
-
-```bash
-omnibot skills install --agent opencode --all-sites
-```
-
-Default `omnibot skills install --agent <agent>` installs only the official packaged omnibot skill, not generated site skills.
-
-Local site memory is reusable strategy, not user task output. Do not write user inputs, scraped records, or private task results into generated site packages.
-
 ## Fallback Discipline
 
 Fallback tiers are for completing operations after better patterns fail. They are not debugging shortcuts.
@@ -243,6 +264,8 @@ Tier order:
 
 When entering a lower tier, state why the higher tier failed. After any fallback action, verify with `snapshot`, `get`, `is`, `wait`, or equivalent evidence.
 
+Before `execute-js`, the agent must have native-attempt evidence: the exact `find`/`snapshot`/`click`/`fill`/`scroll`/`get`/`read` commands tried, their result, why they were insufficient, and the post-JS verification command to run. Without that evidence, use a native command instead.
+
 ## Debug Evidence
 
 Debugging is for evidence. Fallback is for completing operations.
@@ -254,6 +277,7 @@ Use screenshots, annotated screenshots, console logs, network logs, trace, recor
 - Missing `OMNIBOT_SESSION_TOKEN` or missing `--tab-id` on page-state commands.
 - Acting without verify or claiming success without evidence.
 - Using `execute-js` first, raw CSS before semantic find, `@eN` across tabs, implicit tab targeting, or shell sleep instead of `omnibot wait`.
+- Using JavaScript read/click/scroll shortcuts when native `get`/`read`/`find`/`snapshot`/`click`/`scroll` can express the task.
 - Using removed commands: `switch-tab`, `focus-tab`, `tab switch`, `tab focus`. These are no longer available.
 - Using `tabs[0]` or the first tab as a target. The first tab is often a user tab or transport tab.
 - Closing user tabs discovered during cleanup. Only close tabs created by the current workflow.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/anti-patterns.md

@@ -5,6 +5,11 @@
 | Missing `OMNIBOT_SESSION_TOKEN` | Workflows can share implicit state across agents. | `OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>` |
 | Missing `--tab-id` | The command may target the wrong page. | Pass `--tab-id <TAB_ID>` on every page-state command. |
 | `execute-js` first | JavaScript bypasses standard browser interaction and hides better evidence. | Try semantic find, snapshot refs, selectors, DOM, and mouse first. For CSS-only dropdowns, use JavaScript only after the trigger clicked, options remain absent from `snapshot -i`, and higher tiers cannot complete open-then-select. |
+| JS page detection (`document.title`, `location.href`) | It teaches agents to treat scripts as normal reads. | Use `get title` and `get url`. |
+| JS text extraction (`document.body.innerText`) | It bypasses `read` cleanup, lazy-page handling, and targeted evidence. | Use `read --screens N` or `get text`. |
+| JS click shortcut (`querySelector(...).click()`) | It can bypass pointer events, overlays, disabled state, and framework/user-intent safety checks. | Use `find ... --action click`, `snapshot -i` + `click @eN`, then selector/DOM/mouse fallback. |
+| JS scroll shortcut (`window.scrollTo`, `scrollIntoView`) | It hides whether the scroll target/container is correct and bypasses Omnibot's action evidence path. | Use `scroll`, `scrollintoview`, `dom scroll`, or `mouse scroll`. |
+| JS value or richtext writes | App frameworks may ignore value/HTML mutation without trusted events and editor integration. | Use `fill`, `type`, `press`, `keyboard`, and `[richtext]` refs. |
 | Reusing `@eN` across tabs | Refs are tab-scoped and may point to a different element elsewhere. | Take a fresh `snapshot -i --tab-id <TAB_ID>` per tab. |
 | Relying on implicit tab targeting | It is unavailable and unsafe for concurrent workflows. | Use explicit `--tab-id` on every page-state command. |
 | Using sleep instead of wait | Fixed sleeps are flaky and either too short or too slow. | Use `omnibot wait --text`, `--url`, selector state, load state, or `--fn`. |
@@ -40,6 +45,9 @@ Do not manually reopen a dropdown just to discover options if `snapshot -i` alre
 - "I can just use the current tab."
 - "This is only one click, no need to verify."
 - "JavaScript is faster."
+- "I just need title/url/text, so JS is fine."
+- "Clicking with JS is equivalent to a user click."
+- "Scrolling with JS is harmless."
 - "The ref probably still points to the same element."
 - "A screenshot is enough even though I need text."
 - "Sleep should be fine."

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/command-reference.md

@@ -90,7 +90,7 @@ omnibot --version
 omnibot -V
 ```
 
-Output: a single line in the form `omnibot <version>` (for example `omnibot 1.6.3`).
+Output: a single line in the form `omnibot <version>`.
 Preferred pattern: See `runtime-and-status.md#version`.
 Fallback relation: Not a fallback command.
 
@@ -150,6 +150,7 @@ Purpose: Check element state.
 
 ```bash
 OMNIBOT_SESSION_TOKEN=checkout omnibot is visible "#submit" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot is hidden "#spinner" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "#submit" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=checkout omnibot is checked "#agree" --tab-id <TAB_ID>
 ```
@@ -325,6 +326,8 @@ OMNIBOT_SESSION_TOKEN=form omnibot keyup Shift --tab-id <TAB_ID>
 Preferred pattern: Prefer `fill`, `type`, and `press` first.
 Fallback relation: Keyboard commands are a focused fallback before mouse or JavaScript.
 
+`keyboard type` preserves keyboard events and updates the focused editable when the browser does not apply the default text insertion. `keyboard inserttext` inserts text directly and intentionally does not emit per-character key events.
+
 ## Semantic Find
 
 Semantic find is Tier 1 for operating by meaning.
@@ -434,7 +437,7 @@ Purpose: Run arbitrary JavaScript in the page.
 Usage tier: Tier 6 fallback only. Do not use first.
 
 ```bash
-OMNIBOT_SESSION_TOKEN=repair omnibot execute-js "return location.href" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=repair omnibot execute-js "return window.appState?.status" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=repair omnibot execute-js --file /tmp/repair.js --tab-id <TAB_ID>
 ```
 
@@ -470,6 +473,8 @@ OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com --tab-id <TAB_ID
 Preferred pattern: See `operation-patterns.md#navigation` and `session-and-tabs.md#tab-explicit`.
 Fallback relation: Verify with `get url --tab-id <TAB_ID>` before continuing.
 
+Safety rule: treat `open` and `tab new` as the only new-tab commands. Never replace a requested new-tab operation with `goto`, plain `navigate`, or an active-tab action. Use `goto --tab-id` or `navigate --same-tab --tab-id` only when reusing an explicitly selected existing tab, and verify the returned tab's URL before mutating page state.
+
 ### close / back / forward / reload / pushstate
 
 Purpose: Change tab lifecycle or history state.
@@ -504,9 +509,13 @@ Purpose: Manage windows and frames.
 
 ```bash
 OMNIBOT_SESSION_TOKEN=research omnibot window new
-OMNIBOT_SESSION_TOKEN=research omnibot frame main
+OMNIBOT_SESSION_TOKEN=research omnibot frame "#payment-frame" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot frame main --tab-id <TAB_ID>
 ```
 
+`frame` targets an iframe by id, name, title, or matching source URL. Set it before child-frame page-state commands and use `frame main` before reading host-page state.
+
 ## Waiting & Batch
 
 ### wait
@@ -566,6 +575,21 @@ OMNIBOT_SESSION_TOKEN=debug-checkout omnibot console clear --tab-id <TAB_ID>
 Preferred pattern: See `debugging-and-evidence.md#console`.
 Fallback relation: Evidence collection, not operation fallback. `console errors` currently uses the console log collection path; verify level filtering in output before treating it as error-only evidence.
 
+### dialog
+
+Purpose: Read, clear, or handle native browser JavaScript dialogs (`alert`, `confirm`, `prompt`).
+
+```bash
+OMNIBOT_SESSION_TOKEN=debug-checkout omnibot dialog logs --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=debug-checkout omnibot dialog clear --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=debug-checkout omnibot dialog handle accept --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=debug-checkout omnibot dialog handle dismiss --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=debug-checkout omnibot dialog handle accept --text "prompt text" --tab-id <TAB_ID>
+```
+
+Preferred pattern: Use `dialog logs` or `dialog clear` before triggering a browser-native dialog so the extension has debugger capture ready. Trigger through normal page actions when possible; use `execute-js` only when the task is explicitly to test a native JS dialog.
+Fallback relation: Evidence and dialog handling, not a general page-operation fallback.
+
 ### network
 
 Purpose: Capture and inspect CDP Network events buffered by the Omnibot browser extension.
@@ -691,6 +715,9 @@ omnibot skills install --agent hermes --profile nuwa
 omnibot skills install --agent opencode
 omnibot skills install --agent claude
 omnibot skills install --agent codex
+omnibot skills install --agent openclaw
+omnibot skills install --agent workbuddy
+omnibot skills install --agent trae
 omnibot skills path
 ```
 
@@ -707,49 +734,3 @@ omnibot license status
 
 Preferred pattern: See `runtime-and-status.md#startup-check`.
 Fallback relation: Not a fallback command.
-
-## Site Memory
-
-### explore
-
-Purpose: Explore one explicit site operation goal and generate reusable installable site skill under `~/.omnibot/skills/omnibot-<name>/`.
-
-```bash
-omnibot explore run https://www.xiaohongshu.com --name xhs --goal "发布图文笔记"
-omnibot explore run https://x.com --goal "post a tweet"
-omnibot explore list
-omnibot explore show xhs
-omnibot explore promote xhs --goal publish-note --version 2026-06-17T21-30-00Z
-```
-
-Rules:
-
-- `--goal` is required for a new exploration.
-- Same site and different goals are stored in the same site package.
-- Same site and same goal create a new preserved version.
-- Safe verified versions become active automatically.
-- Dangerous verified versions remain candidates until promoted.
-
-### skills list-sites
-
-Purpose: List generated site skills available for installation.
-
-```bash
-omnibot skills list-sites
-```
-
-### skills install --site
-
-Purpose: Install one generated site skill into an agent's skill directory.
-
-```bash
-omnibot skills install --agent opencode --site xhs
-omnibot skills install --agent claude --site xhs
-omnibot skills install --agent opencode --all-sites
-```
-
-Rules:
-
-- `--site` installs one generated site skill by name.
-- `--all-sites` installs all generated site skills.
-- Without `--site` or `--all-sites`, only the official packaged omnibot skill is installed.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/debugging-and-evidence.md

@@ -93,6 +93,12 @@ Trace is evidence. It does not replace operation verification.
 
 Use record/replay when a flow must be captured or reproduced.
 
+When a user asks for a complete recording or trace workflow, treat `start` as an
+internal setup step: continue with the requested browser actions, run the
+matching `stop -o <path>`, verify the artifact exists and contains events, and
+only then report the result. Do not stop after `record start` or `trace start`
+to ask what should be recorded when the user already specified the workflow.
+
 ```bash
 OMNIBOT_SESSION_TOKEN=debug-checkout omnibot record start
 OMNIBOT_SESSION_TOKEN=debug-checkout omnibot click --tab-id <TAB_ID> @e4

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/fallback-operations.md

@@ -7,6 +7,15 @@ Every fallback escalation must answer two questions:
 - Which higher tier failed, and why?
 - How will the result be verified?
 
+Before using `execute-js`, the answer must include native-attempt evidence:
+
+- The native command path already tried (`find`, `snapshot -i`, `click`, `fill`, `scroll`, `get`, `read`, `wait`, `dom`, or `mouse`).
+- The observed failure or missing state.
+- Why the next native tier is insufficient.
+- The exact post-JS verification command.
+
+If the task is normal page identity, text extraction, click, scroll, fill/type, or wait, and you do not have that evidence, go back to `operation-patterns.md#native-first-decision-gate`.
+
 ## Fallback Tier Model
 
 ### Tier 1 Semantic
@@ -99,6 +108,16 @@ Mouse fallback is fragile across viewport size, scroll position, and responsive
 
 Do not use `execute-js` first.
 
+Do not use JavaScript as a shortcut for native commands:
+
+| Shortcut | Native command instead |
+| --- | --- |
+| `return document.title` / `location.href` | `get title`, `get url` |
+| `document.body.innerText` | `read --screens N`, `get text` |
+| `querySelector(...).click()` | `find ... --action click`, `click @eN`, `click selector` |
+| `.value = ...` or `innerHTML = ...` | `fill`, `type`, richtext refs |
+| `window.scrollTo` / `scrollIntoView()` | `scroll`, `scrollintoview`, `dom scroll`, `mouse scroll` |
+
 Use `execute-js` only when:
 
 - Semantic find fails.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/operation-patterns.md

@@ -2,6 +2,22 @@
 
 Use this file to choose behavior by task. Every page-state workflow must set `OMNIBOT_SESSION_TOKEN=<workflow-name>` and pass `--tab-id <TAB_ID>` on each page-state command.
 
+## Native-First Decision Gate
+
+Use native Omnibot commands for normal browser operations. Treat `execute-js` as a repair tool only after native attempts fail with evidence.
+
+| If you need to... | Use first | JS shortcut to avoid |
+| --- | --- | --- |
+| Know where you are | `get title`, `get url` | `return document.title`, `location.href` |
+| Read visible or rendered content | `read`, `get text`, `get html`, `get attr`, `get count` | `document.body.innerText` |
+| Click a control | `find ... --action click`, `snapshot -i` + `click @eN`, `click selector` | `querySelector(...).click()` |
+| Scroll | `scroll`, `scrollintoview`, `dom scroll`, `mouse scroll` | `window.scrollTo`, `scrollIntoView()` |
+| Enter text | `find ... --action fill`, `fill`, `type` | `.value = ...`, `innerHTML = ...`, `keyboard`, `press` |
+
+If a page task can be phrased as click, fill, type, press, scroll, wait, read, get, or is, use that command. Do not translate user-visible actions into JavaScript unless the fallback file says the higher tiers have failed.
+
+Text versus keys: `fill`/`type` are the only native commands for inserting text and dispatching the page's input events. Use `press`/`keyboard` only for a key such as Enter, Escape, Tab, arrows, or a shortcut; raw keydown/keyup events do not guarantee that a focused text control receives characters.
+
 ## Read
 
 ### When to use
@@ -16,7 +32,7 @@ Use targeted state commands when the agent needs one value, visibility, enabled/
 2. `read --screens N --tab-id <TAB_ID>` for longer or lazy-loaded pages.
 3. `read <URL>` when opening a temporary tab only for reading that URL.
 4. `get title/url/text/html/value/attr/count/box/styles` for narrow evidence.
-5. `is visible/enabled/checked` for boolean state.
+5. `is visible/hidden/enabled/checked` for boolean state.
 5. `snapshot -i` when actionable refs are needed.
 6. `dom visible` or `execute-js` fallback only after standard reads cannot access the state.
 
@@ -25,8 +41,12 @@ Use targeted state commands when the agent needs one value, visibility, enabled/
 ```bash
 OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=research omnibot read --screens 3 https://example.com/article
+OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
 ```
 
+Do not use `execute-js "return document.title + location.href"` or `execute-js "return document.body.innerText"` for normal page detection or text extraction. Use `get` or `read`; they are the native evidence path.
+
 ### Verification
 
 Use the narrowest read that proves the claim:
@@ -34,6 +54,7 @@ Use the narrowest read that proves the claim:
 ```bash
 OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=research omnibot is visible "#main" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot is hidden "#spinner" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=research omnibot get count ".result" --tab-id <TAB_ID>
 ```
 
@@ -86,6 +107,8 @@ OMNIBOT_SESSION_TOKEN=checkout omnibot is visible ".success" --tab-id <TAB_ID>
 
 If semantic and refs fail, document why and continue at `fallback-operations.md#selector-fallback`.
 
+Do not use `execute-js` for a visible button, link, menu item, tab, card, or modal control until the native click tiers above have failed and you have re-observed the page. A JS `.click()` can bypass pointer events, framework guards, disabled state, overlays, and user-intent safety checks.
+
 ### Static-text refs
 
 When `snapshot -i` shows only `StaticText` for a visible control label, do not assume the text ref itself is clickable. Prefer, in order:
@@ -159,7 +182,7 @@ Insert an image after a specific paragraph:
 ```bash
 OMNIBOT_SESSION_TOKEN=editor omnibot find text "第二段锚点文字" --action click --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=editor omnibot click ".syl-toolbar-tool.image .syl-toolbar-button" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=editor omnibot wait --selector ".upload-image-panel input[type=file]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=editor omnibot wait ".upload-image-panel input[type=file]" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=editor omnibot upload ".upload-image-panel input[type=file]" "/path/to/image.png" --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=editor omnibot find role button --name "确定" --action click --tab-id <TAB_ID>
 ```
@@ -170,6 +193,8 @@ Verify the inserted image by counting visible image cards, not raw `<img>` nodes
 
 If fill does not update the application state, use `fallback-operations.md#javascript-fallback` only after selector/focus/type attempts fail. JavaScript must dispatch real `input` and `change` events.
 
+Do not use JS `.value = ...`, `innerText`, or `innerHTML` for normal form fields or rich text. Native `fill`/`type` paths already handle events and rich text editor integration.
+
 ## Select / Check
 
 ### When to use
@@ -223,6 +248,31 @@ Do not loop on manual open -> snapshot -> open -> snapshot when `snapshot -i` al
 
 If native select/check fails, use `fallback-operations.md#selector-fallback`. Use JavaScript only if events must be synthesized or if evidence shows a CSS-only multi-step widget cannot be completed through semantic, snapshot, selector, DOM, or mouse tiers.
 
+## Scroll
+
+### When to use
+
+Use Scroll when content, controls, lazy-loaded lists, dropdown panels, or editor areas are off-screen.
+
+### Preferred sequence
+
+1. `scroll down|up|left|right <pixels>` for page scroll.
+2. `scroll down|up|left|right <pixels> --selector <container>` for scrollable containers.
+3. `scrollintoview @eN` or `scrollintoview selector` for a known target.
+4. `dom scroll` when visible DOM node fallback is needed.
+5. `mouse scroll` only when element/container scroll commands fail.
+6. `execute-js` scroll only after the native tiers fail.
+
+### Example
+
+```bash
+OMNIBOT_SESSION_TOKEN=read omnibot scroll down 800 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=read omnibot scrollintoview @e7 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=read omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+Do not start with `execute-js "window.scrollTo(...)"` or `element.scrollIntoView()`. Native scroll commands preserve the agent's observe -> act -> verify loop and produce clearer failure modes.
+
 ## Navigation
 
 ### When to use
@@ -236,6 +286,8 @@ Use Navigation to open pages, create tabs, change history, reload, close tabs, m
 3. Verify with `get url --tab-id <TAB_ID>`.
 4. Run all later page-state commands with `--tab-id <TAB_ID>`.
 
+Do not chain navigation, discovery, and multiple mutations before observing the result. After navigation, verify the URL and snapshot first; then issue one action and verify its state before continuing. Multi-control workflows must use one observe -> act -> verify cycle per control.
+
 ### Example
 
 ```bash
@@ -270,6 +322,18 @@ OMNIBOT_SESSION_TOKEN=research omnibot window new
 OMNIBOT_SESSION_TOKEN=research omnibot frame main
 ```
 
+Iframe workflow:
+
+1. Verify the host tab URL and snapshot first.
+2. Set the frame target explicitly, for example `frame #payment-frame --tab-id <TAB_ID>` (an iframe `id`, `name`, `title`, or matching `src` is accepted).
+3. Re-observe the child context with `snapshot -i --tab-id <TAB_ID>` before filling or clicking.
+4. Perform one child-frame action and verify its child-frame state with `get`, `is`, or `wait`.
+5. Return to the host with `frame main --tab-id <TAB_ID>` before reading host-page state.
+
+Do not assume a host-page selector reaches an iframe. If a child selector returns `null`, establish the frame target and re-observe; for cross-origin frames, report the explicit inaccessible-frame result rather than using JavaScript to bypass it.
+
+Cross-origin caveat: a CDP snapshot may expose remote-frame refs for observation or coordinate actions, but `fill`/`type` may still fail to focus a child control. Verify the child value after every write; if focus fails, report cross-origin text entry as unsupported instead of claiming success or retrying with JavaScript.
+
 ### Verification
 
 Always verify the final target:
@@ -388,7 +452,7 @@ OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TA
 Confirm the input accepted the file:
 
 ```bash
-OMNIBOT_SESSION_TOKEN=form omnibot get "input[type=file]" attr value --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot get attr "input[type=file]" value --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
 ```
 

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/runtime-and-status.md

@@ -99,7 +99,7 @@ omnibot --version
 omnibot -V
 ```
 
-Use `version` to print the installed omnibot CLI version. Output is a single line in the form `omnibot <version>` (for example `omnibot 1.6.3`) with no banner, JSON, or daemon calls. Prefer this over `omnibot --help` or `doctor` when you only need the version string.
+Use `version` to print the installed omnibot CLI version. Output is a single line in the form `omnibot <version>` with no banner, JSON, or daemon calls. Prefer this over `omnibot --help` or `doctor` when you only need the version string.
 
 ## skills path
 
@@ -116,6 +116,9 @@ omnibot skills install --agent hermes --profile nuwa
 omnibot skills install --agent opencode
 omnibot skills install --agent claude
 omnibot skills install --agent codex
+omnibot skills install --agent openclaw
+omnibot skills install --agent workbuddy
+omnibot skills install --agent trae
 ```
 
 Install only when setting up or repairing an agent integration. It is not part of normal page operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omniaibot/win-x64",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "omnibot executable for Windows x64",
   "os": [
     "win32"