npm - @omniaibot/win-x64 - Versions diffs - 1.6.2 → 1.6.3 - Mend

@omniaibot/win-x64 1.6.2 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

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

@@ -1,384 +1,396 @@
-# Operation Patterns
-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.
-## Read
-### When to use
-Use Read when the agent needs clean rendered page content: article text, search results, feed items, long pages, lazy-loaded text, or a human-readable summary source.
-Use targeted state commands when the agent needs one value, visibility, enabled/checked state, layout box, or computed styles. Use `snapshot -i` when the agent needs current visible UI structure for deciding the next action.
-### Preferred sequence
-1. `read --tab-id <TAB_ID>` for clean page text on an existing tab.
-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. `snapshot -i` when actionable refs are needed.
-6. `dom visible` or `execute-js` fallback only after standard reads cannot access the state.
-### Example
-```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
-```
-### Verification
-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 get count ".result" --tab-id <TAB_ID>
-```
-### Fallback entry point
-If `read` or targeted reads omit needed runtime state, go to `fallback-operations.md#fallback-tier-model`. Start with DOM fallback before JavaScript.
-## Click
-### When to use
-Use Click for buttons, links, menu items, cards, checkouts, modal actions, and any user-like click target.
-### Preferred sequence
-1. `find role/text/testid --action click`
-2. `snapshot -i` -> `click @eN`
-3. `click selector`
-4. `dom click`
-5. `mouse click`
-6. `execute-js` click
-7. `cdp` fallback
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
-```
-If semantic find is ambiguous, use refs from the same tab:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-```
-### Verification
-Verify the expected state, not just command success:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot is visible ".success" --tab-id <TAB_ID>
-```
-### Fallback entry point
-If semantic and refs fail, document why and continue at `fallback-operations.md#selector-fallback`.
-## Fill
-### When to use
-Use Fill for text inputs, textareas, search boxes, login fields, and form fields where the final value must be controlled.
-### Preferred sequence
-1. `find label/placeholder --action fill`
-2. `snapshot -i` -> `fill @eN`
-3. `fill selector`
-4. `focus` + `type`
-5. `execute-js` set value and dispatch `input`/`change` events
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot find label "Email" --action fill --action-value "a@b.com" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-```
-With refs:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot fill --tab-id <TAB_ID> @e2 "a@b.com"
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-```
-### Verification
-Use `get value`, visible validation text, enabled state, or submit readiness:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
-```
-### Fallback entry point
-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.
-## Select / Check
-### When to use
-Use this pattern for dropdowns, checkboxes, toggles, agreement boxes, filters, and boolean controls.
-### Preferred sequence
-1. Observe state with `snapshot -i` and `is checked` when relevant.
-2. Use `select`, `check`, or `uncheck` with refs or selectors.
-3. Verify with `get value`, `is checked`, visible text, or result count.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot select @e5 "US" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot get value "select[name=country]" --tab-id <TAB_ID>
-```
-Checkbox example:
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot check "#agree" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
-```
-### Verification
-For checkboxes, verify boolean state. For selects, verify value or dependent page state.
-### CSS-only dropdowns and custom menus
-Some dropdowns, hover menus, tooltips, and custom selects are CSS-only widgets. The visible trigger may be accessible, while the option nodes are hidden `<div>` elements without `role`, accessible name, or stable refs.
-Use this evidence path before JavaScript:
-1. Try semantic `find` or a normal `select`/`click` against the trigger.
-2. Verify whether the selected label, result order, or dependent state changed.
-3. Run `snapshot -i` after opening the control.
-4. If the trigger clicked but options are absent from the accessibility tree, do not keep retrying `find` or stale refs.
-5. Escalate to `fallback-operations.md#css-only-dropdown-javascript-fallback` for an atomic open-then-select script.
-`snapshot -i` not showing an option does not prove the DOM node is missing. It may only prove the widget is not exposed through the accessibility tree.
-### Fallback entry point
-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.
-## Navigation
-### When to use
-Use Navigation to open pages, create tabs, change history, reload, close tabs, move between pages, create windows, or select frames.
-### Preferred sequence
-1. Create or discover a tab with `tabs`, `tab list`, `tab new`, `open`, or `navigate`.
-2. Save the returned tab id.
-3. Verify with `get url --tab-id <TAB_ID>`.
-4. Run all later page-state commands with `--tab-id <TAB_ID>`.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot tab new https://example.com --label research
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
-```
-History and lifecycle:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot back --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot forward --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot reload --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot wait --load domcontentloaded --tab-id <TAB_ID>
-```
-Other navigation commands:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
-OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com --same-tab --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
-OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot pushstate /dashboard --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot close <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot tab list
-OMNIBOT_SESSION_TOKEN=research omnibot tab close research
-OMNIBOT_SESSION_TOKEN=research omnibot window new
-OMNIBOT_SESSION_TOKEN=research omnibot frame main
-```
-### Verification
-Always verify the final target:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot wait --load networkidle --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
-```
-### Fallback entry point
-Same-tab navigation must include `--tab-id <TAB_ID>`. If the target tab id is unknown, run `omnibot tabs` first and choose the intended tab explicitly.
-## Wait
-### When to use
-Use Wait after navigation, clicks, form submissions, reloads, dynamic rendering, lazy loading, or any action that changes asynchronous state.
-### Preferred sequence
-1. Wait for selector visibility or hidden state.
-2. Wait for text.
-3. Wait for URL.
-4. Wait for load state.
-5. Wait for a JavaScript condition with `--fn`.
-6. Avoid shell sleep.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#spinner" --state hidden --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --text "Welcome" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot get text "#main" --tab-id <TAB_ID>
-```
-Other waits:
-```bash
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load domcontentloaded --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load networkidle --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=checkout omnibot wait --fn "window.appReady === true" --tab-id <TAB_ID>
-```
-### Verification
-After waiting, read the final condition with `get`, `is`, `wait`, or `snapshot`.
-### Fallback entry point
-If waits time out, collect evidence with `debugging-and-evidence.md`; do not replace them with shell sleep.
-## Extraction
-### When to use
-Use Extraction for retrieving page text, HTML fragments, links, counts, assets, or clipboard data.
-### Preferred sequence
-1. `get text/html/attr/count` for targeted extraction.
-2. `read --screens N` for clean page text, long pages, or lazy-loaded content.
-3. `snapshot -i` for structured page observation before action planning.
-4. `assets list/export` for resources.
-5. `clipboard read` only when clipboard content is part of the task.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=extract omnibot get text "#article" --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot get attr "a.next" href --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot get count ".result" --tab-id <TAB_ID>
-```
-Long page example:
-```bash
-OMNIBOT_SESSION_TOKEN=extract omnibot read --screens 5 --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=extract omnibot assets list --tab-id <TAB_ID>
-```
-### Verification
-Verify extraction completeness with expected markers in `read`, element counts, or targeted reads for known selectors.
-### Fallback entry point
-If content exists only in runtime objects, use `fallback-operations.md#javascript-fallback` after explaining why `read`, `snapshot`, and `get` could not access it.
-## Upload
-### When to use
-Native upload is currently unavailable in the extension transport. Do not use `omnibot upload` as an agent workflow step until file chooser support is implemented.
-### Preferred sequence
-1. Observe the upload UI and confirm the task requires a local file.
-2. Report that native upload is currently unavailable.
-3. If the user still wants a workaround, ask for approval before using page-specific JavaScript or manual browser interaction.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
-# upload is currently unavailable; do not run omnibot upload here.
-```
-### Verification
-If upload support is implemented later, verify with visible filename, count, enabled submit state, or application-specific confirmation:
-```bash
-OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
-```
-### Fallback entry point
-Do not treat JavaScript as a normal upload fallback. File inputs and browser file chooser behavior are security-sensitive and page-specific.
-## Batch
-### When to use
-Use Batch for short, known-safe extension/CDP command chains where the target tab and verification are already explicit. Batch is not a wrapper for normal CLI commands such as `snapshot` or `click`.
-### Preferred sequence
-1. Keep batches short.
-2. Include only deterministic operations.
-3. Verify after the batch with a separate command.
-4. Use `--file` for complex JSON quoting.
-### Example
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"cdp","method":"Runtime.evaluate","params":{"expression":"document.title","returnByValue":true}}]' --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
-```
-File example:
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
-```
-### Verification
-Do not treat batch success as task success. Verify final page state separately.
-### Fallback entry point
-Batch is not a fallback tier. If a batched operation fails, re-run the workflow step-by-step and enter the normal fallback model.
+# Operation Patterns
+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.
+## Read
+### When to use
+Use Read when the agent needs clean rendered page content: article text, search results, feed items, long pages, lazy-loaded text, or a human-readable summary source.
+Use targeted state commands when the agent needs one value, visibility, enabled/checked state, layout box, or computed styles. Use `snapshot -i` when the agent needs current visible UI structure for deciding the next action.
+### Preferred sequence
+1. `read --tab-id <TAB_ID>` for clean page text on an existing tab.
+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. `snapshot -i` when actionable refs are needed.
+6. `dom visible` or `execute-js` fallback only after standard reads cannot access the state.
+### Example
+```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
+```
+### Verification
+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 get count ".result" --tab-id <TAB_ID>
+```
+### Fallback entry point
+If `read` or targeted reads omit needed runtime state, go to `fallback-operations.md#fallback-tier-model`. Start with DOM fallback before JavaScript.
+## Click
+### When to use
+Use Click for buttons, links, menu items, cards, checkouts, modal actions, and any user-like click target.
+### Preferred sequence
+1. `find role/text/testid --action click`
+2. `snapshot -i` -> `click @eN`
+3. `click selector`
+4. `dom click`
+5. `mouse click`
+6. `execute-js` click
+7. `cdp` fallback
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
+```
+If semantic find is ambiguous, use refs from the same tab:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+```
+### Verification
+Verify the expected state, not just command success:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot is visible ".success" --tab-id <TAB_ID>
+```
+### Fallback entry point
+If semantic and refs fail, document why and continue at `fallback-operations.md#selector-fallback`.
+### 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:
+1. `find role button --name "<label>" --action click`.
+2. `click "text=<label>"`.
+3. `get box "text=<label>"` followed by `mouse click <center-x> <center-y>`.
+4. CDP/JS fallback only after verifying the semantic and coordinate paths failed.
+## Fill
+### When to use
+Use Fill for text inputs, textareas, search boxes, login fields, and form fields where the final value must be controlled.
+### Preferred sequence
+1. `find label/placeholder --action fill`
+2. `snapshot -i` -> `fill @eN`
+3. `fill selector`
+4. `focus` + `type`
+5. `execute-js` set value and dispatch `input`/`change` events
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot find label "Email" --action fill --action-value "a@b.com" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+```
+With refs:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot fill --tab-id <TAB_ID> @e2 "a@b.com"
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+```
+### Verification
+Use `get value`, visible validation text, enabled state, or submit readiness:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+```
+### Fallback entry point
+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.
+## Select / Check
+### When to use
+Use this pattern for dropdowns, comboboxes, checkboxes, toggles, agreement boxes, filters, and boolean controls.
+### Preferred sequence
+1. Use `snapshot -i` first; visible comboboxes may include auto-probed option refs.
+2. Use `click @option` if `snapshot -i` lists auto-probed combobox option refs.
+3. Use `select @combobox "value"` for native selects or simple select-like controls.
+4. Use `check` / `uncheck` for boolean controls.
+5. Verify selected label, value, URL query, result count, or dependent page state.
+`snapshot -i` can list options for visible custom comboboxes even though the dropdown closes during observation. These refs are still actionable because Omnibot stores the option's `openerSelector` and can reopen the owning combobox before clicking the option.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot click @e22 --tab-id <TAB_ID>  # @e22 [option] "OpenAI Chat"
+OMNIBOT_SESSION_TOKEN=form omnibot get url --tab-id <TAB_ID>
+```
+Checkbox example:
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot check "#agree" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=form omnibot is checked "#agree" --tab-id <TAB_ID>
+```
+### Verification
+For checkboxes, verify boolean state. For selects, verify value or dependent page state.
+### CSS-only dropdowns and custom menus
+Some dropdowns, hover menus, tooltips, and custom selects are CSS-only or portal-based widgets. The visible trigger may be accessible, while the option nodes are hidden `<div>` elements without `role`, accessible name, or stable refs. Start with `snapshot -i`; visible comboboxes may include auto-probed option refs before any manual dropdown opening.
+Escalation order:
+1. Run `snapshot -i` and look for `[option]` refs near the combobox.
+2. If an option ref exists, click the option ref directly and verify.
+3. If options are absent, click/hover the trigger once, run `snapshot -i` again, then click the option ref if it appears.
+4. If trigger interaction works but options remain absent or option refs fail verification, use `fallback-operations.md#css-only-dropdown-javascript-fallback`.
+Do not loop on manual open -> snapshot -> open -> snapshot when `snapshot -i` already lists auto-probed combobox options.
+### Fallback entry point
+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.
+## Navigation
+### When to use
+Use Navigation to open pages, create tabs, change history, reload, close tabs, move between pages, create windows, or select frames.
+### Preferred sequence
+1. Create or discover a tab with `tabs`, `tab list`, `tab new`, `open`, or `navigate`.
+2. Save the returned tab id.
+3. Verify with `get url --tab-id <TAB_ID>`.
+4. Run all later page-state commands with `--tab-id <TAB_ID>`.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot tab new https://example.com --label research
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+History and lifecycle:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot back --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot forward --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot reload --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot wait --load domcontentloaded --tab-id <TAB_ID>
+```
+Other navigation commands:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
+OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com --same-tab --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
+OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot pushstate /dashboard --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot close <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot tab list
+OMNIBOT_SESSION_TOKEN=research omnibot tab close research
+OMNIBOT_SESSION_TOKEN=research omnibot window new
+OMNIBOT_SESSION_TOKEN=research omnibot frame main
+```
+### Verification
+Always verify the final target:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot wait --load networkidle --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+### Fallback entry point
+Same-tab navigation must include `--tab-id <TAB_ID>`. If the target tab id is unknown, run `omnibot tabs` first and choose the intended tab explicitly.
+## Wait
+### When to use
+Use Wait after navigation, clicks, form submissions, reloads, dynamic rendering, lazy loading, or any action that changes asynchronous state.
+### Preferred sequence
+1. Wait for selector visibility or hidden state.
+2. Wait for text.
+3. Wait for URL.
+4. Wait for load state.
+5. Wait for a JavaScript condition with `--fn`.
+6. Avoid shell sleep.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait "#spinner" --state hidden --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --text "Welcome" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot get text "#main" --tab-id <TAB_ID>
+```
+Other waits:
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load domcontentloaded --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --load networkidle --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot wait --fn "window.appReady === true" --tab-id <TAB_ID>
+```
+### Verification
+After waiting, read the final condition with `get`, `is`, `wait`, or `snapshot`.
+### Fallback entry point
+If waits time out, collect evidence with `debugging-and-evidence.md`; do not replace them with shell sleep.
+## Extraction
+### When to use
+Use Extraction for retrieving page text, HTML fragments, links, counts, assets, or clipboard data.
+### Preferred sequence
+1. `get text/html/attr/count` for targeted extraction.
+2. `read --screens N` for clean page text, long pages, or lazy-loaded content.
+3. `snapshot -i` for structured page observation before action planning.
+4. `assets list/export` for resources.
+5. `clipboard read` only when clipboard content is part of the task.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=extract omnibot get text "#article" --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot get attr "a.next" href --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot get count ".result" --tab-id <TAB_ID>
+```
+Long page example:
+```bash
+OMNIBOT_SESSION_TOKEN=extract omnibot read --screens 5 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=extract omnibot assets list --tab-id <TAB_ID>
+```
+### Verification
+Verify extraction completeness with expected markers in `read`, element counts, or targeted reads for known selectors.
+### Fallback entry point
+If content exists only in runtime objects, use `fallback-operations.md#javascript-fallback` after explaining why `read`, `snapshot`, and `get` could not access it.
+## Upload
+### When to use
+Native upload is currently unavailable in the extension transport. Do not use `omnibot upload` as an agent workflow step until file chooser support is implemented.
+### Preferred sequence
+1. Observe the upload UI and confirm the task requires a local file.
+2. Report that native upload is currently unavailable.
+3. If the user still wants a workaround, ask for approval before using page-specific JavaScript or manual browser interaction.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
+# upload is currently unavailable; do not run omnibot upload here.
+```
+### Verification
+If upload support is implemented later, verify with visible filename, count, enabled submit state, or application-specific confirmation:
+```bash
+OMNIBOT_SESSION_TOKEN=form omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
+```
+### Fallback entry point
+Do not treat JavaScript as a normal upload fallback. File inputs and browser file chooser behavior are security-sensitive and page-specific.
+## Batch
+### When to use
+Use Batch for short, known-safe extension/CDP command chains where the target tab and verification are already explicit. Batch is not a wrapper for normal CLI commands such as `snapshot` or `click`.
+### Preferred sequence
+1. Keep batches short.
+2. Include only deterministic operations.
+3. Verify after the batch with a separate command.
+4. Use `--file` for complex JSON quoting.
+### Example
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"cdp","method":"Runtime.evaluate","params":{"expression":"document.title","returnByValue":true}}]' --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get title --tab-id <TAB_ID>
+```
+File example:
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+```
+### Verification
+Do not treat batch success as task success. Verify final page state separately.
+### Fallback entry point
+Batch is not a fallback tier. If a batched operation fails, re-run the workflow step-by-step and enter the normal fallback model.