rea-agents 4.1.0 → 5.0.0

package/README.md

@@ -17,6 +17,8 @@
 
 <a href="https://trendshift.io/repositories/82054?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-82054" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/82054" alt="morluto%2Frea | Trendshift" width="250" height="55"/></a>
 
+**[Website](https://morluto.github.io/rea/) · [Guides](https://morluto.github.io/rea/guides/) · [Showcases](https://morluto.github.io/rea/showcase/)**
+
 [Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <code>npx rea-agents setup</code>
@@ -51,49 +53,6 @@ REA connects your agent to tools for inspecting native binaries, JavaScript and
 
 Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper or Ghidra installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs neither engine.
 
-## Just ask your agent
-
-After [setup](#quick-start), restart your agent and ask:
-
-```text
-Understand how search works in the Notes app, show me the evidence, and build a
-similar feature for my project.
-```
-
-Replace Notes with the app you want to understand, or ask for an overview first.
-
-## The investigation model
-
-<table>
-<tr>
-<td width="33%" valign="top">
-<strong>Decompile</strong><br /><br />
-Open an app and recover readable code, strings, names, and other clues about how it works.
-</td>
-<td width="33%" valign="top">
-<strong>Understand</strong><br /><br />
-Follow the code from one part of the app to another until the agent can explain how a feature actually works.
-</td>
-<td width="33%" valign="top">
-<strong>Recreate</strong><br /><br />
-Turn what the agent learned into a feature for your own product, adapted to your stack, interface, and requirements.
-</td>
-</tr>
-</table>
-
-REA shows how it reached its conclusions. It does not claim to recover original source code or automatically clone an application.
-
-## Why REA
-
-|                          |                                                                                                       |
-| ------------------------ | ----------------------------------------------------------------------------------------------------- |
-| **Built for agents**     | Ask what an app does and let your agent inspect it instead of guessing.                               |
-| **CLI and MCP**          | Run the same reverse-engineering capabilities from your terminal or agent.                            |
-| **Guided setup**         | Configure your agent, connect an existing analysis tool, or install Hopper with your approval.        |
-| **From insight to code** | Understand a feature, then build your own version in the same coding session.                         |
-| **Local by design**      | Analysis runs on your supported local host. REA does not upload the app to a hosted analysis service. |
-| **Keeps context**        | Investigate several apps without starting over for every question.                                    |
-
 ## Quick start
 
 ### Run setup (recommended)
@@ -108,25 +67,21 @@ Choose which supported agents should use REA, then review the exact paths and ch
 
 Setup shows its changes before applying them and backs up existing configuration. See [Installation and setup](docs/installation.md) for requirements and setup options.
 
-### With an agent (recommended)
-
-After setup, restart your agent and [describe the app or feature](#just-ask-your-agent) you want to understand. Hopper can run in demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.
-
-REA supports Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin, OpenCode, Antigravity, GitHub Copilot CLI, Command Code, and VS Code. Existing REA registrations are selected by default during setup; other detected agents remain unselected until chosen. Other agents can use the [manual MCP configuration](#manual-mcp-configuration).
+### AI Coding Assistants (optional)
 
-### Install the skill separately
+Add the skill to your AI coding assistant for richer context:
 
 ```bash
 npx skills add morluto/rea --skill reverse-engineer-anything
 ```
 
-This installs agent instructions, not MCP registration or analysis engines.
-Follow the skill's [conditional connection guide](skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed):
-prepare a scoped `npx rea-agents setup` plan if registration is missing, review
-and approve its actual changes, then restart/reconnect and verify the tools.
-Guided setup above installs a version-matched skill by default. The skills.sh
-route uses repository instructions, which can be ahead of the released server;
-see [released package and main](docs/installation.md#released-package-and-main).
+The skill provides REA's investigation workflow. Run setup above to connect REA to your agent and configure analysis tools. Setup already installs a version-matched skill by default; this command installs the repository version.
+
+### With an agent (recommended)
+
+After setup, restart your agent and [describe the app or feature](#just-ask-your-agent) you want to understand. Hopper can run in demo mode; if it shows a first-run prompt, choose the demo or enter an existing license.
+
+REA supports Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin, OpenCode, Antigravity, GitHub Copilot CLI, Command Code, and VS Code. Existing REA registrations are selected by default during setup; other detected agents remain unselected until chosen. Other agents can use the [manual MCP configuration](#manual-mcp-configuration).
 
 ### First result from the terminal
 
@@ -142,6 +97,40 @@ MCP setup, Hopper, Ghidra, or executing the application. For a native app, confi
 its engine first, then use `analyze` with that app's path. Run `doctor` when you
 need diagnosis; it is not a prerequisite for each analysis.
 
+### Check readiness for the task at hand
+
+`rea doctor` without options is an audit of the whole integration. It checks
+every detected agent registration, the installed skill, and every optional
+analysis engine, so it can report `healthy: false` while your current task works.
+Choose a readiness scope for the work you are doing:
+
+| Task                                | Readiness check                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------------- |
+| Static JavaScript/Electron analysis | None. Run `analyze-javascript-application` directly.                                         |
+| Troubleshoot one analysis engine    | `rea doctor --provider ghidra --json` (or `hopper`, `ida`)                                   |
+| Check one agent's MCP registration  | `rea doctor --client codex --json` (see [client IDs](docs/installation.md#supported-agents)) |
+| Check the installed skill           | `rea doctor --skill --json`                                                                  |
+
+A scoped report has `scope.mode: "explicit"`. Only `scope_checks` determine
+`healthy` and the exit status. Everything else is listed in
+`informational_checks`; you don't need to fix it for this task. For example, a
+missing engine you are not using needs no repair. `environment_healthy` still
+summarizes the full audit. `--target` adds a target check, but without a scope
+option the report remains audit-wide.
+
+When more than one installed engine supports a native target, REA does not pick
+one: opening the target fails with `code: "capability_unavailable"`,
+`details.selection_reason: "ambiguous"`, and the providers in
+`details.candidate_ids`. Choose one once: pass `--provider` on
+the CLI or `provider_id` on `open_binary`, or set `REA_ANALYSIS_PROVIDER` as a
+standing preference. An explicit selector overrides the environment variable.
+The session keeps that choice and never falls back to another engine.
+Recovery depends on `details.selection_reason`. For `ambiguous`, choose one of
+the candidates. For `provider_unavailable`, the engine you selected needs repair,
+so run `rea doctor --provider <id> --json` and follow its remediation. Neither
+reason means you have to install every engine. See
+[Choosing a deep-analysis provider](#choosing-a-deep-analysis-provider).
+
 ### Install the rea command
 
 Install the command-line interface:
@@ -168,7 +157,7 @@ external-tool prerequisites depend on the selected workflow; the native
 provider guides describe their supported platforms.
 
 - macOS 12 or newer
-- Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
+- Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, or CachyOS
 - Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+
 - npm; REA does not require or install a particular npm version
 
@@ -176,9 +165,9 @@ Deep native binary analysis requires [Hopper](https://www.hopperapp.com/), [Ghid
 
 Firmware region inspection and explicit extraction use caller-supplied Binwalk and Unblob on Linux. See [Firmware analysis](docs/firmware-analysis.md) for setup, provenance, resource limits and native handoff.
 
-Static APK analysis uses a separately supplied headless JADX JAR and Java, with no emulator or APK execution. See [Android analysis](docs/android-analysis.md) for setup, CLI/MCP operations, coverage and public test fixtures.
+Static APK analysis uses a separately supplied headless JADX JAR and a full JDK, with no emulator or APK execution. See [Android analysis](docs/android-analysis.md) for setup, CLI/MCP operations, coverage and public test fixtures. Authenticated IPA and macOS `.app`, ZIP, or DMG inventory Evidence can be projected into bundle anatomy, such as XPC services, app extensions, login items, privileged helpers, and launchd plists, with [Apple application analysis](docs/apple-application-analysis.md).
 
-Repository main includes experimental Windows x64 Ghidra support for native x86-64 PE applications on local NTFS, with bundled Job Object, private-DACL, and path-admission controls. Check the [release boundary](docs/installation.md#released-package-and-main) before expecting this from an npm package. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
+Repository main and npm 4.1.0 include experimental Windows x64 Ghidra support for native x86-64 PE applications on local NTFS, with bundled Job Object, private-DACL, and path-admission controls. Check the [release boundary](docs/installation.md#released-package-and-main) before expecting this from an older npm package. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
 
 If something is not working, run:
 
@@ -194,7 +183,7 @@ On macOS, setup can install Hopper in `~/Applications` after approval. It verifi
 
 On supported Linux distributions, setup can install Hopper and its demo-session dependencies through your system package manager. You may see a system authorization prompt. Demo sessions use a private virtual display, leaving your desktop alone. See [Hopper installation](docs/installation.md#hopper) for download verification and platform details.
 
-The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
+REA prefers an executable `/opt/hopper/bin/Hopper` on Linux. If it is unavailable, REA automatically checks `~/.local/share/rea/hopper/bin/Hopper`. If Hopper was installed elsewhere:
 
 ```bash
 export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
@@ -204,16 +193,16 @@ rea doctor --json
 If doctor reports a missing analysis engine even though the file exists, inspect shared-library resolution with:
 
 ```bash
-ldd /opt/hopper/bin/Hopper | grep 'not found'
+ldd /absolute/path/to/Hopper | grep 'not found'
 ```
 
 Install the missing packages and rerun `rea setup`. The Linux demo needs Xvfb, Python 3, X11, and XTEST; approved setup installs these dependencies. If you use the curl installer, add `~/.local/bin` to your shell `PATH` when needed.
 
-REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` on macOS and `/opt/hopper/bin/Hopper` on Linux. Explicit configuration always takes precedence.
+REA uses `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` by default on macOS. On Linux it prefers executable `/opt/hopper/bin/Hopper`, then executable `~/.local/share/rea/hopper/bin/Hopper`, and keeps `/opt/hopper/bin/Hopper` as the diagnostic fallback if neither exists. Explicit `HOPPER_LAUNCHER_PATH` configuration always takes precedence.
 
 ### Ghidra analysis provider
 
-Already use Ghidra? REA can connect it to your agent on Linux x64 or macOS x64/arm64. It requires **Ghidra 12.1.4** and a **64-bit JDK 21**. On macOS, your Ghidra installation must also include the native decompiler for your architecture.
+Already use Ghidra? REA can connect it to your agent on Linux x64 or macOS x64/arm64. It accepts **Ghidra 12.1.x** and the **64-bit full JDK** that installation declares (`application.java.min` through `application.java.max`). Current 12.1 releases require JDK 21 or newer and set no maximum. The bridge is verified with Ghidra 12.1.4 and JDK 21. On macOS, your Ghidra installation must also include the native decompiler for your architecture.
 
 Set the installation paths, then run setup:
 
@@ -297,6 +286,11 @@ Import an older source tree as a reference. REA keeps it separate from observati
 rea import-reference-source /absolute/path/to/source
 ```
 
+Historical-source import requires safe no-follow file opens and currently runs
+on Linux and macOS. Native Windows reports `unsupported_host`; run the import
+with Linux REA in WSL or on another supported host. Changing permissions or
+reinstalling REA does not enable this Windows workflow.
+
 Imports read the path supplied to the command. File names do not cause automatic omissions; files are represented by hashes and metadata. To exclude selected paths, set `REA_REFERENCE_SECRET_PATTERNS_JSON` to a JSON string array of ignore patterns. Exports never replace an existing file unless `--overwrite` is explicit.
 
 Use a snapshot to save successful analysis results and reuse them on later runs. REA reuses a result only when the target bytes, operation, parameters, analysis tool, and settings match. It does not cache changes or cursor-dependent calls. Snapshot files stay local and use owner-only permissions.
@@ -314,6 +308,49 @@ result is returned. Pass `snapshot_path` and, when required, `overwrite: true` t
 `close_binary` to save atomically before Hopper resources are released. If the
 save fails, REA deliberately leaves the session open.
 
+## Just ask your agent
+
+After [setup](#quick-start), restart your agent and ask:
+
+```text
+Understand how search works in the Notes app, show me the evidence, and build a
+similar feature for my project.
+```
+
+Replace Notes with the app you want to understand, or ask for an overview first.
+
+## The investigation model
+
+<table>
+<tr>
+<td width="33%" valign="top">
+<strong>Decompile</strong><br /><br />
+Open an app and recover readable code, strings, names, and other clues about how it works.
+</td>
+<td width="33%" valign="top">
+<strong>Understand</strong><br /><br />
+Follow the code from one part of the app to another until the agent can explain how a feature actually works.
+</td>
+<td width="33%" valign="top">
+<strong>Recreate</strong><br /><br />
+Turn what the agent learned into a feature for your own product, adapted to your stack, interface, and requirements.
+</td>
+</tr>
+</table>
+
+REA shows how it reached its conclusions. It does not claim to recover original source code or automatically clone an application.
+
+## Why REA
+
+|                          |                                                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- |
+| **Built for agents**     | Ask what an app does and let your agent inspect it instead of guessing.                               |
+| **CLI and MCP**          | Run the same reverse-engineering capabilities from your terminal or agent.                            |
+| **Guided setup**         | Configure your agent, connect an existing analysis tool, or install Hopper with your approval.        |
+| **From insight to code** | Understand a feature, then build your own version in the same coding session.                         |
+| **Local by design**      | Analysis runs on your supported local host. REA does not upload the app to a hosted analysis service. |
+| **Keeps context**        | Investigate several apps without starting over for every question.                                    |
+
 ## One prompt, a full investigation
 
 ```text
@@ -334,6 +371,21 @@ REA gives the agent a clear path from that request to working code:
 
 REA handles the app analysis in steps 1 through 5. The agent performs step 6 with its normal file-editing and test tools, using what it learned about the app.
 
+## Showcase
+
+### DX-Ball: game reconstruction (in progress)
+
+[DX-Ball](https://github.com/N0zoM1z0/dx-ball) follows the journey from a classic
+Windows game's executable to maintainable C. Using REA's Ghidra provider, the
+project traces functions, game state and dependencies, then checks reconstructed
+behavior with original-x86 differential tests and pinned-compiler replay.
+
+A [sound-pan investigation](https://github.com/N0zoM1z0/dx-ball/blob/main/docs/GAMEPLAY_OWNER.md)
+turns incomplete pseudocode into a C implementation that passes 3,205 original-x86
+cases and reproduces all 63 compiled function bytes. Follow its
+[REA workflow](https://github.com/N0zoM1z0/dx-ball/blob/main/docs/REA.md)
+from binary evidence to reconstruction.
+
 ## What agents can do
 
 - Investigate a feature you like and build a version tailored to your own product.
@@ -349,20 +401,20 @@ See [native investigation](docs/native-investigation.md) for keyed archives, ins
 
 ## Tool catalog for investigation
 
-| Tool family               | Count | Examples                                                                                                                                                  |
-| ------------------------- | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Native inspection         |    41 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets                                           |
-| Investigation workflows   |    14 | app overviews, function dossiers, native APIs and dispatch, batch decompilation, feature traces, call paths, call graphs, Swift and Objective-C discovery |
-| Native macOS utilities    |     7 | Mach-O metadata, code signatures, plists, architectures, and Swift demangling without launching Hopper                                                    |
-| Artifact graph            |     5 | directory and package inventories, compiled Interface Builder files, Apple asset catalogs, and extraction                                                 |
-| Managed PE/CLI            |     7 | .NET identity, metadata, CIL instructions, native dependencies, reconstruction imports, and build comparisons                                             |
-| Firmware                  |     2 | Linux firmware region inspection and explicit extraction                                                                                                  |
-| Android APK               |     5 | package and manifest declarations, class search, member inventories, method decompilation, and incoming static references                                 |
-| Browser observation       |     9 | page structure, network metadata, scripts, source maps, WebMCP discovery, screenshots, and capture comparisons                                            |
-| Electron analysis         |     5 | renderer observation, static app mapping, and static/runtime reconciliation                                                                               |
-| JavaScript runtime        |     2 | Node/Electron Inspector target discovery, script locations, and execution-context events                                                                  |
-| Application workflows     |     7 | cross-layer feature traces, build comparisons, historical source mapping, static return-shape comparison, and reconstruction checks                       |
-| Workspace and observation |    21 | sessions, evidence bundles, navigation context, process/artifact/function comparisons, and open-question tracking                                         |
+| Tool family               | Count | Examples                                                                                                                                                                                                 |
+| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Native inspection         |    41 | functions, pseudocode, assembly, strings, symbols, calls, references, annotations, byte reads, and file offsets                                                                                          |
+| Investigation workflows   |    14 | app overviews, function dossiers, native APIs and dispatch, batch decompilation, feature traces, call paths, call graphs, Swift and Objective-C discovery                                                |
+| Native macOS utilities    |     7 | Mach-O metadata, code signatures, plists, architectures, and Swift demangling without launching Hopper                                                                                                   |
+| Artifact graph            |     5 | directory and package inventories, compiled Interface Builder files, Apple asset catalogs, and extraction                                                                                                |
+| Managed PE/CLI            |     7 | .NET identity, metadata, CIL instructions, native dependencies, reconstruction imports, and build comparisons                                                                                            |
+| Firmware                  |     2 | Linux firmware region inspection and explicit extraction                                                                                                                                                 |
+| Android APK               |     5 | package and manifest declarations, class search, member inventories, method decompilation, and incoming static references                                                                                |
+| Browser observation       |    11 | page structure, network metadata, scripts, source maps, WebMCP discovery, screenshots, and capture comparisons                                                                                           |
+| Electron analysis         |     5 | renderer observation, static app mapping, and static/runtime reconciliation                                                                                                                              |
+| JavaScript runtime        |     2 | Node/Electron Inspector target discovery, script locations, and execution-context events                                                                                                                 |
+| Application workflows     |    13 | captured website script export; Android/Apple inventory projections; cross-layer feature traces, build comparisons, historical source mapping, static return-shape comparison, and reconstruction checks |
+| Workspace and observation |    21 | sessions, evidence bundles, navigation context, process/artifact/function comparisons, and open-question tracking                                                                                        |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness records direct behavioral captures.
 
@@ -370,12 +422,37 @@ The public interface describes what the agent is trying to learn. Providers deci
 
 REA supports native application, JavaScript, Electron, .NET, and browser investigation on macOS and Linux. Individual tools have platform and runtime prerequisites. `rea capabilities` and `rea providers` describe the binary-session providers and auxiliary operations; they are not an inventory of every browser, Android, or application workflow. Use the connected MCP tool list and `binary_session` tool availability for the full MCP surface, and the relevant guide for each tool's prerequisites. Repository main can be ahead of [the npm release](docs/installation.md#released-package-and-main).
 
-Static Android APK inspection is verified on Linux with headless JADX; see [Android analysis](docs/android-analysis.md) for its separate prerequisites and coverage.
+Static Android APK inspection supports Linux and macOS; the current metadata bridge is verified on macOS arm64 with headless JADX; see [Android analysis](docs/android-analysis.md) for its separate prerequisites and coverage.
 
 - **Native binaries:** Open Mach-O, ELF, PE, and Mac `.app` targets through a selected deep provider. Hopper and Ghidra cover broad inventory and function analysis; the IDA adapter supplies its documented read-only function/string operations. Hopper also accepts `.hop` databases and supports annotations.
 - **Packages and resources:** Inspect directories, ZIP, APK, IPA, ASAR, plists, compiled Interface Builder files, and Apple asset catalogs. Artifact requests name the input and requested extraction or traversal directly; macOS DMG traversal also requires the host's native mounting support.
 - **JavaScript and Electron:** Map modules, imports, source maps, routes, IPC channels, storage, and native add-ons without running the app. Compare builds and trace a feature across the recovered graph. Dynamic and ambiguous relationships remain unresolved. See [JavaScript application workflows](docs/javascript-application-workflows.md).
 - **Websites:** Inspect a selected page in an existing Chrome-family browser. Capture page structure, network metadata, script evidence, and screenshots requested by the call. Passive observation does not navigate or execute page JavaScript. See [browser observation](docs/browser-observation.md).
+
+  Export retained scripts with `export_web_scripts` / `rea export-web-scripts`
+  into a verified local directory, then use the existing JavaScript analysis
+  and tracing tools. Source URLs, frame or transaction references, competing
+  versions, and missing-source states remain inline. See
+  [captured website scripts](docs/website-script-export.md).
+  Inspect a selected node's listener sources or observe an externally triggered
+  execution window with `inspect_web_event_listeners` / `observe_web_execution`.
+  Precise coverage resets counters and affects optimized execution; see
+  [website runtime attribution](docs/web-runtime.md).
+  Trace one exported script's native imports with `trace_web_module_imports` /
+  `rea trace-web-module-imports`, preserving query/fragment identity and optional
+  import-map context. Requires caller-supplied Chromium via
+  `REA_BROWSER_EXECUTABLE`; see [module relationships](docs/website-module-trace.md).
+
+- **Source locations:** Trace one retained website script point through a selected
+  local source map with `rea trace-web-source-location`. See
+  [captured website source locations](docs/web-source-location.md) for byte
+  identities, embedded original content and coverage limits.
+  Recover readable modules from selected local bundles with
+  `recover_javascript_sources` / `rea recover-javascript-sources`, then pass
+  the returned `analysis_input` to static analysis. This optional Linux x64
+  adapter requires caller-supplied Wakaru 1.13.0; see
+  [JavaScript source recovery](docs/javascript-recovery.md).
+
 - **Electron and Node runtime observation:** Inspect selected Electron pages or attach to a Node/Electron V8 Inspector target. Inspector observation records script locations and execution-context events; it does not infer imports, IPC activity, or which modules executed. See [runtime observation](docs/javascript-runtime-observation.md).
 - **.NET assemblies:** Inspect metadata and CIL instructions, compare builds, and check declared native dependencies without loading or running the assembly. Imported decompiler output is labeled as analyst inference. See [managed-code analysis](docs/managed-code-analysis.md).
 - **Controlled behavior capture:** Run process, browser, or Electron scenarios with the target, actions, and lifecycle declared in each request, then compare the resulting evidence. Missing observations cannot establish that two runs behaved the same way.
@@ -457,7 +534,7 @@ The [current status](#current-status) section describes shipped capabilities. Th
 
 1. **Expand browser and Electron interaction:** add scenario actions beyond the current click and wait operations.
 2. **Observe native apps at runtime:** explore LLDB, Frida, system logs, and native API tracing.
-3. **Evaluate more tools and targets:** assess IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, Windows-native tools, mobile apps, and firmware.
+3. **Evaluate more tools and targets:** assess Binary Ninja, Rizin, LIEF, Windows-native tools, mobile apps, and firmware. IDA support already ships via the bring-your-own upstream adapter; see the [IDA provider guide](docs/ida-provider.md).
 
 Setup already lets you choose agent integration and Hopper installation. Support for installing additional analysis tools is future work, described in the [installation roadmap](docs/roadmap.md).
 
@@ -476,7 +553,7 @@ Setup offers supported agent integrations for selection. Existing REA registrati
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@4.1.0", "mcp"]
+      "args": ["-y", "rea-agents@5.0.0", "mcp"]
     }
   }
 }
@@ -630,9 +707,9 @@ Process Capture records behavior and is not a security sandbox.
 Capture a scenario or compare two saved Process Capture Evidence records:
 
 ```bash
-rea capture-process ./scenario.json > authority.json
-rea capture-process ./reconstruction.json > reconstruction.json
-rea compare-process-captures authority.json reconstruction.json
+rea capture-process ./authority-scenario.json --json > authority-capture.json
+rea capture-process ./reconstruction-scenario.json --json > reconstruction-capture.json
+rea compare-process-captures authority-capture.json reconstruction-capture.json --json
 ```
 
 The comparison reports each observed dimension separately and identifies the
@@ -640,9 +717,16 @@ first terminal, interaction, exit, filesystem, or process divergence.
 See [Process Capture](docs/process-capture.md) for scenario fields, limits, and
 evidence boundaries.
 
-REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows
-architectures. If the capability check reports that the backend is unavailable,
-reinstall REA for the current platform and architecture.
+Process Capture currently runs on Linux and macOS with a working native PTY
+backend. Native Windows capture remains unavailable until the PTY adapter can
+verify descendant cleanup; installing or reinstalling its Windows PTY binary
+does not enable capture. For Linux commands, run Linux REA inside WSL.
+Comparing existing capture Evidence remains available on Windows.
+
+On supported capture hosts, a missing or incompatible PTY binary can be fixed
+by reinstalling REA for the current platform, architecture, and Node.js version
+with optional dependencies enabled. Use separate scenario and output files;
+`--json` produces the JSON consumed by the comparison command.
 
 ASAR inventory verifies Electron integrity metadata for both archive entries
 and `.asar.unpacked` companion files. Integrity failures identify the logical
@@ -727,3 +811,17 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution ch
 ## License
 
 [MIT](LICENSE)
+
+## Star history
+
+<a href="https://www.star-history.com/?repos=morluto%2Frea&amp;type=date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=morluto/rea&amp;type=date&amp;theme=dark&amp;legend=top-left" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=morluto/rea&amp;type=date" />
+    <img alt="REA GitHub star history" src="https://api.star-history.com/chart?repos=morluto/rea&amp;type=date" />
+  </picture>
+</a>
+
+## Disclaimer
+
+REA provides tools for lawful reverse-engineering research, analysis, and reconstruction. You are responsible for obtaining any required authorization and complying with applicable laws. The project does not endorse illegal or unauthorized use.