From d85b661be80bd19d477c46ebe0501839c7b63ee7 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 12 Jul 2026 22:28:10 +0000 Subject: [PATCH] docs: simplify REA onboarding --- README.md | 50 ++++++++++++++++++++++----------- skills/rea-analysis/SKILL.md | 4 +-- tests/readmeConsistency.test.ts | 8 ++++++ 3 files changed, 44 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 2ff10e445..b57d7e004 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,8 @@ npx skills add morluto/rea Then ask: ```text -Set up REA and reverse engineer the Notes app. Explain how search works, -show me how you know, and build a similar feature for my project. +Use REA to understand how search works in the Notes app, show me the +evidence, and build a similar feature for my project. ``` Notes is only an example. Name any app you want to understand, or ask the agent to start with an overview. @@ -89,30 +89,35 @@ npx skills add morluto/rea Ask your agent to set up REA. It will check your Mac, explain anything it needs to install, ask for approval, and guide you through system prompts. After setup, restart the agent if it asks you to load the full REA toolset. -### From Terminal +Approve installation if needed, complete the one-time activation when prompted, then describe the app or feature you want to understand. REA handles the binary-analysis tools behind the scenes. + +### From Terminal — no installation ```bash npx -y rea-agents setup --yes +npx -y rea-agents doctor +npx -y rea-agents analyze /Applications/Notes.app ``` If macOS or an installer asks for confirmation, complete the prompt and run the same command again. Restart a configured coding agent so it loads REA. -### What setup handles +### From Terminal — install the `rea` command + +```bash +npm install --global rea-agents +rea setup --yes +rea doctor +rea analyze /Applications/Notes.app +``` + +Choose either the no-install commands or the global installation. You do not need both. + +### Requirements - macOS 12 or newer -- Node.js 24.18.x with npm 11.16.x (`nvm use` selects the pinned version) +- Node.js 24.18.x with npm 11.16.x -If process capture reports that its native PTY backend is unavailable, install Xcode command-line tools and run `npm run rebuild:native`. Linux source builds require Python, `make`, and a C++ toolchain. Compatible packaged binaries do not require this rebuild. - -Process capture is disabled by default. Enabling it requires -`REA_PROCESS_CAPTURE_ENABLED=true`, approved executable and working roots in -`REA_PROCESS_EXECUTABLE_ROOTS_JSON` and `REA_PROCESS_WORKING_ROOTS_JSON`, and an -environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. The current PTY adapter -uses host networking, so it additionally requires the explicit operator grant -`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`. Without that grant the adapter -refuses to launch; loopback replay alone does not constitute network isolation. - -You do not need to install the reverse-engineering tools manually. Setup installs Homebrew and [Hopper](https://www.hopperapp.com/) when needed, configures detected Claude Desktop and Cursor installations, and installs the REA skill. Hopper is separate software and requires its own license; setup installs it but does not provide a license. +You do not need to choose or install binary-analysis tools yourself. REA setup handles them when needed. Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate Mac app with its own license. REA can install it, but you must approve the installation and complete its one-time activation. If something is not working, run: @@ -294,6 +299,19 @@ REA derives explicit format and architecture arguments to prevent common FAT and Closing a REA session shuts down its bridge and removes its private socket directory. It does not quit a Hopper application the user may be using. +## Advanced process-capture setup + +Process capture is disabled by default. Enabling it requires +`REA_PROCESS_CAPTURE_ENABLED=true`, approved executable and working roots in +`REA_PROCESS_EXECUTABLE_ROOTS_JSON` and `REA_PROCESS_WORKING_ROOTS_JSON`, and an +environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY +adapter uses host networking, it also requires +`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`. + +If the native PTY backend is unavailable, install Xcode command-line tools and +run `npm run rebuild:native`. Linux source builds require Python, `make`, and a +C++ toolchain. Compatible packaged binaries do not require this rebuild. + ## Security model REA does not provide a hosted analysis service. Hopper communication uses an authenticated private local socket. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. REA is not a security sandbox: providers and launched targets run with the current user's permissions, and each capability reports its side effects and limitations. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md). diff --git a/skills/rea-analysis/SKILL.md b/skills/rea-analysis/SKILL.md index f316fe0da..45e0dae15 100644 --- a/skills/rea-analysis/SKILL.md +++ b/skills/rea-analysis/SKILL.md @@ -21,8 +21,8 @@ Notes is only a documentation example. Never select an app unless the user names ## Ensure REA is ready 1. Run `npx -y rea-agents doctor`. -2. If setup is needed, explain that REA may install Homebrew and Hopper. Hopper is separate software and requires its own license. -3. Obtain approval before installing external software, then run `npx -y rea-agents setup --yes`. +2. If setup is needed, tell the user REA needs to install its local binary-analysis tools. Do not lead with implementation details or assume the user knows reverse-engineering products. +3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents setup --yes`. 4. If macOS or an installer requests human input, tell the user exactly what needs attention. After they finish, rerun setup and doctor. 5. If setup registers a new MCP server, tell the user to restart their coding agent to load all REA tools. Direct CLI commands remain available before restart. diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.ts index 0eac0b074..5af523905 100644 --- a/tests/readmeConsistency.test.ts +++ b/tests/readmeConsistency.test.ts @@ -43,4 +43,12 @@ describe("localized README product facts", () => { ); }, ); + + it("keeps both English CLI onboarding paths discoverable", async () => { + const content = await readFile(resolve("README.md"), "utf8"); + expect(content).toContain("npx -y rea-agents analyze"); + expect(content).toContain("npm install --global rea-agents"); + expect(content).toContain("rea setup --yes"); + expect(content).toContain("You do not need both"); + }); });