@reticlehq/server 3.6.0 → 3.7.0

package/docs/predicates.mdx

@@ -5,7 +5,7 @@ description: The grammar for declaring what should be true. Every kind, every fi
 icon: filter
 ---
 
-A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
+A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has thirteen kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, `compare`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
 
 It is the argument to `until` on [`reticle_act_and_wait`](/tools/act-and-wait), and to `predicate` on [`reticle_assert`](/tools/assert) and [`reticle_assert { action: "wait" }`](/tools/wait-for).
 
@@ -25,17 +25,19 @@ Reticle grades them, and it will tell you when you have chosen a weak one. This
 
 Take the advice. `element` and `text` are convenient and weak; `signal`, `state` and `net` are what make a green trustworthy.
 
-| Kind               | Grade     | Proves                                                 |
-| ------------------ | --------- | ------------------------------------------------------ |
-| `signal`           | strongest | The app declared success in its own words              |
-| `state`            | strong    | A registered store actually changed                    |
-| `net`              | strong    | A specific request fired, with a countable cardinality |
-| `route`            | medium    | Navigation happened                                    |
-| `console`          | medium    | Something logged, or nothing did                       |
-| `element` / `text` | weak      | Something rendered. A mock renders too                 |
-| `animation`        | weak      | An animation ran or finished                           |
-| `settled`          | timing    | The page went quiet. A precondition, not a proof       |
-| `compare`          | its sides | Two readings agree: the stronger side's grade          |
+The verdict reports the grade it proved, strongest first: `signal`, `net`, `state`, then `presence`.
+
+| Kind               | Grade      | Proves                                                 |
+| ------------------ | ---------- | ------------------------------------------------------ |
+| `signal`           | `signal`   | The app declared success in its own words              |
+| `net`              | `net`      | A specific request fired, with a countable cardinality |
+| `state`            | `state`    | A registered store actually changed                    |
+| `route`            | `presence` | Navigation happened                                    |
+| `console`          | `presence` | Something logged, or nothing did                       |
+| `element` / `text` | `presence` | Something rendered. A mock renders too                 |
+| `animation`        | `presence` | An animation ran or finished                           |
+| `settled`          | `presence` | The page went quiet. A precondition, not a proof       |
+| `compare`          | its sides  | Two readings agree: the stronger side's grade          |
 
 ## The leaves
 
@@ -49,7 +51,7 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 }
 ```
 
-`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `pressed`, `focused`, `inViewport`, `present`.
+`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `value`, `by`, `component`, `source`, `scope`, `self`, `attrs`, `matchCase`. Written flat on the predicate instead of under `query`, these fields are moved into `query` for you. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `pressed`, `focused`, `inViewport`, `present`.
 
 `value` is the one worth knowing about. `{ "role": "textbox", "name": "Amount" }` collapses to "a textbox called Amount exists", which passes against an empty field; adding `value` is what makes it an assertion about what the user will actually send. `by` selects the locator strategy explicitly, `component` and `source` match React component identity and source location, and `self` restricts a scoped match to the scope element itself rather than its descendants.
 
@@ -69,7 +71,7 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 { "kind": "text", "contains": "Saved successfully", "visible": true }
 ```
 
-`contains` is the field the published schema declares. `value` and `text` are accepted as aliases and rewritten to it. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
+`contains` is the field the published schema declares. `value`, `text` and `query` are accepted as aliases and rewritten to it. The match is case-sensitive; `ignoreCase: true` relaxes that. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
 
 Use `scope` to restrict the search to a CSS selector or element ref. If Reticle reports that the text is split across the scope's children, retry its generated predicate with `"self": true`; that checks the scope root's combined subtree text while still enforcing `contains`.
 
