rea-agents 4.0.1 → 5.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rea-agents",
   "mcpName": "io.github.morluto/rea",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -35,15 +35,19 @@
     "rea-agents": "scripts/rea.mjs"
   },
   "engines": {
-    "node": "^22.19.0 || >=24.11.0"
+    "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
   },
   "packageManager": "npm@11.16.0",
   "files": [
     "dist",
     "install.sh",
     "bridge/hopper_bridge.py",
+    "bridge/native/NativeUIChildren.swift",
     "bridge/native/ReaNativeUI.swift",
     "bridge/ghidra/ReaGhidraBridge.java",
+    "bridge/ghidra/ReaGhidraExtensions.java",
+    "bridge/ghidra/ReaGhidraPrepareCom.java",
+    "bridge/android/ReaJadxBridge.java",
     "scripts/rea.mjs",
     "scripts/electron-active-hook.cjs",
     "scripts/electron-active-hook-boundaries.cjs",
@@ -52,7 +56,10 @@
     "scripts/prepare.mjs",
     "skills",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "native/windows/build/manifest.json",
+    "native/windows/build/rea-windows-x64.node",
+    "scripts/verify-windows-native-artifact.mjs"
   ],
   "scripts": {
     "deps:check": "node scripts/check-dependency-install.mjs",
@@ -73,16 +80,15 @@
     "precheck:test": "npm run deps:check",
     "check:test": "turbo run typecheck lint format:check knip metadata:check test:run",
     "precheck:pr": "npm run deps:check",
-    "check:pr": "turbo run typecheck lint format:check knip metadata:check test:run && npm run docs:check",
+    "check:pr": "turbo run typecheck lint format:check knip metadata:check test:run && npm run docs:check && npm run jscpd && npm run scan:todos",
     "precheck:ci": "npm run deps:check",
     "check:ci": "turbo run typecheck lint format:check knip metadata:check jscpd scan:todos",
-    "build:cached": "turbo run build",
+    "build:cached": "node scripts/check-dependency-install.mjs && turbo run build",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
+    "lint": "oxlint && npm run verify:module-boundaries",
+    "lint:fix": "oxlint --fix && npm run verify:module-boundaries",
     "knip": "knip",
-    "lint:dead": "knip",
     "jscpd": "jscpd src/ tests/",
     "scan:todos": "node scripts/scan-todos.mjs",
     "start": "node scripts/rea.mjs mcp",
@@ -115,22 +121,32 @@
     "typecheck": "tsc --noEmit",
     "verify:test-temp-hygiene": "npm run build:cached && node scripts/verify-test-temp-hygiene.mjs",
     "verify:hopper": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper.mjs",
-    "verify:apple-dispatch": "npm run build:cached && node scripts/verify-apple-dispatch.mjs",
+    "verify:apple-dispatch": "npm run build:cached && node scripts/verify/apple/dispatch.mjs",
     "verify:native-ui": "npm run build:cached && node scripts/verify-native-ui.mjs",
-    "verify:keyed-archive": "npm run build:cached && node scripts/verify-keyed-archive.mjs",
+    "verify:keyed-archive": "npm run build:cached && node scripts/verify/apple/keyed-archive.mjs",
+    "verify:macos-bundle": "npm run build:cached && node scripts/verify/apple/macos-bundle.mjs",
     "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
+    "verify:ida": "npm run build:cached && node scripts/verify-real-ida.mjs",
     "verify:ghidra:switch": "npm run build:cached && node scripts/verify-real-ghidra-switch.mjs",
     "verify:ghidra:dos": "npm run build:cached && node scripts/verify-real-ghidra-dos.mjs",
+    "verify:ghidra:com": "npm run build:cached && node scripts/verify-real-ghidra-com.mjs",
     "verify:ghidra:aarch64-jump-table": "npm run build:cached && node scripts/verify-real-ghidra.mjs --aarch64-jump-table",
-    "verify:interface-builder": "npm run build:cached && node scripts/verify-interface-builder.mjs",
+    "verify:interface-builder": "npm run build:cached && node scripts/verify/apple/interface-builder.mjs",
     "verify:ghidra:cross-format": "npm run build:cached && node scripts/verify-real-ghidra.mjs --cross-format",
     "verify:ghidra:windows": "npm run build:cached && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs",
     "verify:browser": "npm run build:cached && node scripts/verify-real-browser.mjs",
+    "verify:browser:dom": "node scripts/verify-browser-dom-destinations.mjs",
+    "verify:browser:network": "npm run build:cached && node scripts/verify-browser-network.mjs",
     "verify:electron": "npm run build:cached && node scripts/verify-real-electron.mjs",
-    "verify:inspector": "npm run build:cached && node scripts/verify-real-javascript-runtime-observation.mjs",
-    "verify:javascript-runtime": "npm run build:cached && node scripts/verify-local-javascript-runtime.mjs",
-    "verify:application-workflows": "npm run build:cached && node scripts/verify-local-application-workflows.mjs",
-    "verify:managed": "npm run build:cached && node scripts/verify-managed-conformance.mjs",
+    "verify:inspector": "npm run build:cached && node scripts/verify/inspector/runtime-observation.mjs",
+    "verify:javascript-runtime": "npm run build:cached && node scripts/verify/javascript/runtime-observation.mjs",
+    "verify:javascript:digests": "npm run build:cached && node scripts/verify/javascript/digests.mjs",
+    "verify:application-workflows": "npm run build:cached && node scripts/verify/javascript/application-workflows.mjs",
+    "verify:managed": "npm run build:cached && node scripts/verify/managed/conformance.mjs",
+    "verify:firmware": "npm run build:cached && node scripts/verify/firmware/analysis.mjs",
+    "fixtures:firmware": "node scripts/fixtures/firmware/generate.mjs",
+    "verify:android": "npm run build:cached && node scripts/verify/android/analysis.mjs",
+    "fixtures:android": "node scripts/fixtures/android/fetch.mjs",
     "verify:agent": "npm run build:cached && node scripts/verify-agent-experience.mjs",
     "verify:hopper:linux": "npm run verify:fixtures && npm run build:cached && node scripts/verify-real-hopper-linux.mjs",
     "verify:setup:linux": "npm run build:cached && node scripts/verify-linux-setup-e2e.mjs",
@@ -145,8 +161,9 @@
     "config:print": "node scripts/print-mcp-config.mjs",
     "evidence:generate": "npm run build:cached && node scripts/generate-completion-ledger.mjs",
     "evidence:check": "npm run build:cached && node scripts/generate-completion-ledger.mjs --check",
-    "docs:api": "typedoc",
-    "docs:api:cached": "turbo run docs:api",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "docs:generate": "node scripts/run-exclusive.mjs docs npm run docs:generate:unlocked",
     "docs:generate:unlocked": "npm run metadata:generate && npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && node scripts/generate-error-schema.mjs",
     "docs:check": "node scripts/run-exclusive.mjs docs turbo run docs:check:built",
@@ -154,9 +171,24 @@
     "docs:error-schema": "npm run build:cached && node scripts/generate-error-schema.mjs",
     "prepack": "node scripts/prepack.mjs",
     "prepare": "node scripts/prepare.mjs",
-    "verify:asset-catalog": "npm run build:cached && node scripts/verify-asset-catalog.mjs",
+    "verify:asset-catalog": "npm run build:cached && node scripts/verify/apple/asset-catalog.mjs",
     "verify:native-ui:permissions": "npm run build:cached && node scripts/verify-native-ui.mjs --allow-permission-denial",
-    "test:focused": "node scripts/run-development-tests.mjs focused"
+    "test:focused": "node scripts/run-development-tests.mjs focused",
+    "build:windows-native": "node scripts/build-windows-native.mjs",
+    "verify:windows-native:artifact": "node scripts/verify-windows-native-artifact.mjs",
+    "prepublishOnly": "npm run verify:windows-native:artifact",
+    "verify:windows-native": "node scripts/verify-windows-native.mjs",
+    "verify:ghidra:windows:package": "node scripts/verify-packaged-ghidra-windows.mjs",
+    "build:ghidra:nativeaot": "node scripts/build-ghidra-nativeaot.mjs",
+    "build:fixtures:nativeaot": "node scripts/generate-nativeaot-fixtures.mjs",
+    "verify:ghidra:nativeaot": "npm run build:cached && node scripts/verify-real-ghidra-nativeaot.mjs",
+    "verify:browser:scripts": "npm run build:cached && node scripts/verify-browser-scripts.mjs",
+    "verify:browser:modules": "npm run build:cached && node scripts/verify-browser-modules.mjs",
+    "verify:test-discovery": "node scripts/verify-test-discovery.mjs",
+    "verify:javascript:recovery": "node scripts/verify/javascript/recovery.mjs",
+    "verify:module-boundaries": "node scripts/verify-module-boundaries.mjs",
+    "verify:browser:source-maps": "npm run build:cached && node scripts/verify-browser-source-maps.mjs",
+    "verify:browser:runtime": "npm run build:cached && node scripts/verify-browser-runtime.mjs"
   },
   "lint-staged": {
     "*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}": [
@@ -172,48 +204,51 @@
     "@electron/asar": "4.2.0",
     "@jridgewell/trace-mapping": "0.3.31",
     "@lydell/node-pty": "1.1.0",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "@zip.js/zip.js": "2.8.26",
     "canonicalize": "3.0.0",
     "cross-spawn": "7.0.6",
     "diff": "9.0.0",
-    "graphology": "0.26.0",
-    "graphology-shortest-path": "2.1.0",
     "ignore": "7.0.6",
-    "incur": "0.4.13",
+    "incur": "0.6.1",
     "isomorphic-git": "1.38.7",
     "jsonc-parser": "3.3.1",
-    "pino": "9.14.0",
+    "pino": "10.4.0",
     "playwright-core": "1.58.2",
     "plist": "5.0.0",
     "semver": "7.8.5",
-    "smol-toml": "^1.7.0",
+    "smol-toml": "1.9.0",
     "write-file-atomic": "7.0.0",
     "ws": "8.21.0",
     "zod": "4.4.3"
   },
+  "overrides": {
+    "vitepress": {
+      "vite": "6.4.4"
+    }
+  },
   "devDependencies": {
-    "@fast-check/vitest": "0.4.1",
+    "@fast-check/vitest": "0.5.0",
     "@types/cross-spawn": "6.0.6",
-    "@types/node": "24.10.1",
+    "@types/node": "26.6.4",
     "@types/semver": "7.7.1",
     "@types/write-file-atomic": "4.0.3",
     "@types/ws": "8.18.1",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "5.0.3",
     "ajv": "8.20.0",
     "husky": "9.1.7",
     "jscpd": "5.0.12",
-    "knip": "6.26.0",
+    "knip": "6.39.0",
     "lint-staged": "16.4.0",
     "oxfmt": "0.72.0",
-    "oxlint": "1.73.0",
-    "turbo": "2.10.5",
-    "typedoc": "0.28.20",
-    "typescript": "5.9.3",
-    "vitest": "4.1.10",
+    "oxlint": "1.87.0",
+    "turbo": "2.11.7",
+    "typescript": "7.0.2",
+    "vitepress": "1.6.4",
+    "vitest": "5.0.3",
     "yaml": "2.9.0"
   }
 }

