@reticlehq/server 2.7.0 → 2.9.0

package/docs/vs-chrome-devtools-mcp.mdx

@@ -0,0 +1,123 @@
+---
+title: Reticle vs Chrome DevTools MCP
+description: Chrome DevTools MCP is slightly cheaper per look. Reticle caught every bug it missed. Here is the trade, measured.
+icon: chrome
+---
+
+**Short answer:** Chrome DevTools MCP is a few percent cheaper per observation. It also caught 8 of 10 bugs where Reticle caught 10. If your tool is cheap because it looks at less, the savings are not savings.
+
+## The measurement
+
+Same app, same bugs, same moment:
+
+|                         | Reticle   | Chrome DevTools MCP |
+| ----------------------- | --------- | ------------------- |
+| Bugs caught (of 10)     | **10**    | 8                   |
+| Detection accuracy      | **1.00**  | 0.82                |
+| Avg tokens per look     | 815       | **758**             |
+| Verification efficiency | **12.27** | 10.55               |
+
+DevTools MCP genuinely wins the cost column. We are not going to bury that. 758 against 815 is a real 7% advantage per observation, and if you are making a very large number of trivial looks it adds up.
+
+But cost per look is only half a metric. Verification efficiency combines both. Regressions caught per 1,000 tokens spent, gated on catching **all** of them with zero false alarms on a known-good control. On that measure Reticle leads 12.27 to 10.55.
+
+<Card title="Why efficiency is gated on the catch rate" icon="chart-column" href="/benchmarks">
+  A tool can look cheap by not looking. The floor exists to stop that counting as a win.
+</Card>
+
+On a real production dashboard, one observation:
+
+|                     | Snapshot | Network | Total     |
+| ------------------- | -------- | ------- | --------- |
+| Reticle             | 678      | 345     | **1,023** |
+| Chrome DevTools MCP | 1,105    | 252     | 1,357     |
+
+Note the flip. DevTools is cheaper on a small page and more expensive on a large one. Its snapshot is 1,105 tokens against Reticle's 678. The cost advantage does not survive contact with a real app.
+
+## What DevTools MCP does better
+
+- **Cheaper on simple pages**, as above.
+- **It is Chrome's own tooling**, which means the performance and tracing surface is deep and authoritative in a way third-party instrumentation is not.
+- **Nothing to install in your app.** No SDK, no plugin, no build-time step. If instrumenting is off the table, this matters a lot.
+- **Real pixels.** Actual rendered frames, with everything that implies.
+
+## The two bugs
+
+DevTools MCP is DOM-and-network only. It can describe what a page looks like and what it requested; it cannot ask the application what it believes.
+
+That is why the misses cluster where they do. The scenarios that separate the tools are the ones where the page is fine and the program is not. A mutation that never reached the store, a success handler that fired for the wrong reason. There is nothing in the DOM or the network log that distinguishes those from working code.
+
+Reticle can require the app's own signal:
+
+```json
+{ "ref": "e5", "action": "click", "until": { "kind": "signal", "name": "deploy:created" } }
+```
+
+That predicate cannot be satisfied by a `200`, by a rendered row, or by a hopeful agent. Either the app declared success or it did not.
+
+## The other difference: where to fix it
+
+DevTools MCP can tell you a request failed. Reticle tells you a request failed **and** that the button which sent it lives at `src/components/Login.tsx:81`.
+
+For a human, that is a convenience. For an agent, it is most of the value. Finding the bug is half the job, and the other half is knowing which file to open.
+
+## They compose
+
+Neither tool forbids the other. A reasonable setup:
+
+- **DevTools MCP** for performance traces, deep Chrome internals, and real screenshots.
+- **Reticle** for the verify loop: did the change work, and where do I fix it.
+
+## Choosing
+
+<CardGroup cols={2}>
+  <Card title="Pick Chrome DevTools MCP" icon="gauge">
+    You cannot instrument the app, you are chasing a performance or rendering problem, or you need
+    Chrome's own tracing.
+  </Card>
+  <Card title="Pick Reticle" icon="crosshairs">
+    You own the app and the failures you care about are the non-visual ones, mock data, dead
+    handlers, double submits, silent validation.
+  </Card>
+</CardGroup>
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Which two bugs did Chrome DevTools MCP miss?">
+  The ones where the page is fine and the program is not: a mutation that never reached the store,
+  and a success handler that fired for the wrong reason. DevTools MCP is DOM-and-network only, so it
+  can describe what the page looks like and what it requested, but it cannot ask the application
+  what it believes. There is nothing in the DOM or the network log that separates those cases from
+  working code.
+</Accordion>
+
+<Accordion title="If DevTools MCP is cheaper, why not just use it?">
+  Because it is cheaper partly by looking at less. Cost per look is half a metric; the other half is
+  whether the look catches the bug. Verification Efficiency combines them and gates on catching
+  every bug with zero false alarms, and on that measure Reticle leads 12.27 to 10.55. The 7%
+  per-look advantage also inverts on a real app: on the production dashboard measured here DevTools'
+  snapshot was 1,105 tokens against Reticle's 678.
+</Accordion>
+
+<Accordion title="Can I run both MCP servers at once?">
+  Yes. They are independent servers with distinct tool names. A reasonable split is DevTools MCP for
+  performance traces, deep Chrome internals and real screenshots, and Reticle for the verify loop
+  and the source pointer.
+</Accordion>
+
+<Accordion title="Do I have to instrument my app to use Reticle?">
+  You have to add the dev-only SDK, which is what `npx @reticlehq/server init` does. Beyond that,
+  look, act and observe work with zero component changes. Signals and registered stores are
+  optional, and they are what buys the assertions DevTools MCP structurally cannot make. If
+  instrumenting is off the table entirely, DevTools MCP is the correct choice.
+</Accordion>
+
+<Accordion title="Does Reticle give me performance traces?">
+  Not in the way Chrome's own tooling does, and it does not pretend to. It can tell you a React
+  render storm is happening (commit rate climbing with no DOM mutation), which DevTools MCP does not
+  surface. For flame charts and deep tracing, use Chrome's.
+</Accordion>
+
+</AccordionGroup>