@@ -121,7 +123,17 @@ Two fields read the RESPONSE BODY, so a request that succeeded with the wrong nu
 
 `bodyMatches` is a field match, keyed like `signal.dataMatches` and taking the same operators (`*`, `$gte`, `$contains`). A key can be a dotted path into a wrapped answer: `{ "data.status": "completed" }`, `{ "items.0.id": "a1" }`, `{ "items.length": 3 }`. A nested object written out as a value is compared whole, so use the path to match one field inside it. Reach for it whenever the value is an enum, because that is the case a substring cannot decide: `bodyContains: "completed"` passes on a body carrying `"completedAt": null`, where the needle matched the KEY and the job was still queued. `completed`/`completedAt`, `success`/`successRate`, `sent`/`unsent` all have that shape.
 
-Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
+Two more read the REQUEST body, what the UI sent: `requestBodyContains` (a substring) and `requestBodyMatches` (a field match, same operators). They are separate fields so neither can be satisfied by the wrong half of the exchange.
+
+All four require body capture, `reticle.connect({ captureNetworkBodies: true })`, and say so when the body was never recorded rather than reporting an ordinary mismatch.
+
+Some endpoints read over POST: a GraphQL query, a tRPC batch, a query bus, a Server Action that loads a list. When one runs twice in an action window, which React StrictMode does in development, the second call looks like a double submit and the verdict comes back `unknown` with `duplicate-request`. Declare the endpoint a read on its clause:
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/graphql", "repeatable": true }
+```
+
+`repeatable: true` keeps that endpoint out of `duplicate-request` for this verdict only. The request is still waited for and still counted, so `count` keeps its meaning. It needs a non-empty `urlContains`, and a clause without one is refused, because it would excuse every request in the window. When the clause names a `method`, only calls with that method are excused: a repeatable `GET` never excuses a `POST` to the same URL. Leave it off for an endpoint that writes: there, the second call is the bug.
 
 ### route
 
@@ -129,7 +141,7 @@ Both require body capture, `reticle({ captureNetworkBodies: true })`, and say so
 { "kind": "route", "pathname": "/success" }
 ```
 
-`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url` and `urlContains` as aliases for `contains`, but the canonical spellings are the ones above.
+`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url`, `urlContains` and `pathContains` as aliases for `contains`, but the canonical spellings are the ones above.
 
 A passing route verdict quotes the transition itself:
 
@@ -143,10 +155,12 @@ A passing route verdict quotes the transition itself:
 }
 ```
 
-<Warning>
-  `route` asserts the route **changed**. Asserting the route you are already on always fails, and
-  the response says so: `expected: "a route change to /"`, `assertion: "route.changed"`.
-</Warning>
+<Note>
+  `route` reads the last route change in the window. When there was none, it reads the session's
+  current URL instead, and the evidence says `decidedBy: "current-route"`. Only when neither exists
+  does it fail, and the response says so: `expected: "a route change to /"`, `assertion:
+  "route.changed"`.
+</Note>
 
 ### console
 
@@ -156,6 +170,8 @@ A passing route verdict quotes the transition itself:
 
 "The flow completed and logged nothing." Worth attaching to most actions. Plenty of features work while quietly throwing.
 
+`contains` narrows it to one message: with `absent: true` it asserts THIS message did not appear, rather than that nothing was logged at all. `textContains` is accepted as an alias.
+
 ### signal
 
 ```json
@@ -269,7 +285,7 @@ A number is read out of displayed text, so `"$1,234.50"` compares as `1234.5`. A
 
 These only work where a before-reading was taken, which today is `reticle_act_and_wait`. Asked anywhere else they report `unknown` with "no before-reading was taken", never a failure, because nothing was compared and a `false` would blame the app for a reading nobody took. For the same reason a relative property is never `already_true`: `unchanged` is trivially true against a baseline taken a microsecond earlier, so the pre-action check skips it and lets the action decide.
 
-A saved flow cannot keep one yet: `FlowExpect` has no slot for `satisfies`, and rather than record a weaker assertion than the one you made, the converter records none.
+A saved flow keeps it: a step's `expect` is a full predicate, `satisfies` included.
 
 A miss quotes the real value back at you:
 
