Agent cheat sheet

​

The core loop: look → act → observe → assert

Verdicts come from reticle_act_and_wait, reticle_assert, reticle_act { steps } when a step declares expect, and reticle_verify (change/flows). Everything else moves or reads the app and proves nothing. Only verified: "yes" is a pass: unknown means Reticle could not tell, and no-fault means nothing was declared to prove. A drive ending without a verdict has no result however many tools it used. reticle_act is the tool agents reach for by habit and it catches nothing; act_and_wait is where defects actually surface. Report unknown as unknown.

• reticle_act_and_wait({ ref, action }) with no until waits for the page to settle (settle: nothing new happening for a short quiet window, measured as network + structural DOM idle; ambient count-up/spinner churn is ignored so an animated page still settles) before returning: the one-call replacement for “click then sleep 500ms”.
• Need to wait without acting? reticle_assert({ action: "wait", predicate: { kind: "settled", quietMs } }).
• Waiting for a specific outcome? Pass that consequence as the predicate ({ signal } / { net }), or allOf it with { kind: "settled" } to wait for both the event and the page going quiet.

// A real assertion about the field's contents.
{ "kind": "element", "role": "textbox", "name": "GST amount", "value": "274.58" }

• You can assert what a field contains. Do not read the value with reticle_look { action: "find" } and compare it in prose: that produces no verdict and does not count as verification.
• { role, text } checks the text, so it does not match every button with that role.
• A text predicate reads rendered text, not a field’s value. Text typed into an <input> or a <textarea> is not on the page as text, so { kind: "text", contains } does not see it. Assert it with value on an element predicate, as above.

// WRONG: neither of these parses
{ "allOf": [ … ] }
{ "kind": "allOf", "allOf": [ … ] }

// RIGHT
{ "kind": "allOf", "predicates": [ … ] }
{ "kind": "anyOf", "predicates": [ … ] }
{ "kind": "not",   "predicate":  { … } }

{
  "kind": "allOf",
  "predicates": [
    { "kind": "signal", "name": "auth:granted" },
    { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
    { "kind": "console", "level": "error", "absent": true },
  ],
}
// -> evidence: [ { name: "auth:granted", … }, { matched: 1 }, { absent: true } ]

​

The 4-layer cross-check: never trust a green the state contradicts

Rule: a passing UI assert that the store, network, or signal contradicts is a false green.

Store reads (reticle_look { action: "state" }) are the reliable path; the DOM can lie (optimistic UI, stale render).

​

Core tool set

• reticle_verify: the tool that checks the whole app or the whole change in one call. { action:"crawl" } drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). { action:"flows" } replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers “here is more to look at”.

​

flows vs baselines vs project.json (the persistence layers)

reticle_project / project.json are the run-history layer. flows answer “does the journey still work?”; baselines answer “did the structure change?”; project.json answers “is this run consistent with prior runs?”.

​

Fields worth reading that you may not know are there

​

Start here

1. First move, always: reticle_session { action: "list" } finds the connected tab. Just ran reticle init or restarted the dev server? You do not need to poll: live tools wait briefly for a tab that is about to connect. Omit sessionId if there’s only one tab. An empty list is not a dead end: read why. It names the case (no app running, an app that never dialled this daemon, a project that is not wired, or a tab that closed) and the fix for each. In a project that is not wired, next_step also names the next calls. lease (present when an app is running) is the zero-install check of the running app: do it first, because it changes no file. consent is the question for init, which changes package.json, the lockfile and the build config: ask the user, and run init only if they agree. Do not fall back to static reasoning until you have read why.
2. reticle_run({ tool: "reticle_domain", args: {} }) learns the app BEFORE testing: the saved flows, what each asserts, and the gaps (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to reticle_run({ tool: "reticle_capabilities", args: {} }) for the raw testable surface (testids, signals, stores, flows).
3. Run the loop: look → act → observe → assert, cross-checking the 4 layers on anything that matters.

​

No MCP tools in this host

npx @reticlehq/server serve --headless
npx @reticlehq/server verify http://localhost:5173/ --expect '{"kind":"text","contains":"Welcome"}'

​

Token note

• Keep observation cheap. Prefer reticle_look { action: "find" } / scoped or interactive reticle_look { action: "page" } / reticle_assert over dumping the full tree. A full verify loop is ~100 tokens; see Token efficiency (~73× leaner than full-tree snapshots).
• Re-look with reticle_look({ action: "page", diff:true }) after an action; it returns only what changed (mode:delta/unchanged), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries cost:{ bytes, tokens }, so re-scope before reading if it’s large.
• Cap broad reads. reticle_look { action: "find" } takes limit (caps descriptors; reports total/truncated) and count_only (just the match count). reticle_observe { action: "network" } / reticle_observe { action: "console" } take limit (most-recent-N, reports droppedOldest) and carry the same cost hint, so a busy page or wide window never floods your context unnoticed.
• A saved flow tells you if it’s a real test. reticle_flow_save returns assertions.grade (asserted / presence-only / assertion-free); if it’s not asserted, add a consequence (reticle_annotate assert-signal/assert-net or a success-state) so it can’t pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an apply heal re-replays the rebound flow and refuses to write if the success consequence no longer fires (status:consequence_broken): it heals the locator, never the intent.
• Predicate schema is not bloated. The recursive predicate DSL used by reticle_assert / reticle_assert { action: "wait" } / reticle_act_and_wait is defined once (PredicateSchema in @reticlehq/core) and shared by all three tools. No action needed.
• One tool surface, and a hatch behind it. Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus reticle_tools and reticle_run. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the tool that checks the whole app in one call, reached by an action argument rather than by a name each. reticle_tools discovers: no args lists every registered tool name and summary, names:[…] loads full params on demand. reticle_run { tool, args } then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with RETICLE_ADVERTISE_ALL_TOOLS=1 (read at startup, so restart it) advertises a wider set outright (the default tools plus the extra ones listed above), with output schemas, under the unmerged names listed above. It is not the whole registry: the count is capped because editors budget tools across every connected MCP server. reticle_verify is advertised: { action:"flows" } replays every saved flow with no model in the loop, and { action:"crawl" } drives every reachable control itself and reports the whole fault set in one call. Sizes are deliberately not quoted here. A count in prose goes stale, and has three times already. reticle_tools reports the live surface, and SKILL.md carries the one gated table.