package/scripts/hopper-demo-x11.py

@@ -20,11 +20,14 @@ import time
 # Keep this digest aligned with LinuxHopper.ts and rerun real-Hopper verification
 # before accepting another vendor build.
 SUPPORTED_HOPPER_SHA256 = {
-    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded"
+    "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
+    "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
 }
 EXPECTED_SCREEN = (1280, 1024)
-EXPECTED_DIALOG = (189, 370, 901, 284)
-DEMO_CLICK = (305, 632)
+DIALOG_TITLES = {"Registration", "Registration — Hopper Disassembler"}
+HOPPER_WINDOW_TITLE = "Hopper Disassembler"
+DEMO_CLICK_LEFT = 116
+DEMO_CLICK_BOTTOM = 22
 PRIVATE_DISPLAY_UNAVAILABLE = 70
 X11_AUTHORIZATION_FAILED = 71
 UNSUPPORTED_HOPPER_BUILD = 72
@@ -196,6 +199,47 @@ def windows(x11: ctypes.CDLL, display: int, root: int) -> list[tuple[int, int, i
     return found
 
 
+def window_title(x11: ctypes.CDLL, display: int, window: int) -> str | None:
+    title = ctypes.c_char_p()
+    if not x11.XFetchName(display, window, ctypes.byref(title)) or not title.value:
+        return None
+    try:
+        return title.value.decode("utf-8", "replace")
+    finally:
+        x11.XFree(ctypes.cast(title, ctypes.c_void_p))
+
+
+def window_transient_for(
+    x11: ctypes.CDLL, display: int, window: int
+) -> int | None:
+    parent = ctypes.c_ulong()
+    if not x11.XGetTransientForHint(display, window, ctypes.byref(parent)):
+        return None
+    return int(parent.value)
+
+
+def find_demo_dialog(
+    x11: ctypes.CDLL,
+    display: int,
+    observed: list[tuple[int, int, int, int, int]],
+) -> tuple[int, int, int, int, int] | None:
+    for candidate in observed:
+        window = candidate[0]
+        if window_title(x11, display, window) not in DIALOG_TITLES:
+            continue
+        parent = window_transient_for(x11, display, window)
+        if parent is None:
+            continue
+        if window_title(x11, display, parent) == HOPPER_WINDOW_TITLE:
+            return candidate
+    return None
+
+
+def demo_click(dialog: tuple[int, int, int, int, int]) -> tuple[int, int]:
+    _window, x, y, _width, height = dialog
+    return x + DEMO_CLICK_LEFT, y + height - DEMO_CLICK_BOTTOM
+
+
 def configure_x11(x11: ctypes.CDLL, xtst: ctypes.CDLL) -> None:
     window_pointer = ctypes.POINTER(ctypes.c_ulong)
     x11.XOpenDisplay.argtypes = [ctypes.c_char_p]
@@ -212,6 +256,18 @@ def configure_x11(x11: ctypes.CDLL, xtst: ctypes.CDLL) -> None:
         ctypes.POINTER(XWindowAttributes),
     ]
     x11.XGetWindowAttributes.restype = ctypes.c_int
+    x11.XFetchName.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.POINTER(ctypes.c_char_p),
+    ]
+    x11.XFetchName.restype = ctypes.c_int
+    x11.XGetTransientForHint.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_ulong,
+        ctypes.POINTER(ctypes.c_ulong),
+    ]
+    x11.XGetTransientForHint.restype = ctypes.c_int
     x11.XQueryTree.argtypes = [
         ctypes.c_void_p,
         ctypes.c_ulong,
@@ -644,6 +700,7 @@ def run_launch(args: argparse.Namespace) -> int:
 
         deadline = time.monotonic() + 10
         observed: list[tuple[int, int, int, int, int]] = []
+        dialog: tuple[int, int, int, int, int] | None = None
         while time.monotonic() < deadline:
             if socket.exists():
                 x11.XCloseDisplay(display)
@@ -659,7 +716,8 @@ def run_launch(args: argparse.Namespace) -> int:
                     "owned Hopper process exited",
                 )
             observed = windows(x11, display, root)