@@ -398,7 +414,7 @@ A combinator needs its own `kind`, and the children go in `predicates`, or in `o
 accepted as an alias for it. `not` takes a single child in `predicate`, or in `of`. A bare
 `{ "allOf": [ … ] }` does not parse, and neither does `{ "kind": "allOf", "allOf": [ … ] }`.
 
-Reticle refuses the call rather than running half of it. The real refusal names the field, the fix and the consequence: _"predicates: Required; unknown field allOf. Nothing ran, the predicate was not evaluated, so no verdict was produced. allOf accepts: predicates."_ Better to be told than to get a green from an assertion that never executed.
+Reticle refuses the call rather than running half of it. The refusal names the field, says that nothing ran and no verdict was produced, lists the fields `allOf` accepts, and shows a valid example. Better to be told than to get a green from an assertion that never executed.
 
 </Warning>
 
@@ -433,10 +449,10 @@ On a failure each child reports separately too, so you can see which one broke:
 
 | Field | Where | What it does |
 | --- | --- | --- |
-| `timeout_ms` | `assert`, `wait_for`, `act_and_wait` | Wait up to N ms for it to become true |
+| `timeout_ms` | `reticle_assert` (both actions), `reticle_act_and_wait` | Wait up to N ms for it to become true |
 | `since` | `net`, `route`, `console`, `animation` and `signal` leaves, and the call itself | Only consider events after this cursor |
 
-The `since` cursor comes from a prior `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago. That applies to every one of the five kinds above, not only to network calls: an unscoped `signal` matches a fire from an earlier action just as readily.
+The `since` cursor comes from a prior `reticle_act` or `reticle_observe` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago. That applies to every one of the five kinds above, not only to network calls: an unscoped `signal` matches a fire from an earlier action just as readily.
 
 <Card title="Where predicates get used" icon="circle-check" href="/tools/act-and-wait">
   Naming the consequence before the action is the whole point.

package/docs/quickstart.mdx

@@ -5,7 +5,7 @@ description: Install Reticle, connect your coding agent, and get a real verdict
 icon: rocket
 ---
 
-**Run the installer once, then ask your agent to verify something in your app; its first Reticle call wires the app (the same thing `reticle init` does, which you can also run yourself).** Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed. Add `reticle connect` later if you want a cloud dashboard.
+**Four steps: run the installer once per machine, run `reticle init` once per project, then optionally `reticle connect` for the dashboard and `reticle sync` to send runs.** Skip `init` and your agent's first `reticle_session` call wires the app instead. Reticle embeds a dev-only SDK in your running app and proves a browser session connected. No account needed for steps 1 and 2.
 
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
@@ -16,7 +16,7 @@ By the end of this page your agent will click a button in your app and prove wha
 
 ## Prerequisites
 
-- Node 20 or newer
+- Node 20.11 or newer
 - A web app you can run locally, and its dev server
 - A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
 
@@ -36,9 +36,9 @@ irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1
 
 </CodeGroup>
 
-This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Warp, Kiro, Amazon Q, Cline, Amp, Continue and Factory Droid. Nothing is asked.
+This puts `reticle` on your PATH and registers the MCP server with every coding agent it can reach: Claude Code, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Copilot CLI, OpenCode, Antigravity, Warp, Kiro, Amazon Q, Cline, Roo Code, Amp, Continue and Factory Droid. Nothing is asked. It does not wire your app, and says so: that is step 2. Want a verdict first? Signed in, `reticle try <url>` drives a URL once in a window you watch.
 
-Codex CLI keeps a TOML config that Reticle will not rewrite, so the installer prints the lines to paste and the file to paste them into.
+Codex CLI keeps a TOML config that Reticle will not rewrite itself, so with the `codex` command installed the installer registers Reticle through `codex mcp add`. Without it, the installer prints the lines to paste and the file to paste them into.
 
 <Note>
   **Run this before opening your agent, and there is nothing to restart.** A coding agent reads its
