Skip to content

docs(setup): acquire packages outside a REA source checkout #9695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
2SinceJuly wants to merge 5 commits into
base: main
Choose a base branch
from
+37 −11
Open

docs(setup): acquire packages outside a REA source checkout #9695

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1443610
docs(setup): acquire packages outside a REA source checkout
2SinceJuly Nov 9, 2026
6a60523
docs(skill): scope the npm checkout shadowing to matching requests
2SinceJuly Nov 9, 2026
ef9bc15
Merge remote-tracking branch 'origin/main' into pr-9695
2SinceJuly Nov 10, 2026
32b9952
docs(setup): qualify the checkout shadowing by request version
2SinceJuly Nov 10, 2026
4b53aa2
docs(setup): pin the public setup commands to the published release
2SinceJuly Nov 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion .agents/skills/reverse-engineer-anything/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,

@chatgpt-codex-connector chatgpt-codex-connector Bot Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include satisfying ranges in the shadowing diagnosis

When an MCP registration uses a semver range satisfied by the checkout's 6.8.0 version (for example rea-agents@^6.8.0), npm still selects the local checkout, but this new only qualifier tells the agent to rule that cause out. npm 11.4.2's implementation explicitly handles a “package requested by version range” by returning the local node when semver.satisfies(...); with the installed npm 11.4.2, an offline run here likewise ended in rea: not found for @^6.8.0 while @latest attempted the registry. This range branch/runtime result is fresh evidence beyond the earlier exact-version thread; include satisfying ranges here and in the matching recovery reference so these closed connections are not misdiagnosed.

AGENTS.md reference: AGENTS.md:L31-L33

Useful? React with 👍 / 👎.

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
Expand Down
8 changes: 7 additions & 1 deletion .agents/skills/reverse-engineer-anything/references/connection-and-recovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines 94 to +97

@chatgpt-codex-connector chatgpt-codex-connector Bot Nov 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Cover the remaining public setup entry points

When a contributor starts from the prominent README command at line 27 or the website command at docs/index.md:31, they can run npx rea-agents setup from a checkout before ever seeing this warning; the guide's linked package-runner section at docs/getting-started/installation.md:1957-1960 also retains only the older “outside the target project” advice. npm 11's exec documentation says an unversioned package name is matched to whatever version exists in the local project, so all of these public entry paths still reproduce the launcher failure this patch is meant to prevent. Put the exclusion beside those commands or use the unaffected @latest form there.

AGENTS.md reference: AGENTS.md:L31-L33

Useful? React with 👍 / 👎.

@2SinceJuly 2SinceJuly Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 4b53aa25: README.md:27 and docs/index.md:31 now run npx rea-agents@latest setup, which resolves the registry entry even when the cwd sits inside a checkout. The README hero also states the exclusion next to the command, and docs/getting-started/installation.md "Package runners and global installation" now names the source checkout alongside the target project.

Leaving the in-checkout shadowing pinned by request version (not an unconditional failure) is intentional — it is what 32b99523 established and npm 11 matches a local package only for an unversioned or exact-version request.

Verified locally: tests/boundary/filesystem/documentationFacts.test.ts and tests/conformance/readmeConsistency.test.ts pass (10 tests); npx oxfmt --check clean on the three touched files. Translations under docs/readme/ are synced in their own batch and were not touched here.


Setup supports Claude Code, Codex, Cursor, Gemini CLI, Grok Build and
[other agents](docs/getting-started/installation.md#supported-agents). See
Expand Down
11 changes: 7 additions & 4 deletions docs/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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`
Expand Down
Loading