-            if any(window[1:] == EXPECTED_DIALOG for window in observed):
+            dialog = find_demo_dialog(x11, display, observed)
+            if dialog is not None:
                 break
             time.sleep(0.1)
         else:
@@ -675,8 +733,10 @@ def run_launch(args: argparse.Namespace) -> int:
                 "expected Hopper demo dialog not found",
             )
 
+        assert dialog is not None
+        click_x, click_y = demo_click(dialog)
         input_results = (
-            xtst.XTestFakeMotionEvent(display, -1, DEMO_CLICK[0], DEMO_CLICK[1], 0),
+            xtst.XTestFakeMotionEvent(display, -1, click_x, click_y, 0),
             xtst.XTestFakeButtonEvent(display, 1, True, 0),
             xtst.XTestFakeButtonEvent(display, 1, False, 0),
         )
@@ -695,9 +755,8 @@ def run_launch(args: argparse.Namespace) -> int:
     finally:
         if display is not None:
             x11.XCloseDisplay(display)
-        if child is not None and child.poll() is None:
-            child.terminate()
-            child.wait()
+        if child is not None:
+            stop_process(child)
         stop_process(xvfb)
         capture.close()
 

package/scripts/rea.mjs

@@ -23,7 +23,7 @@ const runtimeFiles = isMcpMode
 
 if (!(await compiledRuntimeExists(runtimeFiles))) {
   process.stderr.write(
-    `REA's compiled runtime is missing. Run \`npm ci\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,
+    `REA's compiled runtime is missing. Run \`npm ci && npm run build:cached\` in ${packageRoot} to install dependencies and build REA, then restart it. If this is an installed package, reinstall rea-agents.\n`,
   );
   process.exitCode = 1;
 } else if (isMcpMode) {
@@ -41,6 +41,7 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
   const { createCli } = await import("../dist/cli.js");
   const {
     renderCliOutputArgumentError,
+    renderEmptyFilteredCliOutput,
     sanitizeCliOutput,
     validateCliOutputArguments,
   } = await import("../dist/cliOutput.js");
@@ -49,9 +50,16 @@ if (!(await compiledRuntimeExists(runtimeFiles))) {
     process.stdout.write(renderCliOutputArgumentError(outputArguments));
     process.exitCode = 1;
   } else {
+    let wroteOutput = false;
     await createCli().serve(args, {
-      stdout: (output) => process.stdout.write(sanitizeCliOutput(output)),
+      stdout: (output) => {
+        const sanitized = sanitizeCliOutput(output);
+        if (sanitized.length > 0) wroteOutput = true;
+        process.stdout.write(sanitized);
+      },
     });
+    if (!wroteOutput)
+      process.stdout.write(renderEmptyFilteredCliOutput(args) ?? "");
   }
 }
 

