From 1443610af8aa95980c0342eab615afc96f48bc76 Mon Sep 17 00:00:00 2001 From: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Date: Tue, 10 Nov 2026 02:39:52 +0800 Subject: [PATCH 1/4] docs(setup): acquire packages outside a REA source checkout npm exec resolves a package request against a local project of the same name, so `npx rea-agents@X` run inside a REA source checkout selects the unbuilt workspace package instead of the published one. The launcher then fails with "'rea' is not recognized" before REA starts, and a client registration that runs it reports a closed connection with no REA diagnostic. The onboarding docs and the bundled skill already said to acquire from a trusted directory outside the target project. Name the source checkout as a second exclusion so the guidance covers the failure DerekMaki reported (#9685), and say what the failure looks like. --- .agents/skills/reverse-engineer-anything/SKILL.md | 5 ++++- .../references/connection-and-recovery.md | 6 +++++- README.md | 4 +++- docs/getting-started/installation.md | 3 ++- 4 files changed, 14 insertions(+), 4 deletions(-) diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md index e956f88ce85..2fddbf07ee5 100644 --- a/.agents/skills/reverse-engineer-anything/SKILL.md +++ b/.agents/skills/reverse-engineer-anything/SKILL.md @@ -70,7 +70,10 @@ 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 resolves `rea-agents` to the +local unbuilt package, so the launcher fails and the client reports a closed +connection. 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..46365eed969 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,12 @@ 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 `rea-agents` 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. 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..1a272e9882b 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,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..2fa5c952930 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1241,7 +1241,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; 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` From 6a60523414a80d3a01d6c33ff109358892d000c4 Mon Sep 17 00:00:00 2001 From: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Date: Tue, 10 Nov 2026 03:48:39 +0800 Subject: [PATCH 2/4] docs(skill): scope the npm checkout shadowing to matching requests The guidance says a checkout makes the `npx -y rea-agents@latest` fallback fail, but npm treats a specifier as a local match only for the same name and exact version: `@latest` keeps resolving the registry entry (npm 11.4 returned its own `ENOTCACHED`, not a checkout hit). Saying otherwise sends agents diagnosing a valid `@latest` launch down the wrong recovery path. --- .agents/skills/reverse-engineer-anything/SKILL.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md index 2fddbf07ee5..93507eb7ecd 100644 --- a/.agents/skills/reverse-engineer-anything/SKILL.md +++ b/.agents/skills/reverse-engineer-anything/SKILL.md @@ -71,9 +71,12 @@ 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 and outside any REA source checkout, -with absolute target paths. Inside a checkout npm resolves `rea-agents` to the -local unbuilt package, so the launcher fails and the client reports a closed -connection. Managed +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 From 32b99523a7eaa8f86eeba9920566cf75842f90b0 Mon Sep 17 00:00:00 2001 From: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Date: Tue, 10 Nov 2026 15:40:50 +0800 Subject: [PATCH 3/4] docs(setup): qualify the checkout shadowing by request version The warning was placed only beside the mcp add aside, over 1,200 lines below the first setup command, so the primary onboarding path could hit the shadowing before ever seeing it. State the exclusion next to the Start setup command as well. The recovery reference still described the checkout as unconditionally shadowing the launch. npm only treats a package as a local match for an unversioned request or one naming the checkout's exact version; an @latest request resolves the registry entry, which is the form SKILL.md recommends. --- .../references/connection-and-recovery.md | 8 +++++--- docs/getting-started/installation.md | 10 ++++++---- 2 files changed, 11 insertions(+), 7 deletions(-) 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 46365eed969..0d168963cc7 100644 --- a/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md +++ b/.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md @@ -161,9 +161,11 @@ installation’s absolute runtime and entry script, or continue through the CLI. 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 `rea-agents` 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. +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/docs/getting-started/installation.md b/docs/getting-started/installation.md index 2fa5c952930..4316de6d0eb 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). @@ -1242,7 +1244,7 @@ registrations. See [Windows Ghidra P0](../providers/windows-ghidra-p0.md) for pr The separate `rea mcp add` builtin delegates most clients to Incur's package-runner child launcher. Run that acquisition from a trusted directory outside any REA -source checkout; prefer managed +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` From 4b53aa25f1f4cf6f8cfcc25a5ceb2a7dc2d29fb9 Mon Sep 17 00:00:00 2001 From: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Date: Tue, 10 Nov 2026 16:45:55 +0800 Subject: [PATCH 4/4] docs(setup): pin the public setup commands to the published release The warning next to Start setup only helps a reader who got that far. The README hero and the website quick start still ran an unversioned npx rea-agents, which inside a source checkout matches the local unbuilt package and fails before REA starts. Pin those commands to @latest so they resolve the published release from any directory, and say why in the hero note. --- README.md | 6 +++++- docs/getting-started/installation.md | 4 +++- docs/index.md | 7 +++++-- 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1a272e9882b..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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 4316de6d0eb..d89f75bb5a9 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1956,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.