@reticlehq/server 2.14.0 → 3.2.0

package/docs/docs.json

@@ -1,369 +0,0 @@
-{
-  "$schema": "https://mintlify.com/docs.json",
-  "theme": "mint",
-  "name": "Reticle",
-  "description": "Reticle is the proof layer for AI agents: it verifies a running web app from the inside, without screenshots, and returns a verdict with evidence.",
-  "colors": {
-    "primary": "#ff9d86",
-    "light": "#ffbcac",
-    "dark": "#d04425"
-  },
-  "logo": {
-    "light": "/logo/wordmark-black.svg",
-    "dark": "/logo/wordmark-white.svg"
-  },
-  "favicon": {
-    "light": "/favicon/mark-black.svg",
-    "dark": "/favicon/mark-white.svg"
-  },
-  "appearance": {
-    "default": "system"
-  },
-  "styling": {
-    "eyebrows": "breadcrumbs",
-    "codeblocks": "dark"
-  },
-  "search": {
-    "prompt": "Search the Reticle docs"
-  },
-  "metadata": {
-    "timestamp": true
-  },
-  "navigation": {
-    "versions": [
-      {
-        "version": "2.14.0",
-        "default": true,
-        "tabs": [
-          {
-            "tab": "Guides",
-            "groups": [
-              {
-                "group": "Get started",
-                "pages": [
-                  "quickstart",
-                  "what-is-reticle",
-                  "why-reticle",
-                  "getting-started",
-                  "for-agents"
-                ]
-              },
-              {
-                "group": "Install",
-                "pages": ["install-agentic", "install-manual", "frameworks"]
-              },
-              {
-                "group": "Instrument",
-                "pages": ["instrumentation", "state-management"]
-              },
-              {
-                "group": "Verify and ship",
-                "pages": ["flows", "testing", "deploy-checks", "integration-patterns"]
-              },
-              {
-                "group": "Working with agents",
-                "pages": [
-                  "multi-agent-testing",
-                  "human-control",
-                  "platform-integration",
-                  "http-transport"
-                ]
-              },
-              {
-                "group": "When it goes wrong",
-                "pages": ["troubleshooting", "debugging"]
-              }
-            ]
-          },
-          {
-            "tab": "Reference",
-            "groups": [
-              {
-                "group": "Tools",
-                "pages": [
-                  "tools-overview",
-                  "tools-snapshot",
-                  "tools-query",
-                  "tools-inspect",
-                  "tools-navigate",
-                  "tools-act",
-                  "tools-act-and-wait",
-                  "tools-act-sequence",
-                  "tools-observe",
-                  "tools-network",
-                  "tools-console",
-                  "tools-state",
-                  "tools-wait-for",
-                  "tools-assert",
-                  "tools-sessions",
-                  "tools-tools-and-run",
-                  "tools-session-and-feedback"
-                ]
-              },
-              {
-                "group": "Beyond the loop",
-                "pages": ["capabilities"]
-              },
-              {
-                "group": "CLI commands",
-                "pages": [
-                  "cli",
-                  "cli/init",
-                  "cli/doctor",
-                  "cli/status",
-                  "cli/serve",
-                  "cli/stop",
-                  "cli/kill",
-                  "cli/restart",
-                  "cli/mcp",
-                  "cli/open",
-                  "cli/drive",
-                  "cli/verify",
-                  "cli/affected",
-                  "cli/gate",
-                  "cli/watch",
-                  "cli/capsules",
-                  "cli/hunt",
-                  "cli/update",
-                  "cli/rollback",
-                  "cli/license",
-                  "cli/version",
-                  "cli/telemetry",
-                  "cli/feedback",
-                  "cli/identify",
-                  "cli/help",
-                  "cli/cloud"
-                ]
-              },
-              {
-                "group": "Packages",
-                "pages": [
-                  "packages",
-                  "packages/core",
-                  "packages/browser",
-                  "packages/server",
-                  "packages/react",
-                  "packages/vite-plugin",
-                  "packages/babel-plugin",
-                  "packages/next",
-                  "packages/test",
-                  "packages/eslint-plugin",
-                  "packages/electron",
-                  "packages/tauri"
-                ]
-              },
-              {
-                "group": "Grammar",
-                "pages": ["predicates", "actions", "recipes"]
-              },
-              {
-                "group": "Long form",
-                "pages": ["agent-cheatsheet", "reticle-manual", "usage", "faq"]
-              }
-            ]
-          },
-          {
-            "tab": "Desktop",
-            "groups": [
-              {
-                "group": "Electron and Tauri",
-                "pages": ["desktop"]
-              }
-            ]
-          },
-          {
-            "tab": "Resources",
-            "groups": [
-              {
-                "group": "How it works",
-                "pages": ["architecture", "benchmarks", "token-efficiency"]
-              },
-              {
-                "group": "Compare",
-                "pages": ["vs-playwright-mcp", "vs-chrome-devtools-mcp", "vs-screenshots"]
-              },
-              {
-                "group": "Practice",
-                "pages": ["best-practices", "skill-file"]
-              },
-              {
-                "group": "Trust & licensing",
-                "pages": ["telemetry", "license-activation", "enterprise"]
-              }
-            ]
-          },
-          {
-            "tab": "Contributing",
-            "groups": [
-              {
-                "group": "Working on Reticle",
-                "pages": ["first-drive", "gates", "gate-plan", "fixtures", "local-registry"]
-              },
-              {
-                "group": "Internals",
-                "pages": ["system-map", "telemetry-contract", "telemetry-events"]
-              }
-            ]
-          }
-        ]
-      }
-    ],
-    "global": {
-      "anchors": [
-        {
-          "anchor": "GitHub",
-          "href": "https://github.com/reticlehq/reticle",
-          "icon": "github"
-        },
-        {
-          "anchor": "Discord",
-          "href": "https://discord.gg/BwAbzv9ZRz",
-          "icon": "discord"
-        },
-        {
-          "anchor": "npm",
-          "href": "https://www.npmjs.com/org/reticlehq",
-          "icon": "npm"
-        },
-        {
-          "anchor": "Changelog",
-          "href": "https://github.com/reticlehq/reticle/blob/main/CHANGELOG.md",
-          "icon": "clock-rotate-left"
-        }
-      ]
-    }
-  },
-  "navbar": {
-    "links": [
-      {
-        "type": "github",
-        "href": "https://github.com/reticlehq/reticle"
-      }
-    ],
-    "primary": {
-      "type": "button",
-      "label": "Get started",
-      "href": "/quickstart"
-    }
-  },
-  "footer": {
-    "socials": {
-      "x": "https://x.com/reticle_hq",
-      "github": "https://github.com/reticlehq/reticle",
-      "linkedin": "https://www.linkedin.com/company/reticlehq",
-      "discord": "https://discord.gg/BwAbzv9ZRz"
-    },
-    "links": [
-      {
-        "header": "Docs",
-        "items": [
-          {
-            "label": "Quickstart",
-            "href": "/quickstart"
-          },
-          {
-            "label": "Usage guide",
-            "href": "/usage"
-          },
-          {
-            "label": "Agent cheat sheet",
-            "href": "/agent-cheatsheet"
-          },
-          {
-            "label": "For agents",
-            "href": "/for-agents"
-          }
-        ]
-      },
-      {
-        "header": "Project",
-        "items": [
-          {
-            "label": "Contributing",
-            "href": "https://github.com/reticlehq/reticle/blob/main/CONTRIBUTING.md"
-          },
-          {
-            "label": "Security",
-            "href": "https://github.com/reticlehq/reticle/blob/main/SECURITY.md"
-          },
-          {
-            "label": "License",
-            "href": "https://github.com/reticlehq/reticle/blob/main/LICENSE"
-          }
-        ]
-      },
-      {
-        "header": "Community",
-        "items": [
-          {
-            "label": "Discord",
-            "href": "https://discord.gg/BwAbzv9ZRz"
-          },
-          {
-            "label": "Star on GitHub",
-            "href": "https://github.com/reticlehq/reticle"
-          },
-          {
-            "label": "X",
-            "href": "https://x.com/reticle_hq"
-          },
-          {
-            "label": "LinkedIn",
-            "href": "https://www.linkedin.com/company/reticlehq"
-          }
-        ]
-      }
-    ]
-  },
-  "redirects": [
-    {
-      "source": "/README",
-      "destination": "/getting-started",
-      "permanent": true
-    },
-    {
-      "source": "/desktop-apps",
-      "destination": "/desktop",
-      "permanent": true
-    }
-  ],
-  "contextual": {
-    "options": ["copy", "view", "claude", "chatgpt", "cursor", "vscode", "mcp", "add-mcp"]
-  },
-  "markdown": {
-    "instructions": [
-      "Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.",
-      "Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.",
-      "A verdict of `verified: \"unknown\"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.",
-      "Package names are scoped `@reticlehq/*`. Run every CLI command as `npx @reticlehq/server <command>`, for example `npx @reticlehq/server init`. `reticle` is a bin name that `@reticlehq/server` installs once it is on your PATH, NOT a package on npm: `npx reticle` fetches an unrelated package published by somebody else, so never run that. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version."
-    ]
-  },
-  "seo": {
-    "metatags": {
-      "og:site_name": "Reticle Docs",
-      "og:type": "website",
-      "og:title": "Reticle Docs: verification for AI coding agents",
-      "og:description": "Reticle verifies a running web app from the inside and returns a verdict with evidence, not a screenshot. Install it, instrument it, and read the full tool reference.",
-      "og:url": "https://docs.reticle.sh",
-      "og:image": "https://docs.reticle.sh/images/og.png",
-      "og:image:alt": "Reticle: your agent says it works. Reticle checks.",
-      "twitter:card": "summary_large_image",
-      "twitter:site": "@reticle_hq",
-      "twitter:creator": "@reticle_hq",
-      "twitter:image": "https://docs.reticle.sh/images/og.png"
-    },
-    "organization": {
-      "name": "Reticle",
-      "url": "https://docs.reticle.sh",
-      "logo": "https://docs.reticle.sh/images/og.png",
-      "sameAs": ["https://github.com/reticlehq/reticle", "https://www.npmjs.com/org/reticlehq"]
-    }
-  },
-  "errors": {
-    "404": {
-      "redirect": false,
-      "title": "No such page",
-      "description": "That page moved or never existed. Start at [Getting started](/getting-started), or search above."
-    }
-  }
-}