package/scripts/verify-windows-native-artifact.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+const root = new URL("../", import.meta.url);
+const packageJson = JSON.parse(
+  await readFile(new URL("package.json", root), "utf8"),
+);
+const manifest = JSON.parse(
+  await readFile(new URL("native/windows/build/manifest.json", root), "utf8"),
+);
+const bytes = await readFile(
+  new URL("native/windows/build/rea-windows-x64.node", root),
+);
+if (
+  manifest.packageVersion !== packageJson.version ||
+  manifest.platform !== "win32" ||
+  manifest.architecture !== "x64" ||
+  manifest.abiVersion !== 1 ||
+  manifest.nodeApiVersion !== 8 ||
+  manifest.artifact !== "rea-windows-x64.node" ||
+  createHash("sha256").update(bytes).digest("hex") !== manifest.artifactSha256
+)
+  throw new Error(
+    "Windows native artifact metadata or SHA-256 does not match this package; run the Windows native build lane.",
+  );
+const offset = bytes.length >= 64 ? bytes.readUInt32LE(0x3c) : bytes.length;
+if (
+  bytes.toString("ascii", 0, 2) !== "MZ" ||
+  offset > bytes.length - 26 ||
+  bytes.toString("ascii", offset, offset + 4) !== "PE\0\0" ||
+  bytes.readUInt16LE(offset + 4) !== 0x8664 ||
+  bytes.readUInt16LE(offset + 24) !== 0x20b
+)
+  throw new Error("Windows native artifact must be a Windows x64 PE32+ image.");
+process.stdout.write(
+  `${JSON.stringify({ ok: true, ...manifest, artifactBytes: bytes.length })}\n`,
+);

