@reticlehq/server 2.6.0 → 2.8.0

package/docs/capabilities.mdx

@@ -0,0 +1,387 @@
+---
+title: Beyond the verify loop
+description: Coverage, storage, fake clocks, autonomous crawling, visual diffing and network mocking. What Reticle does once look-act-observe-assert is not enough.
+icon: sparkles
+---
+
+Most of the time you want the verify loop. Look, act, observe, assert.
+
+These are the tools for the times you want something else, and they are the ones people are most surprised exist. All of them live in the cold tail, reachable through [`reticle_run`](/tools-tools-and-run).
+
+## Available anywhere
+
+These work through the always-on SDK, in any connected session.
+
+### Coverage: what you have not driven yet
+
+```json
+{ "tool": "reticle_coverage" }
+```
+
+```json
+{
+  "total": 3,
+  "exercised": 0,
+  "untouched": [
+    { "ref": "e3", "label": "textbox \"Email\"" },
+    { "ref": "e4", "label": "textbox \"Password\"" },
+    { "ref": "e5", "label": "button \"Sign in\"" }
+  ]
+}
+```
+
+Not code coverage. Control coverage: which interactive elements this session has actually touched.
+
+Useful at the end of a drive, when the agent is about to report success. "I verified the page" reads differently next to `exercised: 0`.
+
+### Storage: the persistence layer
+
+```json
+{ "tool": "reticle_storage" }
+```
+
+```json
+{
+  "local": {},
+  "session": { "__reticle_ref_base": "100", "__reticle_session": "lease-0cee1313…" },
+  "cookies": {}
+}
+```
+
+localStorage, sessionStorage and readable cookies.
+
+This is where the "logged in but nothing persisted" bug lives. A login can fire its success signal, mutate state, and write nothing. Reload, and you are back at the login screen.
+
+<Tip>
+  `storageKeysChanged` already appears in every `act_and_wait` summary, so you often do not need
+  this tool. Read it there first.
+</Tip>
+
+### Clock: freeze time, skip the wait
+
+```json
+{ "tool": "reticle_clock", "args": { "freeze": true } }
+```
+
+```json
+{ "frozen": true }
+```
+
+```json
+{ "tool": "reticle_clock", "args": { "advanceMs": 5000 } }
+{ "tool": "reticle_clock", "args": { "reset": true } }
+```
+
+Toasts that auto-dismiss, debounced search, polling, session timeouts, retry backoff. All of these are normally verified by sleeping, which is slow and flaky in equal measure.
+
+Freeze the clock, advance it by exactly the interval, assert the consequence. No sleeping, no guessing, and the same result on a fast laptop and a loaded CI runner.
+
+### Crawl: click everything, report anomalies
+
+```json
+{ "tool": "reticle_crawl", "args": { "maxSteps": 6 } }
+```
+
+```json
+{
+  "interactiveFound": 3,
+  "stepsRun": 3,
+  "anomalies": [],
+  "counts": { "consoleErrors": 0, "failedRequests": 0, "deadControls": 0, "contradictions": 0 },
+  "visited": ["- textbox \"Email\"", "- textbox \"Password\"", "- button \"Sign in\""],
+  "truncated": false
+}
+```
+
+Autonomously clicks every reachable control and reports what went wrong. No script, no plan. The counts are the useful part: `deadControls` and `contradictions` are the two that indicate a real problem rather than a busy page.
+
+This is the tool for an app you did not write and do not understand yet.
+
+<Warning>
+  It clicks **everything**, so point it at a dev environment. `maxSteps` bounds it, defaulting to
+  25.
+</Warning>
+
+### Reconcile: what the API said versus what rendered
+
+```json
+{ "tool": "reticle_reconcile" }
+```
+
+Compares the data an endpoint returned against what the page actually displays.
+
+The bug it catches is specific and common: the API returned ten rows, the table shows nine, and nothing errored. Neither the network log nor the DOM is wrong on its own. Only the comparison is.
+
+### Domain: which of your flows actually prove anything
+
+The most useful tool nobody knows about.
+
+```json
+{ "tool": "reticle_domain" }
+```
+
+```json
+{
+  "flowCount": 47,
+  "coverage": { "asserted": 14, "presenceOnly": 2, "assertionFree": 31 },
+  "gaps": {
+    "declaredUntestedSignals": [
+      "deploy:created",
+      "deploy:shipped",
+      "modal:opened",
+      "toast:shown",
+      "…"
+    ],
+    "declaredUntestedTestids": ["deploy-submit", "drawer", "palette", "…"]
+  },
+  "summary": "47 flows: 14 asserted, 2 presence-only, 31 assertion-free. 13 declared signal(s) no flow asserts. 33 flow(s) assert no consequence."
+}
+```
+
+Read that summary again. Thirty-one of forty-seven flows **assert no consequence**, which means they replay green whatever the app does. That is a suite that looks like coverage and is not.
+
+Each flow comes back graded, with the consequence that must hold and a risk level:
+
+```json
+{
+  "name": "deploy-journey",
+  "grade": "asserted",
+  "mustHold": "nav:changed",
+  "risk": { "level": "high", "reason": "last run drifted", "lastStatus": "drift" }
+}
+```
+
+```json
+{
+  "name": "console-compose",
+  "grade": "assertion-free",
+  "warning": "This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state."
+}
+```
+
+`declaredUntestedSignals` is the other half: signals your app emits that no flow ever checks. It is a to-do list for your test suite, generated from what the app says about itself.
+
+<Tip>
+  Run this before writing a new flow. It tells you what is already covered, what is covered badly,
+  and which declared signal has never been asserted. All three are better starting points than
+  guessing.
+</Tip>
+
+### Baselines: semantic snapshots, not pixels
+
+```json
+{ "tool": "reticle_baseline", "args": { "action": "save", "name": "checkout-empty" } }
+{ "tool": "reticle_baseline", "args": { "action": "diff", "name": "checkout-empty" } }
+```
+
+Records the meaningful state of a page and compares later. Structure and content rather than pixels, so a font change does not fail your check and a missing row does.
+
+## Needs a driven browser
+
+Four tools apply their effects through the Chrome DevTools Protocol. The always-on SDK cannot do that, so they need a browser Reticle is driving.
+
+<Warning>
+**A pooled lease is not enough.** Verified: acquiring one with `reticle_lease` and calling these
+still returns `{ "ok": false, "reason": "no-cdp-provider" }` and `"no-visual-provider"`.
+
+Point `RETICLE_CDP_URL` at a Chrome started with `--remote-debugging-port`. That is currently the reliable route.
+
+</Warning>
+
+### Screenshots and visual diffing
+
+```json
+{ "tool": "reticle_screenshot", "args": { "name": "login-baseline" } }
+{ "tool": "reticle_visual_diff", "args": { "baseline": "login-baseline" } }
+```
+
+<Warning>
+  Note the asymmetry. `reticle_screenshot` names the baseline with **`name`**; `reticle_visual_diff`
+  refers to it with **`baseline`**. Passing `name` to the diff is rejected, and it is an easy
+  mistake to make twice.
+</Warning>
+
+`fullPage` captures the whole scroll height. `ref` or `clip` scopes to one element or region. `threshold` sets the pixel-difference tolerance, defaulting to `0.01`, and `masks` excludes regions that are expected to change.
+
+Reticle reads program truth, not pixels, so this is the deliberate exception: a font that failed to load or a compositing glitch is only visible in the actual frame.
+
+### Viewport pinning
+
+```json
+{ "tool": "reticle_viewport", "args": { "width": 1280, "height": 800 } }
+```
+
+Fixes the viewport so a visual baseline is reproducible across machines. Without it, a diff taken on a laptop and re-run in CI compares two different layouts and fails for a reason nobody wants to debug.
+
+### Network mocking
+
+```json
+{
+  "tool": "reticle_network_mock",
+  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
+}
+```
+
+Return a 500, force offline, or delay a response. First matching rule wins. `clear: true` turns it off.
+
+Most error states have never actually run. This is how you find out whether yours works, without touching the backend or waiting for a real outage to tell you.
+
+## Flows: record once, replay forever
+
+The loop closer, and the reason Reticle is not only an interactive tool.
+
+```json
+{ "tool": "reticle_record", "args": { "action": "start", "recordingName": "ship-a-deploy" } }
+{ "tool": "reticle_record", "args": { "action": "stop", "recordingName": "ship-a-deploy" } }
+{ "tool": "reticle_flow_save", "args": { "flowName": "ship-a-deploy" } }
+{ "tool": "reticle_flow_verify" }
+```
+
+<Warning>
+  The argument names are not interchangeable. `reticle_record` takes **`recordingName`**,
+  `reticle_flow_save` takes **`flowName`**, and neither accepts `name`. Reticle rejects the call
+  rather than guessing, which is the right call and still costs you a turn.
+</Warning>
+
+Stopping a recording returns a **large** payload. A one-click recording came back at roughly 63,000 characters, and 69,000 of the 70,000 were the raw `events` array. There is currently no way to cap it: `max_events` and `filters` are rejected, even though the response's own `cost.recommendation` suggests them.
+
+The parts you actually want are tiny. Read these and ignore the rest:
+
+```json
+{
+  "program": { "name": "ship-a-deploy", "steps": [{ "tool": "reticle_act", "stable": true, "args": { … } }] },
+  "proposedConsequences": [
+    { "predicate": { "kind": "signal", "name": "auth:granted" }, "tier": 0, "label": "signal \"auth:granted\" fires" },
+    { "predicate": { "kind": "state", "store": "app", "path": "auth" }, "tier": 1, "label": "state \"app\" changes" },
+    { "predicate": { "kind": "net", "method": "POST", "urlContains": "/api/login", "status": 200 }, "tier": 1, "label": "POST /api/login responds" }
+  ],
+  "summary": { "total": 440, "network": 1, "consoleErrors": 0, "signals": 1 }
+}
+```
+
+`proposedConsequences` is the useful part and the reason to record at all. Reticle watched the interaction and worked out what would have proved it, ranked by strength. Tier 0 is the app's own signal. You do not have to invent the assertion; you pick one.
+
+### Saving and replaying
+
+```json
+{ "tool": "reticle_flow_save", "args": { "flowName": "ship-a-deploy" } }
+```
+
+```json
+{
+  "name": "ship-a-deploy",
+  "stepCount": 1,
+  "assertions": {
+    "grade": "assertion-free",
+    "warning": "This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken."
+  }
+}
+```
+
+Reticle grades the flow as you save it, and tells you when you have just created a test that cannot fail. Take the warning seriously: an assertion-free flow replays green whatever the app does.
+
+A replay against a drifted app names what moved and where:
+
+```json
+{
+  "status": "drift",
+  "decision": {
+    "whatChanged": "testid \"login-submit\" not found",
+    "whereInSource": "src/components/Login.tsx:81",
+    "suggestedFix": "rebind the anchor to \"sign-out\" (closest survivor)"
+  }
+}
+```
+
+`reticle_flow_heal` proposes the rebind. It refuses when it is not confident:
+
+```json
+{
+  "status": "unhealable",
+  "applied": false,
+  "message": "drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=0.5); file left untouched; add a data-testid or fix the flow by hand"
+}
+```
+
+Flows live in `.reticle/` as human-readable files, so they are reviewed in pull requests and diffed like code. They anchor on meaning, a testid plus a signal, rather than volatile refs or coordinates.
+
+<Card title="Flows in full" icon="repeat" href="/flows">
+  Recording, replay, self-healing, and what lives in `.reticle/`.
+</Card>
+
+## Handing results to something else
+
+### The CI artifact
+
+```json
+{ "tool": "reticle_run_export" }
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "11fd8ee9-2820-4bfa-bfe3-e4eeb111af26",
+  "durationMs": 41968,
+  "project": { "name": "reticle", "framework": "other" },
+  "agent": { "id": "reticle-mcp", "kind": "coding-agent" },
+  "flows": [
+    { "name": "suite-404", "status": "pass", "steps": 3, "oracle": "fault:injected" },
+    {
+      "name": "deploy-journey",
+      "status": "fail",
+      "steps": 1,
+      "failureReason": "testid \"login-submit\" not found"
+    }
+  ],
+  "verdict": { "status": "partial", "confidence": "high", "blockingRisks": 0 }
+}
+```
+
+A versioned, machine-readable record of a verification run. This is what you hand to CI, a dashboard, or a platform embedding Reticle in its pipeline.
+
+`oracle` on a passing flow names the consequence that made it a pass, so a green row says what it proved rather than only that it was green.
+
+### The capability contract
+
+```json
+{ "tool": "reticle_contract_save" }
+```
+
+```json
+{ "saved": true, "path": ".reticle/contract.json", "testidCount": 49, "signalCount": 16 }
+```
+
+Persists the app's live capability registry to a git-checked file. A fresh agent can read it without booting the app, and a diff shows when someone removes a signal something depended on.
+
+### Talking to the human
+
+```json
+{ "tool": "reticle_session", "args": { "action": "narrate", "text": "Checking the deploy flow." } }
+{ "tool": "reticle_session", "args": { "action": "review" } }
+```
+
+`narrate` writes a line into the presenter panel, so the person watching knows what you are doing. `review` drains the bugs they pinned on elements from that panel:
+
+```json
+{ "marks": [], "pendingCount": 0 }
+```
+
+An empty list here is a real reading, not a missing one.
+
+## Discovering the rest
+
+```json
+{ "tool": "reticle_tools" }
+```
+
+Returns every tool with a one-line summary, and the profile currently in force. Load the full argument grammar for the ones you want before calling them:
+
+```json
+{ "names": ["reticle_network_mock", "reticle_clock"] }
+```
+
+<Tip>
+  Do this rather than guessing at arguments. Reticle refuses a call with unknown parameters rather
+  than running it, and says why: *"NOT applied, so any result would be an answer to a different
+  question."* Good behaviour, but a wasted turn you can skip.
+</Tip>

