@reticlehq/server 3.4.0 → 3.5.0

package/docs/getting-started.md

@@ -4,7 +4,7 @@ description: 'Zero to your agent verifying your real app, step by step, with wor
 icon: rocket
 ---
 
-**To get started with Reticle: run the installer, open your coding agent, then run `npx @reticlehq/server init` in your project root.** Getting started is three stages. **Installation** is one command in a terminal, `curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh` (or `irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex` on Windows): it puts the CLI on the machine and registers the MCP server with every agent it can reach, so the tools are there the next time you open your agent. **Onboarding** is `init`: it wires your project, starts your dev server, opens the app and waits for it to connect. **The first run** is what proves anything: `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`, or from a terminal `npx @reticlehq/server verify <url> --explore --persona "<the journey worth proving>"`. A connected app is not a verified one. Reticle is a verification layer that embeds a dev-only SDK in your running web app so an AI coding agent can prove a change works instead of guessing. It needs Node 20 or newer, an app you run locally, and an agent that speaks MCP.
+**To get started with Reticle Cloud: run the installer, then `reticle connect --project "My App"` in your app directory before opening your coding agent.** The installer puts the CLI on the machine and registers its MCP tools with supported agents. `connect` wires your app, checks that a browser session connected, opens sign-in approval if needed, links the named cloud project, and syncs existing history. The first run is what proves anything: ask your agent to verify one journey in your app, or use `reticle_verify { action: "explore", persona: "<the journey worth proving>" }`. A connected app is not a verified one. For local-only verification without an account, use `reticle init` instead. You need Node 20.11 or newer, an app you run locally, and an agent that speaks MCP.
 
 > **Looking for the fast path?** [Quickstart](/quickstart) gets you to a real verdict in five minutes, and every response on it was captured live. [Agentic install](/install-agentic) and [Manual install](/install-manual) cover setup in detail, per agent and per framework.
 >
@@ -58,7 +58,17 @@ Everything is **dev-only** and **localhost-only**. It's tree-shaken out of produ
 
 ---
 
-## Fastest path: `reticle init`
+## Cloud setup: `reticle connect`
+
+After the one-time [installer](/quickstart), run this in your app directory:
+
+```bash
+npx @reticlehq/server connect --project "My App"
+```
+
+Approve the short browser code if Reticle asks you to sign in. The command then links this folder and sends any history already on the machine. Open or restart your coding agent and ask it to verify one real journey. For a new project, the dashboard has no result until that first run is recorded.
+
+## Local-only path: `reticle init`
 
 From your project root:
 

package/docs/install-agentic.mdx

@@ -248,7 +248,7 @@ Three of these are answers only the caller has. `init` reads your repository; it
 | `--env KEY=VALUE` | What the app needs to reach a usable state: the key from `.env.example`, the mock backend, the variable that skips an auth wall. Repeatable, and a value may contain spaces and equals signs. Without it a real app sits on a login screen and there is no flow to drive. |
 | `--app <dir>` | Monorepos. `init` can find the apps that are servable; only your request says which one you are working in. |
 | `--license <key>` | Writes `RETICLE_LICENSE_KEY` to `.env` and keeps `.env` out of git. Do not do those two by hand. |
-| `--json` | One object on stdout: what was wired, what connected, the verdict, and an `agentTodo` array. For agents. |
+| `--json` | One result object on stdout; progress and package-manager output go to stderr. Default init reports runtime setup and connection. `--files-only` and `--dry-run` report the wiring result. Init does not drive a flow or produce a verification verdict. |
 | `--files-only` | Write the files, register the MCP server with every agent on the machine, pre-approve Reticle's tools, and stop: no dev server, no drive. What `init` did before it learned to boot the app, and the upgrade path for a machine that installed Reticle on an earlier version. |
 | `--no-open` | Do not open a browser: CI, a container, an SSH session, or a tab you already have. |
 | `--dry-run` | See the plan before anything is written. |

package/docs/install-manual.mdx

@@ -175,7 +175,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.5"
 ```
 
 ```rust

package/docs/packages/next.mdx

@@ -44,10 +44,13 @@ Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merg
 | --- | --- |
 | `webpack` | Pushes an `enforce: 'pre'` rule for `/\.(t\|j)sx$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
 | `turbopack` | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` pointing at `@reticlehq/next/loader` |