package/skills/reverse-engineer-anything/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: reverse-engineer-anything
-description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
+description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
-  version: "24"
-  tool_count: 116
-  catalog_digest: "5bb3f994a3c4d0c87a34ff5aab4e28141b5fa6f3a98b5ae7e95686d85d9d983e"
+  version: "27"
+  tool_count: 133
+  catalog_digest: "83b4c3445ed0ec003c0aeefa3188f123d9ae319484f8b1e2b611d2fe278c9c72"
 ---
 
 # REA
@@ -15,32 +15,110 @@ behavior not established by available source. For ordinary analysis of a
 complete source repository, use normal repository tools and do not run REA
 readiness or provider commands.
 
+## Connect only when needed
+
+Installing this skill supplies instructions; it does not register the REA MCP
+server, install analysis engines, or add tools to an already-running agent.
+
+If REA tools are available and their registration is not known to be stale,
+proceed directly to the target. Do not run diagnostics or setup before every
+investigation. Use the connected server's actual tool list and input schemas;
+a skill installed from repository main may describe capabilities absent from
+an older npm release. Keep complete inline Evidence when that server does not
+advertise retained references.
+
+When tools are absent or registration is stale:
+
+1. Diagnose without changing files. For Codex, run
+   `npx -y rea-agents@latest doctor --client codex --json`. Substitute the current
+   supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
+   `gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
+   `commandcode`, or `vscode`. If the client is unknown, use `doctor --json` and
+   inspect its registration results before choosing a setup scope.
+2. Distinguish the reason. Missing, malformed, or stale registration needs a
+   scoped configuration repair. An aligned registration with no tools in the
+   active session needs a restart/reconnection; doctor cannot prove that the
+   current agent has connected. A missing provider affects only tasks requiring
+   that provider: static JavaScript inspection needs neither Hopper nor Ghidra,
+   and Android inspection has separate bring-your-own JADX/Java prerequisites.
+3. For a configuration repair, prepare the read-only plan:
+   `npx -y rea-agents@latest setup --client codex --dry-run --json`.
+   Use the current client's ID, show its exact proposed paths, backups, and
+   changes, and obtain approval before setup writes configuration or installs
+   Hopper. Setup normally installs the matching bundled skill too; include that
+   replacement in the reviewed plan. After approval, apply the same scope with
+   `npx -y rea-agents@latest setup --client codex --yes`. Add `--install-hopper`
+   only if that separate installation was needed and explicitly approved.
+4. Restart/reconnect the affected agent. Verify that REA tools actually appear
+   in the session, then resume the original investigation. If they remain
+   absent, inspect the client's MCP launch error rather than repeating setup.
+
+REA setup never installs or upgrades Node.js, npm, Homebrew, Java, Ghidra, IDA,
+JADX, Binwalk, or Unblob. Use existing prerequisites; do not install unrelated
+software to repair
+MCP registration. For an unsupported client, use manual stdio registration
+with a version-pinned `rea-agents` package or continue through the CLI.
+
+A concrete CLI fallback for an operator-supplied JavaScript tree or ASAR is:
+
+```bash
+npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
+```
+
+No MCP registration or native engine is required. Read the returned Evidence,
+graph, limitations, and unknowns with the same care as an MCP result; the CLI
+returns the Evidence record directly. This fallback does not establish that
+MCP is configured. Native CLI tasks still require their selected engine.
+
 ## Route the target first
 
-Choose the first tool from the target the user supplied. Do not call
-`open_binary` unless the target is native or an analysis database.
+Choose the first tool from the target the user supplied. Use `open_binary` for
+active-target native or archive workflows; target-free tools take their own
+explicit path or endpoint and do not need it.
 
 - ASAR or extracted JavaScript/Electron tree:
   `analyze_javascript_application`.
-- Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG:
+- Archive/package member inventory (ZIP/APK/IPA/MSIX/AppX or DMG):
   `open_binary` with the supplied local path; use `inspect_artifact` when its
   graph and findings help answer the question.
+- Android APK code, classes, methods, or incoming references:
+  `inspect_android_package`, then focused Android tools when advertised.
+  Archive member inventory still uses the archive route above.
 - Managed PE/CLI assembly: `inspect_managed_artifact`.
+- Firmware image: `inspect_firmware_regions` when advertised. Use
+  `extract_firmware` when extraction is requested, with a caller-selected new
+  absolute output directory. These tools use caller-supplied Binwalk/Unblob on
+  Linux; see the [firmware guide](https://github.com/morluto/rea/blob/main/docs/firmware-analysis.md).
+- .NET NativeAOT PE/ELF: native Ghidra analysis. Native code can yield pseudocode;
+  consult the NativeAOT workflow in `references/native-and-artifacts.md` for
+  optional metadata recovery and its supported host/layout boundary.
 - User-owned browser page already open: `list_browser_targets`.
 - User-owned Electron runtime already open: `list_electron_targets`.
 - Native executable, library, or analysis database: `open_binary`, then
   use focused analysis tools directly; call `binary_overview` when metadata or
-  inventory context is useful.
+  inventory context is useful and available from the selected provider.
+
+For an existing IDA MCP configuration, use `open_binary` with the original
+input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
+The legacy attached profile binds the already-open GUI input by SHA-256 and
+leaves its database open. The modern headless profile creates and closes an
+owned private database without saving. Installation and registration reuse
+[mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp); see the
+[IDA provider guide](https://github.com/morluto/rea/blob/main/docs/ida-provider.md).
+Proceed directly to `analyze_function`, pseudocode, or function/string searches
+after opening; IDA does not supply `binary_overview`. Consult session availability
+when composing broader workflows. Modern direct callers and unsupported dossier
+facets remain unknown; live IDA results are not replayed from snapshots.
 
 If the app is missing, ask which app to inspect. Resolve a human-readable app
 name to one clear installed artifact when possible; ask only when matches are
 ambiguous. Never choose an example app on the user's behalf.
 
 In a target-free session, use `open_binary` to bind any archive/package or
-native target whose analysis tool operates on the active target. Do not call a
-tool hidden from `tools/list`; inspect `binary_session` with
-`detail: "capabilities"` for the exact remediation when a desired capability
-is unavailable.
+native target whose analysis tool operates on the active target. Do not call an
+unadvertised tool; inspect `binary_session` with `{}` and its
+`result.tool_availability` for availability reasons and remediation. The tool
+list stays complete; availability depends on the operation, target, and host.
 
 ## Work summary-first
 
@@ -98,23 +176,13 @@ as complete while required questions remain open.
   [references/native-and-artifacts.md](references/native-and-artifacts.md)
 - ASARs, extracted JavaScript, feature tracing, and version comparison:
   [references/javascript-applications.md](references/javascript-applications.md)
+- Android APK declarations, classes, methods, and static references:
+  [references/android-applications.md](references/android-applications.md)
 - Passive browser/Electron observation and static/runtime reconciliation:
   [references/runtime-observation.md](references/runtime-observation.md)
 - Evidence paging, comparisons, residual unknowns, and verification:
   [references/evidence-workflows.md](references/evidence-workflows.md)
 
-## Readiness and setup
-
-The readiness rule is conditional: when REA tools are available and their
-registration is not known to be stale, proceed directly; do not run `doctor`
-before every task. Run `npx -y rea-agents@latest doctor` when the MCP server or
-required provider is unavailable, registration is reported stale, or the user
-asks for an environment diagnosis. Propose
-`npx -y rea-agents@latest setup` only when doctor identifies an alignment or
-provider problem. Show the exact plan and obtain approval before setup writes
-configuration or installs Hopper. Restart the agent after MCP registration
-changes; direct CLI commands remain available immediately.
-
 ## Finish the task
 
 Explain findings in plain language and tie them to returned evidence. When the

package/skills/reverse-engineer-anything/references/android-applications.md

@@ -0,0 +1,31 @@
+# Android application artifacts
+
+Use the connected server's advertised Android tools. Repository main and npm
+4.1.0 include this family. A skill installation alone cannot add it to an
+older server.
+
+Start with `inspect_android_package` on the caller's APK path for package
+identity, manifest declarations, coverage, and inline Evidence. Use
+`search_android_classes` to find candidates, `inspect_android_class` for one
+class's members, `inspect_android_method` for decompilation, and
+`trace_android_references` for incoming static references. Each call takes its
+own APK path and explicit selectors; do not open a native session first.
+Choose an `overload_index` from the class inventory when methods are ambiguous
+instead of guessing.
+
+The provider requires a separately supplied headless JADX MCP JAR 0.7.1 and
+Java 17 or newer. `REA_JADX_MCP_JAR` selects the absolute JAR path; `JAVA_HOME`
+can select Java. REA setup does not install or configure that JAR, and doctor
+provider scopes cover Hopper/Ghidra rather than JADX. Use existing tools and
+report missing prerequisites for the Android task specifically.
+
+Real verification covers Linux. macOS has the POSIX launch boundary but no
+claimed real-provider verification; Windows is unsupported. Calls use one
+worker, a bounded JVM heap, and provider deadlines. The APK is never launched,
+and no emulator is required.
+
+Manifest entries and decompiled text are static observations, not execution or
+policy enforcement. Incoming references are recovered static relationships;
+reflection, dynamic loading, and unresolved calls remain unknown. Preserve
+artifact digests, locations, diagnostics, and incomplete coverage. For archive
+members rather than code analysis, use `open_binary` and `inspect_artifact`.

package/skills/reverse-engineer-anything/references/javascript-applications.md

@@ -15,7 +15,9 @@ registration, defaults, or policy enforcement from static analysis.
 
 Use `trace_application_feature` on existing application Evidence for one
 literal node ID, route, string, API, IPC channel, module, or native export.
-Choose a direction and include the complete application Evidence inline. Include
+Choose a direction and reuse the returned application Evidence ID when the
+connected server advertises retained references, or supply complete Evidence
+inline. Include
 Hopper or Ghidra Evidence only when its artifact digest matches exactly.
 
 For version comparison, analyze each version once, then call
@@ -27,10 +29,25 @@ opposite-side coverage; otherwise report unknown.
 When the question asks how one exact exported callable's returned object shape
 changed, analyze each version once and then call
 `compare_javascript_export_shapes` with explicit module paths and export names.
-Include the complete Evidence records from both analysis calls. Accept variant
+Use the returned IDs on the same connection, or complete inline Evidence
+records, from both analysis calls. Accept variant
 pairing only through the tool's unique exact literal discriminant. Cite the
 comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous
 variants, and incomplete parent-property coverage stay unknown. This is static
 inference, not runtime behavior. When runtime semantics are needed, run
 behavioral probes against the relevant application versions and capture them
 through the available browser, Electron, or process workflows.
+
+## Reusing application Evidence
+
+When advertised by the connected server, application trace and compare tools
+accept complete inline Evidence or
+`{"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`
+for their application input (`application`, or `left`/`right`). This notation is
+a template: replace it with the actual returned ID. Versions before 4.1.0 accept only full
+inline Evidence. Use the exact ID
+returned by the producer on the same MCP connection. Resolution does not run
+analysis or select a provider; findings remain inline. Native observation
+arrays still take full Evidence. `close_binary` clears retained references;
+export a bundle before closing, or supply portable inline Evidence in another
+connection. A missing reference includes its ID and recovery guidance.