# 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 --same-tab https://example.com
OMNIBOT_SESSION_TOKEN=research omnibot open https://example.com
OMNIBOT_SESSION_TOKEN=research omnibot goto https://example.com
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

Use Upload when a browser form needs a local file attached through a file input.

### Preferred sequence

1. Observe the file input or upload control.
2. Use `upload` against the input selector.
3. Verify that the uploaded file appeared or form state changed.

### Example

```bash
OMNIBOT_SESSION_TOKEN=form omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=form omnibot upload "input[type=file]" /path/to/file.png --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=form omnibot wait --text "file.png" --tab-id <TAB_ID>
```

### Verification

Use 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

If upload input is hidden behind custom UI, click the semantic upload control first. Use JavaScript only after standard upload cannot reach the input.

## Batch

### When to use

Use Batch for short, known-safe command chains where the target tab and verification are already explicit.

### 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":"snapshot","interactive":true}]' --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --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.
