rea-agents 3.1.0 → 3.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rea-agents",
   "mcpName": "io.github.morluto/rea",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -89,17 +89,17 @@
     "test:run": "node scripts/run-exclusive.mjs test vitest run",
     "test:local": "node scripts/run-exclusive.mjs test vitest run --changed --passWithNoTests --maxWorkers=1",
     "pretest:fast": "npm run build:cached",
-    "test:fast": "vitest run --project domain --project services --project adapters --project composition --project boundary --project mcp-boundary --project conformance",
+    "test:fast": "vitest run --project domain --project services --project adapters --project composition --project boundary --project process-boundary --project mcp-boundary --project conformance",
     "pretest:boundary": "npm run build:cached",
-    "test:boundary": "vitest run --project boundary --project mcp-boundary --project process-global",
+    "test:boundary": "vitest run --project boundary --project process-boundary --project mcp-boundary --project process-global",
     "pretest:mcp": "npm run build:cached",
     "test:mcp": "vitest run --project mcp-boundary",
     "pretest:acceptance": "npm run build:cached",
     "test:acceptance": "vitest run --project acceptance",
     "pretest:changed": "npm run build:cached",
-    "test:changed": "vitest run --project domain --project services --project adapters --project composition --project boundary --project mcp-boundary --project conformance --project evaluation --changed",
+    "test:changed": "vitest run --project domain --project services --project adapters --project composition --project boundary --project process-boundary --project mcp-boundary --project conformance --project evaluation --changed",
     "pretest:integration": "npm run build:cached",
-    "test:integration": "vitest run --project boundary --project mcp-boundary --project process-global --project acceptance",
+    "test:integration": "vitest run --project boundary --project process-boundary --project mcp-boundary --project process-global --project acceptance",
     "pretest:coverage": "npm run build:cached",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
     "test:ci": "npm run test:coverage -- --reporter=default --reporter=junit --outputFile.junit=test-results.xml",
@@ -110,13 +110,16 @@
     "pretest:verbose": "npm run build:cached",
     "test:verbose": "vitest run --reporter=verbose",
     "pretest:watch": "npm run build:cached",
-    "test:watch": "vitest --project domain --project services --project adapters --project composition --project boundary --project mcp-boundary --project conformance --project evaluation --changed",
+    "test:watch": "vitest --project domain --project services --project adapters --project composition --project boundary --project process-boundary --project mcp-boundary --project conformance --project evaluation --changed",
     "pretest:watch:all": "npm run build:cached",
     "test:watch:all": "vitest --changed",
     "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:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.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: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:electron": "npm run build:cached && node scripts/verify-real-electron.mjs",
@@ -200,6 +203,7 @@
     "turbo": "2.10.5",
     "typedoc": "0.28.20",
     "typescript": "5.9.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.10",
+    "yaml": "2.9.0"
   }
 }

package/scripts/electron-active-hook.cjs

@@ -4,21 +4,6 @@ const {
   createElectronActiveBoundaryPatches,
 } = require("./electron-active-hook-boundaries.cjs");
 