package/docs/vs-playwright-mcp.mdx

@@ -0,0 +1,125 @@
+---
+title: 'Reticle vs Playwright MCP: outside in, inside out'
+sidebarTitle: vs Playwright MCP
+description: Playwright MCP drives any website from the outside. Reticle verifies an app you own from the inside. They solve different problems, and they compose.
+icon: masks-theater
+---
+
+**Short answer:** if you need to drive a website you do not control, use Playwright MCP. If you need to prove that a change to _your_ app actually worked, use Reticle. They are not really competitors, and the best setup often runs both.
+
+## The one-line difference
+
+Playwright MCP drives a browser **from the outside**. Reticle runs **inside** your app.
+
+That single architectural choice explains every difference below. An outside-in tool can go anywhere and see anything rendered. An inside-out tool needs to be installed, and in exchange it can read things that were never rendered at all. Application state, emitted signals, the exact requests that fired.
+
+## Measured, on the same app at the same moment
+
+|                         | Reticle   | Playwright MCP |
+| ----------------------- | --------- | -------------- |
+| Bugs caught (of 10)     | **10**    | 9              |
+| Detection accuracy      | **1.00**  | 0.91           |
+| Avg tokens per look     | **815**   | 1,292          |
+| Verification efficiency | **12.27** | 6.97           |
+
+On a real production dashboard, observing once:
+
+|                | Snapshot | Network | Total     |
+| -------------- | -------- | ------- | --------- |
+| Reticle        | 678      | 345     | **1,023** |
+| Playwright MCP | 1,522    | 671     | 2,193     |
+
+Reticle is about 2.1x leaner on a large page. The gap comes from what each tool sends: Playwright MCP returns the accessibility tree, and on a complex app that tree is enormous. Reticle asks narrower questions: `mode: "interactive"` returns only controls, `count_only` returns a number.
+
+<Card title="How these were measured" icon="chart-column" href="/benchmarks">
+  The method, the scenarios, and the control where a false positive would count against us.
+</Card>
+
+## What Playwright MCP does better
+
+This is not a courtesy section. There are real cases where Playwright is the correct choice and Reticle is not.
+
+- **Sites you do not own.** Reticle needs a dev-only SDK in the app. No SDK, no Reticle. Playwright drives anything with a URL, which is the entire point of it.
+- **Cross-browser.** Firefox and WebKit are first-class in Playwright. Reticle's real-input and screenshot paths are Chromium-oriented.
+- **True pixels.** A screenshot is the actual rendered frame. A font that failed to load or a compositing glitch shows up there and can be missed by structural reads.
+- **Maturity and ecosystem.** Playwright is a large, battle-tested project with an enormous community. We are not going to pretend otherwise.
+
+## What Reticle does that Playwright cannot
+
+- **Assert on the app's own success signal.** When your app emits `auth:granted`, Reticle can require that exact signal. Playwright can check that a DOM element appeared, which a mock also does.
+- **Read application state.** `stateDiffs` shows `auth` moving from `null` to a real user. A POST that returns `200` without touching state is caught here and nowhere else.
+- **Map a DOM node to source.** `src/components/Login.tsx:81`, via the React fiber tree. Playwright can tell you the selector; it cannot tell you the file.
+- **Grade its own evidence.** Every verdict reports `honesty.grade`: `presence`, `state`, `net` or `signal`, weakest to strongest. Plus whether the capture was clean and complete.
+- **Say "unknown".** Reticle distinguishes "did not happen" from "I could not tell". That third state is the difference between a check and a coin flip.
+
+## The false-green case
+
+Here is the failure both tools face, and only one catches reliably.
+
+Your agent adds a "save" button. It calls an API. The API returns `200`. A row appears in the table. Reload the page and the row is gone, nothing was ever persisted.
+
+Playwright MCP sees the row appear. That is a pass by every DOM-based check you could write.
+
+Reticle sees `stateDiffs: []`. The store never changed. And fails the assertion, with the file and line of the button that lied.
+
+## Use both
+
+They compose cleanly, and the combination is better than either alone:
+
+- **Drive with Playwright** when you need a browser context it is better at. A third-party OAuth flow, a cross-browser check, a genuine pixel diff.
+- **Assert with Reticle** when the question is "did my app actually do the thing".
+
+Reticle also has a driven mode (`reticle drive`) that provides real CDP input and screenshots, so a lot of teams do not need both. Start with whichever matches the question you ask most often.
+
+## Choosing
+
+<CardGroup cols={2}>
+  <Card title="Pick Playwright MCP" icon="globe">
+    You are testing a site you do not own, you need Firefox or WebKit, or you need real pixel
+    comparison as the primary signal.
+  </Card>
+  <Card title="Pick Reticle" icon="crosshairs">
+    You own the app, an agent is editing it, and you want proof it worked rather than a screenshot
+    that looks fine.
+  </Card>
+</CardGroup>
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Can I use Reticle and Playwright MCP at the same time?">
+  Yes, and it is a common setup. They are separate MCP servers with separate tool namespaces, so
+  nothing collides. Drive with Playwright where it is stronger (a third-party OAuth hop, a
+  cross-browser pass, a genuine pixel diff) and assert with Reticle where the question is "did my
+  app actually do the thing".
+</Accordion>
+
+<Accordion title="Does Reticle work on a site I do not own?">
+  No. Reticle reads the program from inside the page, which requires a dev-only SDK in the app. No
+  SDK, no Reticle. That is the single hardest boundary between these two tools, and it is why
+  Playwright MCP is the right answer for anything you cannot instrument.
+</Accordion>
+
+<Accordion title="Is Reticle actually cheaper, or only on the pages you chose?">
+  On a full-tree-vs-full-tree comparison the gap is modest, roughly 1.8x. The large gap comes from
+  not needing the full tree: Playwright MCP's primary perception primitive returns the accessibility
+  tree, Reticle's answers a specific question. On a small page both are cheap. On the real
+  production dashboard measured here Reticle was about 2.1x leaner. Force Reticle to dump the whole
+  page every step and you save very little.
+</Accordion>
+
+<Accordion title="Does Reticle support Firefox or WebKit?">
+  Not meaningfully. The always-on in-page SDK is browser-agnostic, but the driven paths that provide
+  real pointer input and screenshots go through CDP and are Chromium-oriented. If cross-browser is a
+  requirement, that is a Playwright job.
+</Accordion>
+
+<Accordion title="Do I have to give up my existing Playwright suite?">
+  No, and you should not. A scripted Playwright or Cypress suite is what gates your releases.
+  Reticle is the in-loop check while an agent is coding and the safety net for the flows nobody ever
+  got round to automating. Your existing `data-testid` attributes work in Reticle unchanged, so the
+  two share the same anchors.
+</Accordion>
+
+</AccordionGroup>

