# AI Upgrade visual-check insertion guide

Use this reference only after `carbon-runtime ai-upgrade inspect` finds existing browser automation and the user approves local model-powered screenshot checks.

## Placement

Good checkpoints have a stable, meaningful visible oracle:

- the first fully loaded application state after navigation and deterministic readiness;
- a critical validation or permission error;
- a completed account, checkout, receipt, dashboard, onboarding, or settings state;
- a responsive/mobile state whose layout is itself under test;
- an existing screenshot already captured for failure or evidence.

Skip intermediate clicks, spinners expected to be transient, duplicate states, API-only tests, and screens likely to expose passwords, payment details, private customer data, health data, tokens, or secrets.

One check per distinct risk state is enough. More checks increase cost, latency, and non-deterministic noise without improving the test.

## Adapter shape

Create one suite-local adapter, then call it from tests. The adapter must:

1. capture a deterministic filename under the suite's existing artifact directory;
2. invoke `.carbon/upgrade/ai-visual-check.py` without a shell;
3. pass `--image`, a stable `--name`, and a narrow `--focus` describing only the visible risk;
4. retain the emitted `.carbon-ai.json` as evidence;
5. surface exit `1` as an AI visual failure, exit `2` as blocked only when `onError=fail`, and otherwise record a warning;
6. never log or persist the provider key.

For JavaScript/TypeScript, use `child_process.execFile` or `spawn` with an argument array. For Python, use `subprocess.run([...], check=False)`. For Java, .NET, or Ruby, use the equivalent no-shell process API. Reuse the framework's own screenshot API and artifact attachment mechanism.

## Review focus

Keep prompts narrow and visible, for example:

- `The checkout success state should be complete, readable, and free of overlap, clipping, raw errors, or stuck loading.`
- `At 390 px width, navigation and the primary action must remain visible without horizontal clipping.`
- `The permission-denied state should be intentionally styled, legible, and contain no debug output.`

Do not ask the model to verify backend state, database writes, prices not visible in the image, authorization correctness, keyboard behavior, semantic accessibility, or API results. Those require deterministic or other evidence.

## Verdict policy

The project helper returns `carbon.ai-visual-check/v1` with screenshot-only provenance. Defaults are:

- `failOn: critical` — only a model `fail` with critical visible severity fails the test;
- `onError: warn` — provider outage, quota, invalid response, or timeout remains visible but does not turn into a false product failure;
- subjective preferences and low-confidence observations are warnings;
- deterministic test failures remain authoritative and must never be overruled by an AI pass.

Teams may tighten the threshold only after reviewing real false-positive and false-negative evidence across repeated runs.