@@ -46,7 +46,7 @@ Codex CLI keeps a TOML config that Reticle will not rewrite, so the installer pr
   you open it. If it was already open, quit and reopen it once.
 </Note>
 
-Prefer not to pipe a script into a shell? The two commands it runs are:
+Prefer not to pipe a script into a shell? The same result by hand:
 
 ```bash
 npm install -g @reticlehq/server
@@ -61,17 +61,16 @@ In your project directory, before opening your coding agent:
 RETICLE_INSTALL_SOURCE=docs_site npx @reticlehq/server init
 ```
 
-This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
+This installs the dev-only SDK, wires your build config, starts the dev server, and checks that a browser session connected. Nothing from your project leaves your machine. If your dev server was already running, restart it once and hard-reload the tab: it read your build config before `init` edited it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools. The `RETICLE_INSTALL_SOURCE` prefix is optional and only tells us which page you installed from. It is idempotent: run it twice and the second run reports what was already done rather than doing it again.
 
-Step 1 is once per machine. This step is once per project. **Skipping it is the most common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
-
-Want a cloud dashboard too? Run `npx @reticlehq/server connect --project "My App"` instead of, or after, `init`. It does everything `init` does, then opens browser sign-in approval, links this folder to the named cloud project, and sends existing local history. Approve the short code shown in the browser and terminal; the command resumes by itself.
+Step 1 is once per machine. This step is once per project. **Skipping it is a common reason Reticle "does nothing":** the agent has the tools, but there is no app on the other end for them to see.
 
 <Note>
   **Skipped this step?** Ask your agent to verify something in the app. Its first `reticle_session`
   call finds a project that has never connected, runs `init` there itself, and lists every file it
   changed under `wired`. Asked about something unrelated, it offers to wire the app instead of doing
-  it. This works in Claude Code, Codex, Cursor and other MCP agents.
+  it. This works in Claude Code, Codex, Cursor and other MCP agents, including a second project
+  while Reticle is already running for another one.
 </Note>
 
 Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