package/docs/cli/affected.mdx

@@ -0,0 +1,51 @@
+---
+title: reticle affected
+description: List which saved flows must re-verify for a set of changed files.
+icon: code-branch
+---
+
+`reticle affected` answers one question: given these changed files, which saved flows cover them? It is the foundation the [gate](/cli/gate) and [watch](/cli/watch) are built on, and it costs your agent nothing per turn because it runs in the environment.
+
+```bash
+npx @reticlehq/server affected [--since <ref>] [file...]
+```
+
+## Arguments and flags
+
+| Argument | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `file...` | strings, positional | none | Explicit changed files |
+| `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
+
+With nothing after it, `reticle affected` means the working tree against `HEAD`. It used to be a usage error, while the rule `reticle init` writes into the agent's own instruction file told the agent to run it.
+
+## What it prints
+
+One `reticle_affected` line. Real capture from this repository, with the file and flow lists trimmed for length:
+
+```json
+{
+  "t": "2026-08-14T19:38:46.407Z",
+  "event": "reticle_affected",
+  "changedFiles": ["docs/cli.mdx", "packages/server/src/tools/e2e-surface-drift.test.ts"],
+  "affected": ["deploy-journey", "verify-route", "console-compose"],
+  "unknownProvenance": ["deploy-journey", "verify-route", "console-compose"]
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `changedFiles` | The resolved file set: your positional arguments plus whatever `--since` added |
+| `affected` | Saved flows that cover at least one of those files |
+| `unknownProvenance` | Flows with no recorded source mapping. They are listed as affected because the safe assumption is that they might be |
+
+## Exit codes
+
+Always `0`. A load error is logged as `reticle_affected_failed`, not thrown. Use [`reticle gate`](/cli/gate) when you want a non-zero exit.
+
+## Worked example
+
+```bash
+npx @reticlehq/server affected --since origin/main
+npx @reticlehq/server affected src/components/Login.tsx
+```

package/docs/cli/capsules.mdx

@@ -0,0 +1,69 @@
+---
+title: reticle capsules
+description: List the saved fail-to-pass bug capsules recorded from failed assertions.
+icon: capsules
+---
+
+`reticle capsules` lists what is in `.reticle/capsules`. A capsule is a minimal failing reproduction plus the consequence that should have held. Replay one with the `reticle_flow_replay` tool.
+
+```bash
+npx @reticlehq/server capsules
+```
+
+No flags.
+
+## What it prints
+
+One `reticle_capsules` line: a `count` and an array. Real capture from this repository, trimmed to three of the sixty-three entries:
+
+```json
+{
+  "event": "reticle_capsules",
+  "count": 63,
+  "capsules": [
+    {
+      "id": "1786713193695-e23",
+      "origin": "failed-assert",
+      "expected": "declared consequence",
+      "observed": "no element matched {\"role\":\"dialog\"} in state 'visible'",
+      "steps": 1
+    },
+    {
+      "id": "1786696531874-e103",
+      "origin": "failed-assert",
+      "expected": "signal auth:granted",
+      "observed": "signal \"auth:granted\" never fired",
+      "steps": 1
+    },
+    {
+      "id": "1785653101906-e3",
+      "origin": "failed-assert",
+      "expected": "declared consequence",
+      "observed": "not settled: 236 request(s) still in flight",
+      "steps": 1
+    }
+  ]
+}
+```
+
+| Field      | Meaning                                          |
+| ---------- | ------------------------------------------------ |
+| `id`       | Capsule id, timestamp plus a cursor              |
+| `flow`     | Present when the capsule came from a named flow  |
+| `origin`   | How it was captured, for example `failed-assert` |
+| `expected` | The consequence that was declared                |
+| `observed` | What actually happened                           |
+| `steps`    | How many steps the reproduction is               |
+
+## Exit codes
+
+| Code | Meaning                                                                  |
+| ---- | ------------------------------------------------------------------------ |
+| `0`  | Listed, even when the count is zero                                      |
+| `1`  | The capsule store could not be read. Logged as `reticle_capsules_failed` |
+
+## Worked example
+
+```bash
+npx @reticlehq/server capsules | jq '.capsules[] | select(.origin == "failed-assert") | .observed'
+```

package/docs/cli/cloud.mdx

@@ -0,0 +1,127 @@
+---
+title: reticle cloud commands
+description: Sign in, link a repository, and read runs and regressions from Reticle Cloud.
+icon: cloud
+---
+
+Ten subcommands bind this repository to Reticle Cloud so runs and flows land on a dashboard. They dispatch before the local parser, so `reticle login` is one tool, not a second binary.
+
+```bash
+npx @reticlehq/server <login|logout|whoami|link|project|config|push|runs|regression|share>
+```
+
+These are thin clients over the `/v1` API. The moat is the server, not the verbs.
+
+## Where credentials live
+
+| Path | Contents | Secret |
+| --- | --- | --- |
+| `~/.reticle/session.json` | `{ url, token, orgName }` from `reticle login` | Yes |
+| `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
+| `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
+
+Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`.
+
+## The commands
+
+### `reticle login`
+
+```bash
+npx @reticlehq/server login                                    # browser device flow (the default)
+npx @reticlehq/server login --email you@acme.com               # headless: requests a code
+npx @reticlehq/server login --email you@acme.com --code 123456 # headless: exchanges it
+npx @reticlehq/server login --email you@acme.com --org "Acme"  # --org is consulted only for a brand new account
+```
+
+With no `--email`, it runs a browser device flow like `gh auth login`: fetch a device and user code, open the browser to approve, poll until confirmed. With `--email` it keeps the two-step code path for CI and servers, because it proves you own the inbox before handing out a session. A local cloud whose dev mailer cannot deliver echoes the code back and completes in one command.
+
+### `reticle logout`
+
+Empties `session.json`. Per-project keys in `credentials.json` stay. Prints `{ "loggedOut": true }`.
+
+### `reticle whoami`
+
+The one call to make when you do not know your state. Real capture:
+
+```json
+{
+  "loggedInAs": "acme",
+  "repo": {
+    "attached": false,
+    "projectId": null,
+    "url": null,
+    "sync": { "runs": true, "memory": true, "flows": true },
+    "verify": "local"
+  }
+}
+```
+
+An unattached repo also gets a next-step nudge on stderr, telling you to run `reticle link`.
+
+### `reticle link`
+
+```bash
+npx @reticlehq/server link [--project <name|id>]
+```
+
+Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_CLOUD_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
+
+### `reticle project`
+
+```bash
+npx @reticlehq/server project ls
+npx @reticlehq/server project create "My App"
+npx @reticlehq/server project rename <projectId> "New name"
+npx @reticlehq/server project rm <projectId>
+```
+
+`rename` and `rm` work but are not in the usage block. Missing or malformed arguments exit `2`.
+
+### `reticle config`
+
+```bash
+npx @reticlehq/server config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
+```
+
+Edits `.reticle/cloud.json` in place. Any value other than `on` or `off` (or `local` or `server` for `--verify`) exits `2`. Requires the repo to be linked.
+
+### `reticle push`
+
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ pushed, failed, total, project }`.
+
+### `reticle runs`
+
+The linked project's recent run artifacts. The key scopes the query server-side.
+
+### `reticle regression`
+
+The CI gate: which flows broke relative to before. **Exits `3`** when any flow regressed, which is the whole point of it being a separate command.
+
+### `reticle share`
+
+```bash
+npx @reticlehq/server share <runId>
+```
+
+Mints a public proof link for one run. A missing `runId` exits `2`.
+
+## Exit codes
+
+| Code | Meaning                                                                             |
+| ---- | ----------------------------------------------------------------------------------- |
+| `0`  | Success                                                                             |
+| `1`  | The API call failed, or the repository is not attached where attachment is required |
+| `2`  | Usage error, or not signed in and no `RETICLE_CLOUD_KEY`                            |
+| `3`  | `regression` only: at least one flow broke                                          |
+
+Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.
+
+## Worked example
+
+```bash
+npx @reticlehq/server login
+npx @reticlehq/server project create "Checkout"
+npx @reticlehq/server link --project "Checkout"
+npx @reticlehq/server verify http://localhost:4173   # runs auto-push once linked
+npx @reticlehq/server regression                      # exit 3 fails the pipeline
+```