> ## 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/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle_act

> Perform an action without checking the result. Useful for setup steps, and dangerous as a final step, because ok means dispatched, not worked.

`reticle_act` clicks, fills, types, selects, drags. It does exactly one thing and makes exactly one promise: the event was dispatched.

<Warning>
  `reticle_act` **proves nothing**. If the action is supposed to cause something, use
  [`reticle_act_and_wait`](/tools/act-and-wait) and get the verdict in the same call. A drive that
  ends on `reticle_act` has no result.
</Warning>

## Example

```json theme={"dark"}
{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
```

Real response:

```json theme={"dark"}
{
  "since": 27544,
  "inputMode": "synthetic",
  "inputModeReason": "not-a-pointer-action",
  "dispatched": true,
  "settled": true,
  "settleReason": null,
  "result": {
    "ok": true,
    "ref": "e104",
    "action": "fill",
    "dispatched": true,
    "settled": true,
    "settleReason": null,
    "testid": "login-password",
    "component": "Login",
    "role": "textbox",
    "name": "Password",
    "effect": {
      "focusMoved": "null->e104",
      "valueChanged": true,
      "domMutatedWithin": 9
    },
    "source": { "file": "src/components/Login.tsx", "line": 59, "column": 8 }
  }
}
```

<Note>
  The `effect` block only lists what is worth knowing. Fields sitting at their uninformative default
  are **omitted**, so a clean action collapses to its consequence. An absent `dispatched`,
  `targetMatched`, `visible` or `enabled` means `true`; an absent `occluded`, `scrolledIntoView`,
  `valueChanged` or `defaultPrevented` means `false`; an absent `focusMoved` or `occludedBy` means
  `null`. Do not read a missing field as a failure.
</Note>

## Actions

`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`

| Action           | Arguments                                                       |
| ---------------- | --------------------------------------------------------------- |
| `fill`, `select` | `{ value }`                                                     |
| `type`, `press`  | `{ text }`. For `press`, the key *name*, e.g. `Escape` or `Tab` |
| `drag`           | `{ toRef }`. The ref to drop onto                               |
| `upload`         | file arguments                                                  |

## Reading the effect block

This is where `act` earns its place even though it proves nothing.

* **`valueChanged: true`**. The field actually took the value. `false` on a `fill` usually means the input is controlled and rejected it, or it's readonly.
* **`focusMoved: "null->e104"`**, focus went where you expected.
* **`domMutatedWithin: 9`**, something re-rendered within 9ms. A `fill` that mutates nothing often means no handler is attached.
* **`defaultPrevented`**. A handler called `preventDefault()`, which is why your form didn't submit.
* **`occluded` / `occludedBy`**. The click landed on something else. This is the answer to at least half of all "the button doesn't work" reports.

## `settled: false` is not a failure

`settled: true` with `settleReason: null`, as above, means a real frame flushed before Reticle stopped watching. `settled: false` with `settleReason: "timeout"` means the page was still busy. On a `fill` that's normal and uninteresting. On a click you expected to complete something, it's a hint that you wanted `act_and_wait` with an explicit `until`. A settle timeout never fails the tool.

## `inputMode` tells you how real the input was

`synthetic` means Reticle dispatched events programmatically. `real` means native CDP input, available under `reticle drive`. Synthetic input is fine for the overwhelming majority of apps; a few drag-and-drop and pointer-gesture libraries only respond to the real thing.

`inputModeReason` explains any choice Reticle made on your behalf, so it is never silent. `not-a-pointer-action` above means a `fill` has no pointer path to take, not that real input was unavailable. Clicks default to the occlusion-honest synthetic path even when CDP is configured; pass `args.native: true` to force a trusted native click for file pickers and clipboard access.

<Warning>
  When the tab is backgrounded, synthetic timers and pointer gestures can silently no-op. Every
  response carries a `warning` when the tab is throttled. Pass `refuseWhenThrottled: true` to make
  Reticle throw instead of pretending it acted.
</Warning>