diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md
index e956f88ce85..93507eb7ecd 100644
--- a/.agents/skills/reverse-engineer-anything/SKILL.md
+++ b/.agents/skills/reverse-engineer-anything/SKILL.md
@@ -70,7 +70,13 @@ returns the Evidence record directly. This fallback does not establish that
MCP is configured. Native CLI tasks still require their selected engine.
Prefer an existing `rea` CLI. When none is installed and REA package acquisition
is within the authorized scope, use `npx -y rea-agents@latest` in its place from a
-trusted directory outside the target project, with absolute target paths. Managed
+trusted directory outside the target project and outside any REA source checkout,
+with absolute target paths. Inside a checkout npm treats `rea-agents` as a local
+match only for an unversioned request or one naming the checkout's exact version,
+and the checkout's package is unbuilt, so such a request fails and the client
+reports a closed connection. An `@latest` request keeps resolving the registry
+entry, so this shadowing does not explain a failure of the `npx -y
+rea-agents@latest` form above. Managed
setup binds the current installation directly; retain its runtime and package
cache entry, or restore that installation before repairing its registration.
For setup-owned registration, configuration repair starts with a read-only setup plan; show paths, backups and
diff --git a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md
index a4604942980..0d168963cc7 100644
--- a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md
+++ b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md
@@ -158,8 +158,14 @@ Use the current supported client's ID: `claude_code`, `claude_desktop`, `codex`,
scope. `grok_bot` uses a chat registration step rather than local `mcp.json`.
For unsupported clients, use manual stdio registration with the selected
installation’s absolute runtime and entry script, or continue through the CLI.
-Acquire packages from a trusted directory outside the target project. Keep a
+Acquire packages from a trusted directory outside the target project and outside
+any REA source checkout. Keep a
package-runner installation and its runtime available while registrations use it.
+Inside a checkout, npm resolves an unversioned `rea-agents` request, or one naming
+the checkout's exact version, to the local unbuilt package, so the launcher fails
+before REA starts and a registration that runs from there reports a closed
+connection rather than a REA diagnostic. A request with `@latest` or another
+version still resolves the registry entry and is unaffected.
Show the plan's exact paths, backups, changes and bundled-skill replacement.
Obtain approval for writes when that concrete scope is not already authorized,
diff --git a/README.md b/README.md
index 4e525c0c458..fa98c114a77 100644
--- a/README.md
+++ b/README.md
@@ -24,11 +24,15 @@
[Quick start](#quick-start) · [How REA works](#how-rea-works) · [What you can analyze](#what-you-can-analyze) · [Showcases](#showcases) · [Build RL environments](#build-rl-environments) · [FAQ](#faq) · [Documentation](#documentation)
-npx rea-agents setup
+npx rea-agents@latest setup
> [!IMPORTANT]
+> Run setup outside a REA source checkout. There an unversioned `npx rea-agents`
+> resolves to that checkout's own unbuilt package and the launcher fails before
+> REA starts; `@latest` resolves the published release instead.
+
> Get REA from [morluto/rea](https://github.com/morluto/rea),
> [rea.tools](https://rea.tools/), or the [rea-agents npm package](https://www.npmjs.com/package/rea-agents).
> Follow the installation and release links from these official sources. A similar
@@ -88,7 +92,9 @@ REA's MCP server and matching workflow instructions, with backups of existing
configuration. Restart your agent afterward. Setup records the selected runtime and REA
entry script directly. If acquired through a package runner, keep its cache entry
available. Run package acquisition from a trusted directory outside the target
-project. Installation and recovery details are in the setup guide below.
+project and outside a REA source checkout: inside that checkout npm resolves
+`rea-agents` to the local (unbuilt) package instead of the published one, so the
+launcher fails before REA starts. Installation and recovery details are in the setup guide below.
Setup supports Claude Code, Codex, Cursor, Gemini CLI, Grok Build and
[other agents](docs/getting-started/installation.md#supported-agents). See
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 9260b6349c5..d89f75bb5a9 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -19,9 +19,11 @@ Setup previews configuration changes and asks for approval before applying them.
npx rea-agents setup
```
-Choose the agents to configure, review the proposed paths and changes, and
-approve the plan. npm's package-download approval and REA's setup approval are
-separate. Setup asks before changing agent configuration or installing Hopper.
+Run this from a trusted directory outside any REA source checkout: an unversioned
+request there matches the checkout's own unbuilt package, so the launcher fails
+before setup starts. Choose the agents to configure, review the proposed paths
+and changes, and approve the plan. npm's package-download approval and REA's
+setup approval are separate. Setup asks before changing agent configuration or installing Hopper.
Restart the agents named in the completion message. Quit Claude Desktop fully
before approving, because a running app can overwrite the registration; on
Windows, see [where Claude Desktop reads its configuration](client-configuration.md#claude-desktop).
@@ -1241,7 +1243,8 @@ Java, or Python. It preserves valid detected Ghidra/JDK settings in agent
registrations. See [Windows Ghidra P0](../providers/windows-ghidra-p0.md) for provider diagnostics.
The separate `rea mcp add` builtin delegates most clients to Incur's package-runner
-child launcher. Run that acquisition from a trusted directory; prefer managed
+child launcher. Run that acquisition from a trusted directory outside any REA
+source checkout, for the same unversioned-match reason as `Start setup`; prefer managed
`rea setup` when supported. That child launcher can fail on Windows with `MCP_ADD_FAILED: spawn npx ENOENT`
before registering a client. REA's setup path is unaffected. For a client supported
by setup, review `rea setup --client opencode --skill=false --dry-run --json`
@@ -1953,7 +1956,9 @@ before running setup again. A global installation provides a more durable path.
Package runners can select project-local packages and read project configuration,
even for explicit version requests. Acquire REA from a trusted working directory,
-outside the target project, and pass absolute target paths to analysis commands.
+outside the target project and outside any REA source checkout: an unversioned
+request inside that checkout matches its own unbuilt package. Pass absolute target
+paths to analysis commands.
REA cannot validate package acquisition that happens before its entrypoint starts.
To request the latest release explicitly, use:
diff --git a/docs/index.md b/docs/index.md
index a48bf941532..f4b12812d4f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -28,10 +28,13 @@ features:
## Start with one command
```bash
-npx rea-agents setup
+npx rea-agents@latest setup
```
-Choose your agent, review the planned changes, and approve setup. Native binary
+Choose your agent, review the planned changes, and approve setup. Run it outside
+a REA source checkout: there an unversioned `npx rea-agents` resolves to the
+checkout's own unbuilt package and the launcher fails before REA starts, so this
+command pins `@latest` to reach the published release. Native binary
analysis can use an existing Hopper, Ghidra, or IDA installation; static
JavaScript analysis needs no native analysis engine.