package/docs/vs-screenshots.mdx

@@ -0,0 +1,137 @@
+---
+title: 'Screenshots lie: why pixels cannot verify AI-generated code'
+sidebarTitle: vs screenshots
+description: The failures that AI coding agents actually produce are invisible in a rendered frame. Here is why a better vision model does not fix that.
+icon: image
+---
+
+**Short answer:** the information is not in the picture. Whether a request fired, what it returned, whether state changed, whether one click sent two requests. None of that is visible in a rendered frame, at any resolution, to any model.
+
+## The four failures a screenshot approves
+
+<CardGroup cols={2}>
+  <Card title="Mock data" icon="ghost">
+    POST returns `200`, the row appears, nothing persisted. Reload and it's gone. The screenshot
+    during the demo is perfect.
+  </Card>
+  <Card title="Dead handler" icon="plug-circle-xmark">
+    Button has an `onClick`, the `onClick` calls a function, the function was never wired to the
+    store. Looks connected all the way down.
+  </Card>
+  <Card title="Double submit" icon="clone">
+    One click, two POSTs, customer charged twice. Zero pixels differ.
+  </Card>
+  <Card title="Silent validation" icon="triangle-exclamation">
+    The form accepts `"abc"` as a quantity and sends it to your database. Renders beautifully.
+  </Card>
+</CardGroup>
+
+Every one of these renders as a correct-looking page. Ask a vision model whether the feature works and it will say yes, because the only evidence available says yes.
+
+## "Just use a better model"
+
+This is the intuition worth killing, because it sounds reasonable and costs teams months.
+
+Model quality is not the constraint. **You cannot see a network call.** You cannot photograph a state mutation. A screenshot of a page whose bug is non-visual contains no signal about that bug, so asking a stronger model to look harder produces a more confident version of the same wrong answer.
+
+Improving the model improves the reading of the evidence. It does not create evidence that was never captured.
+
+## What "reading the program" means instead
+
+Reticle runs inside the app and reads what actually happened:
+
+```json
+{
+  "verified": "yes",
+  "verdict": {
+    "evidence": { "method": "POST", "url": "/api/login", "status": 200, "durationMs": 67 }
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 0 },
+    "consoleErrors": 0,
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
+    "signals": ["auth:granted"]
+  }
+}
+```
+
+Read what that rules out. `net.total: 1` kills double-submit. `stateDiffs` kills mock data, the store genuinely changed. `signals` is the app declaring success in its own words. `consoleErrors: 0` kills "it worked but threw".
+
+No pixel in the world carries that.
+
+## A real one, caught on the first run
+
+On the first drive of a real production dashboard, before any instrumentation, Reticle's network observation flagged two endpoints returning `500`. A database migration that had not been applied.
+
+**The page rendered fine.** The sidebar loaded. Nothing looked broken. A screenshot agent would have called it done and moved on.
+
+That is the thesis in one incident: "looks done" and "is done" are different properties, and the difference is usually non-visual.
+
+## When a screenshot is the right tool
+
+Screenshots are not useless. They are the correct instrument for a specific class of bug, and this page would be dishonest without saying so:
+
+- A font that failed to load
+- A GPU or compositing glitch
+- Layout that breaks only at a particular viewport
+- Anything where the actual rendered frame _is_ the thing under test
+
+Those are real bugs and structural reads can miss them. Reticle has `reticle_screenshot` and `reticle_visual_diff` for exactly this, and if pixel regression is your primary concern, a dedicated visual tool will serve you better.
+
+The argument is not "screenshots are bad". It is that a screenshot cannot answer "did the code work", and that is the question an AI coding agent needs answered on every change.
+
+## The honest limits
+
+We have not proven that Reticle makes agents _fix_ more bugs. A controlled test did not show a fix-rate improvement; the benchmark was confounded and we are still working on measuring it properly.
+
+What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives.
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="Would a better vision model fix this?">
+  No, and this is the single most expensive misconception on the page. Model quality improves the
+  _reading_ of evidence; it cannot create evidence that was never captured. A screenshot of a page
+  whose bug is non-visual contains no signal about that bug at any resolution, so a stronger model
+  produces a more confident version of the same wrong answer.
+</Accordion>
+
+<Accordion title="So screenshots are useless?">
+  No. They are the correct instrument for a specific class of bug: a font that failed to load, a GPU
+  or compositing glitch, layout that breaks only at one viewport, and anything where the rendered
+  frame _is_ the thing under test. Reticle ships `reticle_screenshot` and `reticle_visual_diff` for
+  exactly those. If pixel regression is your primary concern, a dedicated visual tool will serve you
+  better.
+</Accordion>
+
+<Accordion title="What does Reticle read instead of pixels?">
+  The program: the network log (did the request fire, how many times, what did it return), the
+  console, client-side routing, registered store state, and any signal the app itself emits. A
+  response carrying `net.total: 1` rules out a double submit; a non-empty `stateDiffs` rules out
+  mock data; `consoleErrors: 0` rules out "it worked but threw".
+</Accordion>
+
+<Accordion title="Does that mean Reticle catches every bug?">
+  No. It has not been shown to make agents _fix_ more bugs; a controlled fix-rate test did not show
+  an improvement and we consider that question open. What is measured is detection: 10 of 10
+  injected regressions caught with zero false alarms, against 9 and 8 for the alternatives. And a
+  purely visual regression still needs the opt-in visual diff.
+</Accordion>
+
+<Accordion title="Can I keep using screenshots alongside Reticle?">
+  Yes, and for a visual product you probably should. The argument here is not that screenshots are
+  bad, it is that a screenshot cannot answer "did the code work", which is the question an AI coding
+  agent needs answered on every change.
+</Accordion>
+
+</AccordionGroup>
+
+<CardGroup cols={2}>
+  <Card title="See a real verdict" icon="rocket" href="/quickstart">
+    Five minutes, and the output on that page was captured live.
+  </Card>
+  <Card title="The full benchmark" icon="chart-column" href="/benchmarks">
+    Method, raw numbers, and where Reticle comes second.
+  </Card>
+</CardGroup>

