# Debugging and Evidence

Debugging is for evidence. Fallback is for completing operations.

Use this file when you need to prove browser state, explain a failure, or collect artifacts for review. Do not use `execute-js` as the first debug tool.

## Screenshot

Use screenshots when visual layout, canvas, dialogs, or visual regressions matter.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot screenshot --tab-id <TAB_ID> -o /tmp/omni-shot.png
OMNIBOT_SESSION_TOKEN=debug omnibot screenshot --annotate --tab-id <TAB_ID> -o /tmp/omni-annotated.png
```

Prefer text extraction when text is enough. Screenshot is evidence, not extraction.

## Console

Use console logs for runtime JavaScript errors, frontend warnings, or app-level diagnostics.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot console errors --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot console logs --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot console clear --tab-id <TAB_ID>
```

Collect console errors before and after the action when debugging regressions.

## Network

Use network logs for failed requests, redirects, blocked assets, API errors, or loading stalls.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot network summary --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot network logs --tab-id <TAB_ID>
```

Pair network evidence with page verification:

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot get text "#main" --tab-id <TAB_ID>
```

## Trace

Use trace for a reproducible artifact around a failing workflow.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot trace start
OMNIBOT_SESSION_TOKEN=debug omnibot click --tab-id <TAB_ID> @e4
OMNIBOT_SESSION_TOKEN=debug omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot trace stop -o trace.zip
```

Trace is evidence. It does not replace operation verification.

## Record and Replay

Use record/replay when a flow must be captured or reproduced.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot record start
OMNIBOT_SESSION_TOKEN=debug omnibot click --tab-id <TAB_ID> @e4
OMNIBOT_SESSION_TOKEN=debug omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot record stop -o flow.json
OMNIBOT_SESSION_TOKEN=debug omnibot replay flow.json
```

After replay, verify final state:

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot get url --tab-id <TAB_ID>
```

## CDP Inspection

Use CDP for low-level inspection when normal evidence is insufficient.

```bash
OMNIBOT_SESSION_TOKEN=debug omnibot cdp Runtime.evaluate '{"expression":"document.title"}' --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=debug omnibot cdp DOM.getDocument '{"depth":1}' --tab-id <TAB_ID>
```

CDP inspection is not a first-choice operation path. If CDP changes state, it becomes Tier 7 fallback and must follow `fallback-operations.md#raw-cdp-fallback`.

## Evidence Checklist

Before reporting a browser issue, collect the smallest evidence set that explains it:

- Runtime: `doctor`, `tabs`, `visibility status`.
- Page state: `get`, `is`, `snapshot`, or `wait`.
- Visual proof: `screenshot --annotate` only if visual state matters.
- Browser diagnostics: `console errors` and `network summary`.
- Reproduction artifact: `trace` or `record` when the flow is unstable.