@@ -93,6 +92,7 @@ Useful flags for the local-only `reticle init` path:
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              [--env KEY=VALUE]... [--files-only] [--json] [--relaunch]
               --app picks WHICH app in a monorepo, when several are found
               --no-mcp skips MORE than the server registration: also the agent rule files
               (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
@@ -102,13 +102,38 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
 Start with `reticle init --dry-run` if you want to see the app changes before anything is written.
 
 <Tip>
-  In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
-  skips the question.
+  In a monorepo, `init` run at the root lists every app it found, each with its own
+  `reticle init --app <dir>` line, and stops. Run the line for the app you want: it writes that
+  app's files and starts nothing (add `--start` to boot it). With only one app, it wires that one
+  without asking.
 </Tip>
 
 Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
 
-## Step 3. Check the setup
+## Step 3. Connect the dashboard (optional)
+
+Skip this if you only want local verdicts. Everything above works without an account.
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+`connect` runs Step 2 first if this project isn't wired yet, so you can use it in place of `init`. Then it:
+
+1. Opens a browser so you can sign in, or create a free account at app.reticle.sh. Approve the short code shown in the browser and in the terminal, and the command carries on by itself.
+2. Links this folder to the cloud project you named, creating it if it doesn't exist. `npx @reticlehq/server status` shows the link.
+3. Sends the runs and flows already on this machine.
+
+After that, every verified run syncs on its own. To sync right now, for example before showing a teammate:
+
+```bash
+npx @reticlehq/server sync            # one sync
+npx @reticlehq/server sync --watch    # keep syncing while you work
+```
+
+A new account gets 10 free credits to try the Harness. What syncs, and how to switch each part off (`reticle config --runs/--memory/--flows on|off`), is in [What is recorded](/what-is-recorded). In CI, set `RETICLE_API_KEY` instead of signing in.
+
+## Step 4. Check the setup
 
 ```bash
 npx @reticlehq/server doctor
@@ -116,9 +141,9 @@ npx @reticlehq/server doctor
 
 `doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
 
-## Step 4. Open your app again when you need it
+## Step 5. Open your app again when you need it
 
-`connect` already started the dev server and opened the app. On a later day, start your dev server as usual, then:
+`init` (or `connect`) already started the dev server and opened the app. On a later day, start your dev server as usual, then:
 
 ```bash
 npx @reticlehq/server open
@@ -128,12 +153,13 @@ This reuses the tab you already have open, or opens one if you don't. The SDK co
 
 <Warning>
   If the browser console says `[Reticle] this page could not open a websocket to …`, your app and
-  the daemon disagree about the port. Set it explicitly:
-  `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or `reticle.connect({url})`. This is
-  the single most common setup problem, and the console message names the exact address it tried.
+  the daemon disagree about the port. Set it explicitly: `RETICLE_PORT=4400 pnpm dev` (Vite
+  plugin), `reticle({ port: 4400 })` in `vite.config`, or
+  `reticle.connect({ url: 'ws://localhost:4400/reticle' })` by hand. The console
+  message names the exact address it tried.
 </Warning>
 
-## Step 5. Look at the page
+## Step 6. Look at the page
 
 Ask your agent to take a snapshot. This is what came back from a real app:
 
@@ -155,7 +181,7 @@ The whole snapshot cost **61 tokens**. This is `mode: "interactive"`, which retu
 
 Each control has a `ref` like `e5`. That's the handle for the next step, and it stays valid until the element leaves the DOM, so you don't re-snapshot between actions.
 
-## Step 6. Act, and prove it
+## Step 7. Act, and prove it
 
 Here is the whole idea of Reticle in one call. Your agent names the expected consequence **before** it acts:
 
@@ -259,17 +285,19 @@ That third state is the one that matters. Most tools have two outcomes and quiet
 </Accordion>
 
 <Accordion title="Will any of this end up in my production build?">
-  No. The SDK is dev-only. The Vite plugin declares `apply: 'serve'`, so it is dropped from `vite
-  build` entirely, and `connect()` self-disables when the build reports `NODE_ENV=production`. The
-  recommended wiring also guards the call behind `import.meta.env.DEV`, so there are two independent
-  locks.
+  No. The SDK is dev-only. A production `vite build` with the Vite plugin injects nothing and
+  replaces the SDK with an inert stub, and `connect()` self-disables when the build reports
+  `NODE_ENV=production`. The recommended wiring also guards the call behind `import.meta.env.DEV`,
+  so there are two independent locks.
 </Accordion>
 
 <Accordion title="Does my code or my app's data leave my machine?">
-  No. The daemon runs on your machine and the SDK runs in your browser. No application code, DOM,
-  network traffic or console output leaves it. Anonymous product analytics are sent unless you opt
-  out with `npx @reticlehq/server telemetry disable`, and they never include your code or your app's
-  data.
+  Not unless you link a project. The daemon runs on your machine and the SDK runs in your browser.
+  Nothing from your app leaves the machine until you link a project (`reticle connect`, or
+  `RETICLE_API_KEY` in CI). After that, what syncs is set by `reticle config`, and when the Harness
+  drives, the platform sees the steps it drives. Secret values never leave. Anonymous product
+  analytics are sent unless you opt out with `npx @reticlehq/server telemetry disable`, and they
+  never include your code or your app's data.
 </Accordion>
 
 <Accordion title="What if my framework is not React or Next.js?">
@@ -293,7 +321,8 @@ That third state is the one that matters. Most tools have two outcomes and quiet
     Emit signals like `auth:granted` so your verdicts get stronger than "the DOM changed".
   </Card>
   <Card title="Every tool" icon="list" href="/tools/overview">
-    The 18 tools your agent sees by default, and the 30 more it can reach on demand.
+    The 10 tools your agent sees by default, and the rest it reaches through `reticle_tools` and
+    `reticle_run`.
   </Card>
   <Card title="Run it in CI" icon="circle-check" href="/testing">
     Turn this session into a suite that blocks a bad merge.

package/docs/required-checks.md

@@ -9,9 +9,9 @@ That gap is the difference between a gate and a decoration. A decoration still c
 
 ## How it works here
 
-`ci.yml` ends in a single job called **`gate`**. It waits on every other job in that file and passes only when each one either succeeded or was legitimately skipped. So one required check, `gate`, covers all fifteen jobs in `ci.yml`.
+`ci.yml` ends in a single job called **`gate`**. It waits on every other job in that file and passes only when each one either succeeded or was legitimately skipped. So one required check, `gate`, covers every other job in `ci.yml` except `fixtures-dispatch`, which notifies another repository and never runs on a pull request.
 
-That trick only reaches so far. A job can only wait on jobs in **its own workflow file**, so the five workflows below cannot be folded into `gate`. Each has to be named in branch protection separately, or it blocks nothing.
+That trick only reaches so far. A job can only wait on jobs in **its own workflow file**, so the other workflows below cannot be folded into `gate`. Each has to be named in branch protection separately, or it blocks nothing.
 
 `server/src/ci-aggregate-covers-jobs.test.ts` fails if a new workflow starts running on pull requests without being accounted for, and if a job in `ci.yml` is not watched by `gate`.
 
@@ -21,13 +21,14 @@ Set these as required status checks on the default branch:
 
 | check | what it is | what merges without it |
 | --- | --- | --- |
-| `gate` | every job in `ci.yml`: build, tests, e2e, desktop, install, Rust, Windows, macOS, bench | a red build of any kind |
-| `package-quality` | the published packages: exports and types correctness, and the browser SDK's size budget | a package that installs but cannot be imported, or a silently growing SDK |
-| `break-gates` | onboarding | a broken first-run experience |
-| `codeql` | security scan | a flagged vulnerability |
+| `gate` | every job in `ci.yml`: build, tests, e2e, desktop, install, Rust, Windows, macOS, bench, package quality, the break gates | a red build of any kind (bench and the Windows install cells run only after merge) |
 | `dco` | contributions are signed off | an unsigned contribution |
 
-`labeler` is deliberately absent. It adds labels to a pull request; there is no result to block on.
+package-quality and the break gates (`launchers`, `early-gates`, `break-matrix`) run as jobs inside `ci.yml` and are covered by `gate`. They used to be separate workflows with no `merge_group` trigger, so requiring them by name would have stalled the queue.
+
+CodeQL (`analyze (javascript-typescript)`) runs on pull requests and in the merge queue, but the ruleset does not require it, so a flagged vulnerability is reported rather than blocked.
+
+`labeler`, `welcome` and `dependabot-auto-merge` are deliberately absent. They label a pull request, greet a first contribution, and turn on auto-merge for Dependabot updates the queue still gates; there is no result to block on.
 
 ## Adding a workflow
 

package/docs/reticle-manual.md

@@ -10,7 +10,9 @@ Every row below is a call that was made against a running app and the answer tha
 
 `refused (names the fix)` means the error told you what to call instead, so you can correct without reading anything else. `refused (no fix named)` means it did not.
 
-## reticle_snapshot
+## reticle_look { action: "page" }
+
+Probed as `reticle_snapshot`, its name before the merge, which still answers. Call it as `reticle_look { action: "page" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -18,7 +20,9 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"mode":"interactive"}` | ran | 434 |
 | a value outside the allowed set: `{"mode":"not-a-mode"}` | refused (names the fix) | 236 |
 
-## reticle_query
+## reticle_look { action: "find" }
+
+Probed as `reticle_query`, its name before the merge, which still answers. Call it as `reticle_look { action: "find" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -26,7 +30,9 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"by":"role","value":"button"}` | ran | 200 |
 | a value outside the allowed set: `{"by":"telepathy","value":"x"}` | refused (names the fix) | 290 |
 
-## reticle_network
+## reticle_observe { action: "network" }
+
+Probed as `reticle_network`, its name before the merge, which still answers. Call it as `reticle_observe { action: "network" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
@@ -34,13 +40,17 @@ Every row below is a call that was made against a running app and the answer tha
 | the documented call: `{"limit":5}` | ran | 1175 |
 | a number outside its range: `{"limit":-1}` | refused (names the fix) | 222 |
 
-## reticle_console
+## reticle_observe { action: "console" }
+
+Probed as `reticle_console`, its name before the merge, which still answers. Call it as `reticle_observe { action: "console" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |
 | an argument the tool does not declare: `{"thisArgDoesNotExist":1}` | refused (names the fix) | 293 |
 
-## reticle_state
+## reticle_look { action: "state" }
+
+Probed as `reticle_state`, its name before the merge, which still answers. Call it as `reticle_look { action: "state" }` and pass the arguments below alongside `action`.
 
 | you call it with | you get back | bytes |
 | --- | --- | --- |

package/docs/skill-file.mdx

@@ -1,107 +1,45 @@
 ---
 title: 'The SKILL file: paste and go'
 sidebarTitle: SKILL file
-description: One URL you paste into any coding agent to teach it Reticle. How it works, what it contains, and when you need it at all.
+description: One URL you paste into any coding agent to teach it Reticle. Where it lives and what it tells the agent.
 icon: graduation-cap
 ---
 
-Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document tells the agent to run `npx @reticlehq/server init`, which wires the project and gets the app connected, then to do the first run with `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, and gives it the rules for verifying afterwards. You often do not need the file at all: that one command configures Claude Code, Cursor and nine other agents directly, and the file mostly exists to tell an agent which journey to prove and how to read what comes back.
+`SKILL.md` is one short document written for a coding agent. Its home is this docs site:
 
-`SKILL.md` is a single document you hand to a coding agent. It teaches the agent to install Reticle, wire it into your app, and then drive a verification loop properly. Without you explaining any of it.
-
-```
-https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md
-```
-
-That URL is live and returns the current version. Paste it into your agent and say "read this and set up Reticle".
-
-<Note>
-  You often do not need it. `npx @reticlehq/server init` writes a `/reticle` slash command for
-  Claude Code automatically, and installs agent rule files for Claude and Cursor. The SKILL file is
-  for agents that `init` cannot configure, for a from-scratch install, or when you want the agent to
-  have the full protocol in context rather than a summary.
-</Note>
-
-## It has two modes, and it picks one itself
-
-The first thing the document tells an agent to do is check which situation it is in:
-
-```bash
-cat .reticle.json 2>/dev/null || echo "NOT_FOUND"
 ```
-
-- **Not found** → run **Setup mode**: register the MCP server, install the SDK, wire the entry point, validate the connection, and prove it on one flow while the user watches.
-- **Found** → run **Test mode**: connect, orient, decide what to test, drive it, report.
-
-One document, two jobs, no flag for you to remember. The second time you invoke it, it skips straight to the useful part.
-
-## What Setup mode actually does
-
-| Phase | What the agent does |
-| --- | --- |
-| Save the skill | Store it as `/reticle` so the loop is one word away from then on |
-| Run `init`, then the first run | Without asking you questions it can answer itself, naming the journey worth proving as the `persona` |
-| Manual fallbacks | Only when `init` could not run: an older CLI that stops after writing files, or the same failure twice |
-| Validate | Confirm a session actually connected. Not that a checklist went green |
-| Prove it | Drive one real flow while you watch, so the install ends in evidence |
-
-That last row is the one that matters. Plenty of installs "succeed" and then nothing works. The skill does not consider itself finished until a real flow has produced a real verdict.
-
-## What Test mode actually does
-
-Five phases: connect, orient, decide what to test, run the tests, report. The reporting format is specified, which matters more than it sounds. An agent left to summarise freely will summarise optimistically.
-
-The rules it operates under are the same ones these docs keep repeating:
-
-- Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.
-- `verified: "unknown"` is not a pass.
-- Never weaken a check to make it pass.
-
-## Feedback is the first section, on purpose
-
-Before setup, before anything, the document tells the agent that reporting problems is part of the job. And that this applies **during** setup, which is where Reticle is most likely to break and least likely to hear about it.
-
-It even covers the case where nothing is installed yet:
-
-```bash
-npx @reticlehq/server feedback --agent --kind gap "init finished but no session ever connected"
+https://docs.reticle.sh/skill.md
 ```
 
-That works with no daemon running, which is the entire point. The install that failed halfway is the one worth hearing about, and in that state the MCP tools do not exist.
-
-<Tip>
-  It also draws a line that saves everyone time: report defects in **Reticle**. A bug found in the
-  app under test is Reticle working correctly, and belongs in the answer to the user.
-</Tip>
-
-## It ships inside the package too
-
-`SKILL.md` is bundled into `@reticlehq/server` at publish time, alongside a copy of this entire documentation site. So an agent that has already installed Reticle can read it from disk without a network round trip:
+Paste that URL into the agent and say "read this and set up Reticle". It is the canonical file with [Agent Skill](https://agentskills.io) frontmatter (`name`, `description`) added. The repository copy, `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md`, has the same body without the frontmatter, and a test fails if the two ever differ. To install the rules as a skill instead, `npx skills add reticlehq/reticle` installs `reticle` (the Claude Code plugin's shorter restructure of this file, held to the same rules by that test) and the task skills beside it. The same file ships inside the package, so an agent with no network can read it from disk:
 
 ```
 node_modules/@reticlehq/server/SKILL.md
 node_modules/@reticlehq/server/docs/
 ```
 
-Handy in a sandbox with no outbound network, which is an increasingly common place for an agent to live.
+The `docs/` folder beside it is a copy of this site.
+
+## What it tells the agent
 
-## Should you read it?
+It is the critical path and nothing else. Read [SKILL.md](https://github.com/reticlehq/reticle/blob/main/SKILL.md) itself to get the rules exactly right; in short:
 
-Probably not, unless you are curious. It is roughly 60 KB and written for an agent, which means it is exhaustive in the way a runbook is exhaustive. Every fallback, every framework, every failure mode spelled out rather than summarised.
+- **First move:** if the `reticle_*` tools are visible, call `reticle_session { action: "list" }`. If they are not, hand the user the installer line and stop.
+- **Setup is `init`, then the first run.** `init` wires the app and waits for a session. It never drives. A dev server that was already running must be restarted once.
+- **Done means a verdict.** A session listed means the SDK reached the page. Setup is finished when the first run returns a verdict.
+- **Only `verified: "yes"` is a pass.** `unknown` means Reticle could not tell. Never weaken a check to make it pass.
+- **Replay before you drive.** `reticle_verify { action: "change" }` or `{ action: "flows" }` re-verifies saved journeys in one call.
+- **Report problems with Reticle** through `reticle_session { action: "feedback" }`, or `reticle feedback --agent` from the shell.
 
-If you want the human version of the same material, you are already in it:
+## Do you need it?
+
+Often not. The installer registers the MCP server with your agents, and `reticle init` writes agent rule files and a `/reticle` command for Claude Code. The SKILL file is for agents `init` cannot configure, for a from-scratch install, or for an agent you want to hold the rules in context.
 
 <CardGroup cols={2}>
   <Card title="Agentic install" icon="wand-magic-sparkles" href="/install-agentic">
     What `reticle init` does, with real output.
   </Card>
-  <Card title="Manual install" icon="screwdriver-wrench" href="/install-manual">
-    Every step `init` cannot automate.
-  </Card>
   <Card title="Agent cheat sheet" icon="bolt" href="/agent-cheatsheet">
     The one-screen version of the drive loop.
   </Card>
-  <Card title="Best practices" icon="star" href="/best-practices">
-    The habits that make verdicts worth trusting.
-  </Card>
 </CardGroup>