> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Observation

> Observe page elements with smart filtering, incremental diffs, response tiers, and accessibility snapshots.

# Observation

Commands for understanding what is on the page before interacting.

## observe

AI-optimized page observation. Returns interactive elements with stable refs that you can pass to action commands.

<CodeGroup>
  ```bash Default (max 50 elements) theme={null}
  bap observe
  ```

  ```bash Full accessibility tree theme={null}
  bap observe --full
  ```

  ```bash Form fields only theme={null}
  bap observe --forms
  ```

  ```bash Navigation elements only theme={null}
  bap observe --navigation
  ```

  ```bash Limit elements theme={null}
  bap observe --max=20
  ```

  ```bash Incremental (changes only) theme={null}
  bap observe --diff
  ```

  ```bash Response tier theme={null}
  bap observe --tier=minimal
  ```
</CodeGroup>

### Flags

<ParamField path="--full" type="flag">
  Return the full accessibility tree instead of just interactive elements.
</ParamField>

<ParamField path="--forms" type="flag">
  Return only form-related elements (textboxes, selects, checkboxes, etc.).
</ParamField>

<ParamField path="--navigation" type="flag">
  Return only navigation elements (links, nav items).
</ParamField>

<ParamField path="--max" type="number" default="50">
  Maximum number of elements to return.
</ParamField>

<ParamField path="--diff" type="flag">
  Incremental observation. Returns only changes since the last observation: elements added, updated,
  or removed.
</ParamField>

<ParamField path="--tier" type="string" default="full">
  Response tier controlling how much data is returned.
</ParamField>

### Response Tiers

| Tier          | What is included                  | When to use                        |
| ------------- | --------------------------------- | ---------------------------------- |
| `full`        | All fields, metadata, screenshots | First page load, debugging         |
| `interactive` | Interactive elements, refs, roles | Most interactions                  |
| `minimal`     | Refs and names only               | Rapid polling, confirmation checks |

```bash theme={null}
bap observe --tier=interactive --max=20
```

### Incremental Observation

After performing an action, use `--diff` to see only what changed instead of re-scanning the entire page:

```bash theme={null}
bap act click:role:button:"Load More"
bap observe --diff
```

The response includes `changes: { added, updated, removed }` -- much smaller than a full observation.

<Tip>
  Use `--diff` after small DOM changes (button clicks, form submissions). Use a full `observe` after
  navigation to a new page.
</Tip>

## snapshot

Full YAML accessibility snapshot, compatible with playwright-cli.

<CodeGroup>
  ```bash Default (saves to .bap/) theme={null}
  bap snapshot
  ```

  ```bash Custom file path theme={null}
  bap snapshot --file=page-state.yml
  ```
</CodeGroup>

The snapshot includes the full accessibility tree in YAML format. Useful for debugging and for playwright-cli compatibility.

<Note>
  `bap observe` is preferred over `bap snapshot` for AI agents. It returns structured data with
  stable refs instead of raw YAML.
</Note>