package/docs/what-is-reticle.mdx

@@ -0,0 +1,63 @@
+---
+title: What is Reticle?
+sidebarTitle: What is Reticle
+description: Reticle is a verification layer for AI coding agents. It runs a dev-only SDK inside your running web app so an agent can prove a change works, instead of guessing. What it is, what it is not, and what it needs.
+icon: circle-question
+---
+
+**Reticle is a verification layer for AI coding agents.** It embeds a dev-only SDK inside your running web application and exposes what that application is actually doing, its DOM, network calls, routing, console, and framework state, as structured tools an agent can call over MCP. The agent names the consequence it expects, performs an action, and gets back a verdict: pass, fail, or an honest "couldn't tell", with the evidence and the `file:line` to open.
+
+It exists because an agent that writes code cannot otherwise tell whether that code works. Reading the diff proves nothing. Unit tests do not run the application. A screenshot shows a page that renders perfectly over a failed request.
+
+## How it works, in three parts
+
+1. **An SDK inside the app.** Dev-only, stripped from production builds, added by a build plugin. It instruments the DOM, network, routing, console, animations, and your state library.
+2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine. The daemon never starts or manages your dev server. It attaches to the app that is running. If none is, the agent is the one told to start it, using your project's own dev script, in the background, and saying so.
+3. **An MCP server.** The daemon exposes the app to your agent as tools. `reticle_snapshot` to look, `reticle_act_and_wait` to act and prove in one call, `reticle_state` and `reticle_network` to observe, `reticle_assert` to check.
+
+Everything stays on your machine. No application code, DOM, network traffic, or console output leaves it.
+
+## What Reticle is not
+
+This is the section most people need, because Reticle sits next to several familiar categories without being any of them.
+
+**Not a browser automation framework.** Playwright, Cypress and Selenium drive a browser from the outside and are excellent at it. Reticle runs inside the page you already have open. If you want to script a browser, use Playwright. Reticle is what an agent uses to answer "did the thing I just changed actually work?"
+
+**Not a replacement for your test suite.** Unit and integration tests still do their job. Reticle covers the layer they structurally cannot reach: behaviour that only exists when the whole application runs. Many teams use both, and Reticle is often the thing that catches a suite passing over a broken app.
+
+**Not a screenshot or visual regression tool.** It can take screenshots, but the point is that it does not need to. Verdicts come from predicates over real events, a request with a status, a state path, a signal your code fired, so they do not break when a button moves four pixels. If pixel-perfect visual diffing is your goal, a dedicated visual testing service fits better.
+
+**Not a monitoring or observability product.** Reticle is a development-time tool aimed at localhost. It is not an APM, not error tracking, and it does not watch production.
+
+**Not an accessibility auditor.** `reticle_snapshot` addresses elements by role and name, which is not the same as auditing contrast, focus order, or screen reader behaviour. Use a dedicated accessibility tool for that.
+
+**Not an AI model, and not an agent.** Reticle has no model of its own and makes no decisions. It gives an agent you already use a way to see the running app. Your agent, your model, your keys.
+
+**Not a hosted service that receives your application data.** The daemon runs on your machine and the SDK runs in your browser. Anonymous product analytics are sent unless you opt out, and they never include your code or your application's data. See the [Telemetry Policy](https://www.reticle.sh/legal/telemetry).
+
+**Not a way to make a failing check pass.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass, because a verification tool that flatters you is worse than none.
+
+## What Reticle needs
+
+Honest constraints, so you can tell in a minute whether it fits:
+
+- **A web application you can run locally**, with its dev server. Reticle attaches; it does not start one.
+- **A build step it can hook**, or two lines added by hand. Vite, Next.js, Remix and Astro are proven by gates in the repository. The SDK is framework agnostic and usually connects elsewhere, with reduced source mapping.
+- **An agent that speaks MCP.** Claude Code, Cursor, Codex, Copilot, Windsurf, OpenCode and others.
+- **Node 20 or newer.**
+
+Electron and Tauri desktop applications are supported, including the IPC boundary a browser-based tool cannot observe at all.
+
+## How it compares
+
+Side by side with the tools people ask about most:
+
+- [Reticle vs Playwright MCP](/vs-playwright-mcp)
+- [Reticle vs Chrome DevTools MCP](/vs-chrome-devtools-mcp)
+- [Reticle vs screenshots](/vs-screenshots)
+
+## Where to go next
+
+- [Quickstart](/quickstart) gets a real verdict out of your own app in about five minutes.
+- [Why Reticle](/why-reticle) is the argument, with the evidence and the cases where it loses.
+- [For agents](/for-agents) is written for the agent rather than for you.