package/docs/fixtures.md

@@ -1,51 +0,0 @@
----
-title: Fixture apps
-description: 'Why the apps in apps/ cannot answer the one question that matters before a release, and what does.'
-icon: cubes
----
-
-The apps in `apps/` cannot tell you whether the install still works, because every one of them is already wired to Reticle. That question is answered in a separate repo, **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**, which keeps a pristine `clean` branch of real third-party apps and runs `node scripts/verify.mjs` to install into each one and assert a session actually connects.
-
-The apps in `apps/` are ours. We chose their defects, so passing against them says less than it looks like, and they are all wired to Reticle already, which makes them useless for the one question that matters before a release: **does the install still work on an app that has never seen Reticle?**
-
-That question is answered in a separate repo: **[`reticle-fixtures`](https://github.com/reticlehq/reticle-fixtures)**.
-
-## Why it is a separate repo
-
-Three reasons, each of which bit us before the split:
-
-- **They are somebody else's package managers.** `react-admin` is a yarn monorepo. Putting it under `apps/*` makes it a member of this pnpm workspace and breaks `pnpm install` for everyone.
-- **They need a branch model this repo cannot give them.** A fresh install is only meaningful on a surface that has never been instrumented. Re-running `init` over an already-wired app reports `·` (already wired) for every step and proves nothing, which is exactly how an install regression ships unnoticed. `reticle-fixtures` keeps a pristine `clean` branch for that, plus `main` at the latest version and `reticle/<version>` per release.
-- **They are large.** The upstream checkouts were eight gigabytes of somebody else's git history sitting gitignored inside this repo.
-
-## What runs there
-
-```bash
-node scripts/materialise.mjs   # build apps/ from fixtures.json at pinned refs
-node scripts/verify.mjs        # install into every clean app, boot it, assert a session connects
-```
-
-The last step is the one that earns its keep. Every install bug found so far has been silent: the app boots, the `init` report reads clean, and nothing connects. Next.js shipped in that state through a whole release: three independent defects, none visible to any check short of opening a browser and looking at `reticle status`.
-
-## What stays here
-
-`apps/` holds bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
-
-The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**
-
-## Wiring Tier 2 (not yet live)
-
-CI can ask this repo to verify a Reticle commit automatically, in the [`vite-ecosystem-ci`](https://github.com/vitejs/vite-ecosystem-ci) shape, where a separate repo holds the downstream apps and the main repo asks it to run. The sending half is built (`fixtures-dispatch` in `.github/workflows/ci.yml`); the receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml).
-
-**It is inert until two things happen, and neither can be done from inside this repository:**
-
-1. A fine-grained PAT with **Actions: write** on `reticlehq/reticle-fixtures`, added to `reticlehq/reticle` as the secret `FIXTURES_DISPATCH_TOKEN`. Until it exists the job logs that Tier 2 is unwired and exits 0. It never reddens CI, because a dispatch failure has nothing to do with the change being pushed.
-2. The template copied into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
-
-The template lives in the _sending_ repo deliberately: the two halves must agree on an event name and payload shape, and a contract whose ends live in different repositories drifts the first time somebody edits one of them.
-
-**Nothing here has ever run.** Treat every line as unverified until somebody has watched one green run. Tier 2 being present in the plan is not Tier 2 being live.
-
-### Why Tier 2 exists when Tier 1 already passes
-
-`pnpm gate:install` (Tier 1) scaffolds pristine apps and catches install **regressions**. It cannot catch install **complexity**: `rowy` is 70 dependencies of somebody else's product, `phanpy` has a 130-line vite config holding ten plugins inside a `defineConfig` callback. That is where install bugs actually hide, and a scaffold deliberately has none of it. The two tiers answer different questions and neither substitutes for the other.

package/docs/gate-plan.md

@@ -1,104 +0,0 @@
----
-title: Release gate plan
-description: 'What has to be true before a PR merges and before a release ships, and what is built so far.'
-icon: list-check
----
-
-Two gates, not one: a **merge gate** that answers "does this PR break anything" and runs on every PR in minutes, and a **release gate** that answers "does this version work in the clients people use" and runs on a release candidate over hours. Phases 0, 1, 2 and 4 are built; Phase 3 (the client matrix) is blocked on `init` learning each client, and Tier 2 is blocked on a token that cannot be created from inside this repo.
-
-> What has to be true before a PR merges and before a release ships, why each piece exists, and what is built so far. Derived from [`system-map.md`](./system-map.md); the harness rules every tier obeys are in [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md).
-
-## Two gates, not one
-
-|         | Merge gate                   | Release gate                                      |
-| ------- | ---------------------------- | ------------------------------------------------- |
-| Answers | does this PR break anything? | does this version work in the clients people use? |
-| Runs    | every PR                     | on a release candidate                            |
-| Who     | machines only                | machines + humans                                 |
-| Budget  | minutes                      | hours                                             |
-
-**They must stay separate.** A merge that waits on a human client matrix stalls every contribution until three people with three editors happen to be awake.
-
-## Tiers
-
-| Tier | Question | Who | When | Blocks |
-| --- | --- | --- | --- | --- |
-| 0: repo | is the code internally consistent | Actions | every PR | merge |
-| 1: install | does it install into an app nobody instrumented | Actions, scaffolded apps | PRs touching install/wire | merge |
-| 2: ecosystem | does it survive third-party apps at real scale | `reticle-fixtures`, dispatch | 3×/week + release | release |
-| 3: conformance | does each MCP client actually work | humans + headless CLIs | release candidate | the tag |
-| 4: canary | does a real model still succeed | nightly, live LLM | nightly | nothing (alerts) |
-
-**Tier 1 vs 2.** Tier 1 scaffolds a pristine app at CI time (`npm create vite`): clean by construction, seconds to produce, catches install _regressions_, fast enough to block a PR. Tier 2 uses vendored production apps and catches install _complexity_. Conflating them produces a gate too slow to block and too shallow to trust.
-
-**Tier 3 is the [CNCF conformance](https://github.com/cncf/k8s-conformance) model:** contributors do not _claim_ a client works, they run one command and submit its machine-generated output as a PR, which a bot validates before a human looks. Self-reported pass/fail cannot gate anything.
-
-**No LLM in the merge path.** Deterministic tests on every commit; live-model evals nightly and alert-only. The `record → save → verify → heal` chain is what makes this possible: a flow is recorded once by an agent, then replayed forever with no model.
-
-## The matrix, factored
-
-3 OS × 6 clients × 8 frameworks × 2 runtimes = 288 combinations. Nobody runs that. Test each axis against a fixed baseline of the others instead: 3 + 6 + 8 + 2 = **19 runs, plus ~4 deliberately chosen full-stack combos** where axis interaction is most likely (Windows+Cursor+Next, macOS+Claude Code+Tauri, …). Publish the factoring, and say plainly which interactions are untested.
-
-## Phases
-
-### Phase 0: the harness contract and the map (**done**)
-
-Nothing below is trustworthy until a gate result can be distinguished from a gate artifact.
-
-- [x] `docs/system-map.md`: topology, connection sequence, tool graph, fragility inventory
-- [x] `apps/e2e/harness-rules.md`: the four rules, with the incidents that produced each
-- [x] `apps/e2e/gate-harness.mjs`: the rules as code, `portHolders`, `freePortSafely`, `startOwnedDaemon`, `watchTransport`, `attributeOutcome`, plus a self-check
-- [x] `run.mjs` and `ci.yml` no longer kill client sockets on the bridge port
-
-### Phase 1: close the silent gaps already in reach
-
-- [x] **Trace-shape assertions**: `apps/e2e/trace-shape.mjs` + `trace-shape-test`. One root span per callId, no nested span without a completed parent (the hang signature), no undeclared parentless `browser.command`, no `ok:false` without an error. Calibrated against a real 494-span run: silent there, fires on all four fault shapes.
-- [x] **Daemon truthfulness (the port half)**: `daemon/port-presence.ts` gives a three-state answer (`daemon` / `foreign` / `free`) from two probes and no platform code. `serve` now refuses a foreign port and waits for a real bind before claiming success; `status` and `doctor` name the obstacle. Guarded by `daemon-port-honesty-test`, which squats the port and includes the free-port control. (#105, #112, #115)
-- [x] **`daemon_alive` heartbeat**: `daemon/heartbeat.ts` beats unconditionally on a fixed cadence (30s, `RETICLE_HEARTBEAT_MS` to override) and `classifyDaemonLife` reads a log back into `alive` / `clean` / `signalled` / `died_silently` / `unknown`. A heartbeat nobody interprets is only log volume, so the reader ships with it and is exported for the gate. Guarded by `daemon-heartbeat-test`, which SIGKILLs a real daemon and includes the tidy-shutdown control. (#123)
-- [x] **`observation_lost`**: a new `VerifiedReason`, matched above the `pass === false` clause, so a lost connection grades UNKNOWN instead of being reported as a failed assertion. Signalled by a structured flag from `waitForPredicate`, never by matching on `failureReason` (which is free prose about the app everywhere else it is produced). Threaded through the assert and wait paths too, not just act. (#124)
-- [x] **Telemetry chokepoint coverage**: `tools/dispatch-chokepoint.test.ts` scans for any `.handler(` call outside `runTool` and fails unless it is declared with a stated reason and cost. Three exist today: family folding in `merge-tools.ts` (counted as the family, not the member), `verify-change-tools.ts` (inner `flow_verify` uncounted), and the bridge test harness. Two of those are known observability gaps; the value is that they are now _known_ and a fourth cannot arrive unnoticed. Verified by introducing a bypass and watching it redden.
-- [x] **Specified transport faults** in place of `kill -9`: `apps/e2e/fault-proxy.mjs` (no dependency; toxiproxy is not installed and the battery is deliberately dependency-free) gives none / reset-peer / blackhole / latency / truncate over `node:net`, each proven distinguishable by its own self-check. `transport-faults-test` puts it between the MCP proxy and a real daemon and asserts the product claim: every call is ANSWERED and the stdio server survives. It also separates the two unanswered-call populations by timing: a queued call answered by the 20s queue timer, a call broken in flight answered in ~600ms via `sse_aborted`. A toxic breaks the connection and never the process, so the self-inflicted `kill -9` confusion is unreachable here.
-
-### Phase 2: the install gate
-
-- [x] **Tier 1, all three `init` paths**: `apps/e2e/install-gate.mjs` (`pnpm gate:install`), wired into CI as its own `install-gate` job. Scaffolds `npm create vite`, `create-next-app` (app router) and `create-next-app --no-app` (pages router), publishes this checkout to a local Verdaccio, lets **`init` do its own dependency install** from it, boots each app, opens it in a real browser and POLLS for a session. **3/3 scaffolds, 8/8 assertions each.** The pages-router path (no `app/` root layout, so connect must mount via `pages/_app`) is the one that once did nothing at all, silently.
-  - `⚠` is an absolute zero, not a tolerated exemption. The earlier `file:`-wired version had to pass `--no-install` and then argue away the `⚠` it produced, which left the step most likely to regress as the one step untested.
-  - A `package-lock.json` check confirms the SDK came from the local registry. Without it a scope typo silently measures PUBLISHED code, which is exactly the defect this work found in `docs/local-registry.md` (`@reticle:` vs `@reticlehq:`).
-  - **Negative control, run FIRST in CI** (`pnpm gate:install:self-test`): every scaffold is mis-wired to a port the daemon is not on and every one must go RED. Verified: all three fail on the session assertion alone (7 passed, 1 failed), attributed FAIL rather than INCONCLUSIVE because the bridge was provably up. A guard that has never failed is not a guard.
-  - `file:` wiring is a dead end and the reason is worth keeping: npm symlinks it, which Vite resolves and Next does not; `--install-links` copies instead and then cannot resolve `workspace:*` at all.
-- [◐] **Tier 2: built, NOT live.** The sending half is `fixtures-dispatch` in `ci.yml` (on `main` only, never fails the workflow; it is a notification, and the verdict lands in the fixtures repo's run). The receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml), kept in the _sending_ repo so the two ends of the contract cannot drift apart.
-  - **Blocked on two things neither of which can be done from inside this repo:** a fine-grained PAT with Actions:write on `reticle-fixtures` added as `FIXTURES_DISPATCH_TOKEN`, and the template copied into that repo. Until the token exists the job says so and exits 0.
-  - **It has never run.** Every line is unverified. Tier 2 appearing in this plan is not Tier 2 being live, and the checkbox is deliberately ◐ rather than ✗ or ✓.
-- [x] **Committed baseline of what `init` plans**: `apps/e2e/install-baseline.json`, one line per step (`mark title → target`) per scaffold, diffed on every run; `--update-baseline` re-records it so a change arrives as a reviewable diff. "Zero ⚠" is an absolute and cannot carry this alone: a step silently changing mark (`✓ → ℹ`) still passes it, and a step DISAPPEARING from the plan passes it most comfortably of all, because the thing that would have warned you is the thing that is gone. A threshold answers "is this bad"; a baseline answers "is this DIFFERENT", and silent regressions are almost always the second question.
-  - The `target` is in the fingerprint and is the load-bearing field. Leaving it out (which the first version did, on an assumption about absolute paths that was simply wrong) made the app-router and pages-router baselines byte-identical, so a regression mounting the pages-router app into the wrong file would have diffed clean. `Mount ReticleDev → app/layout.tsx` vs `→ pages/_app.tsx` is the whole distinction.
-  - Proven by tampering: changing one committed entry to `vite.config.js` reddens with a readable expected/got, while every other assertion stays green, which is the point, since a one-character target change is invisible to both "zero ⚠" and "a session appeared".
-- [x] **Risk routing**: a `changes` job computes the diff with plain `git diff --name-only` (no third-party action: the question is "what changed", and a paths-filter dependency for a one-line diff is a supply-chain decision for nothing) and gates `install-gate` on it. It **fails open**: an unresolvable base ref runs every tier, because the cost of a false positive is CI time and the cost of a false negative is the 0%-connect class shipping again.
-  - The reason this was deferred is now solved rather than ignored: a job skipped by an `if:` reports **skipped**, and a branch-protection rule requiring `install-gate` directly would block every docs-only PR forever, waiting on a job that will never run. So nothing is required directly: a single aggregate `gate` job is, and it passes when every dependency succeeded **or was deliberately skipped**, and fails on anything else. `always()` on that job is load-bearing; without it the aggregate is itself skipped whenever a dependency is, reproducing the problem one level up.
-  - Routing verified against twelve representative paths without touching CI.
-
-### Phase 3: the client matrix
-
-**Blocked on `init` learning each client.** Today only Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`) are first-class; everything else gets a printed JSON snippet, so a per-client release artifact would measure the contributor's copy-paste rather than the product.
-
-- [x] **`init` support per client**: `init/mcp-clients.ts` registers Reticle with **seven** clients, not two. Every path and shape was read from that client's own documentation rather than recalled: Cursor/Windsurf/Gemini share `mcpServers`, VS Code uses `servers`, OpenCode uses `mcp` with the command as an **array**, Codex is TOML. A single "write mcp.json" assuming the Cursor shape produces a file three of them ignore: an install that reports success and registers nothing.
-  - Detection is conservative and one-directional: we write into a config a client **already has**, never creating `~/.gemini` or `~/.codeium` for somebody who does not use them.
-  - Codex is deliberately not auto-written. Editing TOML without a parser risks every _other_ server in the user's file; it returns MANUAL with an exact block.
-- [x] **Per-client compat script**: `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising the default surface (the count is asserted in `surface-sizes.test.ts`, never restated here).
-  - It proves only the half a machine can prove, and the verdict is named `runnable-unverified` so the distinction survives into the matrix. Whether the client _reads_ that path needs the real client, which is the submitted half.
-- [x] **Submission flow**: `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](https://github.com/reticlehq/reticle/blob/main/docs/matrix/README.md).
-- [x] **Generated `MATRIX.md`**: built from submitted records, prettier-ignored because a generated file that fails `format:check` teaches people to skip the gate. **The current honest state is seven clients and ZERO ticks**: `◐` means a runnable entry was written where the client documents it and _nobody has run that client_, and the generated legend says so rather than rounding `◐` up to `✅`.
-
-### Phase 4: rates, not booleans
-
-Connection stability is a rate. A pass/fail cannot express "breaks a lot", and a number that is not recorded cannot regress.
-
-- [x] **Soak with a recorded stability rate**: `apps/e2e/soak.mjs` (`pnpm gate:soak`), run inside the e2e battery where a paired app already exists, and appended to `bench/soak-history.jsonl` so the rate can regress against itself. One held-open MCP link for the whole run, never a reconnect per call (harness rule 3). First recorded row: **120/120 answered, 0 link drops over 39s**.
-  - **Idle time between rounds is the point**, not a pause for politeness. 150 back-to-back calls finish in seconds and measure throughput; the disconnect users actually report happens while nobody is calling: the agent is thinking and the next call finds the link gone. Keep-alives, idle shutdown and proxy timeouts all live in that gap, so a soak with no idle never enters it. `--idle-ms 30000 --rounds 60` is the half-hour release soak.
-  - Attribution is 3-valued: a transport that did not stay up reports INCONCLUSIVE and claims nothing about the product (harness rule 4).
-- [x] **Per-tool latency and failure budgets**, same run, `bench/TOOL-PROFILE.md`. Answers "which tool is breaking": `tool-surface-sweep` proves each tool is callable **once**, and one call cannot have a failure rate.
-  - **Latency is recorded, NOT gated, and that is a deliberate deviation from the wording of this plan.** CLAUDE.md: timing assertions are a bug. A p95 budget in wall-clock ms is a statement about the machine, goes red only under parallel CI load, and teaches everyone to re-run; a gate people re-run has stopped working. A >4x p95 jump prints a loud WARN instead. What IS gated: answer rate (absolute) and per-tool failure rate (vs the recorded baseline), both deterministic.
-  - The warn carries a 50ms floor, added because the first real run shouted `reticle_sessions p95 8ms vs 1ms (>4x)`: true, imperceptible, and exactly how a warning channel dies.
-  - It profiles the **6 repeatable read-only tools, not all 48 advertised**, and says so in the generated file. Repeating a mutating tool measures the fixture drifting rather than the tool degrading.
-  - Eleven-case self-check (`node apps/e2e/soak.mjs --self-check`), in CI's `matrix-records` job. It needs no build and no app, proven by running it in an empty directory, which is how a static import of the built CLI was caught.
-- [ ] false-green scorecard as a standing gate against apps we did not write (#130)
-  - **Genuinely blocked here, not deferred by choice.** "Apps we did not write" is the whole content of the check, and this repo contains only apps we wrote. It belongs to the fixtures repo (Tier 2) and needs `FIXTURES_DISPATCH_TOKEN`.