/install-and-verify

name: install-and-verify
description: Verify that a web app change actually works by driving the running app from the inside (DOM, network, routing, console, framework state) instead of screenshots or guessing. Use after any user-facing change, when a fix is claimed but unproven, when a test passes but the UI is broken, or when you need a real verdict rather than "looks right". Also use to install and wire up Reticle in a project that does not have it yet.
license: Apache-2.0
metadata:
  version: 3.7.0
  homepage: https://www.reticle.sh
  repository: https://github.com/reticlehq/reticle

Reticle: prove the change, do not guess

Reticle embeds a dev-only SDK in the user's running app and exposes it to you as `reticle_*` MCP tools. You look, act, observe, and assert against the real app. No screenshots, and no browser download for the verify loop: it drives the tab the user already has open. (A driven browser, which `reticle_lease` and `--drive` use, does need Chromium; Reticle says so when it needs one.)

Where the rest of the documentation is

Everything not in this file is at `https://docs.reticle.sh`, and it is built to be fetched rather than browsed. **Append `.md` to any page URL to get its source with no site chrome**, so you can pull one page instead of a whole document you mostly do not need:

curl https://docs.reticle.sh/llms.txt                  # every page title and URL, small enough to read whole
curl https://docs.reticle.sh/cli/doctor.md             # one CLI command: flags, real output, exit codes
curl https://docs.reticle.sh/tools/act-and-wait.md     # one tool: arguments and what a verdict means
curl https://docs.reticle.sh/troubleshooting.md        # the failures people actually hit

Read `llms.txt` first and pick the one page that answers the question. That is almost always cheaper than pulling a large file and hoping the part you need survived. There is a `/llms-full.txt` with the entire site in one file; use it only to seed a context window deliberately.

Every page arrives with the four rules that matter prepended, whether you asked for them or not, so a single fetch orients you without a second call.

Which path am I on

cat .reticle.json 2>/dev/null || echo NOT_FOUND

• `NOT_FOUND` → **SETUP** below.
• File exists → **VERIFY** below. If `reticle_session { action: "list" }` then returns an empty list, go to [references/troubleshooting.md](references/troubleshooting.md); do not restart setup.

Both paths are about THIS PROJECT. The machine step is separate and comes first: one command that puts the CLI on PATH, registers the MCP server with the coding agents it finds, and pre-approves Reticle's own tools where an agent has a per-server approval rule (Claude Code, for one). A user who would rather choose each step can follow `https://docs.reticle.sh/install-manual.md` instead.

curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh     # macOS, Linux
irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex          # Windows PowerShell

**If you can see `reticle_*` tools, that already happened and you can ignore it.** If you cannot, hand the user that one line to run in a terminal and stop there. `init` can register the MCP server itself, but doing it from inside a client that has already read its server list means the tools cannot appear until the client restarts, which ends your turn in the middle of setup. The terminal-first order is what removes that step, so do not work around it.

Read this before you touch SETUP

**Installed means a verdict was produced. Writing config files is not installed.**

Every earlier point looks like success and is not:

• `init` exited 0. Files were written. Nothing connected.
• The `reticle_*` tools appeared. Your client can reach a daemon. The app is very likely still uninstrumented.
• A session is listed. The app dialled in. The user has still seen nothing happen.

**Do not tell the user Reticle is set up until step 5 has produced a verdict.** The single most common outcome in the field is an agent that finishes step 1, reports success, and leaves a user with config files and no instrumented page.

Finish the setup steps

**Finish the setup steps; ask the user only when a step needs their decision.** Running `init`, fixing wiring it could not, starting the dev server and opening the browser are setup steps, not decisions.

The repo already answers which framework, package manager, port, editor or MCP client, so work those out rather than asking. Say what you did in one line.

Three places always need the user:

1. **No recognisable dev script in `package.json`.** Say so; do not invent one. 2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer. `init` writing a pre-approval rule for the `reticle` server is not that: it is a scoped, announced config change the human asked for by running the command, and it covers only Reticle's own tools. 3. **On a first install only, the client restart that loads the MCP tools** (step 2). Even then, keep going until the app is running and connected, and stop for the restart last, with only the drive left.

Setup requires a client restart, which ends your turn. This skill survives that restart. **After the restart, re-read this file and resume at the step you were on.** Do not start over, and do not skip forward.

---

SETUP

**One command wires the project. A second one proves a flow.**

RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init

It detects the framework and package manager, wires the build config, installs the SDK, registers the MCP server, starts the dev server, opens the app, and waits for a session to connect from inside it. That connection IS the proof onboarding worked: the SDK is in the page and the tools have something to talk to. It exi