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

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# Action reference

> Every action reticle_act and reticle_act_and_wait can perform, with its arguments and the one that has a history.

```json theme={"dark"}
{ "ref": "e42", "action": "fill", "args": { "value": "hello" } }
```

| Action               | Arguments                   | Notes                                                                |
| -------------------- | --------------------------- | -------------------------------------------------------------------- |
| `click` / `dblclick` | none                        | Dispatches a real click                                              |
| `hover`              | none                        | `mouseover` + `mouseenter`, so JS hover state triggers               |
| `focus` / `blur`     | none                        |                                                                      |
| `fill`               | `{ value }`                 | Sets value via a React-safe native setter, then `input` and `change` |
| `type`               | `{ text }`                  | **Appends** to the current value                                     |
| `clear`              | none                        | Empties an input                                                     |
| `select`             | `{ value }`                 | For `<select>`                                                       |
| `check` / `uncheck`  | none                        | Checkbox and radio                                                   |
| `submit`             | none                        | Submits the element's `<form>`                                       |
| `press`              | `{ text }`                  | The key **name**: `Escape`, `Tab`, `Enter`                           |
| `scrollIntoView`     | none                        |                                                                      |
| `upload`             | `{ name, content?, type? }` | Sets a file on `<input type="file">`                                 |
| `drag`               | `{ toRef }`                 | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD     |
| `webmcp`             | `{ tool, params }`          | Calls a `navigator.modelContext` tool, if the site exposes one       |

## `fill` versus `type`

`fill` replaces. `type` appends. Reaching for `type` when you meant `fill` is how a field ends up containing `hellohello`, and neither call will complain.

## `press` takes `text`, not `key`

Both are accepted today, and `text` wins when both are present. Use `text`. It is what the tool description documents.

<Warning>
  This one has history worth knowing. The implementation used to read `args.key` and **default to
  `Enter`**, so the documented call, `{ action: "press", args: { text: "Escape" } }`, silently sent
  `Enter` and reported success.

  Three consequences, worst last: the requested key never arrived, so Escape-to-close and Tab-traversal went unverified while looking verified; nothing in the result said the argument had been ignored; and `Enter` is not a neutral substitute. On a focused field inside a form it **submits it**. A request to close a dialog could file the form behind it.

  Two field reports were exactly this, both diagnosed as "synthetic events don't reach the app". Wrong root cause: the event reached the app perfectly well and simply said `Enter`.
</Warning>

That bug is fixed, and the reason it is written down here is that it is the exact shape of failure Reticle exists to catch. An action that reports success while doing something else.

## Batching

Several actions in one round trip:

```json theme={"dark"}
{
  "steps": [
    { "ref": "e101", "action": "fill", "args": { "value": "admin@reticle.dev" } },
    { "ref": "e102", "action": "fill", "args": { "value": "hunter2" } },
    { "ref": "e103", "action": "click" }
  ]
}
```

<Warning>
  [`reticle_act_sequence`](/tools-act-sequence) returns `ok: true` when the steps were
  **dispatched**, not when they worked. Batch the setup, then prove the outcome with
  [`reticle_act_and_wait`](/tools-act-and-wait) on the final step.
</Warning>

## Real versus synthetic input

`inputMode` in the response says which you got. `synthetic` means events dispatched programmatically. Correct for the overwhelming majority of apps. `real` means native CDP input, available under `reticle drive`, and needed by a few drag-and-drop and pointer-gesture libraries.

<Warning>
  On a throttled tab, synthetic timers and pointer gestures can silently no-op. Pass
  `refuseWhenThrottled: true` to fail loudly instead of acting into a tab the browser has paused.
</Warning>

## What every action reports

`valueChanged`, `focusMoved`, `domMutatedWithin`, `defaultPrevented`, `occluded` and `occludedBy`. Plus the element's `testid`, `component` and `source` file and line.

`occluded` is the answer to a large share of "the button doesn't work" reports: the click landed on the modal overlay sitting on top of it.

<Card title="Full field-by-field walkthrough" icon="hand-pointer" href="/tools-act">
  What each effect field tells you, with a real response.
</Card>