-const boundedEnvironmentNumber = (name, fallback) => {
-  const value = Number(process.env[name]);
-  return Number.isInteger(value)
-    ? Math.min(20_000, Math.max(1, value))
-    : fallback;
-};
-
-const MAX_EVENT_NAME_LENGTH = 128;
-const MAX_CHANNEL_LENGTH = 1_024;
-const MAX_IDENTIFIER_LENGTH = 256;
-const MAX_ARGUMENT_SHAPES = 32;
-const maxEvents = boundedEnvironmentNumber(
-  "REA_ELECTRON_ACTIVE_MAX_RUNTIME_EVENTS",
-  5_000,
-);
 const ipcEventKinds = new Set([
   "main-handler-invocation",
   "main-event-invocation",
@@ -34,13 +19,9 @@ const events = [];
 let observed = 0;
 let observedIpc = 0;
 let observedRuntime = 0;
-let truncated = false;
 let sequence = 0;
 let correlationSequence = 0;
 
-const boundedString = (value, maximum) =>
-  typeof value === "string" ? value.slice(0, maximum) : null;
-
 const shape = (value, depth = 0) => {
   if (depth > 2 || value === null) return value === null ? "null" : "nested";
   if (Array.isArray(value)) return "array";
@@ -78,7 +59,7 @@ const isAllowedNavigation = (value) => {
 
 const processType = () =>
   typeof process.type === "string" && process.type.length > 0
-    ? process.type.slice(0, MAX_IDENTIFIER_LENGTH)
+    ? process.type
     : "main";
 
 const identity = (value, prefix) => {
@@ -86,9 +67,9 @@ const identity = (value, prefix) => {
   const id = value.id;
   const processId = value.pid;
   return typeof id === "string" || typeof id === "number"
-    ? `${prefix}:${String(id)}`.slice(0, MAX_IDENTIFIER_LENGTH)
+    ? `${prefix}:${String(id)}`
     : typeof processId === "number"
-      ? `${prefix}:pid:${String(processId)}`.slice(0, MAX_IDENTIFIER_LENGTH)
+      ? `${prefix}:pid:${String(processId)}`
       : null;
 };
 
@@ -96,7 +77,7 @@ const frameIdentity = (event) => {
   const frame = event?.senderFrame ?? event?.frame;
   const id = frame?.frameTreeNodeId ?? frame?.routingId ?? frame?.id;
   return typeof id === "string" || typeof id === "number"
-    ? `frame:${String(id)}`.slice(0, MAX_IDENTIFIER_LENGTH)
+    ? `frame:${String(id)}`
     : null;
 };
 
@@ -104,10 +85,6 @@ const record = (event) => {
   observed += 1;
   if (ipcEventKinds.has(event.kind)) observedIpc += 1;
   else observedRuntime += 1;
-  if (events.length >= maxEvents) {
-    truncated = true;
-    return null;
-  }
   const raw = {
     sequence: ++sequence,
     correlation_id:
@@ -117,14 +94,12 @@ const record = (event) => {
     event: null,
     phase: "observed",
     channel: null,
-    channel_truncated: false,
     direction: null,
     sender: null,
     receiver: null,
     frame: null,
     target: null,
     argument_shapes: [],
-    argument_shapes_truncated: false,
     result_shape: null,
     process_type: processType(),
     source: "electron-active-hook",
@@ -139,27 +114,24 @@ const record = (event) => {
     : [];
   events.push({
     ...raw,
-    correlation_id: boundedString(raw.correlation_id, MAX_IDENTIFIER_LENGTH),
-    event: boundedString(raw.event, MAX_EVENT_NAME_LENGTH),
-    channel: boundedString(raw.channel, MAX_CHANNEL_LENGTH),
-    channel_truncated:
-      raw.channel_truncated === true ||
-      (typeof raw.channel === "string" &&
-        raw.channel.length > MAX_CHANNEL_LENGTH),
-    sender: boundedString(raw.sender, MAX_IDENTIFIER_LENGTH),
-    receiver: boundedString(raw.receiver, MAX_IDENTIFIER_LENGTH),
-    frame: boundedString(raw.frame, MAX_IDENTIFIER_LENGTH),
-    target: boundedString(raw.target, MAX_IDENTIFIER_LENGTH),
-    argument_shapes: argumentShapes
-      .slice(0, MAX_ARGUMENT_SHAPES)
-      .map((value) => boundedString(value, 64) ?? "unknown"),
-    argument_shapes_truncated:
-      raw.argument_shapes_truncated === true ||
-      argumentShapes.length > MAX_ARGUMENT_SHAPES,
-    result_shape: boundedString(raw.result_shape, 64),
-    process_type: boundedString(raw.process_type, MAX_IDENTIFIER_LENGTH),
-    artifact_path: boundedString(raw.artifact_path, 16_384),
-    artifact_sha256: boundedString(raw.artifact_sha256, 64),
+    correlation_id: raw.correlation_id,
+    event: typeof raw.event === "string" ? raw.event : null,
+    channel: typeof raw.channel === "string" ? raw.channel : null,
+    sender: typeof raw.sender === "string" ? raw.sender : null,
+    receiver: typeof raw.receiver === "string" ? raw.receiver : null,
+    frame: typeof raw.frame === "string" ? raw.frame : null,
+    target: typeof raw.target === "string" ? raw.target : null,
+    argument_shapes: argumentShapes.map((value) =>
+      typeof value === "string" ? value : "unknown",
+    ),
+    result_shape:
+      typeof raw.result_shape === "string" ? raw.result_shape : null,
+    process_type:
+      typeof raw.process_type === "string" ? raw.process_type : null,
+    artifact_path:
+      typeof raw.artifact_path === "string" ? raw.artifact_path : null,
+    artifact_sha256:
+      typeof raw.artifact_sha256 === "string" ? raw.artifact_sha256 : null,
   });
   return events.at(-1);
 };
@@ -173,10 +145,7 @@ const recordIpc = (kind, channel, args, details = {}) =>
     return record({
       kind,
       channel: typeof channel === "string" ? channel : null,
-      argument_shapes: values
-        .slice(0, MAX_ARGUMENT_SHAPES)
-        .map((value) => shape(value)),
-      argument_shapes_truncated: values.length > MAX_ARGUMENT_SHAPES,
+      argument_shapes: values.map((value) => shape(value)),
       ...details,
     });
   })();
@@ -496,6 +465,5 @@ globalThis.__reaElectronActiveSnapshot = () => ({
   observed,
   observed_ipc: observedIpc,
   observed_runtime: observedRuntime,
-  truncated,
   hook_error: globalThis.__reaElectronActiveHookError === true,
 });

package/scripts/hopper-demo-x11.py

@@ -36,11 +36,8 @@ UNEXPECTED_DISPLAY_GEOMETRY = 77
 X11_INPUT_FAILED = 78
 RUNTIME_DEPENDENCY_UNAVAILABLE = 79
 X11_SOCKET_DIRECTORY_UNUSABLE = 80
-DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC_V1="
+DIAGNOSTIC_PREFIX = "REA_X11_DIAGNOSTIC="
 X11_SOCKET_DIRECTORY = Path("/tmp/.X11-unix")
-XVFB_STDERR_LIMIT = 16 * 1024
-
-
 class AdapterFailure(Exception):
     def __init__(
         self,
@@ -48,20 +45,18 @@ class AdapterFailure(Exception):
         reason: str,
         message: str,
         stderr_bytes: int = 0,
-        stderr_truncated: bool = False,
     ) -> None:
         super().__init__(message)
         self.code = code
         self.reason = reason
         self.stderr_bytes = stderr_bytes
-        self.stderr_truncated = stderr_truncated
 
-    def with_stderr(self, capture: BoundedStderr) -> AdapterFailure:
-        self.stderr_bytes, self.stderr_truncated, _ = capture.snapshot()
+    def with_stderr(self, capture: CapturedStderr) -> AdapterFailure:
+        self.stderr_bytes, _ = capture.snapshot()
         return self
 
 
-class BoundedStderr:
+class CapturedStderr:
     def __init__(self, stream: object) -> None:
         self._stream = stream
         self._retained = bytearray()
@@ -77,15 +72,13 @@ class BoundedStderr:
                 return
             with self._lock:
                 self._bytes += len(chunk)
-                remaining = XVFB_STDERR_LIMIT - len(self._retained)
-                if remaining > 0:
-                    self._retained.extend(chunk[:remaining])
+                self._retained.extend(chunk)
 
-    def snapshot(self) -> tuple[int, bool, str]:
+    def snapshot(self) -> tuple[int, str]:
         with self._lock:
             retained = bytes(self._retained)
             total = self._bytes
-        return total, total > len(retained), retained.decode("utf-8", "replace")
+        return total, retained.decode("utf-8", "replace")
 
     def close(self) -> None:
         self._thread.join(timeout=0.5)
@@ -284,14 +277,11 @@ def diagnostic(
     operation: str,
     status: str,
     failure: AdapterFailure | None = None,
-    capture: BoundedStderr | None = None,
+    capture: CapturedStderr | None = None,
 ) -> dict[str, object]:
     mode, read_only, _ = socket_directory_state()
-    captured_bytes, captured_truncated, _ = (
-        (0, False, "") if capture is None else capture.snapshot()
-    )
+    captured_bytes, _ = (0, "") if capture is None else capture.snapshot()
     return {
-        "schema_version": 1,
         "component": "hopper_private_display",
         "operation": operation,
         "status": status,
@@ -308,9 +298,6 @@ def diagnostic(
         "xvfb_stderr_bytes": captured_bytes
         if failure is None
         else failure.stderr_bytes,
-        "xvfb_stderr_truncated": captured_truncated
-        if failure is None
-        else failure.stderr_truncated,
     }
 
 
@@ -441,8 +428,8 @@ def authorize_display(
         ) from error
 
 
-def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
-    stderr_bytes, stderr_truncated, text = capture.snapshot()
+def classify_xvfb_failure(capture: CapturedStderr) -> AdapterFailure:
+    stderr_bytes, text = capture.snapshot()
     mode, read_only, directory = socket_directory_state()
     if read_only is True:
         return AdapterFailure(
@@ -450,7 +437,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_read_only",
             "X11 socket directory is read-only",
             stderr_bytes,
-            stderr_truncated,
         )
     if directory and mode != "1777":
         return AdapterFailure(
@@ -458,7 +444,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_mode",
             "X11 socket directory mode is not 1777",
             stderr_bytes,
-            stderr_truncated,
         )
     if mode is not None and not directory:
         return AdapterFailure(
@@ -466,7 +451,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "socket_directory_type",
             "X11 socket path is not a directory",
             stderr_bytes,
-            stderr_truncated,
         )
     lowered = text.lower()
     if "error while loading shared libraries" in lowered:
@@ -475,7 +459,6 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "missing_library",
             "Xvfb shared library unavailable",
             stderr_bytes,
-            stderr_truncated,
         )
     if any(
         marker in lowered
@@ -490,21 +473,19 @@ def classify_xvfb_failure(capture: BoundedStderr) -> AdapterFailure:
             "address_collision",
             "private display address collision",
             stderr_bytes,
-            stderr_truncated,
         )
     return AdapterFailure(
         PRIVATE_DISPLAY_UNAVAILABLE,
         "xvfb_startup_failed",
         "private X display unavailable",
         stderr_bytes,
-        stderr_truncated,
     )
 
 
 def start_xvfb(
     session: Path,
     args: argparse.Namespace,
-) -> tuple[subprocess.Popen[bytes], str, Path, BoundedStderr]:
+) -> tuple[subprocess.Popen[bytes], str, Path, CapturedStderr]:
     authority = session / "Xauthority"
     collision: AdapterFailure | None = None
     for _ in range(3):
@@ -551,7 +532,7 @@ def start_xvfb(
                 "xvfb_startup_failed",
                 "Xvfb stderr unavailable",
             )
-        capture = BoundedStderr(process.stderr)
+        capture = CapturedStderr(process.stderr)
         deadline = time.monotonic() + 2
         socket = Path(f"/tmp/.X11-unix/X{display_number}")
         while time.monotonic() < deadline and process.poll() is None:

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

@@ -3,8 +3,8 @@ name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or approved runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
   version: "23"
-  tool_count: 116
-  catalog_digest: "bab5657d9525ec4f798d0a9ef6001412d9c11f77fb0ddc925c7076fd10921dc9"
+  tool_count: 114
+  catalog_digest: "3e9ab4e05563ea2609b7cf4db67638a79cd8a74188c292718d99a63451d5b9db"
 ---
 
 # REA
@@ -23,13 +23,14 @@ Choose the first tool from the target the user supplied. Do not call
 - ASAR or extracted JavaScript/Electron tree:
   `analyze_javascript_application`.
 - Archive, application package, ZIP/APK/IPA/MSIX/AppX, or DMG:
-  `open_binary` with the supplied local path, then `inspect_artifact` or
-  `inventory_artifact` (both operate on the active target and accept no path).
+  `open_binary` with the supplied local path; use `inspect_artifact` when its
+  graph and findings help answer the question.
 - Managed PE/CLI assembly: `inspect_managed_artifact`.
 - 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
-  `binary_overview`.
+  use focused analysis tools directly; call `binary_overview` when metadata or
+  inventory context is useful.
 
 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
@@ -43,16 +44,48 @@ is unavailable.
 
 ## Work summary-first
 
-Start with the default summary projection. Do not repeat an identical tool call.
-Do not fetch full Evidence or a full application graph unless a specific claim
-requires detail absent from the summary. For JavaScript graphs, follow the
-paged resource URIs returned by the summary and fetch only the relevant page.
+Start with the default result and use its inline Evidence and graph context.
+Do not repeat an identical tool call. Make a focused follow-up only when the
+returned result leaves a specific question unanswered.
 
 Every conclusion must distinguish observations, inferences, and unknowns. Cite
 Evidence IDs, preserve limitations and incomplete coverage, and never imply
 that static analysis observed execution. Ask for approval only where a tool or
 policy requires it; approval never broadens a different authority boundary.
 
+## Plan broader investigations
+
+For requests that span multiple features or subsystems, use a staged workflow:
+
+1. Turn the request into a checklist of questions and the evidence each answer
+   needs. Resolve target identity and constraints from the conversation and
+   workspace before asking for information again.
+2. Inspect the current REA session, artifact identity, saved analysis database,
+   bookmarks, and prior evidence. Reuse matching state; do not open duplicate
+   sessions or repeat identical analysis.
+3. Start with the smallest useful overview or inventory. Follow each question
+   from its entry point through relevant data and state changes to its result.
+   Batch related operations around a specific hypothesis, then expand only when
+   the returned evidence leaves a concrete gap.
+4. Inspect relevant packaged resources and configuration alongside code when
+   they affect the question. Use format-aware inventory and parsers; do not
+   infer behavior from filenames, strings, or layout alone.
+5. Corroborate a conclusion with the evidence type it requires. Use runtime
+   observation or controlled replay only when static evidence cannot answer the
+   question and the required authority is available.
+6. Decompose work into independent questions. When parallel workers are
+   available and the questions do not depend on one another, assign distinct
+   scopes, point workers to existing evidence, and ask them to return sources,
+   conclusions, and unresolved gaps. Otherwise, work sequentially.
+7. Keep a concise finding ledger linking each conclusion to Evidence IDs,
+   confidence/evidence type, search boundary, and remaining unknowns. Update
+   the shared index or investigation report so later passes can reuse results.
+
+Before finishing, revisit the original checklist. Mark each question as
+answered, partially answered, or unresolved based on its evidence; keep
+bounded negative searches bounded, and do not describe a broad investigation
+as complete while required questions remain open.
+
 ## Read only the relevant guide
 
 - Native binaries, managed assemblies, archives, and extraction:
@@ -68,9 +101,11 @@ policy requires it; approval never broadens a different authority boundary.
 
 ## Readiness and setup
 
-If REA tools are available, use them directly; do not run `doctor` on every
-task. If the MCP server is unavailable or registration is reported stale, run
-`npx -y rea-agents@latest doctor`. Propose
+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

package/skills/reverse-engineer-anything/references/evidence-workflows.md

@@ -1,9 +1,11 @@
 # Evidence, comparison, and verification workflows
 
-REA results are Evidence v2. Cite evidence IDs and preserve authority,
-limitations, coverage, and residual unknowns. Read the smallest deterministic
-page that answers the question. Continue from a returned next offset while
-`has_more` is true only when exhaustive coverage matters.
+REA returns Evidence with each result. Read that result directly, cite its
+Evidence ID when another tool or your explanation needs a stable reference, and
+preserve authority, limitations, coverage, and residual unknowns. If a result
+is incomplete or paginated, continue only when the remaining data matters to
+the task; do not fetch a bundle or resource merely to read a result already
+returned inline.
 
 Use `record_unknown` only with explicit approval and name the authority or
 environment still required. Supply supporting and contradicting evidence IDs.

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

@@ -1,10 +1,10 @@
 # JavaScript and Electron application artifacts
 
-Use `analyze_javascript_application` for an operator-supplied ASAR or extracted
-tree beneath an approved investigation root. Every call requires `approved:
-true`; source-map contents require separate approval. Keep the default summary.
-Use its counts, roots, node kinds, top findings, coverage, unknowns, and graph
-page URIs before requesting more data.
+Use `analyze_javascript_application` directly on the operator-supplied ASAR or
+extracted tree. The complete result, graph, and Evidence context are returned
+inline. Source-map contents are part of the static analysis. Start from its
+findings, coverage, unknowns, and graph context, then make a focused follow-up
+only when a specific question remains unanswered.
 
 BrowserWindow preferences, preload and contextBridge surfaces, IPC
 registrations, utility processes, and native binding requests are static syntax
@@ -15,8 +15,8 @@ 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 finite bounds. Link Hopper or Ghidra Evidence only when
-the exact artifact digest matches.
+Choose a direction and include the complete application Evidence inline. Include
+Hopper or Ghidra Evidence only when its artifact digest matches exactly.
 
 For version comparison, analyze each version once, then call
 `compare_application_versions`. Accept only its digest, source-map, structural
@@ -27,9 +27,9 @@ 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.
-Use the Evidence IDs returned by the two 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. Use `run_controlled_replay` separately only when the user
-needs approved runtime semantics.
+Include the complete 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. Use `run_controlled_replay` separately only
+when the user needs approved runtime semantics.

package/skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -2,8 +2,9 @@
 
 ## Native targets
 
-After `open_binary`, use `binary_overview` once and narrow around the requested
-feature. Prefer literal search, names, decompilation, callers, callees, and
+After `open_binary`, use focused search, procedure, or function tools directly.
+Use `binary_overview` when target metadata or inventory context helps answer the
+question. Prefer literal search, names, decompilation, callers, callees, and
 cross-references. Addresses and recovered pseudocode are analysis observations,
 not original source. Provider unavailability and unsupported metadata remain
 unknown rather than false.
@@ -23,13 +24,16 @@ parser and must not become an implicit setup dependency.
 
 ## Packages and extraction
 
-Call `inventory_artifact` before extraction for application bundles, archives,
-ZIP/APK/IPA/MSIX/AppX, ASAR, or DMG inputs. Continue deterministic occurrence
-pages from the returned offset only when needed. Cite graph manifest IDs.
+Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX,
+ASAR, or DMG inputs when the artifact graph and findings help answer the
+question. It returns the complete artifact graph inline. Cite graph manifest
+IDs when using them.
 
-`extract_artifact` requires explicit approval, an absent absolute output root,
-and selected occurrence IDs. Never extract every entry implicitly. Symlinks and
-encrypted entries are inventory facts, not extractable files.
+Use `extract_artifact` when materialized files are needed. It takes no arguments
+and materializes all regular files into a fresh temporary directory chosen by
+REA. Symlinks and encrypted entries are inventory facts, not extractable files.
+The operation still requires the filesystem-write permission grant; callers do
+not choose the destination.
 
 Native DMG traversal is macOS-only, read-only, and requires both operator policy
 and `native_mount_approved: true`; without both, retain the root-hash-only result.