package/docs/why-reticle.mdx

@@ -0,0 +1,109 @@
+---
+title: 'Why Reticle: seeing is not believing'
+sidebarTitle: Why Reticle
+description: AI-written code fails by looking correct. Reticle reads the running program instead of the pixels, so a silent failure stops being invisible.
+icon: lightbulb
+---
+
+**Use Reticle because AI-written code fails by looking correct.** A screenshot cannot show you whether a request fired, what status it returned, whether application state changed, or whether one click sent one request or two. Reticle reads the running program instead of the pixels, so those silent failures stop being invisible.
+
+Software has always had bugs. What changed is the _kind_ of bug that reaches you.
+
+A human writing code by hand produces errors that announce themselves: a stack trace, a red screen, a test that goes red. An agent writing code produces something more dangerous: a change that looks completely correct, renders beautifully, and does nothing. The page is fine. The data never saved.
+
+We call it a **false green**, and it is the defining failure mode of the AI-coding era.
+
+## What a false green actually looks like
+
+<CardGroup cols={2}>
+  <Card title="Mock data" icon="ghost">
+    The POST returns `200`. The row appears in the table. Reload the page and it's gone. Nothing was
+    ever persisted.
+  </Card>
+  <Card title="Dead handler" icon="plug-circle-xmark">
+    The button has an `onClick`. The `onClick` calls a function. The function was never wired to the
+    store. It looks connected all the way down.
+  </Card>
+  <Card title="Double submit" icon="clone">
+    One click, two POSTs. The user gets charged twice. Nothing on screen is wrong.
+  </Card>
+  <Card title="Silent validation" icon="triangle-exclamation">
+    The form accepts `"abc"` as a quantity and cheerfully sends it to your database.
+  </Card>
+</CardGroup>
+
+Every one of these renders as a perfectly nice page. A screenshot approves them all. So does an agent that just took the screenshot, and the agent is the one telling you it's done.
+
+## Why looking harder doesn't fix it
+
+The instinct is to give the agent better eyes: a screenshot, a vision model, a full accessibility tree. This does not work, for a reason that has nothing to do with model quality.
+
+**The information is not in the picture.** Whether a request fired, what status it returned, whether application state changed, whether the console logged an error, whether one click sent one request or two, none of that is visible. You cannot see a network call. You cannot photograph a state mutation. Asking a better model to look more carefully at a screenshot of a page whose bug is non-visual is asking it to hallucinate more confidently.
+
+Reticle takes the other route. It runs **inside** your app and reads the program: network, state, console, routing, framework internals, and the app's own success signals. The answer is not interpreted from pixels. It is read from the running program, which means it is deterministic and the same every time.
+
+## The evidence
+
+We built eleven scenarios: ten bugs, plus a control where nothing is wrong, so anything flagged on the control counts as a false positive. Each tool got the same app, the same moment, the same task.
+
+| Tool | Bugs caught | Detection accuracy | Avg tokens per look | Verification efficiency |
+| --- | --- | --- | --- | --- |
+| **Reticle** | **10 / 10** | **1.00** | **815** | **12.27** |
+| Playwright MCP | 9 / 10 | 0.91 | 1,292 | 6.97 |
+| Chrome DevTools MCP | 8 / 10 | 0.82 | 758 | 10.55 |
+
+Observing one real dashboard once, with no bug involved:
+
+| Tool | Snapshot | Network | Observe total | Can it assert success? |
+| --- | --- | --- | --- | --- |
+| **Reticle** | 678 | 345 | **1,023** | Yes, via the app's own signal. 46 tokens, un-fakeable |
+| Chrome DevTools MCP | 1,105 | 252 | 1,357 | No. DOM and network only |
+| Playwright MCP | 1,522 | 671 | 2,193 | No. DOM and network only |
+
+That last column is the one that matters more than the token counts. The other tools can _describe_ what a page looks like. Only Reticle can check whether the thing the app itself considers success actually happened.
+
+<Card title="How every number was measured" icon="chart-column" href="/benchmarks">
+  The full method, the raw data, and the scenarios where Reticle comes second.
+</Card>
+
+## Where Reticle loses
+
+A benchmark that only shows you the wins is an advertisement wearing a lab coat. Ours doesn't.
+
+- **Sites you don't own.** Reticle needs a dev-only SDK inside the app. If you're driving a third party's website, use Playwright. That is what it's for, and it's excellent at it.
+- **Pixels.** Reticle reads the program, not the screen. If your bug is "the button is three pixels too far left", Reticle is the wrong instrument.
+- **Chrome DevTools MCP is cheaper per look.** 758 tokens against our 815. It catches fewer bugs, so the efficiency works out in our favour, but on raw cost per glance it wins.
+
+## What we have not proven
+
+Being honest here costs us something, and we'd rather pay it than have you find out later.
+
+We ran a controlled test of whether an agent equipped with Reticle _fixes_ more bugs than one without it. **It did not show a fix-rate improvement.** The benchmark was confounded in ways we can point at, and we don't consider the question settled. But we are not going to claim a number we didn't measure.
+
+What Reticle demonstrably does is catch failures that are invisible to the alternatives, and hand back the file and line to go fix. Whether that translates into a better fix rate is a separate question, and we're still working on measuring it properly.
+
+## When you should use it
+
+<CardGroup cols={2}>
+  <Card title="A good fit" icon="circle-check">
+    You own the app. An agent edits it. You want the agent to prove its work rather than assure you
+    of it. React gets you source pointers on top.
+  </Card>
+  <Card title="A bad fit" icon="circle-xmark">
+    You're testing a site you don't control, you need pixel-level visual regression, or your app has
+    no dev build to instrument.
+  </Card>
+</CardGroup>
+
+## The one-sentence version
+
+Your agent already tells you it works. Reticle is the part that checks. And, more usefully, the part that says "I couldn't tell" instead of guessing.
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/quickstart">
+    Five minutes to your first real verdict.
+  </Card>
+  <Card title="Architecture" icon="sitemap" href="/architecture">
+    How it reads the program without slowing your app down.
+  </Card>
+</CardGroup>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,10 +19,10 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0",
-    "ws": "^8.18.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.21.3",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.7.0"
+    "@reticlehq/core": "2.9.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -30,7 +30,7 @@
   },
   "optionalDependencies": {
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.48.0",
+    "playwright": "^1.62.1",
     "pngjs": "^7.0.0"
   },
   "license": "SEE LICENSE IN LICENSE",