+| `env.NEXT_PUBLIC_RETICLE_URL` | The bridge URL: a valid `RETICLE_PORT` override, otherwise project daemon discovery and `.reticle.json` |
 | `env.NEXT_PUBLIC_RETICLE_TOKEN` | The pairing token, when one exists on disk |
 | `env.NEXT_PUBLIC_RETICLE_ROOT` | `process.cwd()`, so source paths come back repository-relative |
 | `env.NEXT_PUBLIC_RETICLE_SDK_VERSION` | The version of the app's installed `@reticlehq/react` |
 
+Daemon discovery reads `RETICLE_STATE_DIR` (default `~/.reticle`). Pairing tokens use `RETICLE_PAIRING_TOKEN_DIR` independently. The generated `ReticleDev` component reads `NEXT_PUBLIC_RETICLE_URL`; restart the dev server after changing these settings.
+
 `readPairingToken()` is also exported at runtime. It is not declared in `index.d.ts`, so TypeScript will not see it.
 
 ### `./loader`

package/docs/packages/tauri.mdx

@@ -21,7 +21,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.5"
 ```
 
 Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.

package/docs/packages/vite-plugin.mdx

@@ -31,6 +31,8 @@ export default defineConfig({
   [`@reticlehq/server`](/packages/server).
 </Warning>
 
+Set `RETICLE_PORT` in the dev server or desktop build environment to use the same custom bridge port as the CLI. A valid value overrides discovery and `.reticle.json`; invalid values are ignored.
+
 ## Why it exists
 
 `apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.

package/docs/packages.mdx

@@ -239,7 +239,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ```toml
 [dependencies]
-reticle-tauri = "3.4"
+reticle-tauri = "3.5"
 ```
 
 <Warning>

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 in a terminal, open your coding agent, then run `init` in your project.** Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+**Run the installer once, then run `reticle connect --project "My App"` in your project.** Reticle embeds a dev-only SDK in your running app, signs you in through browser approval when needed, and syncs your checks to the project you name.
 
 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.
 
@@ -53,18 +53,20 @@ npm install -g @reticlehq/server
 npx @reticlehq/server setup mcp
 ```
 
-## Step 2. Open your coding agent, and wire the project
+## Step 2. Connect this project
 
-The `reticle_*` tools are already there. In your project directory:
+In your project directory, before opening your coding agent:
 
 ```bash
-npx @reticlehq/server init
+npx @reticlehq/server connect --project "My App"
 ```
 
-Like `npm init` or `git init`, this is the per-project step: it installs the SDK, wires it into your app's entry point, starts your dev server and then opens your app to prove a session connected. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+This installs the SDK, wires your app, starts the dev server, and checks that a browser session connected. It then opens browser sign-in approval if needed, 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. A saved sign-in is reused after the cloud accepts it. Open your coding agent once this command finishes; if it was already open during installation, restart it to load the new tools.
 
 Step 1 is once per machine. This step is once per project.
 
+Want local-only verification without an account? Run `reticle init` in this step instead. You can run `reticle connect` later to sync your history.
+
 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:
 
 ```text
@@ -80,7 +82,7 @@ npx skills add reticlehq/reticle
 
 Then type `/reticle` and the agent runs the install from the skill.
 
-Useful flags, from `reticle init` itself:
+Useful flags for the local-only `reticle init` path:
 
 ```
 reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
@@ -90,7 +92,7 @@ reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
               only make sense once the tools are reachable.
 ```
 
-Start with `--dry-run` if you want to see the plan before anything is written.
+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`
@@ -107,9 +109,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. Start your app and open it
+## Step 4. Open your app again when you need it
 
-Start your dev server as usual, then:
+`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

package/docs/tools/act.mdx

@@ -59,7 +59,7 @@ Real response:
 
 ## Actions
 
-`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
+`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag`
 
 | Action           | Arguments                                                       |
 | ---------------- | --------------------------------------------------------------- |

package/docs/usage.md

@@ -419,7 +419,6 @@ A `state` assertion is graded as a **consequence** (a wrong element or stale ren
 | `scrollIntoView` | n/a |  |
 | `upload` | `{ name, content?, type? }` | sets a file on `<input type=file>` |
 | `drag` | `{ toRef }` | pointer-based drag (dnd-kit / rbd) + HTML5 DnD |
-| `webmcp` | `{ tool, params }` | calls a `navigator.modelContext` tool if the site exposes one |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,11 +23,11 @@
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/browser": "3.4.0",
-    "@reticlehq/init": "3.4.0",
-    "@reticlehq/engine": "3.4.0",
+    "@reticlehq/browser": "3.5.0",
+    "@reticlehq/engine": "3.5.0",
+    "@reticlehq/core": "3.5.0",
     "open-verification": "1.0.0",
-    "@reticlehq/core": "3.4.0"
+    "@reticlehq/init": "3.5.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",