chore(release/6.3.0): release rea-agents 6.3.0 (#1381)

* chore(release/6.3.0): release rea-agents 6.3.0

* docs(release): restore 6.3 capture migration notes

* docs(release): include omitted 6.3 ancestry entries

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>

.agents/skills/rea-tool-design/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: rea-tool-design
+description: Design or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.
+---
+
+# REA tool design
+
+Use the [tool-design guide](../../../docs/tool-design.md) for tool boundaries,
+contract semantics, provider ownership, and discoverability. Inspect the current
+contract and nearest existing tool relevant to the analyst question; source,
+documentation, and live catalogs may describe different versions.
+
+For a design request, return the proposed boundary, input/result shape, Evidence
+semantics, nearest alternative, and verification approach. Implement when
+requested, preserving the user's scope and existing authorization.
+
+For implementation or verification, consult [testing](../../../docs/testing.md)
+for the affected consumer and provider lanes, and
+[contributing](../../../CONTRIBUTING.md) for generated-file ownership. Read
+provider/workflow guides only as the task requires.

.github/workflows/ci.yml

@@ -8,7 +8,9 @@ on:
 
 concurrency:
   group: ci-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  # The latest main push verifies the full tree, including earlier changes.
+  # Publication uses its own release workflow and concurrency group.
+  cancel-in-progress: true
 
 env:
   HUSKY: "0"
@@ -47,15 +49,22 @@ jobs:
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
-          if [[ "${{ github.event_name }}" != "pull_request" ]]; then
+          if [[ "${GITHUB_EVENT_NAME}" != "pull_request" ]]; then
             echo "required=true" >> "${GITHUB_OUTPUT}"
-          elif git diff --quiet "${BASE_SHA}" "${HEAD_SHA}" -- \
+          # Compare the PR's changes, excluding unrelated updates on its base.
+          elif git diff --quiet "${BASE_SHA}...${HEAD_SHA}" -- \
             . \
             ':(exclude)docs/**' \
+            ':(top,exclude,glob)README*.md' \
             ':(exclude)AGENTS.md' \
             ':(exclude)CONTRIBUTING.md'; then
             echo "required=false" >> "${GITHUB_OUTPUT}"
           else
+            diff_status=$?
+            # A failed comparison must fail classification, not report a scope.
+            if [[ "${diff_status}" -ne 1 ]]; then
+              exit "${diff_status}"
+            fi
             echo "required=true" >> "${GITHUB_OUTPUT}"
           fi
 
@@ -302,7 +311,7 @@ jobs:
       - run: npm run verify:windows-native:artifact
       - run: npm run verify:package
       - name: Verify real Node Inspector discovery and observation
-        if: matrix.platform == 'darwin'
+        timeout-minutes: 10
         run: npm run verify:inspector
 
   apple-artifacts:
@@ -321,6 +330,8 @@ jobs:
       - run: npm run verify:keyed-archive
       - run: npm run verify:asset-catalog
       - run: npm run verify:macos-bundle
+      - name: Legacy simulator platform verification
+        run: npm run verify:legacy-simulator
       - name: Native installer and compiled NIB hierarchy regressions
         run: npm run test:focused -- tests/boundary/filesystem/installScript.test.ts tests/boundary/filesystem/nibNativeHierarchy.test.ts tests/boundary/filesystem/interfaceBuilderBundle.test.ts
       - name: Real binary metadata and Interface Builder integration
@@ -365,48 +376,6 @@ jobs:
           if-no-files-found: error
           retention-days: 30
 
-  javascript-runtime-observation:
-    name: JavaScript runtime observation (${{ matrix.os }})
-    needs: changes
-    if: github.event_name == 'push' || needs.changes.outputs.code == 'true'
-    strategy:
-      fail-fast: false
-      max-parallel: 2
-      matrix:
-        include:
-          - os: ubuntu-latest
-            platform: linux
-            architecture: x64
-          - os: ubuntu-24.04-arm
-            platform: linux
-            architecture: arm64
-          - os: windows-latest
-            platform: win32
-            architecture: x64
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 10
-    env:
-      NODE_OPTIONS: "--max-old-space-size=1024"
-      UV_THREADPOOL_SIZE: "2"
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version-file: .nvmrc
-          cache: npm
-      - name: Verify native runtime identity
-        env:
-          EXPECTED_CI_PLATFORM: ${{ matrix.platform }}
-          EXPECTED_CI_ARCHITECTURE: ${{ matrix.architecture }}
-        run: >-
-          node -e "const assert = require('node:assert/strict');
-          assert.equal(process.platform, process.env.EXPECTED_CI_PLATFORM);
-          assert.equal(process.arch, process.env.EXPECTED_CI_ARCHITECTURE);
-          console.log(JSON.stringify({ platform: process.platform, architecture: process.arch, node: process.version }));"
-      - run: npm ci
-      - name: Verify real Node Inspector discovery and observation
-        run: npm run verify:inspector
-
   windows-curated:
     name: Windows capability and package lane
     needs: [changes, windows-native-build]
@@ -448,6 +417,7 @@ jobs:
           tests/boundary/filesystem/binaryTarget.test.ts
           tests/boundary/filesystem/safeOutputTree.test.ts
           tests/boundary/providers/native/artifactProvider.archiveSafety.test.ts
+          tests/boundary/providers/native/artifactProvider.extractionCompleteness.test.ts
           tests/boundary/filesystem/setupUnavailableProvider.test.ts
           tests/boundary/filesystem/windowsNpxRegistration.test.ts
           tests/boundary/filesystem/webScriptManifestPaths.test.ts
@@ -455,7 +425,6 @@ jobs:
           tests/acceptance/webModuleCli.test.ts
           tests/acceptance/webSourceLocationCli.test.ts
           tests/boundary/cli/referenceSourceImportStatus.test.ts
-          src/cliReferenceSourceImportStatus.test.ts
           tests/boundary/filesystem/asarInventoryFreshness.test.ts
           tests/composition/javascript-applications/javascriptArtifactReconstruction.test.ts
           tests/conformance/providers/ghidra/windowsCapabilities.test.ts
@@ -463,6 +432,7 @@ jobs:
           tests/boundary/providers/ghidra/ghidraTransport.test.ts
           tests/boundary/providers/ghidra/ghidraTargetSnapshot.test.ts
           tests/boundary/providers/ghidra/ghidraLauncher.test.ts
+          tests/boundary/providers/hopper/hopperClient.cleanupRetry.test.ts
           src/windows/WindowsNativeLoader.test.ts
           src/windows/WindowsOwnedProcess.test.ts
           src/ghidra/GhidraLauncherEnvironment.test.ts
@@ -474,6 +444,12 @@ jobs:
           tests/process-global/updateMaintenance.test.ts
           tests/conformance/providers/ghidra/realGhidraWindowsWorkflow.test.ts
       - run: npm run verify:windows-native
+      - name: Verify real Node Inspector discovery and observation
+        timeout-minutes: 10
+        env:
+          NODE_OPTIONS: "--max-old-space-size=1024"
+          UV_THREADPOOL_SIZE: "2"
+        run: npm run verify:inspector
       - run: npm run verify:package:windows
       - name: Verify native directory identity on Node 24
         run: >-
@@ -484,12 +460,13 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22.19.0
-      - name: Verify native directory identity on Node 22
+      - name: Verify native path boundaries on Node 22
         run: >-
           npx vitest run --coverage.enabled=false
           tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts
           tests/boundary/filesystem/javascriptPackagePrecedence.test.ts
           tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
+          tests/boundary/process/sourceMapUncHosts.test.ts
       - uses: actions/upload-artifact@v4
         if: always()
         with:

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "6.2.0"
+  ".": "6.3.0"
 }

AGENTS.md

@@ -1,116 +1,49 @@
 # Repository Guidelines
 
-## Product Direction
+## Product and Authority
 
-REA exposes reverse-engineering tools through a CLI and MCP server. Hopper, the bring-your-own Ghidra adapter, and the bring-your-own IDA MCP adapter are operation-capable deep binary-analysis providers. Ghidra is supported on Linux x64/arm64 and macOS x64/arm64 with matching native decompiler tools, and has an experimental Windows x64 P0 boundary for approved native x86 and x86-64 PE applications; on Linux and macOS it supplies inventory, function analysis, and atomic function annotation edits in an ephemeral database, without modifying executable bytes or controlling a GUI. Windows P0 has no mutation authority. IDA adapts upstream legacy attached GUI and modern headless database-supervisor profiles for live read-only analysis; initial real verification covers Windows, and an attached GUI database is never saved or closed. Keep provider-specific code out of the domain and application layers.
+REA is a local-only reverse-engineering tool with shared CLI/MCP workflows. Distinguish observations, derivations, inferences, and unknowns; preserve Evidence provenance and session semantics through both adapters. Provider support and setup live in [README.md](README.md#choosing-a-deep-analysis-provider) and its linked guides.
 
-Prioritize:
+Ghidra uses ephemeral databases without modifying executable bytes or controlling a GUI; Windows Ghidra P0 has no mutation authority. IDA analysis is read-only; never save or close an attached GUI database.
 
-- tool results that distinguish observations, inferences, and unknowns;
-- equivalent behavior through the CLI and MCP;
-- additive, idempotent configuration with backups;
-- end-to-end tests for packaged artifacts and real Hopper/Ghidra claims.
+Configuration changes must be additive and idempotent, with backups. Installers must not install or upgrade unrelated software, including Homebrew, Node.js, npm, Java, or Ghidra. Ghidra and IDA are bring-your-own. `rea setup` must show its planned changes and require approval before writing files or installing Hopper.
 
-Installers must not install or upgrade Homebrew, Node.js, npm, Java, Ghidra, or other unrelated software. Ghidra is bring-your-own. `rea setup` must print its planned changes and require approval before writing files or installing Hopper.
+Preserve caller-selected inputs and local evidence, including output, URLs, paths, digests, and metadata. Redact transport authentication credentials and explicitly marked sensitive values; do not infer secrecy from names or text patterns. Do not persist the ambient environment merely because a child inherits it.
 
-REA is a local-only tool. Preserve caller-selected inputs, captured output, URLs, paths, digests, mismatch locations, and analysis metadata. Do not guess that local evidence is secret from environment-variable names, argument names, or text patterns. Redact transport authentication credentials and values the caller explicitly marks sensitive; do not persist the entire ambient environment merely because a child inherits it.
+## Architecture and Cleanup
 
-## Project Structure & Module Organization
+Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. See [docs/architecture.mermaid](docs/architecture.mermaid) when changing composition.
 
-REA is a layered ESM TypeScript application. Dependencies flow inward from pure domain logic through contracts, providers, application workflows, and CLI/MCP adapters. See [docs/architecture.mermaid](docs/architecture.mermaid) for the component map.
+Give each interpretation and resource a clear owner. Preserve identity, omission, uncertainty, and source evidence across boundaries. Retain ownership of resources whose cleanup failed. Reuse `src/process/` supervision and identity primitives; a PID and executable path alone do not establish ownership after exit or reuse.
 
-- `src/domain/` owns pure provider-neutral semantics; `src/contracts/` owns caller-visible schemas and the canonical tool inventory.
-- `src/hopper/`, `src/ghidra/`, `src/ida/`, `src/browser/`, `src/inspector/`, `src/native/`, `src/artifacts/`, and `src/dotnet/` own provider-specific boundaries. Keep provider protocols out of domain and application code.
-- `src/application/` composes shared CLI/MCP workflows, including Evidence provenance, unknowns, and eligible snapshot bindings; `src/server/` translates MCP requests; `src/cli.ts` and `src/main.ts` are the CLI and MCP entry points.
-- `src/process/` owns shared process lifecycle primitives, not provider wire protocols. Reuse its supervision and identity primitives before adding provider-local lifecycle code; a PID and executable pathname alone do not establish ownership after exit or reuse. `bridge/` contains provider-side adapters.
-- `tests/` contains unit, composition, boundary, acceptance, and conformance tests. `scripts/verify-*` and capability directories under `scripts/verify/` contain real-toolchain checks.
-- `docs/public/product-catalog.json`, `docs/verification/managed-conformance-*.json`, and `skills/` are ignored build outputs. Update source contracts and authored instructions in `skill-src/`, then run `npm run docs:generate`; never commit derived catalog digests or portable conformance projections.
-- `.cache/mcp-tool-catalog.json` is generated test metadata. Generate it with `npm run mcp-catalog:generate`; source checking and runtime builds do not consume it.
+Assess brittleness in touched code during implementation, debugging, review, and maintenance. Fix the producing representation or ownership rule before adding downstream repairs. Normalize once at the owning boundary using format-aware parsers. Remove superseded representations, aliases, wrappers, and redundant tests after verifying affected consumers. Introduce abstractions only when they remove observed complexity.
 
-## Build, Test, and Development Commands
+Parse unknown boundary values and model expected failures with the tagged error algebra and `Result`. Preserve partial facts and meaningful failure reasons. Keep identity and lookup values separate from display formatting; preserve source values and explicit unknowns when normalization loses information. Absolute paths, file URLs, and HTTP paths have different semantics.
 
-- `npm ci`: install the locked dependencies.
-- `npm run build:cached`: compile the CLI/MCP runtime and bundle its authored skill. Test catalogs and documentation/conformance artifacts have separate tasks.
-- `npm run test:local`: run changed source tests without building; pass exact source test paths to run them regardless of Git status.
-- `npm run test:focused -- PATH...`: run exact test files, preparing runtime and generated artifacts required by the selected tests.
-- `npm run check:changed`: run cached static checks and source tests affected since the branch merge base (default `origin/main`).
-- `npm run check:fast`: run cached typecheck and lint checks.
-- `npm run check:pr`: opt into the complete local deterministic gate and generated-document checks for broad changes; CI owns full coverage. Routine iterations need focused tests and relevant checks, not the whole gate each time.
-- `npm run docs:check`: build and validate generated documents for the current checkout; `npm run docs:generate` regenerates them. CI retains ignored outputs as artifacts and does not push snapshot commits to feature branches.
-- For provider-dependent changes, see [docs/testing.md](docs/testing.md) and run the matching real-provider verification.
-- Keep each verification lane's prerequisites limited to the claim it checks. Use host-native fixtures for host/provider acceptance; put optional cross-target formats and their external toolchains in a separate lane. Preflight required commands and report the missing dependency and lane clearly.
+Validate advertised JSON Schemas after SDK conversion against their declared dialect and actual clients. Bind handlers to named contracts with exact types; catalog ordering must never select an operation or schema.
 
-See [docs/testing.md](docs/testing.md) for test scopes and verification lanes and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution checks. Pre-commit formats and lints staged source; pre-push runs `npm run check:fast`.
+## Development
 
-## Configuration & Environment Variables
+Use [.nvmrc](.nvmrc) and `package.json#packageManager` for the pinned toolchain. Cursor Cloud may place older Node.js first on `PATH`; environment setup installs the pinned toolchain under `/usr/local/bin`.
 
-Configuration is parsed and validated by `src/config.ts` and `src/config/`. Keep user-facing setup and provider configuration in [README.md](README.md) and the relevant guide under `docs/`; do not maintain a second environment-variable catalogue here.
+- `npm ci`: install locked dependencies.
+- `npm run build:cached`: build the runtime and packaged skill.
+- `npm run test:local -- PATH...`: source tests without building.
+- `npm run test:focused -- PATH...`: exact tests with their required artifacts.
+- `npm run check:fast`: cached typecheck/lint and the pre-push check.
+- `npm run docs:check`: validate generated documentation.
 
-## Coding Style & Naming Conventions
+Use relevant checks for the change. The complete local gate, `npm run check:pr`, is optional for broad changes or CI diagnosis. See [CONTRIBUTING.md](CONTRIBUTING.md) for development, generated-file ownership, and release conventions.
 
-Use ESM TypeScript, two-space indentation, and the committed Oxfmt configuration. Keep compiler strictness intact (`strict`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`). Use `camelCase` for values/functions, `PascalCase` for classes/types, and `UPPER_SNAKE_CASE` for constants. Parse unknown values at every MCP, environment, and subprocess boundary. Avoid `any`, unchecked casts, non-null assertions, import-time I/O, and floating promises. Exported APIs require concise JSDoc. Model expected failures with the tagged error algebra and `Result`, not broad exception wrappers.
+`docs/public/product-catalog.json`, `docs/verification/managed-conformance-*.json`, and `skills/` are ignored outputs. Edit source contracts and `skill-src/`, then regenerate as needed. `.cache/mcp-tool-catalog.json` is test metadata; runtime builds and source checking do not consume it. Never commit binaries, provider project documents, credentials, `dist/`, `node_modules/`, or local planning artifacts.
 
-Assess brittleness during implementation, debugging, review, and maintenance. Simplify duplicated rules, scattered defaults, caller-specific exceptions, and unclear invariants in touched code. Prefer standard format-aware parsers and existing shared helpers; normalize once at the owning boundary while preserving source evidence. Keep refactors focused on the task, and introduce abstractions only when they remove observed complexity. Verify preserved behavior and corrected edge cases through affected callers.
+## Tool and Test Changes
 
-## Boundary Contracts
+For tool design, follow [docs/tool-design.md](docs/tool-design.md): start from the analyst question, reuse existing contracts, preserve caller choices, and return useful evidence inline. Limits must follow real format, protocol, authority, or resource constraints. Account for representation expansion before allocation; derive completeness from examined coverage.
 
-Treat a boundary as a contract between the producer's actual representation and the consumer's required meaning. When implementing or auditing a boundary, trace the value through parsing, normalization, authorization, serialization, and the CLI/MCP result. Establish affected callers from their code paths; similar tool names or workflows do not prove that they share a schema or failure mode.
+For test changes or provider claims, use [docs/testing.md](docs/testing.md). Prefer real public CLI/MCP workflows, then production-boundary integration, then producer goldens. Keep module tests for distinct semantics stronger workflows cannot reliably reproduce. Preserve malformed-input, cancellation, cleanup, permission, capacity, and target-identity coverage when pruning. Report unverified coverage explicitly; simulated providers do not establish real-provider behavior.
 
-When changing boundary behavior, inspect adjacent input representations, failure paths, and affected callers, and correct the underlying assumption across those cases.
-
-Keep portable evidence and scenario validation distinct from host-native execution checks. Absolute filesystem paths, file URLs, and HTTP paths have different semantics; do not substitute one platform's syntax for the domain concept. Interpret provider metadata according to its documented or observed producer behavior. Keep values used for identity, provenance, matching, and path resolution separate from display formatting. When normalization loses information, preserve the source value and an explicit unknown; display placeholders must not feed back into lookup or selection.
-
-Preserve meaningful failure reasons through application and adapter layers. Malformed input is distinct from an unsupported target, unavailable provider, or host operating-system permission denial. Diagnostics should identify the failed constraint and the target or lifecycle request it applies to. Recovery advice must address that reason and point to an available workflow; generic catches must not erase actionable validation details. Preserve collected observations on execution failure independently of whether cleanup succeeds.
-
-Preserve partial native facts. A shared schema must not require one provider's full metadata before another provider can report the facts it observes. Keep observed classifications and endpoints alongside explicit unknowns for unsupported flags; never invent missing flags or discard known facts to satisfy an all-or-nothing availability shape. Before claiming a native API lacks a capability, inspect the installed API and probe representative producer objects. Exercise the resulting partial representation through CLI, MCP, and composed results such as function dossiers.
-
-Leave meaningful target, action, capture, and output choices to the agent. A selected operation already expresses intent; do not require approval booleans or repeated permission declarations. Trace each setting to its consumer: remove ignored options and single-value confirmations, derive built-in lifecycle behavior, and supply defaults for omitted optional metadata. Report actual effects and limitations where they help interpret results rather than asking callers to restate them.
-
-Verify the representation consumed at the next boundary. Internal validator success does not establish JSON Schema validity or client compatibility: validate advertised input and output schemas against their declared dialect after SDK conversion, and keep generated contracts aligned. Use representative producer data and regressions that exercise the failed behavior. Platform and provider support claims require the corresponding real workflow; package startup, capability probes, and mock transport tests establish only their narrower claims. Report unverified coverage explicitly.
-
-Bind tool handlers to named contracts, preserving their exact input and output types. Catalog ordering is presentation metadata; changing that order must not select a different schema or operation for an existing handler.
-
-## Designing MCP Tools
-
-Start from the analyst question and desired result, not a provider API. Before adding a tool, inspect the existing contract and its nearest alternative.
-
-Let agents compose experiments with ordinary commands, scripts, and local fixture servers. REA tools should perform the requested inspection or capture and return evidence. A custom orchestration language, replay engine, or separate prepare/execute plan needs an observed requirement that those primitives cannot satisfy. A plan-only tool without an executor does not establish runtime behavior; expose the useful inspection directly.
-
-- Prefer reusable, composable primitives: inspect one explicit object or
-  relationship and return evidence that can support different analyst
-  questions. Compose primitives into a workflow only for a recurring outcome
-  that benefits from joining evidence sources; keep one-application or
-  business-domain interpretations out of general tool contracts.
-- Use **inspect/search** tools for facts about a target or candidate set; use **trace** tools for relationships; use **compare** tools for explicitly paired inputs.
-- Add a **workflow** when observed agent use shows a repeated sequence that REA can compose without losing analyst control. Return useful results inline so callers can choose their next action.
-- Use **observe/capture** only when runtime activity is required, and declare authority and lifecycle effects in the contract.
-- Extend an existing tool when intent and result contract are unchanged. Add a tool for a distinct analyst outcome or materially different authority.
-- Keep caller-facing names and results provider-neutral. Put engine-specific behavior in provider adapters and report each provider's exact coverage.
-- Keep results complete by default. Add a limit only when it follows from a real format, protocol, authority, or resource-safety constraint; explain truncation and unsupported facets. Account for representation expansion and products of independently bounded dimensions before allocating or retaining output. Derive facet completeness from what was examined and exhausted, not an empty failure list. Keep observed, derived, inferred, and unknown results distinct.
-- Include artifact identity, source locations, Evidence references, actionable errors, and relevant limitations when they affect conclusions. Return the evidence needed for the next analysis inline rather than requiring a resource or identifier lookup.
-- Implement shared application workflows behind CLI and MCP adapters. Update canonical contracts and generated catalog together.
-
-See [docs/tool-design.md](docs/tool-design.md) for the design checklist. When usability or tool selection changes, evaluate representative CLI/MCP tasks as well as schema and transport behavior.
-
-## Testing Guidelines
-
-Prefer full end-to-end workflows through the public CLI or MCP with real providers and no mocked dependencies, then integration across production boundaries, then goldens captured from real producers. Keep a focused module test only for a distinct failure or semantic case that stronger workflows cannot reliably reproduce. Delete redundant getter, serialization, enum, count, and snapshot assertions when a stronger consumer workflow already proves the claim. Test paths, compiled imports, and suites named E2E do not establish end-to-end coverage. See [docs/testing.md](docs/testing.md) for pruning and classification rules.
-
-Treat advertised examples as executable contracts: derive them from representative producer data, exercise them through the advertised CLI or MCP workflow, and assert the behavior they claim to demonstrate. Share production projections where practical and declare omitted coverage explicitly.
-
-Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use fake launcher/socket seams; MCP tests connect with the client SDK version pinned in `package.json`. Preserve the canonical tool inventory defined by `TOOL_CONTRACTS` and verified through `CATALOG_IDENTITY` and generated product metadata. Cover malformed input, cancellation, lifecycle cleanup, and actual format, protocol, host-permission, and target-identity boundaries. Do not add tests that merely freeze arbitrary caps or prescribed call sequences. Real Hopper, Ghidra, browser, managed conformance, and any real managed-tool claims cannot be replaced by mocks; use the corresponding `verify:*` command.
-
-Keep tool catalogs complete and self-describing; prefer capability- and session-scoped availability over schema truncation. Serialized bytes alone do not measure agent usability or model context cost.
-
-## Cursor Cloud specific instructions
-
-Development requires Node.js 24.18.0 and npm 11.16.0 (`.nvmrc` and `packageManager`). The Cloud Agent image places an older `node` on `PATH` ahead of a normal install. Environment setup installs the pinned toolchain under `/usr/local` and prepends `/usr/local/bin` for login shells. Confirm `node -v` is `v24.18.0` before installing dependencies.
-
-`npm ci` installs locked dependencies. `npm run build:cached` produces the CLI and MCP server. `npm run check:fast` is the pre-push typecheck and lint. Hopper, Ghidra, and IDA are optional bring-your-own providers. JavaScript analysis and the deterministic Vitest suites do not need them. `rea doctor` reports those engines as missing until they are configured.
-
-## Commit & Pull Request Guidelines
-
-Use Conventional Commit subjects because Release Please derives changelogs from them. Release Please uses `always-bump-minor`: every release increments minor, including breaking changes. Examples: `feat: add historical source import`, `fix(process): stop timers after exit`, and `docs: update architecture`. Use `!` or a `BREAKING CHANGE:` footer for breaking changes. Pull request titles must follow the same format because squash merges use the title as the release commit. Pull requests should describe contract or behavior changes, list verification commands, link issues, and include sanitized MCP examples when schemas change. State whether real Hopper/Ghidra verification was performed. Never commit binaries, Hopper or Ghidra project documents, credentials, `dist/`, `node_modules/`, or local planning artifacts (e.g. `.codex/`).
+Use Conventional Commit subjects and PR titles. Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope.
 
 <!-- BEGIN:turborepo-agent-rules -->
 

CHANGELOG.md

@@ -1,5 +1,172 @@
 # Changelog
 
+## [6.3.0](https://github.com/morluto/rea/compare/rea-agents-6.2.0...rea-agents-6.3.0) (2026-10-09)
+
+
+### ⚠ BREAKING CHANGES
+
+* **captures:** Historical captures without current producer accounting or transaction identity, and web diffs missing accessibility or storage dimensions, are rejected. Preserve original captures and recapture with the current producer; update comparison consumers to include every dimension rather than synthesizing missing observations. See the [process capture guide](docs/process-capture.md) and [browser scenario contract](docs/browser-scenario-contract.md). ([3283a45](https://github.com/morluto/rea/commit/3283a45d09457c79e3adadb50a48620926d4bc5b))
+* **browser:** JSON shape paths now contain typed property and array-element segments. WebMCP input_schema_shape is replaced by input_schema and input_schema_sha256, retaining declared examples and defaults.
+* **process:** Filesystem digest omission entries now require system_code; budget and changed-file omissions use null, and unavailable-file omissions preserve the operating-system error code.
+* **contracts:** Provider analysis outputs must explicitly supply metadata previously repaired with defaults; unsupported nullable facets must be reported as null.
+* **javascript:** Semantic graph facts now store evidence context IDs and locations. Graph and semantic trace results require an inline evidence_contexts table.
+* **contracts:** source-map URLs now live in target observations selected by declared_url_sha256, and doctor skill identity no longer emits installed_catalog_digest. Use the documented observation join and identity.skill.state instead.
+* **javascript:** remove the never-incremented truncated_scopes statistic from JavaScript application analysis results and schemas.
+* **native:** Objective-C attribute tokens now contain only name and value. Properties report nullable atomicity and readonly facts; class flags, ivar counts, and method requirement flags are nullable when unobserved.
+
+### Features
+
+* **setup:** register OMP during setup ([#1301](https://github.com/morluto/rea/pull/1301)) ([8b4c359](https://github.com/morluto/rea/commit/8b4c3591358ee59297d8298ede1b63d08459d817))
+* **javascript:** record Electron integrity mismatches ([7915ee5](https://github.com/morluto/rea/commit/7915ee51781878ed67e094259924b6e6f3093b3f))
+
+
+### Bug Fixes
+
+* **inspector:** retain observations after capture failures ([dea3498](https://github.com/morluto/rea/commit/dea3498b2b8d919606eefc4fd62f6ebcbbe5ed30))
+* **artifacts:** bind ASAR interpretation to owned snapshots ([d79317c](https://github.com/morluto/rea/commit/d79317cda0bbe8240eb7e25b0a5de90dcffca5fa))
+* **artifacts:** infer legacy Mach-O simulator platforms ([5aa2002](https://github.com/morluto/rea/commit/5aa200285ab066e48b37b716495936e6e2a963fd))
+* **artifacts:** preserve archive facts and Unicode path identity ([5751f5c](https://github.com/morluto/rea/commit/5751f5caac86c770123ae739a4e4101a72b0989c))
+* **artifacts:** reject incomplete inventoried extraction ([5e8fb53](https://github.com/morluto/rea/commit/5e8fb531e255a4a04fc053c54096f66d5c84cde3))
+* **artifacts:** retain DMG ownership through uncertain attachment ([a27794c](https://github.com/morluto/rea/commit/a27794c246b3f11d7f92ae7f6d276718190ab731))
+* **artifacts:** validate only active extraction entries ([cfb12e4](https://github.com/morluto/rea/commit/cfb12e47dc241f057be93a00892f7d7361d6119d))
+* **browser:** follow only HTTP redirect statuses for source maps ([82bbe74](https://github.com/morluto/rea/commit/82bbe743336244d398e67512659ea6943d43a4a4))
+* **browser:** preserve payload shapes and WebMCP declarations ([4951a89](https://github.com/morluto/rea/commit/4951a897c53bb6882300c5d7a9660a3f43e374f5))
+* **browser:** release attached viewport overrides without resizing the external page ([f6cfbfc](https://github.com/morluto/rea/commit/f6cfbfcc554ff24173dd7ad5333e8e26ab9c962d))
+* **browser:** retain attached scenario emulation until cleanup ([a0523b3](https://github.com/morluto/rea/commit/a0523b375eb3147f1d2d1e7eb10a2f4546f5d0fc))
+* **browser:** retain malformed redirect diagnostics ([617cd84](https://github.com/morluto/rea/commit/617cd84d27d100e7cc3cd4b5721dea4a996c9775))
+* **browser:** serialize attached scenarios through cleanup settlement ([cfce91d](https://github.com/morluto/rea/commit/cfce91d418fbcde4a9ef283a61549279751854e7))
+* **ci:** scope verification and reuse native runners ([#1344](https://github.com/morluto/rea/issues/1344)) ([d5cb8ae](https://github.com/morluto/rea/commit/d5cb8aee063065a48233458e04771635167825c8))
+* **cli:** avoid duplicate primary cleanup diagnostics ([37fcea7](https://github.com/morluto/rea/commit/37fcea78cecbeeadd869e9a3d77dd133ed264a0a))
+* **cli:** classify JSON input permission denials ([08daf05](https://github.com/morluto/rea/commit/08daf056cc8e4d092f9592574d09d5182457b7bc))
+* **cli:** classify oversized JSON inputs ([f7cf4c8](https://github.com/morluto/rea/commit/f7cf4c890d4b9c70b1f56e6c627b44a59e58fd73))
+* **cli:** stream JSON inputs beyond the whole-document string limit ([#1360](https://github.com/morluto/rea/issues/1360)) ([6ce3288](https://github.com/morluto/rea/commit/6ce3288f3bd65a886e47905455ed5c9b661015e6)), closes [#1331](https://github.com/morluto/rea/issues/1331)
+* **cli:** stream JSON results at the shared command boundary ([810107a](https://github.com/morluto/rea/commit/810107a2ad15cc52afd6662aec24d231d8c77225))
+* **contracts:** advertise NUL with a portable hex escape ([3f59a84](https://github.com/morluto/rea/commit/3f59a84bd1039763bb349894542601ed78be2033)), closes [#1329](https://github.com/morluto/rea/issues/1329)
+* **contracts:** require observed provider output metadata ([a4ba8ae](https://github.com/morluto/rea/commit/a4ba8aecd507637b6261026afc17f79516840d50))
+* **electron:** preserve unrepresentable numeric option evidence ([41a228c](https://github.com/morluto/rea/commit/41a228c1b01a89127858b1706879ede08a81deaf))
+* **evidence:** order canonical projections independently of locale ([614fb76](https://github.com/morluto/rea/commit/614fb7681ee9e4eba7219c1ee9e90d6a85d78095))
+* **files:** reject nonregular capture and JSON inputs ([5f16124](https://github.com/morluto/rea/commit/5f16124a31fa4a82bd03037506809d6be959d768))
+* **filesystem:** reject unstable artifact targets ([7829b1a](https://github.com/morluto/rea/commit/7829b1aeef8f43f186be2d2adbd6c67541306a7a))
+* **ghidra:** reject a native decompiler built for another host ([#1280](https://github.com/morluto/rea/issues/1280)) ([3728c82](https://github.com/morluto/rea/commit/3728c8267b4fb6da78cbae42a2a6cbddff80ea84)), closes [#1192](https://github.com/morluto/rea/issues/1192)
+* **ghidra:** retain process ownership after failed launch rollback ([07675f7](https://github.com/morluto/rea/commit/07675f78c66ce9e8706e808d417265e18ba9f3a5))
+* **ghidra:** verify dense jump tables on an optimized fixture ([#1374](https://github.com/morluto/rea/issues/1374)) ([73a664b](https://github.com/morluto/rea/commit/73a664bc78ee618045a2733b8714821281f77403))
+* **hopper:** allow restart after verified owned-provider shutdown ([1c12349](https://github.com/morluto/rea/commit/1c123493a21cc579ba7532c40e7ef30df45db3e8))
+* **hopper:** probe interior navigation from multi-byte instructions ([#1285](https://github.com/morluto/rea/issues/1285)) ([bf934d5](https://github.com/morluto/rea/commit/bf934d5592e707ba5e7769043de3a430ed8d4923))
+* **ida:** compare admitted document paths consistently ([890bb66](https://github.com/morluto/rea/commit/890bb66b35d5f9f8ee54ff0049bf7dc7b82b2480))
+* **javascript:** avoid positive-zero evidence for signed zero ([9055bd6](https://github.com/morluto/rea/commit/9055bd695b75f72fb1b8a538d1485d30c0b0ee0b))
+* **javascript:** decline source-map UNC references with an unusable host ([#1372](https://github.com/morluto/rea/issues/1372)) ([f504c2a](https://github.com/morluto/rea/commit/f504c2a351027f17ac353fba2d7cfc3505ee17d6))
+* **javascript:** distinguish prefix-only builtins from packages ([2b4abbf](https://github.com/morluto/rea/commit/2b4abbf1ccb6dd6ad1248cf48e381df0842542c1))
+* **javascript:** honor module-sync package exports ([#1361](https://github.com/morluto/rea/issues/1361)) ([d0e6069](https://github.com/morluto/rea/commit/d0e606930acb701790c286340226b1e3e7060b4f))
+* **javascript:** parse declaration artifacts in ambient mode ([4896adc](https://github.com/morluto/rea/commit/4896adcd0f9316034e83129685ed3807ade6f3ea))
+* **javascript:** preserve agreeing module provenance ([db171be](https://github.com/morluto/rea/commit/db171be6e570fd1261a30d711e4da2d17de85a93))
+* **javascript:** preserve capture-time guards and ordering ([001851f](https://github.com/morluto/rea/commit/001851fde6f972e6ebd01fddccdff4c645a85f63))
+* **javascript:** preserve semantic evidence through satisfies ([e995b19](https://github.com/morluto/rea/commit/e995b19f834ba78faa294f5959fd3ad8a97290ca))
+* **javascript:** preserve uncertainty after references escape to calls ([#1292](https://github.com/morluto/rea/issues/1292)) ([355a292](https://github.com/morluto/rea/commit/355a292198bf58245c67ae315fdb4f77e62769cc))
+* **javascript:** reject invalid package exports configurations ([7a4f268](https://github.com/morluto/rea/commit/7a4f2685d41b134507331c322f0f5da8e1f6c3f4))
+* **javascript:** resolve exported callables through lexical bindings ([#1351](https://github.com/morluto/rea/issues/1351)) ([a9f5dad](https://github.com/morluto/rea/commit/a9f5dad5a8f196c88f6305d8d958b355cc0b52c2))
+* **javascript:** resolve query-only HTML references to their document ([55a46f7](https://github.com/morluto/rea/commit/55a46f7c7176075c9edda4fe61ed995f2ceadf6a))
+* **javascript:** retain array identity after length mutations ([4bcea1a](https://github.com/morluto/rea/commit/4bcea1aa76e3e7ca665197181739c5e27a62c40a))
+* **javascript:** retain distinct module provenance path components ([2bd7de6](https://github.com/morluto/rea/commit/2bd7de6f8ca62fc1d48334cfa7fdced461b7b153))
+* **javascript:** retain unresolved value frontiers in provenance queries ([3e19875](https://github.com/morluto/rea/commit/3e19875c7fa9c61cff655bbe6046ddc4ab558533))
+* **javascript:** store source map URLs once ([ed8fcae](https://github.com/morluto/rea/commit/ed8fcae94b699b62b44162f880faa077a36c455d))
+* **json:** preserve runtime limits across JSON file readers ([#1350](https://github.com/morluto/rea/issues/1350)) ([9c4a68b](https://github.com/morluto/rea/commit/9c4a68bc19a0f7d39557e3cc039f5877f6550f63))
+* **managed:** bind graph facts to their source Evidence ([cc7b5af](https://github.com/morluto/rea/commit/cc7b5af0777fc68ebba10ec061244729ebf2357d))
+* **mcp:** admit composed analysis through result bookkeeping ([e11f4d3](https://github.com/morluto/rea/commit/e11f4d371abaa8cb65ebf7b94fa216329fd78d88))
+* **mcp:** advertise object roots for union input schemas ([#1373](https://github.com/morluto/rea/issues/1373)) ([39dabd0](https://github.com/morluto/rea/commit/39dabd0608ed9617d60f16ece05993089f24ff38))
+* **mcp:** advertise primitive semantic literal seeds ([f62b449](https://github.com/morluto/rea/commit/f62b44971deee0e99df6fcf32758c8e5592400ed))
+* **mcp:** preserve JavaScript workflow identity validation ([#1366](https://github.com/morluto/rea/issues/1366)) ([53ed942](https://github.com/morluto/rea/commit/53ed942a85f51ff9f0e4f01cbb53359df476071d)), closes [#1364](https://github.com/morluto/rea/issues/1364) [#1065](https://github.com/morluto/rea/issues/1065)
+* **mcp:** retry failed shutdown resources and retain failure reasons ([e64678e](https://github.com/morluto/rea/commit/e64678e8f9768dd819d8f5f12cc844a6660ff2c5))
+* **native:** distinguish symbol definitions from metadata ([70bad53](https://github.com/morluto/rea/commit/70bad53847b0e14489acee73d204ff645e1adfcd))
+* **native:** preserve unknown Objective-C metadata ([b112d44](https://github.com/morluto/rea/commit/b112d44a3961939881779c81a57e7a3f9d1372f7))
+* **native:** refuse to list architectures of non-Mach-O targets ([#1325](https://github.com/morluto/rea/issues/1325)) ([1b73b5a](https://github.com/morluto/rea/commit/1b73b5ab4bc75bd424e643de8e49f142ffa2b336))
+* **native:** retain LLDB cleanup ownership through client close ([7ad353f](https://github.com/morluto/rea/commit/7ad353fa8b3f07e14face80336678d23cc7c6507))
+* **process:** keep unobserved file contents unknown ([#1358](https://github.com/morluto/rea/issues/1358)) ([f91f279](https://github.com/morluto/rea/commit/f91f2798b4dc6adb61b3ffe28a24a5d55adbd6ff))
+* **process:** retain per-file digest open failures ([415145d](https://github.com/morluto/rea/commit/415145d04f09a15cbfb7dda8ea9dc363a77f9bf0))
+* **reference:** report malformed UTF-8 before import parsing ([f166a2a](https://github.com/morluto/rea/commit/f166a2ae15b072216173a51a8f5cad930a858366))
+* report malformed application evidence as input errors ([218c131](https://github.com/morluto/rea/commit/218c13160ec0ed7116d6633fc76559ec39dae4d7))
+* retain completed observations when later analysis steps fail ([35f121f](https://github.com/morluto/rea/commit/35f121f4acac821e848c485fb82a2c42f51f6ea1))
+* **setup:** install the skill for Claude Code ([b4a1919](https://github.com/morluto/rea/commit/b4a19193fe3baf9075f8ac419517021ea0c71ea3))
+* **setup:** recognize supported Nobara hosts ([f0dc233](https://github.com/morluto/rea/commit/f0dc233d64de4c215c453c346e516b7622713e95))
+* **skill:** pin packaged commands to the shipping package version ([2793672](https://github.com/morluto/rea/commit/2793672ee2a575f97a8011c7fec5288098cdd5d1))
+* **skill:** pin packaged commands to the shipping package version ([#1346](https://github.com/morluto/rea/issues/1346)) ([f39e71c](https://github.com/morluto/rea/commit/f39e71ce1897bb5c704b33a8b0049567f11e3a13))
+* **snapshot:** preserve complete investigation revision histories ([#1354](https://github.com/morluto/rea/issues/1354)) ([1c0cc8a](https://github.com/morluto/rea/commit/1c0cc8a6753b5ac781b28ebb1832f3a6a1771a68))
+* **targets:** cancel resolution before provider admission ([f3c4a33](https://github.com/morluto/rea/commit/f3c4a332f7bd198bd67f0187bc2a85c7b31bb960))
+* **update:** preserve disabled client registrations ([abf5e24](https://github.com/morluto/rea/commit/abf5e243c4d2cae03404b6e1fb1ccc77be917b53))
+
+
+### Performance Improvements
+
+* **javascript:** index version relationships once per comparison ([#1347](https://github.com/morluto/rea/issues/1347)) ([b1e85ad](https://github.com/morluto/rea/commit/b1e85ad711743a594c572dbd5b0d5cb664e2a502))
+* **javascript:** validate the version change graph once ([#1370](https://github.com/morluto/rea/issues/1370)) ([037709a](https://github.com/morluto/rea/commit/037709a52c0824f4d2bbee90d8e2642b2d88d364))
+* **json:** encode streamed JSON iteratively ([#1322](https://github.com/morluto/rea/issues/1322)) ([56598be](https://github.com/morluto/rea/commit/56598beb4e82968a313deb9efdf4b98db5bd1f4f))
+
+
+### Code Refactoring
+
+* use canonical implementations and types directly ([765e809](https://github.com/morluto/rea/commit/765e809e366eff21b4b9c224f1a813ad64245ea3))
+* **artifacts:** remove unused root classifier ([5291bca](https://github.com/morluto/rea/commit/5291bca108af781214572fac709f9808bb8aa4db))
+* **artifacts:** test inventory changes at materialization boundary ([750fb65](https://github.com/morluto/rea/commit/750fb6565052e9eaad40b946b6a284d0730d14f8))
+* **browser:** open scenario sessions without a factory wrapper ([d1983a4](https://github.com/morluto/rea/commit/d1983a45767bfcdc020652f48109a78a3f9fa590))
+* **catalog:** import CLI metadata from its owner ([8c96baa](https://github.com/morluto/rea/commit/8c96baab80dc258d31ca1632d761fffb11dbaaae))
+* consolidate boundary semantics and prune redundant tests ([392f1f3](https://github.com/morluto/rea/commit/392f1f310733f2c365da7bc57a1154cf10ec4ba0))
+* **javascript:** normalize erased expression syntax once ([b628bba](https://github.com/morluto/rea/commit/b628bba1fa65fd3b51363bf4b745f0afc57e1dba))
+* **javascript:** parse runtime evidence into one verified owner ([006b295](https://github.com/morluto/rea/commit/006b295f1de19fd5351832cf52d98a202a5cd5cd))
+* **javascript:** remove obsolete scope truncation statistic ([449d570](https://github.com/morluto/rea/commit/449d57075eec71b2f064af8877c50cbbde30a283))
+* **javascript:** share Babel child traversal ([0f10499](https://github.com/morluto/rea/commit/0f10499245ec2fab8823f116caf34450b3a7385b))
+* **javascript:** share semantic evidence at fact construction ([e3bbb9a](https://github.com/morluto/rea/commit/e3bbb9ac453da8d15f3b32511180451613710616))
+* **process:** remove duplicate observation and trace entry points ([070339a](https://github.com/morluto/rea/commit/070339af50a50a0f23e82db859e761c53277ee79))
+* **providers:** use canonical artifact and managed identities ([87f0051](https://github.com/morluto/rea/commit/87f0051496aff1b05ab24d6b63f79884f4ca9b8f))
+* **reference:** simplify malformed UTF-8 handling ([377df71](https://github.com/morluto/rea/commit/377df715ea5b2523cd6c1084fdc286eb8a056182))
+* remove obsolete source exclusions and identity wrapper ([44c92f8](https://github.com/morluto/rea/commit/44c92f88c51841735741811a68cc89fde14efa80))
+* remove single-use forwarding helpers ([4144e45](https://github.com/morluto/rea/commit/4144e454f385c372d29e301e6bb959092c606a6e))
+
+
+### Documentation
+
+* keep license sections text-only ([e10f1f0](https://github.com/morluto/rea/commit/e10f1f0901fa56fb4443837cf9528b31a12e140e))
+* align translated README artwork and layout ([ccfbe87](https://github.com/morluto/rea/commit/ccfbe87e984e456e12c66d0d2fe6d5a559d09518))
+* add README artwork and refine closing sections ([4b8e744](https://github.com/morluto/rea/commit/4b8e744d90579e353371649047215c4e4be7a5f6))
+* add repository-local REA tool design skill ([7738c1f](https://github.com/morluto/rea/commit/7738c1f6a9ccf1ec9868ef832f154abe9ba5eebd))
+* celebrate 40,000 GitHub stars 🎉 ([3edb217](https://github.com/morluto/rea/commit/3edb2172def0e0bd9076f23148f0c41cd2f341a3))
+* celebrate 40,000 GitHub stars 🎉 ([5ecc98a](https://github.com/morluto/rea/commit/5ecc98a5eac4c10d33e9c418b9ffae61c68e3ef2))
+* consolidate agent guidance around ownership and boundaries ([ba44222](https://github.com/morluto/rea/commit/ba4422296dc409d49836f25642555e00463bfe3b))
+* **contracts:** explain canonical URL and skill metadata ownership ([e36afa1](https://github.com/morluto/rea/commit/e36afa112fd7b7ab5a925ca452de93b68f12a6ab))
+* correct MCP error and capture import guidance ([077d6c4](https://github.com/morluto/rea/commit/077d6c407b3ea7443a7277ae0e5531b3927dd742))
+* correct README setup and runtime guidance ([5b3715e](https://github.com/morluto/rea/commit/5b3715ef825a30150b02d3f1bb7d40dd89453018))
+* explain CI scope and native runner reuse ([#1348](https://github.com/morluto/rea/issues/1348)) ([6c9161d](https://github.com/morluto/rea/commit/6c9161d61745e242643f224ce49e7468143a15f3))
+* prune repeated contributor and tool design instructions ([5d79387](https://github.com/morluto/rea/commit/5d79387505ebae1ec8d800ee3ffd901920a9d8be))
+* remove retired architecture and migration artifacts ([7a0c800](https://github.com/morluto/rea/commit/7a0c80085128e6329ca2e4f54f3539f3245c57d1))
+
+
+### Tests
+
+* share the client registration command to restore the jscpd gate ([#1317](https://github.com/morluto/rea/pull/1317)) ([5d16be2](https://github.com/morluto/rea/commit/5d16be2a7185db8b70a5fcbc5f5e1be63297f2c8))
+* **mcp:** remove arbitrary schema inventory thresholds ([24673aa](https://github.com/morluto/rea/commit/24673aaae497ca4ef0902544c0cd69817f5424ed))
+* **android:** allow provider readiness under load ([961c3c3](https://github.com/morluto/rea/commit/961c3c3de79ec44d608d011eb3fa3d6bd645cf6a))
+* **artifacts:** verify extraction races with real filesystem changes ([1ac8389](https://github.com/morluto/rea/commit/1ac8389c5c1f75faf8d7f2f3faf2f24febad5fea))
+* **browser:** avoid duplicating source-map listener setup ([9367dc1](https://github.com/morluto/rea/commit/9367dc13bd8d2732d36d5376b5de170c9f4af424))
+* **browser:** report redirect status cases independently ([5a61562](https://github.com/morluto/rea/commit/5a61562dc200120c7b8020854085c17b8203e95d))
+* **cli:** remove duplicate malformed JSON assertion ([5d32e42](https://github.com/morluto/rea/commit/5d32e4252941e93065cadd83b9f02aa6427544d8))
+* exercise source test selection through Git and Vitest ([25711ad](https://github.com/morluto/rea/commit/25711ad2590af136dfb301839dddd6d30971ba76))
+* **filesystem:** bound FIFO regressions at consumers ([0bfb6e0](https://github.com/morluto/rea/commit/0bfb6e00abae1e67a96e548d64954bb21861f621))
+* **ghidra:** allow rollback tests to reach spawned process ([d761d73](https://github.com/morluto/rea/commit/d761d7358b45fe0724b182a206241fd605f338b0))
+* **javascript:** share primitive expansion producer fixtures ([c867bcd](https://github.com/morluto/rea/commit/c867bcd0aadd63473865f9a328459e0db3c89565))
+* **javascript:** share semantic graph test facts ([ac356c4](https://github.com/morluto/rea/commit/ac356c46ad6a17c8864bc5d350984786db62d2f5))
+* **javascript:** verify distinct module origins through reconstruction ([96b2b24](https://github.com/morluto/rea/commit/96b2b245fdefc9c78f5dcf6ce054232b51f7c117))
+* **json:** remove assertions covered by CLI output consumers ([a959a83](https://github.com/morluto/rea/commit/a959a8309db79fbee6477efd7ee541615e625627))
+* **managed:** include shared dossier fixture in artifact inputs ([66a20a2](https://github.com/morluto/rea/commit/66a20a2597b5daebc0a292361aa62a78b7df6e7d))
+* **native:** retain trace diagnostics when observed hits differ ([048b798](https://github.com/morluto/rea/commit/048b79878c70c594789909082499dc675472b63a))
+* **package:** share validated native dossier fixtures ([ca90109](https://github.com/morluto/rea/commit/ca9010936a934a49fbc6cf69eb1d7fc2242b6da9))
+* **process:** publish capture readiness atomically ([74be526](https://github.com/morluto/rea/commit/74be52611e66f680ef1919d521fc3c304bc2326e))
+* **process:** report cleanup details on cancellation failures ([79d5b9a](https://github.com/morluto/rea/commit/79d5b9a826b9204c1ef59b0a5c5ec83e7a2f2bec))
+* **process:** use owned CLI and workspace fixtures ([4940a86](https://github.com/morluto/rea/commit/4940a867e2e56cbb974bfa321008a8f35db47d52))
+* share snapshot replay and managed graph fixtures ([d83cbd2](https://github.com/morluto/rea/commit/d83cbd2abf1bbf15beef990f5353457fdbaaeb8e))
+
+
+### Continuous Integration
+
+* enforce architecture guards with portable checkout paths ([ecc67ca](https://github.com/morluto/rea/commit/ecc67cab2d85cacda245890ffe84b80ac395d79e))
+
 ## [6.2.0](https://github.com/morluto/rea/compare/rea-agents-6.1.0...rea-agents-6.2.0) (2026-10-09)
 
 

CONTRIBUTING.md

@@ -1,39 +1,30 @@
 # Contributing to REA
 
-REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflow enhancements. Open an issue before a large contract or architecture change so its scope can be agreed before implementation.
+REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflows. For large contract or architecture changes, explain the intended scope and link the relevant issue or design discussion.
 
 ## Choosing a contribution
 
-Small contributions are welcome when they solve a concrete problem, including
-broken commands, misleading documentation, and missing regression coverage.
-Explain the problem, keep the diff focused, and share how you checked the change.
+Explain the concrete problem, keep related corrections together, and report
+verification and unavailable coverage. Contributions should justify their review
+and maintenance cost. Keep cosmetic polish with useful fixes; confusing or
+incorrect user instructions warrant standalone corrections. Collect other
+cosmetic-only suggestions in an issue rather than separate PRs.
 
-Please avoid standalone cosmetic changes without a clear benefit, such as fixing
-a typo in an internal comment, changing capitalization or punctuation in
-already-clear prose, or reformatting unchanged code. Include related polish in a
-useful fix when practical. For cosmetic-only suggestions, please open an issue
-instead of a standalone PR so they can be collected and addressed together.
-Corrections to confusing explanations or incorrect instructions are welcome.
-
-Avoid speculative cleanup without a concrete problem to solve. Keep related
-corrections in one PR.
-
-Before requesting review, read the final diff and run the relevant checks. Be clear
-about anything you couldn't test. You should be able to explain the changes you
-submit.
-
-We may decline changes when the benefit doesn't justify the review or maintenance
-work.
-
-For capability organization and provider composition, follow the incremental
-[migration guide](docs/capability-migration.md). Run `npm run verify:test-discovery`
-after adding or moving tests.
+For capability organization and provider composition, use the
+[architecture map](docs/architecture.mermaid). Production factories in
+`src/composition/` construct fresh providers without starting engines or acquiring
+targets; optional adapter failures must preserve successful peers. Run
+`npm run verify:test-discovery` after adding or moving tests. Resolved import
+boundaries are checked by `npm run verify:module-boundaries`, included in lint.
 
 When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.
 
 ## Development setup
 
-REA development requires Node.js 24.18.x and npm 11.16.x (pinned toolchain via `nvm use`; the supported runtime range is Node.js ^22.19 || ^24.11 || >=26, as the README badge states). Real-Hopper verification additionally requires either macOS 12+ or an officially supported Linux host (Ubuntu 24.04+, Fedora 41+, 64-bit Arch, or CachyOS) and an installed Hopper application. Linux demo verification uses its own private Xvfb display and does not require a desktop session. Run `nvm use` before installing dependencies.
+Use the development toolchain pinned in `.nvmrc` and
+`package.json#packageManager`. Run `nvm use` before installing dependencies;
+installed-package runtime support is documented in
+[installation](docs/installation.md#start-setup).
 
 ```bash
 npm ci
@@ -48,7 +39,8 @@ catalogs, documentation projections, or managed verification evidence. Turbo
 caches deterministic builds and static checks across Git worktrees. After a package, lockfile, or managed-skill version change, run
 `npm run metadata:generate` before building.
 
-Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the canonical tool inventory defined by `TOOL_CONTRACTS` unless a deliberate contract change updates every verifier, generated catalog artifact, and snapshot. Keep tool discovery complete and report capability- and session-scoped availability through `binary_session`.
+Repository invariants live in [AGENTS.md](AGENTS.md). Keep provider-specific
+protocols in adapters and shared CLI/MCP workflows in the application layer.
 
 ## Documentation website
 
@@ -74,112 +66,77 @@ The separate GitHub Pages host uses only the manual
 
 ## Development feedback and PR verification
 
-For an ordinary edit, run the relevant regression and cached static checks:
+Select checks for the behavior changed. For a source edit:
 
 ```bash
 npm run test:focused -- src/config.test.ts
 npm run check:fast
 ```
 
-`test:local` selects dirty source tests without building; explicit source test
-paths run even on a clean tree. `check:changed` adds source tests affected since
-the branch merge base with `origin/main`. Use `npm run test:changed -- --base
-REVISION` to choose another base. Changed-test selection follows the import
-graph and is feedback, not complete correctness evidence. Inspect relevant
-boundary and provider behavior explicitly; see [docs/testing.md](docs/testing.md).
+`test:local` runs source tests without building. `check:changed` combines cached
+static checks with source tests affected since the merge base with `origin/main`.
+Import-graph selection can miss runtime registration, bridges, and generated data;
+select relevant boundary tests explicitly. See [testing](docs/testing.md#developer-commands)
+for commands, test placement, pruning, and real-provider prerequisites.
 
-Before handing off a PR, run the relevant tests, `npm run check`, and
-`npm run docs:check` when contracts or generated metadata change. Record which
-checks ran. CI owns complete deterministic tests and aggregate coverage. Use
-`npm run check:pr` for a deliberate full local gate on broad changes or when
-investigating CI failures; it is not required after each edit, rebase, or push.
-Packaging, setup, installation, or distribution changes also require
-`npm run verify:package` and `npm pack --dry-run`. Provider behavior changes
-require the matching real-provider `verify:*` lane.
+Before requesting review, run relevant tests and `npm run check`; add
+`npm run docs:check` when contracts or generated metadata change. Record the
+checks and unavailable coverage. CI owns the full deterministic suite and
+coverage. `npm run check:pr` is an optional full local gate for broad changes or
+CI diagnosis. Packaging/setup/distribution changes additionally require
+`npm run verify:package` and `npm pack --dry-run`; provider changes require the
+matching real-provider lane. State which host/provider workflows ran.
 
-`check:fast` runs cached source/test typecheck and lint without compiling or
-running generators. `npm run test:prepare` prepares all artifacts consumed by
-the complete suite; focused tests prepare only their runtime and declared
-artifact dependencies. The test-only MCP catalog lives at
-`.cache/mcp-tool-catalog.json` and can be regenerated independently with
-`npm run mcp-catalog:generate`.
+Pre-commit formats and lints staged files; pre-push runs `check:fast`.
 
-Build and generation commands hold one SQLite exclusive transaction around
-their whole Turbo graph, including cache restoration. The persistent database
-in `.cache/rea-command-locks/` is a lock identity, not a stale-file marker;
-the operating system releases ownership when the command supervisor exits.
-On POSIX, that supervisor retains the transaction and process-group identity
-through cancellation, including loss of its parent runner. Windows cancellation
-waits for the command to complete. Do not remove the database while commands
-are running.
+### Generated files and command ownership
 
-`check` adds formatting, dead-code, and package-metadata freshness checks.
-Formatting uses Oxfmt and the committed `.oxfmtrc.json`; generated sources use
-the same configuration. Pre-commit formats and lints staged files; pre-push runs
-`check:fast`.
-`docs:check` builds and validates generated metadata for the current checkout.
-The product catalog (`docs/public/product-catalog.json`), portable managed
-conformance projections (`docs/verification/managed-conformance-*.json`), and
-packaged skill (`skills/`) are ignored generated outputs. `docs:generate`
-prepares documentation and managed evidence; `evidence:generate` prepares only
-the managed commitment and its runtime/skill dependencies. Edit skill
-instructions and references in `skill-src/`; the skill task adds metadata to
-the packaged copy without rewriting authored files. The generated manifest
-commits to that exact packaged skill bundle. It is a portable projection of
-the deterministic managed verifier, not a record of optional real-provider runs.
-CI validates these outputs and retains them as artifacts instead of pushing
-generated-only commits onto feature branches. Reviewed source metadata such as
-`src/generatedPackageMetadata.ts` and `docs/error-contract.schema.json` remains
-tracked and checked for freshness. Do not commit ignored generated outputs.
-The build-generated product catalog contains documented facts and their provider
-identity, rather than full runtime schema hashes. The managed skill contains
-instructions and inventory metadata; doctor compares its installed files with
-the canonical bundle. Schema-only fixes should not change these outputs or the
-skill commitment in the conformance manifest. Runtime schema identity remains
-available through doctor and `binary_session`.
-Real-provider execution remains uncached; deterministic builds use Turbo.
+`docs:generate` prepares documentation and portable managed evidence;
+`evidence:generate` prepares only the managed commitment and its runtime/skill
+dependencies. The ignored outputs are `docs/public/product-catalog.json`,
+`docs/verification/managed-conformance-*.json`, and `skills/`. Edit authored
+skill instructions in `skill-src/`. CI validates generated outputs and retains
+them as artifacts; do not commit them. Reviewed source metadata, including
+`src/generatedPackageMetadata.ts` and `docs/error-contract.schema.json`, remains
+tracked and checked for freshness.
 
-Local `npm test` runs every deterministic Vitest project without coverage or
-retries. CI runs four coverage shards and merges JUnit and timing reports.
-CI cancels superseded PR runs and skips package, Windows, and full test lanes
-for documentation-only PRs. Coverage thresholds remain in `vitest.config.ts`.
+The packaged skill contains instructions and inventory metadata, not runtime
+schema hashes. Its conformance commitment covers that exact bundle and portable
+verification; it does not attest optional real-provider runs. Schema-only changes
+should not alter that commitment. Doctor and `binary_session` expose runtime
+schema identity.
 
-Tests that need a temporary directory must use
-`createTestTempDirectory` from `tests/fixtures/temporaryDirectory.ts`. The
-helper binds exact-path, awaited cleanup to the current Vitest case, including
-failure and timeout completion. Run `npm run verify:test-temp-hygiene` to build
-REA, execute the complete suite under a fresh `TMPDIR`, and reject any remaining
-REA-owned temporary path. Never add a glob cleanup for shared `/tmp/rea-*`
-content.
+Build/generation commands hold a SQLite transaction around the entire Turbo
+graph, including cache restoration. `.cache/rea-command-locks/` databases identify
+locks, not stale files; never remove them while commands run. POSIX cancellation
+retains process-group ownership until settlement; Windows waits for completion.
+Real-provider execution is uncached.
 
-Set `REA_LOG_LEVEL` to `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or
-`silent` to control structured JSON diagnostics. MCP mode defaults to `info` and
-always writes logs to stderr so the stdio protocol remains intact. One-shot CLI
-logging is opt-in and writes to stdout when a level is configured, preserving
-machine-readable command output by default. Request arguments, bridge
-authentication tokens, and environment data are redacted.
+### Temporary files and diagnostics
 
-Changes that claim real Hopper behavior must also be tested against the
-source-owned, digest-bound conformance manifest. The verifier builds the
-platform-native fixtures before starting Hopper:
+Tests use `createTestTempDirectory` from `tests/fixtures/temporaryDirectory.ts`
+for exact-path, awaited cleanup, including failures and timeouts.
+`npm run verify:test-temp-hygiene` runs the suite under a fresh `TMPDIR` and
+rejects remaining REA-owned paths. Never glob-clean shared `/tmp/rea-*` content.
 
-```bash
-npm run verify:hopper
-```
+`REA_LOG_LEVEL` selects `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or
+`silent`. MCP defaults to `info` on stderr; one-shot CLI logging is opt-in on
+stdout. Request arguments, bridge tokens, and environment data are redacted
+from diagnostic logs.
 
-On a self-hosted Linux runner with the setup-installed Xvfb dependencies, use:
+## Real Hopper changes
 
-```bash
-npm run verify:hopper:linux
-```
+Run `npm run verify:hopper` on a supported macOS host or
+`npm run verify:hopper:linux` on the supported Linux demo runner. These build
+native fixtures and verify the installed engine through CLI/MCP; package or
+simulated-provider checks do not establish engine behavior. See
+[real-toolchain verification](docs/testing.md#end-to-end-integration-and-golden-evidence)
+for prerequisites and scope, and [Hopper setup](docs/installation.md#hopper)
+for supported hosts and unattended startup.
 
-Set `REA_HOPPER_CONFORMANCE_MANIFEST_PATH` only to verify another source-built
-manifest. The normal commands use `build/conformance/manifest.json`; generated
-fixtures and manifests remain ignored and must not be committed.
-
-The macOS and Linux real-Hopper workflows remain separate so a successful mock or package test cannot be reported as platform-runtime proof. Pull requests changing setup, launch, bridge, or Hopper behavior must state which real workflows ran and why either workflow was unavailable.
-
-Describe the behavior change and verification performed in the pull request. Never commit binaries, Hopper documents, credentials, `dist/`, `node_modules/`, or local planning artifacts.
+Use the default `build/conformance/manifest.json` unless explicitly verifying
+another source-built manifest with `REA_HOPPER_CONFORMANCE_MANIFEST_PATH`.
+Generated fixtures and manifests remain ignored.
 
 ## Maintainer release checklist
 

README.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#what-you-can-analyze)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA community">
 <tr>
@@ -52,7 +52,7 @@ See a feature in an app that you want in your own product? Ask your agent to inv
 
 REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
 
-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.
+Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper, Ghidra, or IDA installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs no native analysis engine.
 
 > **[Visit the REA website](https://rea.tools/)** for setup instructions, illustrated guides, and real case studies.
 
@@ -156,7 +156,7 @@ Additional tools and host support depend on the target:
 | JavaScript / Electron  | Modules, imports, source maps, routes, IPC and native add-on relationships           | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/)                                                         |
 | Websites               | Page structure, scripts, network observations and requested screenshots              | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/)                                                        |
 | Saved network captures | Requests, responses, exposed payloads and source locations                           | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md)                                   |
-| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | Static inspection; [managed-code guide](docs/managed-code-analysis.md)                                                                |
+| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | None (static only); [managed-code guide](docs/managed-code-analysis.md)                                                               |
 | Android APKs           | Manifest declarations, classes, decompiled methods and references                    | Headless JADX and a full JDK on Linux/macOS/Windows x64; [Android guide](docs/android-analysis.md)                                    |
 | Firmware               | Regions, extraction results and native-analysis handoffs                             | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md)                                                                |
 | Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources      | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
@@ -181,6 +181,8 @@ for features added since the latest npm release.
 
 ## Showcases
 
+[![Illustrations of the DX-Ball sound-pan, Notion clipboard-bridge, and TH04 bullet-ring showcases](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: reconstruct a sound-pan calculation
 
 Follow a sound call into its position-to-pan helper, inspect the instructions,
@@ -243,7 +245,7 @@ ask you to choose demo mode or activate your license. See
 <details>
 <summary><strong>What does installing the skill from skills.sh do?</strong></summary>
 
-The skill supplies investigation instructions for your agent. Use `rea setup`
+The skill supplies investigation instructions for your agent. Use `npx rea-agents setup`
 to register REA's MCP server and install the matching instructions, then restart
 your agent. See [skill-only installation](docs/installation.md#skill-only-installation).
 
@@ -303,23 +305,9 @@ For exact options, prerequisites and result contracts:
 
 Report vulnerabilities through [SECURITY.md](SECURITY.md).
 
-## Contributing
-
-We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
-report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
-to improve the code or docs.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
-[testing](docs/testing.md) for verification lanes, and the
-[architecture map](docs/architecture.mermaid) for the project structure.
-
-## Project links
-
-[Website](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md)
-
 ## Star history
 
-🎉 **30,000 GitHub stars — thank you!**
+🎉 **40,000 GitHub stars — thank you!**
 
 Thanks to everyone using REA, reporting bugs, requesting features, testing builds, and contributing fixes.
 
@@ -337,6 +325,16 @@ REA provides tools for lawful reverse-engineering research, analysis, and recons
 
 REA is an open-source software project. We have not issued or endorsed any cryptocurrency or token. Tokens using the REA name are not affiliated with the project.
 
+## Contributing
+
+We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
+report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
+to improve the code or docs.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
+[testing](docs/testing.md) for verification lanes, and the
+[architecture map](docs/architecture.mermaid) for the project structure.
+
 ## License
 
 [MIT](LICENSE)

README_ar.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA يشغّل جسر التحليل داخل Hopper لفحص ملف ثنائي للشيفرة الأصلية" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="مجتمع REA">
 <tr>
@@ -154,6 +154,8 @@ npx rea-agents@latest setup
 
 ## دراسات الحالة
 
+[![رسوم توضيحية لأمثلة توزيع الصوت في DX-Ball وجسر الحافظة في Notion وحلقة الطلقات في TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: إعادة بناء حساب توزيع الصوت بين القناتين
 
 تتبّع استدعاء صوت إلى الدالة المساعدة التي تحوّل الموضع إلى توزيع بين القناتين، وافحص التعليمات، وحوّل الشيفرة شبه البرمجية غير المكتملة إلى C. تجتاز إعادة البناء 3,205 حالات اختبار على x86 الأصلي، وتعيد إنتاج جميع بايتات الدالة المترجمة البالغ عددها 63 بايتًا.
@@ -202,7 +204,7 @@ npx rea-agents@latest setup
 <details>
 <summary><strong>ماذا يفعل تثبيت المهارة من skills.sh؟</strong></summary>
 
-توفّر المهارة تعليمات الاستقصاء لوكيلك. استخدم `rea setup` لتسجيل خادم MCP الخاص بـ REA وتثبيت التعليمات المطابقة، ثم أعد تشغيل وكيلك. راجع [تثبيت المهارة وحدها](docs/installation.md#skill-only-installation).
+توفّر المهارة تعليمات الاستقصاء لوكيلك. استخدم `npx rea-agents setup` لتسجيل خادم MCP الخاص بـ REA وتثبيت التعليمات المطابقة، ثم أعد تشغيل وكيلك. راجع [تثبيت المهارة وحدها](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -254,19 +256,9 @@ npx rea-agents@latest setup
 
 أبلغ عن الثغرات وفق [SECURITY.md](SECURITY.md).
 
-## المساهمة
-
-نرحّب بمساعدتك في تطوير REA! [افتح issue](https://github.com/morluto/rea/issues) للإبلاغ عن خطأ أو اقتراح ميزة، أو [أرسل pull request](https://github.com/morluto/rea/pulls) لتحسين الشيفرة أو التوثيق.
-
-راجع [CONTRIBUTING.md](CONTRIBUTING.md) لإعداد بيئة التطوير والفحوص، و[دليل الاختبار](docs/testing.md) لمسارات التحقق، و[خريطة البنية](docs/architecture.mermaid) لهيكل المشروع.
-
-## روابط المشروع
-
-[الموقع](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [الأمان](SECURITY.md)
-
 ## سجل النجوم
 
-🎉 **30,000 نجمة على GitHub — شكرًا لكم!**
+🎉 **40,000 نجمة على GitHub — شكرًا لكم!**
 
 شكرًا لكل من يستخدم REA، ويبلّغ عن الأخطاء، ويقترح ميزات، ويختبر إصدارات البناء، ويساهم بالإصلاحات.
 
@@ -282,6 +274,12 @@ npx rea-agents@latest setup
 
 يوفّر REA أدوات لأبحاث الهندسة العكسية والتحليل وإعادة البناء المشروعة. أنت مسؤول عن الحصول على أي تفويض مطلوب والالتزام بالقوانين المعمول بها. لا يؤيد المشروع الاستخدام غير القانوني أو غير المصرّح به.
 
+## المساهمة
+
+نرحّب بمساعدتك في تطوير REA! [افتح issue](https://github.com/morluto/rea/issues) للإبلاغ عن خطأ أو اقتراح ميزة، أو [أرسل pull request](https://github.com/morluto/rea/pulls) لتحسين الشيفرة أو التوثيق.
+
+راجع [CONTRIBUTING.md](CONTRIBUTING.md) لإعداد بيئة التطوير والفحوص، و[دليل الاختبار](docs/testing.md) لمسارات التحقق، و[خريطة البنية](docs/architecture.mermaid) لهيكل المشروع.
+
 ## الترخيص
 
 [MIT](LICENSE)

README_de.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA startet seine Analysebrücke in Hopper und untersucht eine native Binärdatei" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA-Community">
 <tr>
@@ -154,6 +154,8 @@ Native Formate und unterstützte Hostsysteme unterscheiden sich je nach Provider
 
 ## Fallstudien
 
+[![Illustrationen der Fallstudien zu DX-Balls Klangbalance, Notions Zwischenablage-Brücke und TH04s Geschossring](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: Eine Stereo-Panning-Berechnung rekonstruieren
 
 Verfolge einen Sound-Aufruf zur Hilfsfunktion, die Positionen in Panning-Werte umrechnet, untersuche die Anweisungen und überführe unvollständigen Pseudocode in C. Die Rekonstruktion besteht 3.205 Tests mit dem ursprünglichen x86-Code und reproduziert alle 63 Bytes der kompilierten Funktion.
@@ -200,7 +202,7 @@ REA startet Hopper, wenn eine Operation es benötigt. Unter macOS kann beim erst
 <details>
 <summary><strong>Was bewirkt die Installation des Skills über skills.sh?</strong></summary>
 
-Der Skill stellt Untersuchungsanweisungen für deinen Agenten bereit. Verwende `rea setup`, um den MCP-Server von REA zu registrieren und passende Anweisungen zu installieren. Starte deinen Agenten anschließend neu. Siehe [Installation nur des Skills](docs/installation.md#skill-only-installation).
+Der Skill stellt Untersuchungsanweisungen für deinen Agenten bereit. Verwende `npx rea-agents setup`, um den MCP-Server von REA zu registrieren und passende Anweisungen zu installieren. Starte deinen Agenten anschließend neu. Siehe [Installation nur des Skills](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ Beginne mit den [praxisnahen Anleitungen](https://rea.tools/guides/) auf der Web
 
 Melde Sicherheitslücken gemäß [SECURITY.md](SECURITY.md).
 
-## Mitwirken
-
-Wir freuen uns über deine Hilfe bei REA! [Öffne ein Issue](https://github.com/morluto/rea/issues), um einen Fehler zu melden oder eine Funktion vorzuschlagen, oder [sende einen Pull Request](https://github.com/morluto/rea/pulls), um Code oder Dokumentation zu verbessern.
-
-Die Entwicklungsumgebung und Prüfungen beschreibt [CONTRIBUTING.md](CONTRIBUTING.md), die Verifikationspfade der [Testleitfaden](docs/testing.md) und die Projektstruktur die [Architekturübersicht](docs/architecture.mermaid).
-
-## Projektlinks
-
-[Website](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Sicherheit](SECURITY.md)
-
 ## Sternverlauf
 
-🎉 **30.000 GitHub-Sterne – vielen Dank!**
+🎉 **40.000 GitHub-Sterne – vielen Dank!**
 
 Danke an alle, die REA nutzen, Fehler melden, Funktionswünsche äußern, Builds testen und Fehlerbehebungen beitragen.
 
@@ -280,6 +272,12 @@ Danke an alle, die REA nutzen, Fehler melden, Funktionswünsche äußern, Builds
 
 REA stellt Werkzeuge für rechtmäßige Reverse-Engineering-Forschung, Analyse und Rekonstruktion bereit. Du bist dafür verantwortlich, erforderliche Genehmigungen einzuholen und geltendes Recht einzuhalten. Das Projekt unterstützt keine rechtswidrige oder unbefugte Nutzung.
 
+## Mitwirken
+
+Wir freuen uns über deine Hilfe bei REA! [Öffne ein Issue](https://github.com/morluto/rea/issues), um einen Fehler zu melden oder eine Funktion vorzuschlagen, oder [sende einen Pull Request](https://github.com/morluto/rea/pulls), um Code oder Dokumentation zu verbessern.
+
+Die Entwicklungsumgebung und Prüfungen beschreibt [CONTRIBUTING.md](CONTRIBUTING.md), die Verifikationspfade der [Testleitfaden](docs/testing.md) und die Projektstruktur die [Architekturübersicht](docs/architecture.mermaid).
+
 ## Lizenz
 
 [MIT](LICENSE)

README_es.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA inicia su puente de análisis dentro de Hopper mientras inspecciona un binario nativo" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Comunidad REA">
 <tr>
@@ -154,6 +154,8 @@ Los formatos nativos y los sistemas anfitriones compatibles varían según el pr
 
 ## Casos prácticos
 
+[![Ilustraciones de los casos de panoramización de sonido de DX-Ball, el puente del portapapeles de Notion y el anillo de proyectiles de TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: reconstruir un cálculo de panoramización de sonido
 
 Sigue una llamada de sonido hasta la función auxiliar que convierte la posición en panoramización, inspecciona las instrucciones y transforma el pseudocódigo incompleto en C. La reconstrucción supera 3.205 casos con el x86 original y reproduce los 63 bytes de la función compilada.
@@ -200,7 +202,7 @@ REA inicia Hopper cuando una operación lo necesita. En macOS, puede aparecer un
 <details>
 <summary><strong>¿Qué hace la instalación de la skill desde skills.sh?</strong></summary>
 
-La skill proporciona instrucciones de investigación a tu agente. Usa `rea setup` para registrar el servidor MCP de REA e instalar las instrucciones correspondientes; después reinicia tu agente. Consulta [instalación solo de la skill](docs/installation.md#skill-only-installation).
+La skill proporciona instrucciones de investigación a tu agente. Usa `npx rea-agents setup` para registrar el servidor MCP de REA e instalar las instrucciones correspondientes; después reinicia tu agente. Consulta [instalación solo de la skill](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ Empieza con las [guías prácticas](https://rea.tools/guides/) del sitio web. Pa
 
 Informa de vulnerabilidades siguiendo [SECURITY.md](SECURITY.md).
 
-## Contribuir
-
-¡Nos encantaría que ayudaras con REA! [Abre una issue](https://github.com/morluto/rea/issues) para comunicar un error o proponer una función, o [envía una pull request](https://github.com/morluto/rea/pulls) para mejorar el código o la documentación.
-
-Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para preparar el entorno de desarrollo y las comprobaciones, la [guía de pruebas](docs/testing.md) para los procesos de verificación y el [mapa de arquitectura](docs/architecture.mermaid) para la estructura del proyecto.
-
-## Enlaces del proyecto
-
-[Sitio web](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Seguridad](SECURITY.md)
-
 ## Historial de estrellas
 
-🎉 **30.000 estrellas en GitHub: ¡gracias!**
+🎉 **40.000 estrellas en GitHub: ¡gracias!**
 
 Gracias a quienes usan REA, informan de errores, solicitan funciones, prueban compilaciones y contribuyen con correcciones.
 
@@ -280,6 +272,12 @@ Gracias a quienes usan REA, informan de errores, solicitan funciones, prueban co
 
 REA proporciona herramientas para la investigación, el análisis y la reconstrucción mediante ingeniería inversa conforme a la ley. Eres responsable de obtener las autorizaciones necesarias y cumplir las leyes aplicables. El proyecto no respalda usos ilegales ni no autorizados.
 
+## Contribuir
+
+¡Nos encantaría que ayudaras con REA! [Abre una issue](https://github.com/morluto/rea/issues) para comunicar un error o proponer una función, o [envía una pull request](https://github.com/morluto/rea/pulls) para mejorar el código o la documentación.
+
+Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para preparar el entorno de desarrollo y las comprobaciones, la [guía de pruebas](docs/testing.md) para los procesos de verificación y el [mapa de arquitectura](docs/architecture.mermaid) para la estructura del proyecto.
+
 ## Licencia
 
 [MIT](LICENSE)

README_fa.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="اجرای پل تحلیل REA در Hopper هنگام بررسی یک فایل باینری بومی" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="انجمن REA"><tr><td align="center" width="360"><a href="https://discord.gg/GkcryMnJDM"><img    src="docs/assets/discord.svg" height="42" alt="Discord" /><br /><strong>به انجمن مهندسی معکوس بپیوندید</strong></a><br /><sub>دیسکورد · پرسش و پاسخ · نمایش دستاوردها</sub></td></tr></table>
 
@@ -146,6 +146,8 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، به‌همراه np
 
 ## نمونه‌های عملی
 
+[![تصویرهایی از نمونه‌های پنینگ صدای DX-Ball، پل کلیپ‌بورد Notion و حلقهٔ گلوله‌های TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: بازسازی محاسبهٔ موقعیت استریوی صدا
 
 یک فراخوانی صوتی را تا تابع کمکی تبدیل موقعیت به pan دنبال کنید، دستورالعمل‌ها را بررسی کنید و شبه‌کد ناقص را به C تبدیل کنید. بازسازی حاصل، هر ۳٬۲۰۵ مورد آزمایش x86 اصلی را با موفقیت پشت سر می‌گذارد و هر ۶۳ بایت تابع کامپایل‌شده را دقیقاً بازتولید می‌کند.
@@ -188,7 +190,7 @@ REA زمانی که عملیاتی به Hopper نیاز داشته باشد آن
 
 <details><summary><strong>نصب skill از skills.sh چه کاری انجام می‌دهد؟</strong></summary>
 
-این skill دستورالعمل‌های بررسی را برای ایجنت فراهم می‌کند. برای ثبت سرور MCP مربوط به REA و نصب دستورالعمل‌های متناظر، `rea setup` را اجرا کنید و سپس ایجنت را مجدداً راه‌اندازی کنید. [نصب مستقل skill](docs/installation.md#skill-only-installation) را ببینید.
+این skill دستورالعمل‌های بررسی را برای ایجنت فراهم می‌کند. برای ثبت سرور MCP مربوط به REA و نصب دستورالعمل‌های متناظر، `npx rea-agents setup` را اجرا کنید و سپس ایجنت را مجدداً راه‌اندازی کنید. [نصب مستقل skill](docs/installation.md#skill-only-installation) را ببینید.
 
 </details>
 
@@ -237,19 +239,9 @@ npx rea-agents@latest setup
 
 آسیب‌پذیری‌ها را از طریق [SECURITY.md](SECURITY.md) گزارش کنید.
 
-## مشارکت
-
-از کمک شما به REA استقبال می‌کنیم! برای گزارش خطا یا پیشنهاد قابلیت، یک [issue باز کنید](https://github.com/morluto/rea/issues) یا برای بهبود کد و مستندات [pull request بفرستید](https://github.com/morluto/rea/pulls).
-
-برای راه‌اندازی محیط توسعه و بررسی‌ها، [CONTRIBUTING.md](CONTRIBUTING.md)، برای مراحل اعتبارسنجی [آزمایش‌ها](docs/testing.md) و برای ساختار پروژه [نقشهٔ معماری](docs/architecture.mermaid) را ببینید.
-
-## لینک‌های پروژه
-
-[وب‌سایت](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [امنیت](SECURITY.md)
-
 ## تاریخچهٔ ستاره‌ها
 
-🎉 **۳۰٬۰۰۰ ستارهٔ GitHub — سپاسگزاریم!**
+🎉 **۴۰٬۰۰۰ ستارهٔ GitHub — سپاسگزاریم!**
 
 از همهٔ کسانی که از REA استفاده می‌کنند، خطاها را گزارش می‌دهند، قابلیت‌های جدید پیشنهاد می‌کنند، buildها را آزمایش می‌کنند و در بهبود پروژه مشارکت دارند سپاسگزاریم.
 
@@ -259,6 +251,12 @@ npx rea-agents@latest setup
 
 REA ابزارهایی برای پژوهش، تحلیل و بازسازی قانونی در حوزهٔ مهندسی معکوس فراهم می‌کند. مسئولیت دریافت مجوزهای لازم و رعایت قوانین مربوط بر عهدهٔ شماست. این پروژه استفادهٔ غیرقانونی یا بدون مجوز را تأیید نمی‌کند.
 
+## مشارکت
+
+از کمک شما به REA استقبال می‌کنیم! برای گزارش خطا یا پیشنهاد قابلیت، یک [issue باز کنید](https://github.com/morluto/rea/issues) یا برای بهبود کد و مستندات [pull request بفرستید](https://github.com/morluto/rea/pulls).
+
+برای راه‌اندازی محیط توسعه و بررسی‌ها، [CONTRIBUTING.md](CONTRIBUTING.md)، برای مراحل اعتبارسنجی [آزمایش‌ها](docs/testing.md) و برای ساختار پروژه [نقشهٔ معماری](docs/architecture.mermaid) را ببینید.
+
 ## مجوز
 
 [MIT](LICENSE)

README_fr.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA lance son pont d'analyse dans Hopper pendant l'inspection d'un binaire natif" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA community">
 <tr>
@@ -155,6 +155,8 @@ Les formats natifs et les hôtes pris en charge varient selon le fournisseur. Co
 
 ## Études de cas
 
+[![Illustrations des études sur la spatialisation sonore de DX-Ball, le pont du presse-papiers de Notion et le cercle de projectiles de TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball : reconstruire un calcul de panoramique sonore
 
 Suivez un appel sonore jusqu'à la fonction qui convertit une position en panoramique, inspectez ses instructions et transformez un pseudo-code incomplet en C. La reconstruction réussit 3 205 cas issus du x86 d'origine et reproduit à l'identique les 63 octets de la fonction compilée.
@@ -201,7 +203,7 @@ REA lance Hopper lorsqu'une opération en a besoin. Sous macOS, une boîte de di
 <details>
 <summary><strong>Que fait l'installation du skill depuis skills.sh ?</strong></summary>
 
-Le skill fournit des instructions d'investigation à votre agent. Utilisez `rea setup` pour enregistrer le serveur MCP de REA et installer les instructions correspondantes, puis redémarrez votre agent. Consultez [l'installation du skill seul](docs/installation.md#skill-only-installation).
+Le skill fournit des instructions d'investigation à votre agent. Utilisez `npx rea-agents setup` pour enregistrer le serveur MCP de REA et installer les instructions correspondantes, puis redémarrez votre agent. Consultez [l'installation du skill seul](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -253,19 +255,9 @@ Commencez par les [guides pas à pas](https://rea.tools/guides/) du site web. Po
 
 Signalez les vulnérabilités via [SECURITY.md](SECURITY.md).
 
-## Contribuer
-
-Votre aide sur REA est la bienvenue ! [Ouvrez une issue](https://github.com/morluto/rea/issues) pour signaler un bug ou proposer une fonctionnalité, ou [envoyez une pull request](https://github.com/morluto/rea/pulls) pour améliorer le code ou la documentation.
-
-Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](docs/testing.md) pour les filières de vérification, et la [carte de l'architecture](docs/architecture.mermaid) pour la structure du projet.
-
-## Liens du projet
-
-[Site web](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Sécurité](SECURITY.md)
-
 ## Historique des étoiles
 
-🎉 **30 000 étoiles GitHub — merci !**
+🎉 **40 000 étoiles GitHub — merci !**
 
 Merci à toutes les personnes qui utilisent REA, signalent des bugs, proposent des fonctionnalités, testent les builds et contribuent des correctifs.
 
@@ -281,6 +273,12 @@ Merci à toutes les personnes qui utilisent REA, signalent des bugs, proposent d
 
 REA fournit des outils destinés à la recherche, à l'analyse et à la reconstruction légales en rétro-ingénierie. Il vous appartient d'obtenir toute autorisation nécessaire et de respecter les lois applicables. Le projet n'encourage aucune utilisation illégale ou non autorisée.
 
+## Contribuer
+
+Votre aide sur REA est la bienvenue ! [Ouvrez une issue](https://github.com/morluto/rea/issues) pour signaler un bug ou proposer une fonctionnalité, ou [envoyez une pull request](https://github.com/morluto/rea/pulls) pour améliorer le code ou la documentation.
+
+Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](docs/testing.md) pour les filières de vérification, et la [carte de l'architecture](docs/architecture.mermaid) pour la structure du projet.
+
 ## Licence
 
 [MIT](LICENSE)

README_ja.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA が Hopper 内で分析ブリッジを起動し、ネイティブバイナリを調べる様子" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA コミュニティ">
 <tr>
@@ -154,6 +154,8 @@ REA には Node.js 22.x（>=22.19）、24.x（>=24.11）、または 26+ と npm
 
 ## 事例
 
+[![DX-Ball の音声パン、Notion のクリップボードブリッジ、TH04 の弾幕リングの事例を表すイラスト](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball：音声のパン計算を再構築する
 
 音声の呼び出しから位置をパンに変換する補助関数をたどり、命令を調べ、不完全な疑似コードを C に書き直します。再構築した実装は、元の x86 に対する 3,205 ケースの検証を通過し、コンパイル後の関数の全 63 バイトを再現しています。
@@ -202,7 +204,7 @@ REA は必要な操作の際に Hopper を起動します。macOS では、初
 <details>
 <summary><strong>skills.sh からスキルをインストールすると何ができますか？</strong></summary>
 
-スキルはエージェントに調査の手順を提供します。`rea setup` で REA の MCP サーバーを登録し、対応する手順をインストールしてから、エージェントを再起動してください。[スキルのみのインストール](docs/installation.md#skill-only-installation)を参照してください。
+スキルはエージェントに調査の手順を提供します。`npx rea-agents setup` で REA の MCP サーバーを登録し、対応する手順をインストールしてから、エージェントを再起動してください。[スキルのみのインストール](docs/installation.md#skill-only-installation)を参照してください。
 
 </details>
 
@@ -254,19 +256,9 @@ npx rea-agents@latest setup
 
 脆弱性の報告は [SECURITY.md](SECURITY.md) に従ってください。
 
-## 貢献する
-
-REA への貢献を歓迎します！[issue を作成](https://github.com/morluto/rea/issues)してバグや機能の提案を報告したり、[pull request を送信](https://github.com/morluto/rea/pulls)してコードやドキュメントを改善したりできます。
-
-開発環境とチェックは [CONTRIBUTING.md](CONTRIBUTING.md)、検証レーンは[テストガイド](docs/testing.md)、プロジェクト構造は[アーキテクチャ図](docs/architecture.mermaid)を参照してください。
-
-## プロジェクトリンク
-
-[ウェブサイト](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [セキュリティ](SECURITY.md)
-
 ## スター履歴
 
-🎉 **GitHub スター 30,000 件、ありがとうございます！**
+🎉 **GitHub スター 40,000 件、ありがとうございます！**
 
 REA の利用、バグ報告、機能の要望、ビルドのテスト、修正への貢献に感謝します。
 
@@ -282,6 +274,12 @@ REA の利用、バグ報告、機能の要望、ビルドのテスト、修正
 
 REA は、合法的なリバースエンジニアリングの研究、分析、再構築のためのツールを提供します。必要な許可を得て、適用される法律に従う責任は利用者にあります。このプロジェクトは違法または無許可の利用を支持しません。
 
+## 貢献する
+
+REA への貢献を歓迎します！[issue を作成](https://github.com/morluto/rea/issues)してバグや機能の提案を報告したり、[pull request を送信](https://github.com/morluto/rea/pulls)してコードやドキュメントを改善したりできます。
+
+開発環境とチェックは [CONTRIBUTING.md](CONTRIBUTING.md)、検証レーンは[テストガイド](docs/testing.md)、プロジェクト構造は[アーキテクチャ図](docs/architecture.mermaid)を参照してください。
+
 ## ライセンス
 
 [MIT](LICENSE)

README_ko.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA가 Hopper 안에서 분석 브리지를 실행해 네이티브 바이너리를 검사하는 모습" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA 커뮤니티">
 <tr>
@@ -154,6 +154,8 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니
 
 ## 사례
 
+[![DX-Ball 사운드 패닝, Notion 클립보드 브리지, TH04 탄환 고리 사례를 보여 주는 그림](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: 사운드 패닝 계산 재구현
 
 사운드 호출에서 위치를 패닝 값으로 변환하는 보조 함수까지 추적하고, 명령을 검사하여 불완전한 의사 코드를 C로 옮깁니다. 재구현한 코드는 원본 x86에 대한 3,205개 테스트 케이스를 통과했으며, 컴파일된 함수의 63바이트 전체를 재현합니다.
@@ -202,7 +204,7 @@ REA는 작업에 필요할 때 Hopper를 실행합니다. macOS에서는 처음
 <details>
 <summary><strong>skills.sh에서 설치하는 스킬은 어떤 역할을 하나요?</strong></summary>
 
-스킬은 에이전트에게 조사 지침을 제공합니다. `rea setup`으로 REA의 MCP 서버를 등록하고 버전에 맞는 지침을 설치한 뒤 에이전트를 다시 시작하세요. [스킬만 설치하기](docs/installation.md#skill-only-installation)를 참고하세요.
+스킬은 에이전트에게 조사 지침을 제공합니다. `npx rea-agents setup`으로 REA의 MCP 서버를 등록하고 버전에 맞는 지침을 설치한 뒤 에이전트를 다시 시작하세요. [스킬만 설치하기](docs/installation.md#skill-only-installation)를 참고하세요.
 
 </details>
 
@@ -254,19 +256,9 @@ npx rea-agents@latest setup
 
 취약점은 [SECURITY.md](SECURITY.md)에 따라 보고하세요.
 
-## 기여
-
-REA에 도움을 보태 주세요! [issue를 등록](https://github.com/morluto/rea/issues)해 버그나 기능을 제안하거나, [pull request를 보내](https://github.com/morluto/rea/pulls) 코드와 문서를 개선할 수 있습니다.
-
-개발 환경과 검사 항목은 [CONTRIBUTING.md](CONTRIBUTING.md), 검증 절차는 [테스트 가이드](docs/testing.md), 프로젝트 구조는 [아키텍처 지도](docs/architecture.mermaid)를 참고하세요.
-
-## 프로젝트 링크
-
-[웹사이트](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [보안](SECURITY.md)
-
 ## 스타 기록
 
-🎉 **GitHub 스타 30,000개, 감사합니다!**
+🎉 **GitHub 스타 40,000개, 감사합니다!**
 
 REA를 사용하고, 버그를 보고하고, 기능을 요청하고, 빌드를 테스트하고, 수정에 기여해 주신 모든 분께 감사드립니다.
 
@@ -282,6 +274,12 @@ REA를 사용하고, 버그를 보고하고, 기능을 요청하고, 빌드를
 
 REA는 합법적인 리버스 엔지니어링 연구, 분석, 재구성을 위한 도구를 제공합니다. 필요한 권한을 얻고 관련 법률을 준수할 책임은 사용자에게 있습니다. 이 프로젝트는 불법적이거나 허가받지 않은 사용을 지지하지 않습니다.
 
+## 기여
+
+REA에 도움을 보태 주세요! [issue를 등록](https://github.com/morluto/rea/issues)해 버그나 기능을 제안하거나, [pull request를 보내](https://github.com/morluto/rea/pulls) 코드와 문서를 개선할 수 있습니다.
+
+개발 환경과 검사 항목은 [CONTRIBUTING.md](CONTRIBUTING.md), 검증 절차는 [테스트 가이드](docs/testing.md), 프로젝트 구조는 [아키텍처 지도](docs/architecture.mermaid)를 참고하세요.
+
 ## 라이선스
 
 [MIT](LICENSE)

README_pl.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA uruchamia most analityczny w Hopperze podczas analizy natywnego pliku binarnego" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Społeczność REA">
 <tr>
@@ -154,6 +154,8 @@ Obsługiwane formaty natywne i platformy zależą od dostawcy analizy. Zobacz [k
 
 ## Przykłady zastosowań
 
+[![Ilustracje studiów przypadku panoramowania dźwięku w DX-Ball, mostka schowka w Notion i pierścienia pocisków w TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: odtworzenie obliczania panoramy dźwięku
 
 Prześledź wywołanie dźwięku do funkcji pomocniczej przeliczającej pozycję na panoramę, sprawdź instrukcje i przekształć niepełny pseudokod w C. Odtworzona implementacja przechodzi 3 205 przypadków dla oryginalnego x86 i odtwarza wszystkie 63 bajty skompilowanej funkcji.
@@ -200,7 +202,7 @@ REA uruchamia Hoppera, gdy wymaga tego operacja. W systemie macOS przy pierwszym
 <details>
 <summary><strong>Co daje zainstalowanie umiejętności z skills.sh?</strong></summary>
 
-Umiejętność dostarcza agentowi instrukcje prowadzenia analizy. Użyj `rea setup`, aby zarejestrować serwer MCP REA i zainstalować pasujące instrukcje, a następnie uruchom agenta ponownie. Zobacz [instalację samej umiejętności](docs/installation.md#skill-only-installation).
+Umiejętność dostarcza agentowi instrukcje prowadzenia analizy. Użyj `npx rea-agents setup`, aby zarejestrować serwer MCP REA i zainstalować pasujące instrukcje, a następnie uruchom agenta ponownie. Zobacz [instalację samej umiejętności](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ Zacznij od [przewodników z przykładami](https://rea.tools/guides/) na stronie
 
 Zgłaszaj podatności zgodnie z [SECURITY.md](SECURITY.md).
 
-## Współtworzenie
-
-Chętnie przyjmiemy Twoją pomoc w rozwoju REA! [Otwórz zgłoszenie](https://github.com/morluto/rea/issues), aby poinformować o błędzie lub zaproponować funkcję, albo [wyślij pull request](https://github.com/morluto/rea/pulls) z ulepszeniami kodu lub dokumentacji.
-
-Zobacz [CONTRIBUTING.md](CONTRIBUTING.md), aby poznać konfigurację środowiska programistycznego i kontrole, [testowanie](docs/testing.md), aby poznać ścieżki weryfikacji, oraz [mapę architektury](docs/architecture.mermaid), aby poznać strukturę projektu.
-
-## Linki projektu
-
-[Strona internetowa](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Zgłoszenia](https://github.com/morluto/rea/issues) · [Bezpieczeństwo](SECURITY.md)
-
 ## Historia gwiazdek
 
-🎉 **30 000 gwiazdek na GitHubie — dziękujemy!**
+🎉 **40 000 gwiazdek na GitHubie — dziękujemy!**
 
 Dziękujemy wszystkim, którzy używają REA, zgłaszają błędy, proponują nowe funkcje, testują kompilacje i przesyłają poprawki.
 
@@ -280,6 +272,12 @@ Dziękujemy wszystkim, którzy używają REA, zgłaszają błędy, proponują no
 
 REA dostarcza narzędzia do zgodnych z prawem badań z zakresu inżynierii wstecznej, analizy i odtwarzania. Odpowiadasz za uzyskanie wymaganych zezwoleń i przestrzeganie obowiązującego prawa. Projekt nie popiera działań nielegalnych ani nieautoryzowanych.
 
+## Współtworzenie
+
+Chętnie przyjmiemy Twoją pomoc w rozwoju REA! [Otwórz zgłoszenie](https://github.com/morluto/rea/issues), aby poinformować o błędzie lub zaproponować funkcję, albo [wyślij pull request](https://github.com/morluto/rea/pulls) z ulepszeniami kodu lub dokumentacji.
+
+Zobacz [CONTRIBUTING.md](CONTRIBUTING.md), aby poznać konfigurację środowiska programistycznego i kontrole, [testowanie](docs/testing.md), aby poznać ścieżki weryfikacji, oraz [mapę architektury](docs/architecture.mermaid), aby poznać strukturę projektu.
+
 ## Licencja
 
 [MIT](LICENSE)

README_pt-BR.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA inicia sua ponte de análise dentro do Hopper enquanto inspeciona um binário nativo" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Comunidade REA">
 <tr>
@@ -154,6 +154,8 @@ Os formatos nativos e os sistemas anfitriões compatíveis variam por provedor.
 
 ## Casos de uso
 
+[![Ilustrações dos estudos de panoramização de áudio do DX-Ball, da ponte da área de transferência do Notion e do anel de projéteis do TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: reconstruir um cálculo de panorâmica de áudio
 
 Siga uma chamada de áudio até a função auxiliar que converte posição em panorâmica, inspecione as instruções e transforme pseudocódigo incompleto em C. A reconstrução passa em 3.205 casos com o x86 original e reproduz todos os 63 bytes da função compilada.
@@ -200,7 +202,7 @@ O REA inicia o Hopper quando uma operação precisa dele. No macOS, um diálogo
 <details>
 <summary><strong>O que faz a instalação da skill pelo skills.sh?</strong></summary>
 
-A skill fornece instruções de investigação ao seu agente. Use `rea setup` para registrar o servidor MCP do REA e instalar as instruções correspondentes, depois reinicie seu agente. Consulte [instalação apenas da skill](docs/installation.md#skill-only-installation).
+A skill fornece instruções de investigação ao seu agente. Use `npx rea-agents setup` para registrar o servidor MCP do REA e instalar as instruções correspondentes, depois reinicie seu agente. Consulte [instalação apenas da skill](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ Comece pelos [guias práticos](https://rea.tools/guides/) do site. Para opções
 
 Relate vulnerabilidades conforme [SECURITY.md](SECURITY.md).
 
-## Contribuir
-
-Sua ajuda com o REA é bem-vinda! [Abra uma issue](https://github.com/morluto/rea/issues) para relatar um bug ou sugerir uma funcionalidade, ou [envie um pull request](https://github.com/morluto/rea/pulls) para melhorar o código ou a documentação.
-
-Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para configurar o ambiente de desenvolvimento e as verificações, o [guia de testes](docs/testing.md) para os fluxos de verificação e o [mapa da arquitetura](docs/architecture.mermaid) para a estrutura do projeto.
-
-## Links do projeto
-
-[Site](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Segurança](SECURITY.md)
-
 ## Histórico de estrelas
 
-🎉 **30.000 estrelas no GitHub — muito obrigado!**
+🎉 **40.000 estrelas no GitHub — muito obrigado!**
 
 Obrigado a todos que usam o REA, relatam bugs, sugerem funcionalidades, testam builds e contribuem com correções.
 
@@ -280,6 +272,12 @@ Obrigado a todos que usam o REA, relatam bugs, sugerem funcionalidades, testam b
 
 O REA fornece ferramentas para pesquisa, análise e reconstrução por engenharia reversa dentro da lei. Você é responsável por obter as autorizações necessárias e cumprir as leis aplicáveis. O projeto não apoia usos ilegais ou não autorizados.
 
+## Contribuir
+
+Sua ajuda com o REA é bem-vinda! [Abra uma issue](https://github.com/morluto/rea/issues) para relatar um bug ou sugerir uma funcionalidade, ou [envie um pull request](https://github.com/morluto/rea/pulls) para melhorar o código ou a documentação.
+
+Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para configurar o ambiente de desenvolvimento e as verificações, o [guia de testes](docs/testing.md) para os fluxos de verificação e o [mapa da arquitetura](docs/architecture.mermaid) para a estrutura do projeto.
+
 ## Licença
 
 [MIT](LICENSE)

README_ru.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA запускает мост анализа внутри Hopper при исследовании нативного бинарного файла" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Сообщество REA">
 <tr>
@@ -154,6 +154,8 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так
 
 ## Примеры
 
+[![Иллюстрации примеров панорамирования звука в DX-Ball, моста буфера обмена Notion и кольца пуль в TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: восстановление расчёта звуковой панорамы
 
 Проследите звуковой вызов до функции, преобразующей координату в значение панорамы, изучите инструкции и превратите неполный псевдокод в C. Восстановленная реализация проходит 3 205 тестов с исходным x86-кодом и воспроизводит все 63 байта скомпилированной функции.
@@ -200,7 +202,7 @@ REA запускает Hopper, когда он нужен для операци
 <details>
 <summary><strong>Что даёт установка skill с skills.sh?</strong></summary>
 
-Skill предоставляет агенту инструкции по исследованию. Используйте `rea setup`, чтобы зарегистрировать MCP-сервер REA и установить соответствующие инструкции, затем перезапустите агента. См. [установку только skill](docs/installation.md#skill-only-installation).
+Skill предоставляет агенту инструкции по исследованию. Используйте `npx rea-agents setup`, чтобы зарегистрировать MCP-сервер REA и установить соответствующие инструкции, затем перезапустите агента. См. [установку только skill](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ npx rea-agents@latest setup
 
 Сообщайте об уязвимостях согласно [SECURITY.md](SECURITY.md).
 
-## Участие в проекте
-
-Будем рады вашей помощи с REA! [Откройте issue](https://github.com/morluto/rea/issues), чтобы сообщить об ошибке или предложить функцию, либо [отправьте pull request](https://github.com/morluto/rea/pulls) с улучшениями кода или документации.
-
-Настройка среды разработки и проверки описаны в [CONTRIBUTING.md](CONTRIBUTING.md), направления проверки — в [руководстве по тестированию](docs/testing.md), а структура проекта — на [схеме архитектуры](docs/architecture.mermaid).
-
-## Ссылки проекта
-
-[Сайт](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Безопасность](SECURITY.md)
-
 ## История звёзд
 
-🎉 **30 000 звёзд на GitHub — спасибо!**
+🎉 **40 000 звёзд на GitHub — спасибо!**
 
 Спасибо всем, кто использует REA, сообщает об ошибках, предлагает новые функции, тестирует сборки и помогает с исправлениями.
 
@@ -280,6 +272,12 @@ npx rea-agents@latest setup
 
 REA предоставляет инструменты для законных исследований, анализа и реконструкции с помощью реверс-инжиниринга. Вы отвечаете за получение необходимых разрешений и соблюдение применимых законов. Проект не поддерживает незаконное или несанкционированное использование.
 
+## Участие в проекте
+
+Будем рады вашей помощи с REA! [Откройте issue](https://github.com/morluto/rea/issues), чтобы сообщить об ошибке или предложить функцию, либо [отправьте pull request](https://github.com/morluto/rea/pulls) с улучшениями кода или документации.
+
+Настройка среды разработки и проверки описаны в [CONTRIBUTING.md](CONTRIBUTING.md), направления проверки — в [руководстве по тестированию](docs/testing.md), а структура проекта — на [схеме архитектуры](docs/architecture.mermaid).
+
 ## Лицензия
 
 [MIT](LICENSE)

README_th.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA เริ่มบริดจ์การวิเคราะห์ภายใน Hopper ขณะตรวจสอบไบนารีเนทีฟ" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="ชุมชน REA">
 <tr>
@@ -154,6 +154,8 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26
 
 ## ตัวอย่างการใช้งาน
 
+[![ภาพประกอบกรณีศึกษาการแพนเสียงใน DX-Ball บริดจ์คลิปบอร์ดของ Notion และวงแหวนกระสุนใน TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: สร้างการคำนวณแพนเสียงขึ้นใหม่
 
 ติดตามการเรียกเสียงไปยังฟังก์ชันช่วยแปลงตำแหน่งเป็นค่าแพน ตรวจสอบคำสั่ง และแปลงโค้ดเทียมที่ยังไม่สมบูรณ์เป็น C การสร้างขึ้นใหม่นี้ผ่านการทดสอบ 3,205 กรณีเทียบกับ x86 ต้นฉบับ และสร้างไบต์ทั้ง 63 ไบต์ของฟังก์ชันที่คอมไพล์แล้วได้ตรงกัน
@@ -200,7 +202,7 @@ REA เริ่ม Hopper เมื่อการดำเนินการ
 <details>
 <summary><strong>การติดตั้งสกิลจาก skills.sh ทำอะไร?</strong></summary>
 
-สกิลให้คำแนะนำการตรวจสอบแก่เอเจนต์ ใช้ `rea setup` เพื่อลงทะเบียนเซิร์ฟเวอร์ MCP ของ REA และติดตั้งคำแนะนำที่ตรงกัน แล้วเริ่มเอเจนต์ใหม่ ดู[การติดตั้งเฉพาะสกิล](docs/installation.md#skill-only-installation)
+สกิลให้คำแนะนำการตรวจสอบแก่เอเจนต์ ใช้ `npx rea-agents setup` เพื่อลงทะเบียนเซิร์ฟเวอร์ MCP ของ REA และติดตั้งคำแนะนำที่ตรงกัน แล้วเริ่มเอเจนต์ใหม่ ดู[การติดตั้งเฉพาะสกิล](docs/installation.md#skill-only-installation)
 
 </details>
 
@@ -252,19 +254,9 @@ npx rea-agents@latest setup
 
 รายงานช่องโหว่ผ่าน [SECURITY.md](SECURITY.md)
 
-## การมีส่วนร่วม
-
-เรายินดีรับความช่วยเหลือในการพัฒนา REA! [เปิด issue](https://github.com/morluto/rea/issues) เพื่อรายงานบั๊กหรือเสนอฟีเจอร์ หรือ[ส่ง pull request](https://github.com/morluto/rea/pulls) เพื่อปรับปรุงโค้ดหรือเอกสาร
-
-ดู [CONTRIBUTING.md](CONTRIBUTING.md) สำหรับการตั้งค่าสภาพแวดล้อมพัฒนาและการตรวจสอบ ดู[การทดสอบ](docs/testing.md) สำหรับแนวทางการตรวจยืนยัน และ[แผนผังสถาปัตยกรรม](docs/architecture.mermaid) สำหรับโครงสร้างโปรเจกต์
-
-## ลิงก์ของโปรเจกต์
-
-[เว็บไซต์](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [ความปลอดภัย](SECURITY.md)
-
 ## ประวัติดาว
 
-🎉 **30,000 ดาวบน GitHub — ขอบคุณทุกคน!**
+🎉 **40,000 ดาวบน GitHub — ขอบคุณทุกคน!**
 
 ขอบคุณทุกคนที่ใช้ REA รายงานบั๊ก เสนอฟีเจอร์ ทดสอบบิลด์ และช่วยแก้ไข
 
@@ -280,6 +272,12 @@ npx rea-agents@latest setup
 
 REA มีเครื่องมือสำหรับการวิจัยวิศวกรรมย้อนกลับ การวิเคราะห์ และการสร้างขึ้นใหม่อย่างถูกกฎหมาย คุณมีหน้าที่ขออนุญาตตามที่จำเป็นและปฏิบัติตามกฎหมายที่เกี่ยวข้อง โปรเจกต์นี้ไม่สนับสนุนการใช้งานที่ผิดกฎหมายหรือไม่ได้รับอนุญาต
 
+## การมีส่วนร่วม
+
+เรายินดีรับความช่วยเหลือในการพัฒนา REA! [เปิด issue](https://github.com/morluto/rea/issues) เพื่อรายงานบั๊กหรือเสนอฟีเจอร์ หรือ[ส่ง pull request](https://github.com/morluto/rea/pulls) เพื่อปรับปรุงโค้ดหรือเอกสาร
+
+ดู [CONTRIBUTING.md](CONTRIBUTING.md) สำหรับการตั้งค่าสภาพแวดล้อมพัฒนาและการตรวจสอบ ดู[การทดสอบ](docs/testing.md) สำหรับแนวทางการตรวจยืนยัน และ[แผนผังสถาปัตยกรรม](docs/architecture.mermaid) สำหรับโครงสร้างโปรเจกต์
+
 ## สัญญาอนุญาต
 
 [MIT](LICENSE)

README_tr.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA, yerel bir ikili dosyayı incelerken Hopper içinde analiz köprüsünü başlatıyor" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA topluluğu">
 <tr>
@@ -154,6 +154,8 @@ Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağ
 
 ## Örnek çalışmalar
 
+[![DX-Ball ses kaydırma, Notion pano köprüsü ve TH04 mermi halkası örneklerinin çizimleri](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: Sesin stereo konumlandırma hesabını yeniden oluşturma
 
 Bir ses çağrısından konumu stereo konumlandırmaya dönüştüren yardımcı fonksiyona ilerleyin, talimatları inceleyin ve eksik sözde kodu C'ye dönüştürün. Yeniden oluşturulan kod, özgün x86 üzerinde 3.205 test durumunu geçer ve derlenmiş fonksiyonun 63 baytının tamamını yeniden üretir.
@@ -200,7 +202,7 @@ REA, bir işlem gerektirdiğinde Hopper'ı başlatır. macOS'ta ilk çalıştır
 <details>
 <summary><strong>skills.sh üzerinden skill yüklemek ne yapar?</strong></summary>
 
-Skill, ajanınıza araştırma talimatları sağlar. REA'nın MCP sunucusunu kaydetmek ve uyumlu talimatları yüklemek için `rea setup` kullanın, ardından ajanınızı yeniden başlatın. [Yalnızca skill yükleme](docs/installation.md#skill-only-installation) belgesine bakın.
+Skill, ajanınıza araştırma talimatları sağlar. REA'nın MCP sunucusunu kaydetmek ve uyumlu talimatları yüklemek için `npx rea-agents setup` kullanın, ardından ajanınızı yeniden başlatın. [Yalnızca skill yükleme](docs/installation.md#skill-only-installation) belgesine bakın.
 
 </details>
 
@@ -252,19 +254,9 @@ Web sitesindeki [uygulamalı rehberlerden](https://rea.tools/guides/) başlayın
 
 Güvenlik açıklarını [SECURITY.md](SECURITY.md) üzerinden bildirin.
 
-## Katkıda bulunma
-
-REA'ya katkınızı bekliyoruz! Hata bildirmek veya özellik önermek için bir [issue açın](https://github.com/morluto/rea/issues); kodu veya belgeleri geliştirmek için bir [pull request gönderin](https://github.com/morluto/rea/pulls).
-
-Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](CONTRIBUTING.md), doğrulama süreçleri için [test rehberi](docs/testing.md) ve proje yapısı için [mimari harita](docs/architecture.mermaid) belgelerine bakın.
-
-## Proje bağlantıları
-
-[Web sitesi](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Güvenlik](SECURITY.md)
-
 ## Yıldız geçmişi
 
-🎉 **GitHub'da 30.000 yıldız — teşekkürler!**
+🎉 **GitHub'da 40.000 yıldız — teşekkürler!**
 
 REA'yı kullanan, hata bildiren, özellik talep eden, derlemeleri test eden ve düzeltmelere katkıda bulunan herkese teşekkürler.
 
@@ -280,6 +272,12 @@ REA'yı kullanan, hata bildiren, özellik talep eden, derlemeleri test eden ve d
 
 REA, yasal tersine mühendislik araştırması, analizi ve yeniden oluşturma için araçlar sağlar. Gerekli izinleri almak ve geçerli yasalara uymak sizin sorumluluğunuzdadır. Proje yasa dışı veya yetkisiz kullanımı desteklemez.
 
+## Katkıda bulunma
+
+REA'ya katkınızı bekliyoruz! Hata bildirmek veya özellik önermek için bir [issue açın](https://github.com/morluto/rea/issues); kodu veya belgeleri geliştirmek için bir [pull request gönderin](https://github.com/morluto/rea/pulls).
+
+Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](CONTRIBUTING.md), doğrulama süreçleri için [test rehberi](docs/testing.md) ve proje yapısı için [mimari harita](docs/architecture.mermaid) belgelerine bakın.
+
 ## Lisans
 
 [MIT](LICENSE)

README_uk.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA запускає міст аналізу всередині Hopper під час дослідження нативного бінарного файла" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Спільнота REA">
 <tr>
@@ -154,6 +154,8 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та
 
 ## Приклади
 
+[![Ілюстрації прикладів панорамування звуку в DX-Ball, мосту буфера обміну Notion та кільця куль у TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: відновлення розрахунку звукової панорами
 
 Простежте звуковий виклик до допоміжної функції, що перетворює координату на панорамування, перевірте інструкції та перетворіть неповний псевдокод на C. Відновлена реалізація проходить 3 205 тестів з оригінальним x86-кодом і відтворює всі 63 байти скомпільованої функції.
@@ -200,7 +202,7 @@ REA запускає Hopper, коли він потрібен для опера
 <details>
 <summary><strong>Що дає встановлення skill із skills.sh?</strong></summary>
 
-Skill надає агенту інструкції дослідження. Використовуйте `rea setup`, щоб зареєструвати MCP-сервер REA та встановити відповідні інструкції, а потім перезапустіть агента. Дивіться [встановлення лише skill](docs/installation.md#skill-only-installation).
+Skill надає агенту інструкції дослідження. Використовуйте `npx rea-agents setup`, щоб зареєструвати MCP-сервер REA та встановити відповідні інструкції, а потім перезапустіть агента. Дивіться [встановлення лише skill](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ npx rea-agents@latest setup
 
 Повідомляйте про вразливості згідно з [SECURITY.md](SECURITY.md).
 
-## Участь у проєкті
-
-Будемо раді вашій допомозі з REA! [Відкрийте issue](https://github.com/morluto/rea/issues), щоб повідомити про помилку чи запропонувати функцію, або [надішліть pull request](https://github.com/morluto/rea/pulls) з поліпшеннями коду чи документації.
-
-Налаштування середовища розробки й перевірки описано в [CONTRIBUTING.md](CONTRIBUTING.md), шляхи верифікації — у [посібнику тестування](docs/testing.md), а структуру проєкту — на [схемі архітектури](docs/architecture.mermaid).
-
-## Посилання проєкту
-
-[Сайт](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Безпека](SECURITY.md)
-
 ## Історія зірок
 
-🎉 **30 000 зірок на GitHub — дякуємо!**
+🎉 **40 000 зірок на GitHub — дякуємо!**
 
 Дякуємо всім, хто використовує REA, повідомляє про помилки, пропонує нові функції, тестує збірки й допомагає з виправленнями.
 
@@ -280,6 +272,12 @@ npx rea-agents@latest setup
 
 REA надає інструменти для законних досліджень, аналізу й реконструкції за допомогою реверс-інжинірингу. Ви відповідаєте за отримання необхідних дозволів і дотримання застосовних законів. Проєкт не підтримує незаконне або несанкціоноване використання.
 
+## Участь у проєкті
+
+Будемо раді вашій допомозі з REA! [Відкрийте issue](https://github.com/morluto/rea/issues), щоб повідомити про помилку чи запропонувати функцію, або [надішліть pull request](https://github.com/morluto/rea/pulls) з поліпшеннями коду чи документації.
+
+Налаштування середовища розробки й перевірки описано в [CONTRIBUTING.md](CONTRIBUTING.md), шляхи верифікації — у [посібнику тестування](docs/testing.md), а структуру проєкту — на [схемі архітектури](docs/architecture.mermaid).
+
 ## Ліцензія
 
 [MIT](LICENSE)

README_vi.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA khởi chạy cầu nối phân tích bên trong Hopper khi kiểm tra tệp nhị phân mã máy" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="Cộng đồng REA">
 <tr>
@@ -154,6 +154,8 @@ Kiểm tra tĩnh JavaScript và .NET đọc các tệp được cung cấp mà k
 
 ## Các nghiên cứu điển hình
 
+[![Minh họa các ví dụ về cân bằng âm thanh DX-Ball, cầu nối bảng nhớ tạm Notion và vòng đạn TH04](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball: tái tạo phép tính phân bố âm thanh trái phải
 
 Lần theo lời gọi âm thanh đến hàm hỗ trợ chuyển vị trí thành giá trị phân bố âm thanh, kiểm tra các lệnh và chuyển mã giả chưa đầy đủ sang C. Bản tái tạo vượt qua 3.205 trường hợp kiểm thử với x86 gốc và tái tạo đủ 63 byte của hàm đã biên dịch.
@@ -200,7 +202,7 @@ REA khởi chạy Hopper khi một thao tác cần đến nó. Trên macOS, hộ
 <details>
 <summary><strong>Cài skill từ skills.sh có tác dụng gì?</strong></summary>
 
-Skill cung cấp hướng dẫn điều tra cho tác nhân. Dùng `rea setup` để đăng ký máy chủ MCP của REA và cài hướng dẫn tương ứng, sau đó khởi động lại tác nhân. Xem [chỉ cài skill](docs/installation.md#skill-only-installation).
+Skill cung cấp hướng dẫn điều tra cho tác nhân. Dùng `npx rea-agents setup` để đăng ký máy chủ MCP của REA và cài hướng dẫn tương ứng, sau đó khởi động lại tác nhân. Xem [chỉ cài skill](docs/installation.md#skill-only-installation).
 
 </details>
 
@@ -252,19 +254,9 @@ Bắt đầu với [hướng dẫn thực hành](https://rea.tools/guides/) trê
 
 Báo cáo lỗ hổng theo [SECURITY.md](SECURITY.md).
 
-## Đóng góp
-
-Chúng tôi hoan nghênh bạn giúp phát triển REA! [Mở issue](https://github.com/morluto/rea/issues) để báo lỗi hoặc đề xuất tính năng, hoặc [gửi pull request](https://github.com/morluto/rea/pulls) để cải thiện mã hay tài liệu.
-
-Xem [CONTRIBUTING.md](CONTRIBUTING.md) về thiết lập môi trường phát triển và các bước kiểm tra, [hướng dẫn kiểm thử](docs/testing.md) về các luồng xác minh và [sơ đồ kiến trúc](docs/architecture.mermaid) về cấu trúc dự án.
-
-## Liên kết dự án
-
-[Trang web](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [Bảo mật](SECURITY.md)
-
 ## Lịch sử sao
 
-🎉 **30.000 sao trên GitHub — xin cảm ơn!**
+🎉 **40.000 sao trên GitHub — xin cảm ơn!**
 
 Cảm ơn mọi người đã sử dụng REA, báo lỗi, đề xuất tính năng, kiểm thử bản dựng và đóng góp bản sửa lỗi.
 
@@ -280,6 +272,12 @@ Cảm ơn mọi người đã sử dụng REA, báo lỗi, đề xuất tính n
 
 REA cung cấp công cụ cho nghiên cứu dịch ngược, phân tích và tái tạo hợp pháp. Bạn có trách nhiệm có được các quyền cho phép cần thiết và tuân thủ luật áp dụng. Dự án không ủng hộ việc sử dụng trái pháp luật hoặc không được cho phép.
 
+## Đóng góp
+
+Chúng tôi hoan nghênh bạn giúp phát triển REA! [Mở issue](https://github.com/morluto/rea/issues) để báo lỗi hoặc đề xuất tính năng, hoặc [gửi pull request](https://github.com/morluto/rea/pulls) để cải thiện mã hay tài liệu.
+
+Xem [CONTRIBUTING.md](CONTRIBUTING.md) về thiết lập môi trường phát triển và các bước kiểm tra, [hướng dẫn kiểm thử](docs/testing.md) về các luồng xác minh và [sơ đồ kiến trúc](docs/architecture.mermaid) về cấu trúc dự án.
+
 ## Giấy phép
 
 [MIT](LICENSE)

README_zh-TW.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA 在 Hopper 中啟動分析橋，檢查原生二進位檔案" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA 社群">
 <tr>
@@ -154,6 +154,8 @@ REA 需要 Node.js 22.x（>=22.19）、24.x（>=24.11）或 26+，以及 npm。
 
 ## 案例
 
+[![DX-Ball 聲音平移、Notion 剪貼簿橋接與 TH04 彈幕環案例的插圖](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball：重建聲像計算
 
 沿聲音呼叫追蹤到根據位置計算聲像的輔助函數，檢查指令，將不完整的偽程式碼轉為 C。重建結果通過了 3,205 個原始 x86 測試用例，並復現了編譯後函數的全部 63 個位元組。
@@ -202,7 +204,7 @@ REA 會在操作需要時啟動 Hopper。在 macOS 上，首次執行時可能
 <details>
 <summary><strong>從 skills.sh 安裝 skill 有什麼作用？</strong></summary>
 
-skill 為 AI 代理提供調查指引。使用 `rea setup` 註冊 REA 的 MCP 服務並安裝對應的指引，然後重新啟動 AI 代理。見[僅安裝 skill](docs/installation.md#skill-only-installation)。
+skill 為 AI 代理提供調查指引。使用 `npx rea-agents setup` 註冊 REA 的 MCP 服務並安裝對應的指引，然後重新啟動 AI 代理。見[僅安裝 skill](docs/installation.md#skill-only-installation)。
 
 </details>
 
@@ -254,19 +256,9 @@ npx rea-agents@latest setup
 
 請按照 [SECURITY.md](SECURITY.md) 報告漏洞。
 
-## 參與貢獻
-
-歡迎幫助改進 REA！你可以[提交 issue](https://github.com/morluto/rea/issues) 報告錯誤或建議功能，也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改進程式碼或文件。
-
-開發設定和檢查見 [CONTRIBUTING.md](CONTRIBUTING.md)，驗證流程見[測試指南](docs/testing.md)，專案結構見[架構圖](docs/architecture.mermaid)。
-
-## 專案連結
-
-[網站](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [安全](SECURITY.md)
-
 ## Star 歷史
 
-🎉 **GitHub Star 達到 30,000 個，感謝大家！**
+🎉 **GitHub Star 達到 40,000 個，感謝大家！**
 
 感謝每一位使用 REA、報告錯誤、提出功能需求、測試建置和貢獻修復的朋友。
 
@@ -282,6 +274,12 @@ npx rea-agents@latest setup
 
 REA 為合法的逆向工程研究、分析和重建提供工具。你有責任取得所需授權並遵守適用法律。本專案不認同非法或未經授權的使用。
 
+## 參與貢獻
+
+歡迎幫助改進 REA！你可以[提交 issue](https://github.com/morluto/rea/issues) 報告錯誤或建議功能，也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改進程式碼或文件。
+
+開發設定和檢查見 [CONTRIBUTING.md](CONTRIBUTING.md)，驗證流程見[測試指南](docs/testing.md)，專案結構見[架構圖](docs/architecture.mermaid)。
+
 ## 授權條款
 
 [MIT](LICENSE)

README_zh.md

@@ -11,7 +11,7 @@
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
 [![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
-[![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js requirements](https://img.shields.io/badge/Node.js-requirements-339933?style=flat-square&logo=nodedotjs&logoColor=white)](#current-status)
 [![skills.sh](https://skills.sh/b/morluto/rea?style=flat-square)](https://skills.sh/morluto/rea/reverse-engineer-anything)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 [![Discord](https://img.shields.io/discord/1556595354999332884?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/GkcryMnJDM)
@@ -28,7 +28,7 @@
 
 <img src="docs/assets/rea-hopper-analysis.png" alt="REA 在 Hopper 中启动分析桥，检查原生二进制文件" width="1200" />
 
-<br />
+<br /><br />
 
 <table aria-label="REA 社区">
 <tr>
@@ -154,6 +154,8 @@ REA 需要 Node.js 22.x（>=22.19）、24.x（>=24.11）或 26+，以及 npm。
 
 ## 案例
 
+[![DX-Ball 声音平移、Notion 剪贴板桥接与 TH04 弹幕环案例的插图](docs/assets/rea-showcases.png)](https://rea.tools/showcase/)
+
 ### DX-Ball：重建声像计算
 
 沿声音调用追踪到根据位置计算声像的辅助函数，检查指令，将不完整的伪代码转为 C。重建结果通过了 3,205 个原始 x86 测试用例，并复现了编译后函数的全部 63 个字节。
@@ -202,7 +204,7 @@ REA 会在操作需要时启动 Hopper。在 macOS 上，首次运行时可能
 <details>
 <summary><strong>从 skills.sh 安装 skill 有什么作用？</strong></summary>
 
-skill 为智能体提供调查指引。使用 `rea setup` 注册 REA 的 MCP 服务并安装匹配的指引，然后重启智能体。见[仅安装 skill](docs/installation.md#skill-only-installation)。
+skill 为智能体提供调查指引。使用 `npx rea-agents setup` 注册 REA 的 MCP 服务并安装匹配的指引，然后重启智能体。见[仅安装 skill](docs/installation.md#skill-only-installation)。
 
 </details>
 
@@ -254,19 +256,9 @@ npx rea-agents@latest setup
 
 请按照 [SECURITY.md](SECURITY.md) 报告漏洞。
 
-## 参与贡献
-
-欢迎帮助改进 REA！你可以[提交 issue](https://github.com/morluto/rea/issues) 报告错误或建议功能，也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改进代码或文档。
-
-开发设置和检查见 [CONTRIBUTING.md](CONTRIBUTING.md)，验证流程见[测试指南](docs/testing.md)，项目结构见[架构图](docs/architecture.mermaid)。
-
-## 项目链接
-
-[网站](https://rea.tools/) · [npm](https://www.npmjs.com/package/rea-agents) · [skills.sh](https://skills.sh/morluto/rea/reverse-engineer-anything) · [Issues](https://github.com/morluto/rea/issues) · [安全](SECURITY.md)
-
 ## Star 历史
 
-🎉 **GitHub Star 达到 30,000 个，感谢大家！**
+🎉 **GitHub Star 达到 40,000 个，感谢大家！**
 
 感谢每一位使用 REA、报告错误、提出功能需求、测试构建和贡献修复的朋友。
 
@@ -282,6 +274,12 @@ npx rea-agents@latest setup
 
 REA 为合法的逆向工程研究、分析和重建提供工具。你有责任取得所需授权并遵守适用法律。项目不支持非法或未经授权的使用。
 
+## 参与贡献
+
+欢迎帮助改进 REA！你可以[提交 issue](https://github.com/morluto/rea/issues) 报告错误或建议功能，也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改进代码或文档。
+
+开发设置和检查见 [CONTRIBUTING.md](CONTRIBUTING.md)，验证流程见[测试指南](docs/testing.md)，项目结构见[架构图](docs/architecture.mermaid)。
+
 ## 许可证
 
 [MIT](LICENSE)

bridge/hopper_bridge.py

@@ -716,6 +716,8 @@ def _analyze_function(document, params):
         "referenced_strings": referenced_strings,
         "referenced_names": referenced_names,
         "basic_blocks": blocks,
+        "native_api": None,
+        "native_value_flow": None,
         "limitations": [
             "Native CallReference classifications are observed where available; detailed reference flags remain unknown.",
             "Hopper's public Python API does not expose equivalent external or thunk classification in this dossier.",

docs/.vitepress/config.ts

@@ -55,7 +55,7 @@ export default defineConfig({
           { text: "Ghidra on Windows", link: "/windows-ghidra-p0" },
           { text: "Ghidra DOS analysis", link: "/ghidra-dos" },
           { text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
-          { text: "Provider evaluation", link: "/provider-evaluation" },
+          { text: "Ghidra semantics", link: "/ghidra-provider" },
         ],
       },
       {
@@ -66,7 +66,6 @@ export default defineConfig({
           { text: "Tool design", link: "/tool-design" },
           { text: "Testing", link: "/testing" },
           { text: "Releasing", link: "/releasing" },
-          { text: "Architecture decisions", link: "/adr/README" },
         ],
       },
     ],

docs/adr/0001-provider-selection-and-analysis-profiles.md

@@ -1,572 +0,0 @@
-# ADR-0001: Provider selection and analysis profiles
-
-- Status: Accepted
-- Date: 2026-07-15
-- Implementation status: The provider registry, deterministic selection,
-  target binding, analysis-profile commitment, and snapshot/Evidence migration
-  are implemented. Ghidra discovery, target/profile resolution, doctor checks,
-  the private headless-session foundation, thirteen read-only inventory/load-image
-  capabilities, and twelve function-analysis capabilities are implemented with
-  real cross-format conformance. Linux/macOS also supports atomic session
-  function annotations; experimental Windows x64 P0 uses bundled native controls
-  and admits only the 25 read-only operations. See the
-  [release boundary](../installation.md#released-package-and-main).
-
-## Context
-
-Before this decision, REA composed the artifact, native macOS, and Hopper
-providers with `CompositeProvider`. That class intentionally requires every
-operation to have one route. Hopper and Ghidra will both implement the deep
-static-analysis operation family, so putting both into that composite would
-either fail at construction or make array order an undeclared selection policy.
-
-The active `BinarySession` also owned one composite client. `open_binary` had no
-provider selector, and the domain `BinaryTarget` contained Hopper loader
-arguments. Analysis snapshot v1 committed those loader arguments and each
-cached entry's provider identity, but it did not commit the selected analysis
-engine, engine version, or complete analysis configuration. Two analyses of the
-same bytes could therefore disagree because of language, compiler, loader,
-analyzer, or provider-version differences while appearing target-compatible.
-
-The decision addressed the earlier representations of
-[`CompositeProvider`](https://github.com/morluto/rea/blob/main/src/application/binary/CompositeProvider.ts),
-[runtime composition](https://github.com/morluto/rea/blob/main/src/composition/binary.ts),
-[`BinarySession`](https://github.com/morluto/rea/blob/main/src/application/binary/BinarySession.ts),
-[`BinaryTarget`](https://github.com/morluto/rea/blob/main/src/domain/binaryTarget.ts),
-[analysis snapshot](https://github.com/morluto/rea/blob/main/src/domain/analysisSnapshot.ts), and
-[session lifecycle inputs](https://github.com/morluto/rea/blob/main/src/contracts/sessionLifecycleInputs.ts).
-
-The next deep provider must not weaken the existing product invariants:
-
-- stable provider-neutral CLI and MCP tool names;
-- exact provenance and explicit unavailable or degraded capabilities;
-- CLI and MCP parity;
-- no silent provider fallback;
-- provider-specific code outside the domain and application models;
-- local, actionable diagnostics with only genuine secrets redacted; and
-- snapshot reuse only when semantic analysis inputs are identical.
-
-## Decision drivers
-
-1. Hopper and Ghidra need to declare overlapping operations without ambiguous
-   dispatch.
-2. A target must have one explainable deep-analysis producer for its lifetime.
-3. Target-free discovery must remain useful and must not start an analysis
-   process.
-4. Existing Hopper-only configurations must keep working when no selector is
-   supplied.
-5. Adding a second installed provider must not silently change results.
-6. Snapshot and Evidence compatibility must include every setting that can
-   materially change analysis.
-7. Provider-specific open settings must not leak into `BinaryTarget` or become
-   generic application fields.
-
-## Terminology
-
-- **Deep provider**: an engine such as Hopper or Ghidra that implements the
-  overlapping static-analysis operation family.
-- **Auxiliary provider**: a provider with a disjoint operation family, such as
-  artifact inventory or native macOS inspection.
-- **Candidate**: a registered deep provider before target selection.
-- **Binding**: the selected deep provider and analysis profile attached to one
-  active target.
-- **Analysis profile**: a canonical commitment to the selected provider,
-  provider version, and normalized semantic analysis settings.
-- **Available**: the adapter and its required local runtime can be used on this
-  host.
-- **Supported**: the candidate accepts the parsed target and supplied open
-  options. Availability and target support are separate observations.
-
-## Decision
-
-### 1. Separate disjoint composition from overlapping selection
-
-`CompositeProvider` remains the mechanism for operation families whose routes
-are disjoint. It must continue rejecting duplicate operation declarations. It
-must not acquire priority, racing, fallback, or provider-selection behavior.
-
-A new `AnalysisProviderRegistry` owns the configured deep-provider candidates.
-Provider IDs are unique; duplicate IDs are a configuration error. The registry
-may hold multiple candidates that declare the same operation. It performs
-candidate discovery, target-support evaluation, option parsing, profile
-resolution, and selection, but it does not choose a different provider for each
-request.
-
-After selection, the session composes exactly one bound deep provider with the
-auxiliary disjoint families:
-
-```text
-                         target-free discovery
-                                  |
-                     AnalysisProviderRegistry
-                       /                    \
-                   Hopper                 Ghidra
-                       \                    /
-                        one selected binding
-                                  |
-        +-------------------------+-------------------------+
-        |                         |                         |
-  selected deep family     artifact family          native family
-        +-------------------------+-------------------------+
-                                  |
-                            BinarySession
-```
-
-An auxiliary operation continues to report its actual auxiliary provider as
-provenance. A deep operation always reports the provider in the active binding.
-The synthetic composite identity is never evidence that two engines jointly
-produced one observation.
-
-Operation ownership is fixed by family:
-
-| Operation family                                             | Executor                                                                                              |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| Deep direct operations and provider-native function analysis | The one bound Hopper or Ghidra provider                                                               |
-| Application-enhanced deep workflows                          | Application composition over the bound provider's declared operations                                 |
-| Native macOS inspection                                      | The disjoint native provider                                                                          |
-| Artifact inventory and extraction                            | The disjoint artifact provider                                                                        |
-| Browser and Electron observation                             | Their independently authorized CDP providers; they do not participate in deep-provider selection      |
-| Session lifecycle, Evidence, comparisons, and reconstruction | The application/session layer using the exact provider provenance recorded by their source operations |
-
-Selecting a deep provider selects the whole deep family. If that provider marks
-an operation unavailable, REA returns the unavailability; it does not borrow
-that one operation from another deep provider. Application-enhanced workflows
-run only when the bound provider supplies their declared dependencies.
-
-### 2. Discover candidates without launching analysis
-
-Each registered candidate exposes three bounded adapter-owned observations:
-
-1. identity and declared capability descriptors;
-2. host availability, including an actionable rejection when unavailable; and
-3. target support plus normalized profile resolution when a target is known.
-
-Target-free discovery may inspect configuration, manifests, executable
-metadata, and documented version files. It must not import a target, create a
-project, open a GUI, or start the long-lived analysis process. Any short-lived
-version probe added later must be explicitly bounded and truthfully declared as
-a process effect.
-
-Candidate output is sorted by provider ID for determinism. Sort order is not
-selection priority. Availability and support use stable codes plus a human
-diagnostic:
-
-| Code                         | Meaning                                                         |
-| ---------------------------- | --------------------------------------------------------------- |
-| `not_configured`             | Required provider location or configuration is absent           |
-| `executable_missing`         | The configured provider entry point is missing or not runnable  |
-| `runtime_missing`            | A required provider runtime, such as Java, is unavailable       |
-| `unsupported_host`           | The host platform or architecture is unsupported                |
-| `unsupported_version`        | The discovered provider or runtime version is unsupported       |
-| `target_kind_unsupported`    | The provider does not accept this target kind                   |
-| `target_format_unsupported`  | The provider does not accept this target format                 |
-| `architecture_unsupported`   | The selected target architecture is unsupported                 |
-| `target_role_unsupported`    | The provider rejects this executable image role                 |
-| `managed_target_unsupported` | The provider does not admit managed code through this deep path |
-| `open_options_invalid`       | The selected adapter rejected its open options                  |
-| `version_unresolved`         | A concrete analysis-engine version could not be committed       |
-
-Diagnostics retain useful local paths, observed versions, architectures, and
-mismatch details. Credentials, authorization headers, license secrets, and
-other genuine secrets remain redacted.
-
-### 3. Use one deterministic selection algorithm
-
-The caller-visible selectors are:
-
-- MCP `open_binary.provider_id`;
-- `rea ... --provider <provider-id|auto>` on every one-shot command that needs
-  deep analysis; and
-- `REA_ANALYSIS_PROVIDER=<provider-id|auto>`, defaulting to `auto`.
-
-The literal value `auto` is reserved and cannot be a provider ID. Precedence is
-request or CLI flag, then environment configuration, then the default `auto`.
-An explicit request for `auto` overrides a concrete environment preference and
-re-enters automatic selection.
-
-Selection occurs after provider-neutral target parsing and before a deep client
-is created:
-
-1. A concrete requested provider ID must exist, be available, support the
-   target, accept its options, and resolve a concrete version and profile. Any
-   failure returns a typed selection error; another provider is never tried.
-2. `auto` filters candidates by availability and target support.
-3. Exactly one usable candidate is selected with source
-   `auto-single-candidate`.
-4. More than one usable candidate is an `ambiguous` selection error. The
-   diagnostic lists the candidates and asks for `provider_id`, `--provider`, or
-   `REA_ANALYSIS_PROVIDER`. REA does not prefer Hopper, Ghidra, registration
-   order, the fastest startup, or the first health response.
-5. When no deep candidate is usable, an automatic open may still establish an
-   unbound target so disjoint artifact or native operations remain available.
-   Deep operations are then explicitly unavailable with the candidate
-   rejections. A concrete request, or a concrete environment preference for a
-   deep-eligible target, remains a hard requirement and fails instead of
-   becoming unbound.
-6. A target that no deep adapter declares support for, such as an artifact-only
-   target, is `not_applicable` rather than a failed deep analysis. Supplying a
-   concrete provider in that open request is still an actionable unsupported-
-   target error. A global environment preference does not make an artifact-only
-   target require a deep provider.
-
-This preserves target opening for non-Hopper capabilities on hosts without a
-deep engine while ensuring that installing a second usable deep engine never
-changes analysis silently.
-
-### 4. Bind once and never fail over mid-session
-
-An active deep binding contains:
-
-```text
-canonical target identity
-selected provider identity and concrete version
-selection source: request | environment | auto-single-candidate
-analysis profile commitment
-owned provider client, once started
-```
-
-The binding is immutable until `close_binary` or an explicit open/switch
-transaction. Provider client creation may remain lazy, but laziness cannot
-change which provider was selected.
-
-- Opening the same canonical target without a new selector keeps the existing
-  binding.
-- Opening the same target with the same provider and profile is idempotent.
-- A different explicit provider or a profile-changing option is a real switch:
-  drain active calls, close owned resources, resolve the new binding, and start
-  it as one serialized transaction.
-- If a switch fails, restore the prior target and binding on a best-effort
-  transactional path and return the original switch error.
-- Provider process exit, timeout, cancellation, capability failure, or adapter
-  error never triggers fallback. The binding stays visible and unavailable
-  until the caller explicitly switches or closes it.
-- A snapshot never chooses or changes the provider. Selection happens first;
-  snapshot compatibility is checked against the resulting binding.
-
-Calls already admitted to one binding complete or cancel against that binding.
-No request can cross a concurrent target or provider transition.
-
-### 5. Keep provider open options adapter-owned
-
-`BinaryTarget` retains only provider-neutral source identity and classification:
-canonical path, source digest, generic kind and format, selected architecture,
-and available architectures. Hopper loader arguments leave the domain model.
-Provider-owned databases use a generic analysis-database classification; their
-adapter determines support. A `.hop` analysis database is therefore accepted only
-by Hopper without teaching the domain how to open it. Ghidra v1 continues to use
-private temporary projects and does not open user projects.
-
-The generic transport may carry one bounded JSON `provider_options` object.
-Only the selected adapter parses its keys and reports `open_options_invalid` at
-that boundary. If this object is exposed over MCP, the CLI parity surface is
-`--provider-options-json` with the same JSON schema and limits. Unknown keys,
-wrong-provider options, excessive depth or size, and non-JSON values fail
-closed.
-
-Environment settings that are inherently adapter-specific, such as the Hopper
-launcher or future Ghidra installation path, remain in adapter configuration.
-They do not become `BinaryTarget` fields. The application layer transports an
-opaque, already-bounded JSON value and the generic commitment described below;
-it does not interpret Hopper or Ghidra option names.
-
-### 6. Commit a canonical analysis profile
-
-Before creating a deep client, the selected adapter normalizes every semantic
-input that can affect analysis. Examples include Hopper loader selection and
-architecture flags, or Ghidra language ID, compiler specification, import mode,
-analyzer set, and analyzer options. Defaults are made explicit, unordered sets
-are sorted, and implicit host-dependent choices are resolved.
-
-The adapter returns this provider-neutral envelope:
-
-```json
-{
-  "provider": { "id": "ghidra", "version": "<concrete version>" },
-  "parameters": {},
-  "digest": "<sha256 of RFC 8785 canonical JSON excluding digest>"
-}
-```
-
-`parameters` is bounded JSON interpreted only by that provider adapter. It
-contains analysis semantics, not credentials, authorization data, temporary
-paths, installation paths, process IDs, timestamps, or other incidental host
-state. The generic domain validates the envelope and digest but treats the
-parameters as opaque data.
-
-A selected deep binding requires a concrete provider version. If the adapter
-cannot determine it, the candidate is unavailable with `version_unresolved`;
-REA does not persist a cache that merely commits `null` or "whatever is
-installed". Provider identity, normalized parameters, or provider version
-changes produce a different digest.
-
-The same target, configuration, and provider must resolve the same profile over
-CLI and MCP. Profile resolution must be side-effect-free and complete before
-the provider imports the target.
-
-### 7. Make snapshots provider- and profile-exact
-
-Analysis snapshots replace Hopper loader arguments with an explicit binding
-commitment:
-
-```text
-target: digest + generic format/kind + selected architecture
-binding: provider identity + analysis profile commitment
-entries: exact immutable queries
-evidence_bundle: retained Evidence records
-```
-
-The snapshot target identity, canonical snapshot content digest, and every
-query ID commit the provider ID, concrete provider version, and profile digest.
-A cached entry is reusable only when all of the following match exactly:
-
-- target digest, generic format and kind, and selected architecture;
-- provider ID and provider version;
-- profile digest;
-- operation and canonical parameters; and
-- the existing cacheability and immutability rules.
-
-Provider or profile switches select a separate cache partition and cannot reuse
-entries from the previous binding. Auxiliary operations are cacheable only if
-their provider defines an equivalent explicit profile commitment; otherwise
-they remain Evidence but not snapshot entries.
-
-Snapshot v1 cannot be parsed as the current snapshot format. Its `loader_args`
-cannot prove which engine version, defaults, or analyzer settings produced the
-entries, so snapshots must be recaptured before they can be used as a cache.
-An embedded Evidence bundle can still be imported separately through the
-Evidence import flow; it is never promoted into an analysis cache.
-
-### 8. Commit concrete or explicitly unknown analysis profiles in Evidence
-
-Every Evidence record includes `analysis_profile`, either the canonical profile
-envelope above or `null` when no profile was observed. Deep-analysis observations
-commit the resolved provider ID, version, and effective configuration in this
-profile. The field participates in the Evidence semantic ID.
-
-An explicitly unknown profile can be displayed and cited, but cannot establish
-profile compatibility, seed snapshot replay, or support an "unchanged"
-conclusion that depends on identical analysis semantics. Snapshot query entries
-must have matching profile-bound Evidence; imports reject missing or mismatched
-observations instead of silently dropping query entries. Both `entries` and
-`workflow_entries` are required arrays, including when empty.
-
-Different providers or profile digests are never snapshot-compatible. A
-derived comparison may compare cross-provider normalized facts only when its
-own contract explicitly defines that semantic comparison. Exact pseudocode,
-provider text, or provider-specific metadata is not treated as equivalent. A
-missing or incompatible profile yields unknown or incompatible, never equal.
-
-### 9. Expose selection truth in status and diagnostics
-
-`binary_session`, `rea providers`, and `rea capabilities` expose the same
-candidate and binding model. The target-free form does not start providers and
-uses `unknown` for target support:
-
-```json
-{
-  "analysis_provider_binding": null,
-  "analysis_provider_candidates": [
-    {
-      "provider": {
-        "id": "hopper",
-        "name": "Hopper Disassembler",
-        "version": "<detected version>"
-      },
-      "availability": {
-        "status": "available",
-        "code": null,
-        "reason": null,
-        "diagnostics": {}
-      },
-      "target_support": {
-        "status": "unknown",
-        "code": null,
-        "reason": "No target is open."
-      },
-      "selected": false,
-      "capabilities": []
-    }
-  ]
-}
-```
-
-With a binding, `analysis_provider_binding` includes the selected identity,
-selection source, and complete profile commitment. Every candidate reports
-`supported`, `unsupported`, or `unknown` target support and whether it was
-selected. Candidate capability descriptors preserve supported, unsupported,
-and degraded truth independently.
-
-An open target also exposes `analysis_run`. Its run ID is allocated by the
-session before client construction and propagated into selected Hopper or
-Ghidra bridge handshake and process environment. Dynamic clients retain
-provider-attributed lineage snapshots only after revalidating launcher
-parent/command and every observed launcher or descendant run token. `not_observed`
-means no dynamic provider has supplied a snapshot. Once one or more start,
-`snapshots` preserves every provider observation; each remains explicitly
-`unavailable` or `verified` and records its `observed_at` time. Retained
-snapshots are not live inventories, and a point-in-time observation never proves
-historical absence.
-
-Status exposes `analysis_provider_candidates` for configured deep providers and
-`analysis_provider_binding` for the selected concrete provider and profile.
-`capabilities` retains effective operation availability and exact provider
-provenance, including auxiliary operation families. There are no synthetic
-flat `provider` or `providers` aliases. Provider prompt completion uses the
-actual selectable candidates.
-
-Selection failures extend the tagged `ProviderSelectionError` with a stable
-reason:
-
-- `unknown_provider`;
-- `provider_unavailable`;
-- `target_unsupported`;
-- `ambiguous`;
-- `invalid_options`.
-
-The error includes the requested ID or `auto`, candidate IDs, rejection codes,
-and actionable local diagnostics. `AnalysisCapabilityUnavailableError` remains
-the error for an operation the selected provider cannot supply.
-`ProviderAdapterError` and more specific provider errors remain failures of the
-already selected provider. None authorizes fallback.
-
-A snapshot whose provider or profile differs from the selected binding returns
-`EvidenceIntegrityError` with stable `profile_mismatch` details. It is an
-integrity incompatibility after selection, not permission to select the
-snapshot's provider.
-
-### 10. Preserve CLI and MCP parity
-
-- `open_binary.provider_id` and one-shot `--provider` use the same parser and
-  selection service.
-- `provider_id: "auto"`, `--provider auto`, and
-  `REA_ANALYSIS_PROVIDER=auto` have identical auto semantics.
-- Startup targets opened from environment configuration use the same service.
-- `rea providers`, `rea capabilities`, and target-free `binary_session` use the
-  same candidate snapshot and reason codes.
-- Guided prompt `provider_id` context is a preference to forward into the open
-  operation; it does not create a hidden routing channel.
-- Tool names and normalized output contracts remain provider-neutral. REA does
-  not add `ghidra_decompile` or `hopper_decompile` tools.
-
-## Provider and snapshot representations
-
-| Behavior or data                                   | Contract                                                                                                             |
-| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| No selector, one usable deep provider              | `auto` selects the sole candidate                                                                                    |
-| No usable deep provider                            | Automatic open may remain unbound for auxiliary operations; deep capabilities explain their unavailability           |
-| Several usable deep providers without a preference | Open fails with `ambiguous`; installation order never becomes policy                                                 |
-| Hopper environment settings                        | Adapter configuration committed into the typed analysis profile, including effective loader arguments                |
-| `open_binary` output                               | Provider-neutral target identity only; no `loaderArgs` projection                                                    |
-| `.hop` input                                       | Analysis database accepted only by Hopper                                                                            |
-| Snapshots                                          | Concrete provider/profile binding, required primitive and workflow entry arrays, and matching authenticated Evidence |
-| Evidence without an observed profile               | Explicit `analysis_profile: null`; ineligible for profile-dependent replay                                           |
-| Snapshot save receipt                              | `primitive_entries`, `workflow_entries`, and `evidence_records` counts without a duplicate `entries` alias           |
-| Provider failure after selection                   | Returned from that provider, without transparent retry through another engine                                        |
-
-## Required behavior scenarios
-
-| Scenario                                                   | Result                                                                      |
-| ---------------------------------------------------------- | --------------------------------------------------------------------------- |
-| Hopper is the only usable candidate, selector omitted      | Hopper is bound by `auto-single-candidate`                                  |
-| Ghidra is the only usable candidate, selector omitted      | Ghidra is bound by `auto-single-candidate`                                  |
-| Both are usable, selector omitted                          | Typed `ambiguous` error; neither provider starts                            |
-| Environment selects Ghidra, request omits a selector       | Ghidra is required and bound or the open fails with its rejection           |
-| Environment selects Ghidra, request selects Hopper         | Request wins; Hopper is required                                            |
-| Environment selects Ghidra, request selects `auto`         | Auto policy runs and is ambiguous when both are usable                      |
-| Unknown concrete provider ID                               | Typed `unknown_provider`; no target transition                              |
-| Selected provider rejects the target or options            | Typed rejection from that candidate only                                    |
-| Selected provider times out after binding                  | Binding remains selected and unavailable; no fallback                       |
-| Same target is reopened without a selector                 | Existing binding remains unchanged                                          |
-| Same bytes are opened with a different profile             | Real provider switch and a separate snapshot partition                      |
-| Snapshot provider or profile differs from the binding      | Typed `EvidenceIntegrityError` with `profile_mismatch`; nothing is imported |
-| Artifact-only target has no deep candidate                 | Target opens unbound; disjoint artifact capabilities remain usable          |
-| Environment prefers Ghidra for an artifact-only target     | Deep selection is `not_applicable`; auxiliary operations remain usable      |
-| Concrete deep provider is requested for artifact-only data | Typed `target_unsupported`; the request is not silently ignored             |
-
-## Consequences
-
-Positive consequences:
-
-- Hopper and Ghidra can coexist without ambiguous operation routes.
-- Provider choice is reproducible, visible, and stable for a target.
-- Installation of another provider cannot silently change analysis.
-- Snapshot and Evidence identities become analysis-configuration aware.
-- Provider adapters retain ownership of their option schemas and diagnostics.
-- Auxiliary capabilities remain usable when no deep engine is installed.
-
-Costs and tradeoffs:
-
-- Multi-provider hosts must choose when more than one candidate is usable.
-- Snapshots must be recaptured when their provider or profile binding changes.
-- Providers must expose deterministic availability, support, version, and
-  profile resolution before they can be admitted.
-- Status and error contracts gain additive structured metadata.
-- Hopper needs an adapter-owned version/profile implementation before profile-
-  exact snapshot persistence is complete.
-
-## Rejected alternatives
-
-### Let `CompositeProvider` choose the first duplicate route
-
-Array order is not a product policy, becomes fragile during wiring changes, and
-hides ambiguity from callers.
-
-### Race providers and keep the first healthy response
-
-Machine load would determine provenance and results. It also starts resources
-the operator did not select and makes cancellation and cleanup harder.
-
-### Fall back after a provider error
-
-Mid-session fallback can combine incompatible engine state and evidence under
-one apparent target. Explicit close or switch is required instead.
-
-### Add provider-prefixed tools
-
-Parallel Hopper and Ghidra tool families would leak adapters into the product
-contract and prevent shared workflows from using capability metadata.
-
-### Store raw provider options in `BinaryTarget`
-
-That repeats the current Hopper coupling and makes every generic consumer learn
-provider schemas. Only canonical profile commitments cross the adapter boundary.
-
-### Treat matching target bytes and provider ID as sufficient for snapshots
-
-Provider versions, analyzer defaults, loaders, languages, and compiler models
-can change results without changing either value.
-
-### Silently upgrade snapshot v1
-
-The missing engine version and analysis settings cannot be reconstructed from
-Hopper loader arguments. A fabricated profile would turn unknown provenance
-into false certainty.
-
-## Implementation progress
-
-The first six implementation stages are shipped:
-
-1. Provider-specific target state was replaced by generic profile and snapshot
-   v2 commitments while preserving Hopper execution behavior.
-2. The registry, selectors, candidate status, binding lifecycle, and
-   overlapping-provider production seams were added.
-3. Proven process-lifecycle primitives were extracted for shared use.
-4. Ghidra availability, target/profile resolution, doctor checks, and a private
-   read-only headless session were admitted without declaring operations.
-5. Program identity, procedures, strings, symbols, memory blocks,
-   address/name resolution, containing-procedure resolution, and search
-   were admitted with exact wire schemas and real debug/stripped ELF
-   conformance.
-6. Function metadata, persistent decompilation, assembly, resolved
-   callers/callees, typed references, xrefs, CFG, and complete function dossiers
-   were admitted. A serial per-Program queue keeps API access ordered without a
-   fixed queue length or per-operation deadline. Real conformance covers
-   x86-64 and AArch64 ELF, PE, Mach-O, stripped symbols, targetless indirect
-   calls, cancellation, and cleanup.
-
-Future stages may deepen format and indirect-flow coverage, but must continue
-to compare normalized semantics rather than provider-specific pseudocode or
-assembly text. Linux and macOS now admit atomic function-name and entry-comment
-edits in the ephemeral database, with readback, rollback, and cache invalidation.
-Executable bytes remain unchanged. Windows P0 retains its read-only boundary;
-GUI and other unimplemented mutations remain unavailable.

docs/adr/0002-controlled-replay-authority-and-sandbox.md

@@ -1,551 +0,0 @@
-# ADR-0002: Controlled JavaScript replay authority and sandbox policy
-
-- Status: Superseded; the controlled JavaScript replay tool was removed
-- Date: 2026-07-16
-- Implementation status: The implementation was removed. The design below is
-  retained as historical context and does not describe a supported REA tool.
-
-> Historical design note: The tool, sandbox backend, and plan/execute workflow
-> described here are no longer part of REA. For runtime behavior, run probes
-> directly against the application and use the available browser, Electron, or
-> process capture workflows.
-
-## Context
-
-REA can reconstruct JavaScript and Electron artifacts, observe an existing
-browser or Electron page through passive CDP, capture an explicitly approved
-process scenario, and correlate those observations without executing bundle
-code in the REA server. The next research workflow needs to execute selected,
-extracted JavaScript modules with controlled inputs and deterministic stubs so
-that parsers, sanitizers, serializers, and similar pure logic can be compared
-across versions.
-
-That workflow crosses a qualitatively different boundary. Source recovered
-from an application is untrusted code. It can intentionally or accidentally
-read files, contact services, spawn processes, exhaust resources, corrupt the
-analysis process, forge protocol output, or interact with another same-user
-process. A JavaScript realm or Node.js `vm` context is useful for constructing
-an API surface, but it is not a security boundary. Node.js also documents its
-permission model as protection against accidental access by trusted code, not
-as containment for malicious code.
-
-Existing authorities cannot be widened to cover this behavior:
-
-- `browser_observe` and `electron_observe` authorize passive attachment to an
-  already-running, operator-owned target. They do not authorize evaluation,
-  navigation, input, or target lifecycle changes.
-- `process_capture` authorizes one declared host process scenario and explicitly
-  states that it is not a sandbox. It cannot silently become permission to run
-  recovered code.
-- static artifact reads authorize inspection of bytes, not execution of those
-  bytes.
-- the Evidence authority `controlled-replay` already describes observations
-  from an approved process experiment. Reusing that epistemic authority is
-  correct, but reusing the process permission capability is not.
-
-The implementation following this ADR must fail closed on hosts where REA
-cannot establish the promised operating-system boundary. It must not copy the
-research `vm.runInContext` scripts into the production server and call that
-isolation.
-
-## Decision drivers
-
-1. Passive observation must never imply authority to execute application code.
-2. The exact code, inputs, stubs, runtime, sandbox policy, and limits approved
-   by the operator must be the ones executed.
-3. Recovered code must not run in the MCP server, CLI adapter, or any provider
-   process.
-4. A sandbox failure must make the capability unavailable, not select a weaker
-   execution mode.
-5. The default policy must provide no host network and no writable host path.
-6. Time, memory, process count, temporary storage, protocol, and output must be
-   bounded independently.
-7. Results must distinguish an observed return, an observed exception or
-   termination, a derived comparison, and an unresolved application-level
-   claim.
-8. A reproducer must commit enough provenance to detect every relevant change
-   without committing proprietary application source to the repository.
-9. CLI and MCP must expose the same plan, approval, execution, cancellation,
-   failure, and Evidence semantics.
-
-## Terminology
-
-- **Passive observation**: bounded reads from an existing browser or Electron
-  target without evaluating code, driving input, navigating, or controlling
-  its lifecycle.
-- **Controlled replay**: execution of operator-selected code in a declared,
-  isolated environment with committed inputs and limits. This is an Evidence
-  authority, not a claim that the real application behaved identically.
-- **Extracted-module replay**: the only admitted JavaScript replay mode in v1.
-  REA evaluates a finite manifest of module bytes and explicit stubs without
-  launching the application.
-- **Application interaction**: launching or driving the original application,
-  browser, renderer, or Electron main process. This is not extracted-module
-  replay and is not authorized by this ADR.
-- **Replay plan**: the canonical, content-addressed description of one proposed
-  run before execution.
-- **Replay worker**: the disposable Node.js process inside the OS sandbox. It
-  is never the REA server process.
-- **Sandbox backend**: the OS mechanisms and adapter that establish namespaces,
-  resource controls, filesystem visibility, and owned cleanup.
-
-## Threat model
-
-### Protected assets
-
-The boundary protects:
-
-- the REA MCP/CLI process, its memory, credentials, sockets, and Evidence
-  ledger;
-- user files outside the approved source reads and all host files from writes;
-- other same-user processes and their control interfaces;
-- host network interfaces, loopback services, Unix sockets, and external
-  services;
-- process, memory, CPU, temporary-storage, output, and protocol capacity;
-- the integrity of the replay plan, result, Evidence provenance, and exported
-  reproducer; and
-- proprietary module bytes, which remain local and are never repository
-  fixtures.
-
-### Adversaries and failure sources
-
-REA treats all of the following as untrusted:
-
-- recovered module source, including transitive modules and source maps;
-- caller-provided JavaScript stubs;
-- structured test inputs and generated fuzz cases;
-- returned values, exceptions, console data, and worker protocol messages;
-- source paths, symbolic links, and files that can change between planning and
-  execution; and
-- a worker that crashes, hangs, forks, allocates aggressively, or exits while
-  descendants remain alive.
-
-An operator-controlled sandbox executable, kernel, Node.js runtime, and REA
-installation are trusted computing base. A hostile host administrator, kernel
-or sandbox vulnerability, hardware side channel, and denial of service by an
-already-compromised same-user process are out of scope. These exclusions do not
-permit REA to omit the per-run resource controls in this decision.
-
-### Required mitigations
-
-The implementation must address:
-
-| Threat                           | Required control                                                                                                |
-| -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Server-process compromise        | Separate worker process inside the OS sandbox; no in-process fallback                                           |
-| Host file reads                  | Empty sandbox root; only a minimal read-only runtime closure; module bytes enter over a private bounded channel |
-| Host file writes                 | No writable bind mounts; size-limited private tmpfs only                                                        |
-| Network access                   | Separate network namespace with no host or external connectivity; no allowlist mode in v1                       |
-| Host process control             | PID/user/IPC/UTS isolation, no inherited control sockets, new session, dropped capabilities                     |
-| Kernel escape/inspection surface | Architecture-checked seccomp denial policy in addition to namespaces, capabilities, and cgroups                 |
-| Fork, memory, or CPU exhaustion  | Per-run cgroup v2 task, memory, swap, and CPU limits plus an outer wall-clock deadline                          |
-| Output/protocol exhaustion       | Independent byte/message/depth limits enforced by the parent before parsing or retaining output                 |
-| Symlink and file-change races    | Canonical authorization, descriptor-backed reads, digesting, staging, and exact plan revalidation               |
-| Undeclared dependencies          | Closed module manifest; exact imports only; missing/dynamic imports fail rather than use host resolution        |
-| Nondeterministic globals         | Versioned clock, PRNG, locale, timezone, platform, and API stubs; undeclared globals are unavailable            |
-| Orphan descendants               | Owned PID namespace and cgroup kill followed by an observable empty-cgroup cleanup check                        |
-| Forged result claims             | Framed worker protocol, strict schemas, parent-computed commitments, and bounded stderr kept separate           |
-| Secret leakage                   | Empty environment, no credential inheritance, bounded local results, and existing genuine-secret redaction      |
-
-## Decision
-
-### 1. Add a distinct `javascript_replay` permission capability
-
-JavaScript replay receives a new permission capability named
-`javascript_replay`. It does not inherit, imply, or satisfy
-`process_capture`, `browser_observe`, `electron_observe`, artifact-read, or
-workspace permissions. Grants for any of those capabilities do not satisfy a
-JavaScript replay request, and a JavaScript replay grant does not authorize
-them.
-
-The administrator ceiling is disabled by default. Its eventual configuration
-must commit:
-
-- canonical roots from which module and optional stub files may be read;
-- the exact Node.js and sandbox-backend executables;
-- filesystem mount authority needed only to construct the private sandbox;
-- network mode `none`; and
-- no inherited environment names.
-
-Configuration establishes only the maximum authority. Every execution also
-requires an active permission grant and literal per-call approval bound to the
-exact replay plan. Project, session, and administrator grants may satisfy the
-permission-policy layer, but none replace that per-run approval.
-
-Reproducer export is a separate host write after the sandbox has stopped. This
-ADR's root-scoped `evidence_write` authority was removed; current exports use
-the path supplied by the caller, while replay still waits for complete sandbox
-cleanup before writing.
-
-### 2. Admit extracted modules only
-
-The v1 mode executes a finite, closed manifest of JavaScript modules. The
-manifest identifies one entry module and every admitted dependency by a stable
-sandbox alias and SHA-256 digest. Imports resolve only to another manifest
-entry or to an explicitly declared, versioned stub. Bare package lookup,
-ambient `node_modules`, import maps from the host, network imports, native
-addons, WASI, FFI, child processes, workers, inspector activation, and implicit
-dynamic import are unavailable.
-
-Modules and stubs are read and hashed by the authorized parent, then copied as
-bytes through a bounded private channel. Original host paths are not mounted
-into the sandbox. The worker cannot reopen the operator's source path.
-
-Source maps may supply locations, but source-map source code is not executed
-unless its bytes are separately present in the approved manifest. A source-map
-name or Webpack module ordinal is never execution authority.
-
-REA does not launch, attach to, navigate, click, type into, or terminate the
-user's application under this capability. A full application process remains
-an independently approved Process Capture experiment; browser and Electron
-targets remain passive. Any future mode that drives an application or permits
-host/allowlisted network requires a new ADR and a distinct permission scope.
-
-### 3. Use a two-phase, content-bound approval flow
-
-One public replay surface supports a plan phase and an execute phase with the
-same schema through CLI and MCP.
-
-The plan phase:
-
-1. validates all caller input and hard limits before file access;
-2. obtains authority to read every selected module or stub path;
-3. canonicalizes and opens each file without following an unapproved identity;
-4. reads bounded bytes, computes digests, and closes the source descriptors;
-5. resolves and probes the exact runtime and sandbox backend without running
-   application code;
-6. normalizes stubs, inputs, generator settings, and limits; and
-7. returns the complete proposed effects and a canonical `plan_digest`.
-
-The plan must disclose at least:
-
-- module aliases, canonical local paths, byte counts, and SHA-256 digests;
-- input and stub identities, provenance, and digests;
-- runtime and sandbox executable paths, versions, and executable digests;
-- sandbox policy version and digest;
-- network `none`, visible read-only runtime paths, and private writable tmpfs
-  size;
-- time, CPU, memory, swap, task, temporary-storage, input, output, protocol,
-  case-count, and serialization limits;
-- deterministic clock, PRNG seed/algorithm, locale, timezone, and platform
-  projection; and
-- expected Evidence and cleanup behavior.
-
-Execution requires the exact `plan_digest`. REA
-rebuilds the plan immediately before admission. Any changed file, runtime,
-sandbox executable, policy, stub, input, limit, or environment commitment
-returns `plan_stale` before application code starts. Approval is not transferable
-to a different plan and cannot be represented by a bare Boolean alone.
-
-Interactive CLI may print the plan and ask for confirmation. Non-interactive
-CLI and MCP must perform the same explicit plan/execute exchange; they may not
-auto-approve because the caller requested JSON output or because permission
-elicitation is supported.
-
-### 4. Require an OS sandbox; fail closed elsewhere
-
-The first production backend is Linux-only. It must combine:
-
-- an empty mount namespace rooted in private tmpfs;
-- a new user namespace with all capabilities dropped and further nested user
-  namespaces disabled;
-- new PID, network, IPC, UTS, and cgroup namespaces;
-- a new terminal session and parent-death behavior;
-- no host D-Bus, agent, browser, Docker, Wayland/X11, SSH, GPG, audio, device,
-  or application sockets;
-- a minimal, read-only runtime closure rather than `/`, the user's home,
-  working directory, or host `/tmp`;
-- a fresh `/proc` for the sandbox PID namespace and a minimal private `/dev`;
-- a parent-generated, architecture-checked seccomp policy that denies at least
-  namespace or mount changes, `ptrace` and cross-process memory inspection,
-  BPF/perf access, kernel keyring and module control, reboot/swap controls, and
-  the `TIOCSTI` terminal injection path;
-- cgroup v2 `memory.max`, `memory.swap.max=0`, `pids.max`, and bounded CPU
-  controls owned for the one run; and
-- an outer REA supervisor that can kill the complete cgroup and verify it is
-  empty.
-
-The seccomp program is passed by descriptor, has a version and digest committed
-to the replay plan, validates the syscall architecture before the syscall
-number, and never permits `ptrace`-based mediation. Seccomp reduces exposed
-kernel surface; it is not described as a complete sandbox by itself.
-
-The reference backend for the implementation PR is Bubblewrap for namespace,
-mount, and seccomp construction plus a delegated cgroup v2 manager for resource
-enforcement. REA must feature-probe the actual required operations; version
-text alone is insufficient. A setuid Bubblewrap installation, a backend that
-silently skips a requested namespace or filter, unavailable user namespaces,
-missing cgroup delegation, or inability to prove cleanup makes the capability
-unavailable. REA setup must not install or upgrade Bubblewrap, systemd, Node.js,
-or kernel components.
-
-macOS, Windows, Linux hosts without every required feature, containers that
-block the required namespaces, and alternative backends are unavailable in
-v1. They must return precise diagnostics and remediation, not a process-only or
-`vm`-only degraded mode.
-
-Node.js runs with its permission model enabled and without grants for network,
-filesystem, child processes, workers, native addons, WASI, FFI, or inspector.
-That layer is defense in depth. It is never cited as the OS security boundary,
-because Node.js explicitly does not promise containment of malicious code.
-
-### 5. Make the worker disposable and deterministic by construction
-
-Each approved run receives a new sandbox, runtime root, worker process, module
-loader, and deterministic state. No module cache, realm, timer, file, global,
-or child survives into another run. Within a multi-case run, every case gets a
-fresh realm and fresh module instances; case order and generator state are
-committed.
-
-The worker exposes a small versioned set of language primitives and explicitly
-selected stubs. It does not expose `process`, `require`, host `console`, timers,
-`fetch`, sockets, filesystem APIs, `Buffer`, worker APIs, native bindings, or
-ambient environment variables. Date/time, randomness, locale, timezone, and
-platform values come only from committed deterministic providers. An
-unsupported global or import produces an observed exception; REA does not
-substitute a convenient host implementation.
-
-Caller-provided stubs are executable untrusted code and receive the same
-sandbox treatment as recovered modules. Built-in stubs have stable IDs,
-versions, canonical source digests, and documented semantics. No undeclared
-fallback stub is allowed.
-
-Inputs are bounded canonical JSON. Results are projected without invoking
-getters, proxies, `toJSON`, or arbitrary coercion: only admitted primitives,
-arrays, and plain data properties are serialized. Cycles, accessors, functions,
-symbols, unsupported prototypes, excessive depth, excessive nodes, and
-oversized values become explicit serialization outcomes. Worker stdout is the
-framed protocol only; bounded diagnostic stderr and bounded, opt-in console
-observations remain separate.
-
-### 6. Enforce independent resource ceilings
-
-Every limit has a conservative product default. The v1 plan and result commit:
-
-- an outer wall-clock deadline for the complete disposable run;
-- cgroup memory, swap, task, and CPU ceilings;
-- Node/V8 heap ceiling as defense in depth;
-- private tmpfs bytes;
-- serialized worker-protocol bytes, aggregate module bytes, and case-input
-  bytes; preset-generated cases also have a fixed preflight count ceiling;
-- stdout, stderr, exception, stack, and aggregate retained-output bytes; and
-- structured-result depth and node count.
-
-The parent enforces protocol and output limits while bytes arrive, before JSON
-parse or Evidence retention. The worker cannot request wider limits. A limit
-hit terminates the complete run cgroup and is an observed termination, not a
-partial successful return.
-
-### 7. Preserve exact provenance and the right Evidence authority
-
-A run that reaches worker admission produces Evidence with:
-
-- provider `rea-javascript-replay` and a concrete implementation version;
-- operation `run_controlled_replay`;
-- authority `controlled-replay`;
-- confidence `observed` for the exact returned value, thrown exception,
-  sandbox denial, limit termination, signal, exit, or crash that REA directly
-  observed;
-- environment isolation `container`, the host platform/architecture, runtime
-  identity, sandbox-backend identity, and sandbox-policy digest;
-- the replay plan digest, module and stub digests, canonical input or generated
-  case digests, deterministic providers, and every effective limit;
-- bounded raw input, output, and exception data when retained, plus their
-  canonical digests and truncation state;
-- start/admission/termination/cleanup states; and
-- explicit limitations for incomplete output, nondeterminism not checked,
-  sandbox diagnostics, or cleanup that could not be proven.
-
-The host module path remains an actionable local diagnostic and Evidence
-subject location, while the worker sees only a stable alias. Module source is
-not embedded in ordinary Evidence. A separately approved reproducer may copy
-module/stub bytes or may retain path-plus-digest references; its manifest says
-which mode was used. Repository tests use source-owned fixtures, and real-app
-verification stores only digests and expected structural facts.
-
-Derived differential results use confidence `derived` and link every source
-run Evidence ID. A repeat with the same commitment can establish
-`repeat-confirmed` for those runs; a single deterministic plan is only
-`committed-not-confirmed`. Neither state proves behavior in the original
-application.
-
-When replay observations are added to the JavaScript Application Graph, their
-graph-fact authority is `controlled-replay`. A claim that the real renderer,
-preload, main process, or remote service behaves the same remains inferred or
-unknown until compatible runtime authority exists. Static inference, passive
-CDP observation, controlled replay, and real application interaction are never
-promoted into one another.
-
-### 8. Treat post-admission failures as observations
-
-Pre-admission failures return a typed error and create no claim that module code
-ran. Once the worker is admitted, REA retains a bounded execution record even
-when the requested function does not return normally.
-
-| Condition                                        | Caller result and Evidence semantics                                                                       |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| Disabled capability or missing grant             | `permission_required`/`capability_unavailable`; no worker admission and no replay observation              |
-| Sandbox/runtime probe failure                    | `capability_unavailable` with exact failed feature; no module execution                                    |
-| Plan digest mismatch or changed source           | `plan_stale`; no module execution                                                                          |
-| Sandbox setup fails before worker admission      | `execution_failure`; no controlled-replay claim about the module                                           |
-| Module returns admitted data                     | Observed return value with complete or explicitly limited coverage                                         |
-| Module throws or result serialization rejects    | Successful replay observation with outcome `exception` or `serialization_error`; application claim unknown |
-| Node permission or sandbox denies an operation   | Observed denial/termination when attributable; no claim that all attempted side effects were enumerated    |
-| Timeout, memory, CPU, task, tmpfs, or output hit | Observed limit termination; requested functional result unknown                                            |
-| Signal, runtime crash, or malformed protocol     | Observed termination plus bounded diagnostics; functional result unknown                                   |
-| Caller cancellation after admission              | Kill full cgroup, record cancellation/cleanup if possible, and project the public cancellation contract    |
-| Cleanup proves an empty cgroup and removed root  | `cleanup: complete`                                                                                        |
-| Cleanup cannot prove emptiness or removal        | `cleanup_incomplete`, name every residual resource, and do not report success                              |
-
-An exception is data, not an adapter failure. A sandbox setup error is not
-evidence that the module crashed. A timeout is not evidence that the function
-would never return. An output limit is not evidence that the truncated prefix
-equals the full result. These distinctions are part of the public contract.
-
-Cancellation and cleanup must be idempotent. REA first stops admission and
-input, kills the owned cgroup, waits for an empty-cgroup observation, removes
-the private runtime root, closes protocol descriptors, and releases timers.
-Failure at one cleanup step does not skip the remaining steps.
-
-### 9. Keep replay records reproducible without overstating determinism
-
-The canonical replay manifest commits:
-
-```text
-plan structure and policy identity
-REA/provider/runtime/sandbox executable identities and digests
-module aliases, dependency graph, bytes digests, and source references
-stub IDs, versions, source digests, and caller-provided stub digests
-canonical inputs or generator algorithm, seed, case order, and case digests
-clock, PRNG, timezone, locale, platform, and exposed-global commitments
-all resource and serialization limits
-network and filesystem projections
-expected entry export and invocation convention
-```
-
-The result manifest adds canonical output/exception/termination digests,
-coverage, dropped-data counts, cleanup state, and source Evidence links.
-Canonical digests are computed by the trusted parent; worker-provided digests
-are ignored.
-
-Reproduction requires exact manifest compatibility. A runtime, sandbox policy,
-built-in stub, module byte, generated case, limit, architecture, or platform
-change is a different experiment. Cross-environment comparison may still be a
-derived investigation, but it is never an exact replay.
-
-### 10. Expose availability and policy truth before execution
-
-`rea doctor`, capability inventory, and the planning response must report the
-JavaScript replay capability without executing application code. Diagnostics
-name the exact missing executable, unsupported host, failed namespace feature,
-cgroup delegation failure, setuid rejection, runtime mismatch, or cleanup-probe
-failure. Genuine secrets remain redacted; local executable paths, versions,
-digests, and kernel feature failures remain visible.
-
-The capability must be absent from executable tool routing until implemented.
-Accepting this ADR does not increase the current tool count and does not add a
-hidden experimental flag.
-
-## Required implementation and verification gate
-
-The implementation PR cannot merge until all of the following are true:
-
-1. `javascript_replay` exists in configuration, permission policy, project
-   grants, policy explanation, CLI, MCP, docs, and capability inventory with
-   fail-closed defaults.
-2. Plan and execute phases have schema-identical CLI/MCP behavior and an exact
-   plan-digest stale check.
-3. No replay-disabled static, browser, Electron, session, setup, doctor, or
-   application workflow can reach module execution.
-4. The worker never imports into the REA server process and no adapter offers a
-   `vm`-only fallback.
-5. The Linux backend feature-probes namespaces, seccomp installation and
-   denial, delegated cgroup v2 limits, and the exact admitted architecture.
-   Every plan content-addresses the worker, seccomp filter, Node executable,
-   ELF loader, shared-library closure, and sandbox executables.
-6. Source-owned fixtures cover parser, sanitizer, clipboard, exception,
-   ambient side-effect attempts, memory pressure, and busy loops. The worker
-   exposes no filesystem, environment, network, process, worker, native-addon,
-   timer, inspector, or ambient package-resolution API.
-7. Tests and the real verifier prove bounded protocol/diagnostics, timeout and
-   OOM cgroup termination, and observed cgroup cleanup.
-8. Evidence tests cover observed return/exception/termination, derived
-   comparison with source Evidence links, stale admission, cancellation
-   projection, and explicit limitations on application-level claims.
-9. Package verification exercises the target-free public contract. The
-   dedicated real-Linux workflow exercises the sandbox backend; environments
-   without delegated user namespaces or cgroups report truthful unavailability
-   rather than selecting a weaker backend.
-10. A real operator-local Notion-like parser or sanitizer benchmark can run
-    without committing its source, and exports only approved local reproducer
-    material.
-
-## Rejected alternatives
-
-### Reuse `browser_observe`, `electron_observe`, or `process_capture`
-
-Rejected because those grants authorize different effects. Reuse would turn a
-passive or unsandboxed process permission into recovered-code execution.
-
-### Execute in the MCP server with `vm.runInContext`
-
-Rejected because a VM context is not a security boundary and a crash, resource
-attack, or escape would compromise the long-lived session and its credentials.
-
-### Use only the Node.js permission model
-
-Rejected because Node.js documents it as a seat belt for trusted code and
-explicitly does not guarantee containment of malicious code. It remains a
-defense-in-depth layer inside the OS sandbox.
-
-### Ship a process-only fallback on unsupported hosts
-
-Rejected because it changes the security claim while preserving the same tool
-name. Unsupported hosts return unavailable.
-
-### Permit network allowlists in v1
-
-Rejected because DNS, redirects, proxies, credentials, service identity, and
-response nondeterminism would substantially expand the threat and Evidence
-model. The v1 namespace has no host or external network.
-
-### Mount the approved project root read-only
-
-Rejected because one approved module does not imply authority to disclose
-every file in its project. The parent stages only exact, digested bytes.
-
-### Treat exceptions, crashes, or limit hits as ordinary tool errors only
-
-Rejected because that discards the principal behavioral observation and makes
-negative results impossible to reproduce. Post-admission termination is
-retained with explicit functional uncertainty.
-
-## Consequences
-
-- JavaScript replay is Linux-only at first and may be unavailable on containers
-  or distributions that disable user namespaces or cgroup delegation.
-- The implementation requires more host probing and lifecycle code than a
-  simple Node worker, but the public security claim remains stable.
-- Plans require two calls in non-interactive environments and become stale when
-  any committed input changes.
-- Network-dependent modules and full application interactions are excluded;
-  their absence is explicit rather than emulated implicitly.
-- Results are reproducible for the committed isolated experiment, not proof of
-  production behavior.
-- Adding another sandbox backend, network mode, or application-interaction mode
-  requires a separate reviewed decision and conformance suite.
-
-## References
-
-- [Node.js permissions](https://nodejs.org/api/permissions.html) documents that
-  the permission model does not protect against malicious code and describes
-  its known filesystem and cross-process limitations.
-- [Bubblewrap README](https://github.com/containers/bubblewrap/blob/main/README.md)
-  describes its namespace construction and makes clear that the caller's
-  arguments, not Bubblewrap alone, define the sandbox security model.
-- [Linux seccomp filter documentation](https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html)
-  explains that syscall filtering reduces kernel surface but is not a complete
-  sandbox by itself.
-- [ADR-0001](0001-provider-selection-and-analysis-profiles.md) establishes the
-  existing rule that provider selection, Evidence provenance, and capability
-  unavailability remain explicit and never silently fall back.

docs/adr/0003-managed-code-evidence-and-provider-boundary.md

@@ -1,452 +0,0 @@
-# ADR-0003: Managed-code evidence and provider boundary
-
-> Historical design record: The non-executing runtime-correlation planning
-> tool described in earlier revisions was removed. This ADR's current
-> implementation status below covers only the static managed tools that ship.
-
-- Status: Superseded for runtime planning; static evidence boundary remains in force
-- Date: 2026-07-16
-- Implementation status: Read-only PE/CLI triage and exact identity are shipped
-  through `inspect_managed_artifact` / `rea inspect-managed-artifact`. Bounded
-  metadata, signatures, method bodies, raw CIL hashes, limited
-  decoded-instruction-tuple v1 hashes, exception regions, call edges, and
-  field-access anchors are shipped through `inspect_managed_members`; `rea
-  inspect-managed-members` provides CLI parity. Static member comparison and build-local
-  token remapping are shipped through `compare_managed_members` /
-  `rea compare-managed-members`. Declaration-only managed/native boundary
-  inventory for ModuleRef, ImplMap/PInvoke, ReadyToRun indicators, and non-IL
-  method flags is shipped through `inspect_managed_native_boundaries` /
-  `rea inspect-managed-native-boundaries`. Managed/native export or function
-  Evidence matching is shipped through `verify_managed_native_boundaries` /
-  `rea verify-managed-native-boundaries`; it verifies only supplied P/Invoke
-  export/function observations and does not map managed tokens to native
-  addresses. Decompiler reconstruction import is
-  shipped through `import_managed_reconstruction` /
-  `rea import-managed-reconstruction`; it records user-supplied C#/IL/pseudocode
-  as analyst inference only after exact static member locks match. Managed
-  inspection does not execute assemblies or observe CLR internals. Managed static graph
-  projection is shipped through
-  `project_managed_application_graph` /
-  `rea project-managed-application-graph`; it projects authenticated managed
-  Evidence into the application graph without changing managed tokens into
-  native addresses. Native-body bridge mapping and an actual runtime executor
-  remain future contracts.
-
-## Context
-
-Professional C# reverse engineering is not one decompiler operation. A file
-described as “.NET” can be ordinary Common Intermediate Language (CIL),
-ReadyToRun code containing both CIL and native implementations, a single-file
-deployment, C++/CLI mixed mode, Unity Mono, Unity IL2CPP, or NativeAOT. Those
-forms have different sources of truth and different native-analysis needs.
-Choosing a decompiler before classifying the artifact can therefore produce a
-plausible but false model.
-
-The durable static facts in an ordinary managed PE are its PE/CLI headers,
-metadata tables, signatures, method bodies, exception regions, and CIL. A C#
-decompiler reconstructs source-like control flow and language constructs from
-those facts. That reconstruction is valuable, but it is not the original
-source and cannot replace the underlying metadata and CIL evidence. Obfuscation
-makes names especially weak while tokens remain coordinates in only one build.
-
-REA already separates one selected deep native provider from disjoint auxiliary
-providers under [ADR-0001](0001-provider-selection-and-analysis-profiles.md).
-It also separates static evidence, passive observation, process capture, and
-interactive observation authorities. Managed analysis must fit those boundaries
-without requiring a CLR to inspect an artifact, loading target code into the
-REA process, or treating a managed token as a native address.
-
-The design is informed by exact-build, reflection-free metadata extraction,
-hash-locked method manifests, independent behavior models, and managed/native
-boundary analysis performed against a local C# application. The application,
-its decompiler output, and its runtime observations are research inputs only;
-they are not distributable REA fixtures.
-
-## Decision drivers
-
-1. Classify the deployment before selecting an analysis route.
-2. Make metadata and CIL independently inspectable without a CLR or target
-   execution.
-3. Preserve exact-build provenance while enabling structural comparison across
-   builds whose MVIDs, tokens, names, and layout differ.
-4. Compose managed and native analysis without introducing another ambiguous
-   deep-provider candidate.
-5. Keep decompiled C# useful but epistemically subordinate to canonical bytes.
-6. Analyze Linux, macOS, and Windows managed artifacts through the same local
-   CLI/MCP contracts on REA's supported hosts.
-7. Keep setup additive and prevent managed analysis from installing .NET,
-   ILSpy, an SDK, or another unrelated toolchain.
-8. Prove semantics with source-built conformance artifacts and compact,
-   operator-local real-application checks.
-
-## Terminology
-
-- **Managed artifact**: a PE, bundle component, or related metadata artifact
-  that carries a CLI header, CLI metadata, CIL, or another managed-runtime
-  commitment.
-- **Classification vector**: independently observed container, runtime family,
-  implementation form, and architecture. It is not one guessed label.
-- **Canonical static observation**: a bounded value decoded directly from the
-  target bytes under a versioned parser contract.
-- **Reconstruction**: source-like output, including decompiled C#, derived from
-  canonical observations.
-- **Structural inference**: a relationship or cross-version match derived from
-  signatures, APIs, constants, control/data-flow shape, or other observations.
-- **Validation**: an independently checked proposition, for example a
-  source-built oracle assertion or a behavior-model corpus result.
-- **Runtime observation**: a separately authorized fact obtained by attaching,
-  loading, debugging, instrumenting, or otherwise executing code.
-
-## Decision
-
-### 1. Classify before analyzing
-
-Managed triage returns a classification vector and the observations supporting
-each dimension. Absence of a marker produces `unknown` or `not_applicable`, not
-an invented runtime family.
-
-| Dimension           | Initial values                                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Container           | PE file, single-file bundle, bundle component, Unity metadata pair, native image, malformed, unknown         |
-| Runtime family      | .NET Framework, modern .NET, Unity Mono, Unity IL2CPP, NativeAOT, mixed CLR/native, unknown                  |
-| Implementation form | CIL, CIL plus ReadyToRun, native only, C++/CLI mixed, metadata only, unsupported, unknown                    |
-| Architecture        | PE machine plus CLI flags; component-specific architecture for bundles; conflicting or unknown when required |
-
-Target-framework attributes, assembly references, metadata stream versions,
-bundle manifests, ReadyToRun directories, and native headers are observations.
-They may support a runtime-family inference, but no single string is treated as
-authoritative when the other bytes conflict.
-
-Classification selects these routes:
-
-| Observed form                     | Managed route                                                                  | Native route and limitation                                                                                |
-| --------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| Ordinary Framework or modern CIL  | Full metadata, signatures, method bodies, and CIL                              | Optional only for declared interop boundaries                                                              |
-| Obfuscated CIL                    | Same canonical route; names receive no special trust                           | Optional for declared interop boundaries                                                                   |
-| Unity Mono assembly               | Same canonical route with Unity context retained                               | Optional for engine/native boundaries                                                                      |
-| ReadyToRun                        | Metadata/CIL where present; implementation availability is per method          | Selected Hopper/Ghidra analyzes native sections; CIL absence is reported per method                        |
-| C++/CLI mixed mode                | Metadata/CIL for managed members and explicit mixed-mode boundary observations | Selected Hopper/Ghidra analyzes native bodies; REA never converts tokens directly to native addresses      |
-| Single-file deployment            | Inventory the bundle, then analyze each authenticated managed component        | Selected Hopper/Ghidra analyzes the host/native components; unsupported compression remains explicit       |
-| Unity IL2CPP                      | Pair and authenticate available Unity metadata; do not claim canonical CIL     | Selected Hopper/Ghidra analyzes the generated native binary; semantic recovery is degraded until supported |
-| NativeAOT                         | Report any independently present managed metadata, otherwise no CIL claim      | Treat as a native target with NativeAOT provenance; managed source reconstruction is unavailable           |
-| Malformed or unsupported artifact | Return bounded partial observations and typed unavailable/unknown scopes       | Do not silently retry by loading or executing the file                                                     |
-
-Classification is byte-driven and bounded. File extensions, product names,
-process names, and an operator's description are hints only.
-
-### 2. Implement managed static analysis as a disjoint auxiliary provider
-
-The initial producer is a REA-owned auxiliary provider with ID
-`rea-dotnet-static`. It owns a disjoint managed-artifact operation family. It is
-not registered as a Hopper/Ghidra deep-provider candidate because it does not
-compete for the same operation names and must be able to coexist with the one
-selected native provider.
-
-```text
-                      one opened artifact/session
-                                  |
-                    SessionProviderRouter
-                      /                       \
-        rea-dotnet-static auxiliary       selected deep binding
-        PE/CLI metadata and CIL            Hopper or Ghidra
-                      \                       /
-                       explicit managed/native links
-                                  |
-                         Evidence and workflows
-```
-
-An ordinary managed artifact can therefore remain unbound to a deep native
-provider while managed operations work. ReadyToRun, C++/CLI, IL2CPP, NativeAOT,
-and interop workflows may additionally require a caller-selected native
-binding. Native-provider failure never causes managed evidence to be relabeled,
-and managed-parser failure never causes an implicit native fallback.
-
-Provider mechanics live under a provider directory such as `src/dotnet/`.
-Provider-neutral identities, evidence states, and bounded values may live in
-the domain/contracts layers. Application code composes results but does not
-parse PE headers, metadata tables, signatures, CIL, ReadyToRun headers, or
-provider-specific output.
-
-### 3. Make the production static path byte-only and execution-free
-
-`rea-dotnet-static` reads approved local bytes and implements the required
-PE/CLI metadata and CIL subset in TypeScript. It does not call any reflection
-API and does not require the .NET runtime. In particular, static inspection
-must never:
-
-- call `Assembly.Load`, `Assembly.LoadFrom`, `ReflectionOnlyLoad`, or an
-  equivalent runtime loader;
-- resolve target dependencies by executing target-controlled resolver code;
-- run module initializers, constructors, entry points, build tasks, plugins, or
-  generated helpers;
-- start the target, attach to a process, contact a service, or inherit target
-  configuration and credentials; or
-- interpret a decompiler, CLR, or native-provider diagnostic as an observation
-  from the artifact bytes.
-
-The parser uses checked offsets and additions, explicit endianness, bounded
-table/heap/body counts, cycle-safe traversal, and typed partial results. A bad
-row, signature, body, resource, or stream does not authorize an unbounded retry
-or a CLR load. Complete-coverage claims require every applicable bounded region
-to have been admitted; otherwise coverage is partial, unknown, or unavailable
-with exact offsets and reasons.
-
-The caller selects the local input path directly. Local artifact
-paths, digests, MVIDs, tokens, malformed offsets, and analysis metadata are
-actionable diagnostics and are not secrets. Credentials, authorization data,
-and genuine secrets remain redacted.
-
-### 4. Bind every finding to exact artifact and producer identity
-
-Every managed result carries a commitment with at least:
-
-```text
-artifact: canonical path + byte length + SHA-256
-component: container identity + component path/name + component SHA-256, when applicable
-classification: container + runtime family + implementation form + architecture
-assembly/module: simple name + version + culture + public-key identity + module name + MVID
-producer: provider ID + exact version + analysis-affecting parameters + profile digest
-```
-
-An assembly-qualified name does not replace the artifact digest or MVID.
-Neither an MVID nor an Authenticode signature proves who authored the behavior.
-Bundle components retain both their container and component commitments so that
-bytes extracted from another host cannot be silently substituted.
-
-Method observations add:
-
-```text
-declaring type + normalized CLI signature
-build-local metadata token
-RVA/file extent when present
-raw CIL byte length + SHA-256 when the body is admitted
-decoded-instruction-tuple SHA-256 when CIL is valid
-separate max-stack, locals-token, and exception-region observations
-```
-
-The shipped `il_sha256` commits only the raw CIL byte stream identified by the
-method header's `il_size`. It does not commit the method header, local-signature
-blob, alignment padding, or extra sections such as exception clauses. Those
-facts remain separate observations and the enclosing artifact SHA-256 binds
-them to the exact file. A digest over the complete method body is not shipped.
-
-The caller-visible field remains named `normalized_il_sha256`, but its shipped
-v1 meaning is deliberately narrower than a canonical semantic CIL identity.
-For a completely decoded method, REA serializes the instruction-order array of
-`[opcode, operand_kind, operand]` tuples with JavaScript `JSON.stringify`,
-encodes that text as UTF-8, and reports its lowercase SHA-256. The tuple
-projection is defined here; the member result carries only the described
-normalized digest.
-
-Operands retain the current decoder projection: metadata and user-string
-operands are build-local lowercase hexadecimal tokens, scalar branch operands
-are decimal target CIL byte offsets, and `switch` retains only its decimal case
-count. Constants and variable indexes are decimal strings; an operand-free
-instruction uses kind `none` and value `null`. Opcode names preserve distinct
-short forms and prefix instructions, but instruction offsets, branch target
-instruction identity, switch targets, resolved token identities, method
-headers, locals, and exception regions are not part of this digest. A partial
-or malformed decode has no `normalized_il_sha256`.
-
-Consequently v1 is a deterministic decoded-tuple fingerprint, not proof of
-semantic equivalence. In particular, methods with the same opcodes and switch
-case counts can share it despite different switch targets, and token movement
-can change it without a semantic change. Cross-build comparison may use it as
-one unique-only structural tier while retaining artifact/MVID commitments and
-ambiguity; it must not describe the digest itself as token-remapped canonical
-CIL. Canonical operand resolution, complete control-flow operands,
-exception/local commitments, and an explicit algorithm version require a new
-normalized-CIL schema.
-
-Metadata tokens are reported because they are precise coordinates inside one
-module. Cross-version identity never consists of a token alone. Matching tries
-exact CIL/signature identity, then an exact declared-type/name/signature tuple,
-then structural shape; a name by itself never selects a pair. Partial or
-malformed bodies leave body facets unknown after a signature tuple pairs the
-methods. Matches cite both build commitments, both local tokens, and all
-competing candidates. V1 cannot cite a separate matching-algorithm version
-because none is exposed.
-
-### 5. Separate five evidence layers
-
-Managed workflows retain these layers independently:
-
-| Layer                  | Examples                                                              | Permitted claim                                                 |
-| ---------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
-| Static observation     | Metadata row, signature, CIL opcode, literal, exception region        | “These bounded bytes decode to this value.”                     |
-| Reconstruction         | Decompiled C#, async/iterator source shape, expression simplification | “This is one source-like representation of cited observations.” |
-| Structural inference   | Likely caller, field flow, behavior slice, cross-build method match   | “These cited structures support this relationship.”             |
-| Independent validation | Synthetic oracle, corpus result, second parser agreement              | “This declared proposition passed the named independent check.” |
-| Runtime observation    | Exact-build attach/load/instrumentation event                         | “This separately authorized experiment observed this event.”    |
-
-Each layer has its own producer, authority, state, confidence, coverage, and
-limitations. A readable C# method is never emitted as original source or exact
-semantic proof. A validator does not upgrade unrelated claims. Runtime
-agreement does not retroactively turn a static inference into an observation.
-
-Negative results are scope-qualified. For example, “no declared P/Invoke rows
-were found in the admitted metadata tables” does not prove the application has
-no native, dynamically resolved, generated, server-side, or protected path.
-
-### 6. Admit ILSpy only as an optional reconstruction and conformance tool
-
-REA's canonical static operations do not depend on ILSpy, a .NET SDK/runtime,
-dnlib, or Mono.Cecil. The following review was current on the decision date:
-
-| Tool                         | Reviewed coordinate | License | Runtime/host observation                                                    | Decision                                                                                         |
-| ---------------------------- | ------------------- | ------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `System.Reflection.Metadata` | 10.0.10             | MIT     | Library targets .NET Framework 4.6.2, .NET 8/9/10, and .NET Standard 2.0    | Pinned independent metadata oracle for conformance; not shipped or invoked by production parsing |
-| `ICSharpCode.Decompiler`     | 10.1.1.8388         | MIT     | Library targets .NET Standard 2.0; output is reconstruction                 | Pinned reconstruction/differential oracle candidate                                              |
-| `ilspycmd`                   | 9.1.0.7988          | MIT     | Cross-platform .NET 8 tool; newer 10.1.1.8388 requires .NET 10              | Initial optional BYO reconstruction coordinate because it matches the source research baseline   |
-| dnlib                        | 4.5.0               | MIT     | Cross-platform library; also exposes assembly-writing APIs                  | Differential test candidate only; its writable model is outside the production trust boundary    |
-| Mono.Cecil                   | 0.11.6              | MIT     | Cross-platform .NET Framework/.NET Standard library with read/write support | Differential test candidate only; not a production dependency                                    |
-
-Coordinates and package hashes used by real verification are checked into a
-source-owned lock manifest when that verifier is implemented. “Latest” is
-never a reproducibility coordinate. A version change requires conformance and
-an explicit profile/version change.
-
-Artifact platform and REA host support are separate. The byte-only parser must
-inspect PE/CLI artifacts produced for Windows on a supported Linux or macOS REA
-host; that is not a claim that REA itself currently runs on Windows. Managed
-library/tool candidates above are cross-platform at their reviewed targets, but
-native composition remains limited by the selected Hopper/Ghidra host and
-format support. Real verification runs the canonical path on Linux and macOS
-and may run pinned oracle checks on Windows without turning that development
-check into a public Windows-host claim.
-
-If a caller-visible C# reconstruction operation is admitted, it is a distinct
-optional capability. It accepts only an exact supported BYO `ilspycmd`, records
-the tool and decompiler version, runs in an owned bounded process without
-loading target code into REA, and links output to the canonical method
-observation. Setup and installers do not download or install ILSpy, .NET, an
-SDK, or a runtime. Doctor may inspect an explicitly configured executable and
-report exact actionable incompatibility. Missing reconstruction never removes
-canonical metadata/CIL capabilities.
-
-This decision does not make a decompiler process a security sandbox. The
-initial public path can defer C# reconstruction while canonical contracts and
-process isolation are proven.
-
-### 7. Use source-built conformance and operator-local real targets
-
-The repository stores source, build descriptions, expected semantic facts,
-and tool lock manifests, but not compiled managed binaries. An isolated build
-step creates fixtures outside source directories and records their SHA-256 and
-MVID before verification. At minimum, the corpus covers:
-
-- Framework-compatible and modern .NET metadata;
-- AnyCPU, x86, and x64 PE/CLI flags;
-- generics, nested types, overloaded signatures, properties, events, resources,
-  attributes, and constants;
-- exceptions, filters, prefixes, switch branches, P/Invoke, async and iterator
-  state machines;
-- obfuscated and Unicode names without assigning semantics from names;
-- malformed headers, tables, heaps, signatures, bodies, and exception regions;
-  and
-- two semantically related builds with different MVIDs, tokens, layout, and
-  selected names.
-
-Expected facts are checked directly and against pinned
-`System.Reflection.Metadata`; ILSpy, dnlib, or Mono.Cecil may add differential
-coverage but do not vote by majority. Disagreement is a failing or explicitly
-unsupported case, not silently normalized output.
-
-The real-application benchmark is an operator-local, opt-in osu! check derived
-from the research workflow. It accepts an explicit path plus a compact
-expectation manifest; verifies target SHA-256, MVID, architecture, and expected
-assembly identity before analysis; and emits only bounded identities, tokens,
-signatures, IL lengths/hashes, match states, and assertion results. It does not
-emit full IL, decompiled source, runtime logs, user data, credentials, or
-service/account material. No proprietary binary, hash-locked application
-manifest, or derived dump is committed to REA.
-
-### 8. Keep runtime behavior separate from static managed analysis
-
-No managed runtime planning or execution tool ships. Managed inspection does
-not execute assemblies or establish which methods ran. Where supported, direct
-process capture can record target-level inputs and outputs, but it does not
-prove CLR method execution or resolution. Internal managed behavior remains
-unknown until independently observed with suitable runtime evidence.
-
-## Public contract consequences
-
-- Managed static operations will have CLI and MCP parity and produce the same
-  Evidence commitments.
-- Adding managed operations changes the caller-visible tool inventory and
-  generated product catalog only in the implementation PR that admits them.
-- Partial parsing includes admitted/dropped counts, exact limitations, and
-  coverage; it never returns a partial list labeled complete.
-- Managed addresses distinguish file offsets, RVAs, native virtual addresses,
-  metadata tokens, and CIL offsets. They are not interchangeable.
-- Cache compatibility is exact on artifact/component commitment, member-result
-  fields, parser profile, and producer version. For shipped v1,
-  `normalized_il_sha256` has no independent algorithm-version field.
-- Provider-neutral workflows may compose canonical managed findings with the
-  one native binding, but every source operation retains its actual producer.
-
-## Alternatives rejected
-
-### Make ILSpy the only managed provider
-
-This would make canonical metadata/IL inventory depend on a separately
-installed CLR and conflate source reconstruction with byte observations. It
-would also make tool-version drift part of ordinary inventory. ILSpy remains a
-valuable optional reconstruction and conformance tool instead.
-
-### Use `Assembly.Load` or reflection-only loading
-
-Both delegate parsing and dependency behavior to a CLR and make static support
-runtime-dependent. Ordinary loading can execute target code; reflection-only
-loading still establishes a CLR load boundary and is unavailable across modern
-runtimes in a uniform way. Neither is required to decode ECMA-335 bytes.
-
-### Register the managed analyzer as another deep candidate
-
-That would force callers to choose managed analysis instead of Hopper/Ghidra
-for ReadyToRun and mixed-mode artifacts even though both are needed. Disjoint
-auxiliary composition represents the real ownership boundary.
-
-### Treat tokens, names, or decompiler output as durable identity
-
-Tokens and obfuscated names change across builds, while decompiler output
-changes across tools and versions. They remain useful build-local coordinates
-or reconstruction labels but are insufficient for exact or structural
-cross-version identity.
-
-### Package a .NET runtime or mutable managed library in REA
-
-This would expand installer effects, package size, patching obligations, and
-the target-parsing attack surface. The initial byte parser keeps canonical
-support within REA's existing Node runtime; external managed tools remain BYO
-or development-only oracles.
-
-## Rollout gates
-
-1. Add read-only triage and identity with malformed-input bounds. Shipped.
-2. Add metadata, signatures, method bodies, deterministic decoded-CIL tuple
-   fingerprints, and exact artifact Evidence. Shipped with the v1 limitations
-   above; full normalized-CIL semantics remain planned.
-3. Add obfuscation-resistant slices and cross-build match states. Shipped.
-4. Compose explicit managed/native boundaries with Hopper/Ghidra. Declaration
-   inventory and native export/function Evidence matching shipped; native-body
-   bridge mapping remains planned.
-5. Add source-built, pinned real-tool, package, CLI, and MCP conformance.
-   Source-owned conformance is shipped; pinned external real-tool checks remain
-   planned.
-6. Project authenticated managed static Evidence into the application graph.
-   Shipped.
-
-Every gate must keep unsupported ReadyToRun, NativeAOT, IL2CPP, mixed-mode, or
-bundle cases explicit rather than broadening claims to make a fixture pass.
-
-## References
-
-- [ECMA-335: Common Language Infrastructure](https://ecma-international.org/publications-and-standards/standards/ecma-335/)
-- [.NET ReadyToRun deployment overview](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run)
-- [.NET Native AOT deployment overview](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/)
-- [.NET single-file deployment overview](https://learn.microsoft.com/en-us/dotnet/core/deploying/single-file/overview)
-- [`System.Reflection.Metadata` package](https://www.nuget.org/packages/System.Reflection.Metadata/10.0.10)
-- [ILSpy repository and releases](https://github.com/icsharpcode/ILSpy)
-- [dnlib repository](https://github.com/0xd4d/dnlib)
-- [Mono.Cecil repository](https://github.com/jbevain/cecil)

docs/adr/README.md

@@ -1,11 +0,0 @@
-# Architecture decision records
-
-Accepted decisions describe the architecture that implementation PRs must
-follow. Acceptance does not by itself mean the behavior is shipped; each record
-states its implementation status separately.
-
-| ADR                                                                                                                | Status               | Implementation                                                                                                                        |
-| ------------------------------------------------------------------------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| [0001: Provider selection and analysis profiles](0001-provider-selection-and-analysis-profiles.md)                 | Accepted             | Provider selection and 25 read-only Ghidra operations on Linux/macOS and experimental Windows x64 P0; Linux/macOS session annotations |
-| [0002: Controlled JavaScript replay authority and sandbox policy](0002-controlled-replay-authority-and-sandbox.md) | Superseded           | Historical design; the controlled JavaScript replay tool was removed                                                                  |
-| [0003: Managed-code evidence and provider boundary](0003-managed-code-evidence-and-provider-boundary.md)           | Partially superseded | Seven static managed tools remain; runtime planning removed                                                                           |

docs/android-analysis.md

@@ -118,6 +118,12 @@ selected overload. Native/abstract methods with no decompiled body report
   responses remain in Evidence. Source revision is populated only for bytes
   matching the audited release JAR.
 
+If a later step fails, the error's `details.partial_observation` retains the
+selected and resolved APK paths, digest, observed provider identity and versions,
+and each upstream request and reply collected before the failure. Failed replies
+remain available even when their payload cannot be interpreted. Cancellation
+also stops target hashing before provider admission.
+
 These operations do not execute the APK or provide split APK/AAB handling,
 signature validation, full resource-table semantics, native-library analysis or
 Android runtime capture. Existing artifact inventory/extraction tools can supply

docs/architecture.mermaid

@@ -58,7 +58,7 @@ graph TD
     end
 
     subgraph "Configuration"
-        CONFIG["src/config.ts + src/config/<br/>Zod-validated env parsing<br/>provider settings and origins"]
+        CONFIG["src/config/<br/>Zod-validated env parsing<br/>provider settings and origins"]
     end
 
     subgraph "Tests"

docs/browser-observation.md

@@ -14,7 +14,7 @@ REA can attach to a user-owned Chrome-family browser through the Chrome DevTools
 - `inspect_web_page` / `rea inspect-web-page` captures DOM structure, accessibility nodes, scripts, resources, safe response/DOM metadata, attach-window network and console metadata, WebSocket frame sizes, workers, quota, and optionally selected storage key names, redacted storage-content fingerprints, or script sources.
 - `analyze_web_bundle` / `rea analyze-web-bundle` parses selected script artifacts without execution and derives chunk edges, route and endpoint candidates, vendor fingerprints, static WebMCP declarations, and optionally source-map/original-source evidence.
 - `observe_web_session` / `rea observe-web-session` arms an observation window of the requested duration for an external user action and records ordered reload, SPA navigation, redirect, failure, lifecycle, and target-termination metadata.
-- `discover_webmcp_tools` / `rea discover-webmcp-tools` uses the experimental CDP WebMCP domain to return every in-scope registration and its complete structural input-schema summary inline. Registrations with the same name and URL in distinct observed frames retain separate identities. `tool_key` includes the observed frame ID; it is not a stable identity across navigation or browser sessions. Same-frame registration updates replace that owner only, and removal leaves other owners intact. REA never exposes `WebMCP.invokeTool`; malformed protocol payloads fail explicitly instead of returning incomplete tool metadata.
+- `discover_webmcp_tools` / `rea discover-webmcp-tools` uses the experimental CDP WebMCP domain to return every in-scope registration and its complete observed `input_schema` declaration and canonical `input_schema_sha256` digest inline. Declarations are untrusted JSON data, including declared types, required fields, enums, examples and reference URLs. REA does not resolve schema references. These fields replace `input_schema_shape`. Registrations with the same name and URL in distinct observed frames retain separate identities. `tool_key` includes the observed frame ID; it is not a stable identity across navigation or browser sessions. Same-frame registration updates replace that owner only, and removal leaves other owners intact. REA never exposes `WebMCP.invokeTool`; malformed protocol payloads fail explicitly instead of returning incomplete tool metadata.
 - `compare_web_captures` / `rea compare-web-captures` compares passive captures or exact-step-aligned browser scenarios. Scenario results commit reproducible literal normalization and expose alignment failures plus artifact-level action, screenshot, DOM, accessibility, URL, history, storage, and event differences. Missing or truncated evidence is never treated as equivalence.
 - `capture_web_screenshot` / `rea capture-web-screenshot` returns a content-addressed visible-viewport PNG.
 - `compare_web_screenshots` / `rea compare-web-screenshots` performs bounded local PNG pixel comparison without OCR or external services.
@@ -134,7 +134,7 @@ REA retains local observation data and removes only URL userinfo credentials, ex
 - DOM snapshots retain node types, node names, value lengths, and attribute names, but not text or attribute values.
 - Accessibility structure and roles are retained by default, while names and descriptions require `include_accessibility_text: true`.
 - Network observations retain method, status, MIME type, size, type, initiator stack location, and complete URLs with userinfo credentials removed. Redirects reported by CDP are attached as ordered `redirects` on the one request ID, with the prior request URL, CDP response URL, method/type, response status/MIME/encoded length, request timestamp, and the next `requestWillBeSent` event timestamp. CDP delivers `redirectResponse` with that next request event, so the latter is an event boundary rather than an exact response timestamp. Redirect response headers and bodies are discarded; hops outside the selected origins are discarded with the request chain. Headers are discarded after an allowlisted projection of length/encoding, structured CSP/Link/policy fields, and untrusted agent hints. Cookies and authorization headers are never retained.
-- Request/response bodies are not requested or parsed by default. When selected, only allowed-origin JSON media types are read, converted immediately to complete value-free property paths/types, and discarded. `Network.getResponseBody` is never sent unless JSON body shape capture is selected.
+- Request/response bodies are not requested or parsed by default. When selected, only allowed-origin JSON media types are read, converted immediately to complete value-free typed paths, types and observation counts, and discarded. Each path segment is either `{ "kind": "property", "name": "raw property name" }` or `{ "kind": "array-element" }`; array-element types include primitives and nested arrays. Literal `*` properties remain distinct from array elements. `Network.getResponseBody` is never sent unless JSON body shape capture is selected. Comparison uses body shapes only when both captures selected them, and compares request/response shapes only where both observations provide those facts. Unavailable or truncated selected coverage makes equivalence unknown; observed differences still report changed.
 - Console observations with a stack source retain call type, argument types, timestamp, and source location. When console text capture is selected, already-delivered primitive values are retained verbatim; objects, getters, and remote properties are never expanded.
 - WebSocket observations retain direction, opcode, and payload byte length. When shape capture is selected, text frames are classified as text or complete value-free JSON shape; binary bytes, hashes, prefixes, and raw frames are never retained.
 - Storage observations always redact values. Key names, IndexedDB names, and cache names require `include_storage_keys`; stable content fingerprints require the additional `include_storage_fingerprints` selection. Cookie fingerprints cover cookies applicable to the current main-frame URL, including its path, rather than every cookie path on that origin. Other storage remains scoped to the origin. Cache bodies above 64 KiB and partial IndexedDB remote objects make fingerprint coverage incomplete, so identical observations remain `unknown`.

docs/browser-scenario-contract.md

@@ -236,12 +236,13 @@ network metadata observation; listing `network` in `events` is then optional.
 Each observed request object receives a capture-scoped `transaction_id`.
 Requests sharing a URL remain distinct. Redirects link to the preceding
 transaction only when it was observed; a null predecessor does not establish
-that no earlier hop existed. Older captures without IDs remain readable and
-their transaction association is unknown.
+that no earlier hop existed. Request events require both transaction fields;
+an absent ID is malformed capture data, while a null redirect predecessor is
+an explicit unknown.
 
 `scenario.network_content` records the resolved content selection. Comparing
-captures with different selection, or legacy captures without that coverage
-information, reports network evidence as unknown with a recovery instruction.
+captures with different selections reports network evidence as unknown with a
+recovery instruction.
 Capturing more data alone does not establish a website change.
 
 `network-content` events reference the exact request or response event through

docs/capability-migration.md

@@ -1,477 +0,0 @@
-# Incremental capability migration
-
-This working guide tracks the migration in #740. Update it as concrete domains
-migrate. Existing public contracts and domain-specific ports remain authoritative;
-there is no new universal provider interface or fixed module manifest.
-
-## Ownership to preserve
-
-| Responsibility                                | Current owner                       | Migration direction                                   |
-| --------------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
-| Analyst semantics and Evidence representation | domain                              | Keep pure and provider-neutral                        |
-| Named public input/output contracts           | contracts                           | Keep exact CLI/MCP meaning and complete discovery     |
-| Producer parsing and external tool protocols  | provider adapters                   | Keep behind the relevant typed port                   |
-| Shared analyst workflows                      | application                         | Share between CLI and MCP                             |
-| Concrete provider construction                | composition, MCP startup            | Keep fresh typed factories at the production boundary |
-| Investigation Evidence and Unknowns           | InvestigationRecords/EvidenceLedger | Consume narrow read/write/atomic record ports         |
-| Target/profile snapshots and invalidation     | BinarySessionRecords/BinarySession  | Keep binary-owned                                     |
-| Subprocess ownership and host primitives      | process/windows                     | Reuse; preserve cancellation and cleanup              |
-| Public translation                            | CLI/MCP adapters                    | Delegate to shared workflows and named contracts      |
-
-Retain exact Evidence IDs, provenance, detached reads, atomic Evidence/Unknown
-mutations and optimistic revisions. Preserve current close and failed-cleanup
-record clearing while extracting ownership; #721 owns any retention-policy change.
-Each CLI invocation and MCP connection keeps its own state. Provider registration
-must not launch engines or install prerequisites.
-
-## Migrate before generalizing
-
-1. Record the actual callers, state, environment, protocol and verification owner
-   of the capability being migrated.
-2. Move concrete construction behind its existing typed port. Preserve injected
-   ports, selected environment, queues, failure state and cleanup behavior.
-3. Test both caller paths and the applicable package/real-provider boundary.
-4. Use independently migrated capabilities to identify repeated metadata and
-   composition needs. Derive a small source declaration only when those needs
-   are established; keep unlike target/lifecycle semantics separate.
-5. Move a coherent capability's files, fixtures and verification lanes in a
-   mechanical PR. Update all path-sensitive consumers in that same PR.
-
-Pure helpers do not need an interface each. A capture-format adapter or typed
-factory may be sufficient. Avoid generic JSON execution, external MCP catalog
-passthrough, eager provider acquisition, new permission fields or a multi-package
-rewrite. Optional loading should preserve successful peers and report the failed
-capability without hiding tools from the catalog.
-
-## Checks before and after a move
-
-`npm run verify:test-discovery` compares actual Vitest file discovery with every
-repository-owned `*.test.ts` under src and tests, including newly added files. The
-check requires Git, includes untracked non-ignored tests, and excludes removed
-paths during a move. It
-rejects missing files and overlapping project ownership. It only lists files;
-it does not replace behavior tests or real-provider verification.
-
-Check imports, project isolation and coverage, development-test selection,
-lint exceptions, catalog/generator imports, npm and CI verification entrypoints,
-fixture ownership, and installed-package bridge/native path resolution.
-Domain and contracts must not import application workflows, caller adapters or
-provider implementations. Production composition is a deliberate outer boundary.
-Other existing adapter imports will migrate incrementally; do not widen a lint
-exception to conceal new protocol code inside application workflows.
-
-`npm run verify:module-boundaries` parses repository-owned source imports,
-reexports, type imports and literal dynamic imports, then checks their resolved
-source layer. Nested names such as `domain/android` are domain code; `src/android`
-is the provider adapter. The check runs with lint, including cached static gates.
-It covers tracked and untracked non-ignored TypeScript source and skips cached
-paths removed during a move. Pass exact source paths for a focused check.
-
-Pure source and its tests keep inward dependencies. Application/server provider
-construction guards cover the migrated deep, Android, firmware, JavaScript recovery and observation
-implementations. Application workflows cannot import composition, including the
-former binary runtime entrypoint; shared browser capture/export helpers remain admitted while their
-ownership is reviewed. Test lane restrictions still use Oxlint. Producer-dependent
-browser and managed comparison tests live in boundary lanes with their original
-fixtures and assertions. This is a development guard, not runtime authorization.
-
-Select verification by the claim changed: schema/composition, package, real
-engine or host-native workflow. Record host/target prerequisites and source-owned
-fixtures. Run heavy lanes serially with bounded workers/heaps and reuse existing
-engines. Recording ports do not prove real provider or platform support.
-
-## Extension examples to validate during migration
-
-An implementation of an existing port should require a provider adapter, typed
-production factory selection, exact producer parsing/provenance and matching
-verification. Existing workflow meaning and public contracts should stay stable.
-
-A new analyst capability deliberately adds semantics, named contracts, a typed
-port/workflow when needed, both caller adapters, availability, documentation and
-verification. Its integration is broader than swapping a provider. The migration
-should eliminate incidental duplicate wiring, not erase those design decisions.
-
-Update these examples with real migrated entrypoints before closing #740.
-
-## First production factory migration
-
-`src/composition/android.ts` and `src/composition/firmware.ts` construct providers
-behind the existing AndroidAnalysisPort and FirmwareAnalysisPort. CLI registrars
-pass their selected environment; MCP uses the process environment unless a caller
-injects a port. Each factory call returns a fresh instance and acquires no process,
-workspace or toolchain. Queues, cleanup-failure state and per-request cleanup stay
-inside the provider. The existing launcher seams remain available to boundary
-fixtures, which now exercise the production factories.
-
-Application workflows and MCP registration must not import these concrete
-providers. Composition may import their implementations. Binary composition also
-uses this outer boundary after its direct-analysis callers were migrated.
-This concrete pilot does not introduce a shared provider interface or module
-manifest.
-
-## Independent optional observation adapters
-
-Browser observation, browser scenarios, Electron observation, Electron scenarios
-and V8 Inspector observation now have separate factories in `src/composition/`.
-CLI commands reuse them; MCP startup dynamically imports each factory independently.
-`OptionalObservationProviders` describes these five existing typed ports only. It
-is provisional startup wiring, not an extensible plugin manifest or a universal
-provider interface.
-
-A failed import or constructor retains the successful peers. The complete tool
-catalog remains advertised. Session availability reports the failed adapter and
-its actual reason, and affected handlers return the existing capability-unavailable
-error. Explicit loading failures take precedence over configured availability.
-Passive Electron and active Electron failures are independent; static JavaScript
-analysis and runtime reconciliation remain usable without either adapter. CLI
-Electron commands also load only their selected runtime factory at execution.
-
-Source identities are available without importing the optional implementations.
-Registration acquires no engines, probes no endpoints, changes no permissions and
-installs nothing. Core transport failures and shutdown still use their existing
-lifecycle. Fault-injection coverage uses the production loading/startup path and
-actual MCP SDK calls; recording ports establish composition behavior, while the
-real Inspector lane separately establishes runtime behavior.
-
-## Investigation record ownership pilot
-
-`src/application/investigation/InvestigationRecords.ts` owns one existing
-EvidenceLedger per runtime. The production session composition constructs that
-owner explicitly; the direct BinarySession constructor retains a fresh default
-for compatibility. There is no second ledger, global store, persistence or new
-retention policy.
-
-The ledger, Unknown Evidence helper and the ledger's two original behavior tests
-now live beside the owner in `src/application/investigation/`. Bundle validation
-and record-owner consumers follow the new paths; retained-reference access still
-uses the narrow record ports. The move preserves implementation bodies and test
-assertions. Binary snapshot/cache files remain with their existing owner.
-
-EvidenceReader, EvidenceWriter and EvidenceUnknownWriter describe existing
-read/write/atomic callback needs. UnknownRegistryPort preserves optimistic
-revisions and consistency verification. Non-binary MCP registrars use these
-record types without depending on the binary execution/lifecycle surface.
-BinarySessionPort retains its compatible record methods through composition.
-
-BinarySessionRecords remains the snapshot owner and compatibility facade. It
-passes the actual active target explicitly for recordUnknown/updateUnknown;
-recordEvidenceWithUnknown keeps its target-free mutation subject. Snapshot import
-merges records without notifying midway, then emits after the cache commits.
-Bundle import retains the full change delta so Unknown-only changes notify even
-when recordsAdded is zero. Clearing resets records, cache and invalidation before
-notification; observer failures remain best effort after a committed mutation.
-
-Close and failed-cleanup clearing, ordinary target-switch retention, detached
-reads, Evidence identities and deterministic bundle transfer keep their existing
-behavior. Snapshots still require an active target and concrete analysis profile;
-extracting investigation ownership does not make them a target-free record store.
-#721 remains responsible for any future lifetime-policy change.
-
-## Inspector adapter ownership
-
-`src/inspector/` owns V8 Inspector discovery, passive capture, script/target
-location interpretation and its lightweight provider identity. The composition
-factory and optional loader use this owner. Browser CDP connection, endpoint/value
-and Electron file-location helpers remain deliberate shared adapter utilities at
-their existing paths; no provider wire protocol moves into domain or process.
-
-Loopback fixtures and producer boundaries now live under
-`tests/fixtures/inspector/` and `tests/boundary/inspector/`. The socket-backed
-unresolved-target reconciliation test moves from composition into the forked
-boundary lane with its original assertions. Adapter tests retain fork isolation.
-`npm run verify:inspector` keeps its public development entrypoint and delegates
-to `scripts/verify/inspector/runtime-observation.mjs`, using the real Node fixture
-under `tests/conformance/inspector/`. Catalog imports, source guards and test
-discovery follow the new paths. Observation authority, lifecycle, producer
-interpretation and caller-visible contracts stay unchanged.
-
-## Auxiliary source declaration pilot
-
-Artifact, macOS native and managed static metadata now belongs to each adapter's
-`*ProviderMetadata.ts` module. The implementation and
-`src/composition/auxiliaryAnalysisProviders.ts` reuse the same identity and exact
-capability descriptors. The declarations reference existing AnalysisProvider
-loaders; they cover these three disjoint auxiliary implementations only. Deep
-candidate selection and the five typed observation ports remain separate.
-
-The binary runtime reads these source declarations while auxiliary construction
-stays lazy. The separate managed-only entrypoint retains direct construction for
-its execution-free workflow. The MCP catalog generator reads declarations without
-constructing implementations, using its canonical macOS platform; actual runtime
-host restrictions remain explicit.
-Discovery and binary operation-kind routing now consume canonical source contracts
-rather than their generated JSON artifact. No declaration imports its generated
-output. Generated catalog facts and public schemas stay unchanged.
-
-All observation registrars resolve contracts by name. An isolated compiled-process
-test reverses presentation arrays and performs actual MCP SDK calls to verify
-advertised schemas and handler meaning. Reordering metadata must not select a
-different operation, schema, provider or deep-provider priority.
-
-## Android layer and verification ownership
-
-Android workflows and their existing typed port live in `src/application/android/`,
-pure APK/inventory semantics in `src/domain/android/`, and the named inspection
-contracts in `src/contracts/android/`. The headless JADX producer remains in
-`src/android/`; `src/composition/android.ts` supplies its fresh factory to both
-caller adapters. Public names, result meaning and JVM/queue/cleanup limits are
-unchanged. Inventory-only application projection remains execution-free.
-
-The real lane and signal-cleanup helper belong to `scripts/verify/android/`; its
-explicit downloader and fixed manifest belong to `scripts/fixtures/android/`.
-`verify:android` and `fixtures:android` keep their command names and repository-root
-`_reference/apk-integration/` fixture default. Synthetic producer fixtures stay in
-`tests/fixtures/android/`, with matching boundary and composition ownership. Real
-JADX CLI/MCP parity requires the fixed APK and existing audited JAR; synthetic
-protocol/cancellation success does not establish that engine or an unverified host.
-
-## Deep-provider source declarations
-
-Hopper, Ghidra and IDA declare their implemented analyst operations in their
-own `*ProviderCapabilities.ts` modules. Hopper's inventory is typed against the
-existing direct-operation contracts; Ghidra reuses its inventory/function adapter
-operations; IDA retains its read-only operation family. Frozen operation arrays
-feed the existing capability builders without importing generated catalog data.
-
-The catalog generator reads these source declarations and joins operation names
-to canonical `TOOL_CONTRACTS`. A missing contract identifies the declaring provider
-and operation. Public schemas and descriptions remain owned by contracts; the
-declarations describe implementation coverage. Provider adapters must not consume
-the generated MCP catalog that is derived from them. The resolved module guard
-checks this edge while admitting canonical source contracts, generated package
-metadata and the existing application snapshot-cache consumer.
-
-Exact provider effects and lifecycle differences remain in their adapters:
-Hopper's GUI and mutation effects, Ghidra's experimental Windows authority and
-mutation restrictions, and IDA's attached/headless effects and live observations.
-This source increment introduces no common provider lifecycle or new interface.
-
-## JavaScript application ownership
-
-`src/application/javascript/` owns JavaScript/Electron artifact analysis and
-graph projection, feature/version/export/source comparisons, runtime Evidence
-and reconciliation, observation ports, and source recovery workflows. Pure
-analysis and public schemas keep their existing domain/contract ownership;
-shared artifact inventory, investigation records and execution types remain
-shared. CLI, MCP and production factories import the owning workflow directly.
-
-`src/domain/javascript/` owns static parsing and semantic IR, application and
-semantic graphs, Electron facts, runtime reconciliation, recovery result
-semantics, and source-to-bundle comparisons. Shared Evidence, digests, ordering,
-comparison semantics and historical-source graphs stay at their existing owners.
-Native handoffs link exact-subject Evidence without selecting or executing a
-provider.
-
-`src/contracts/javascript/` owns the JavaScript/Electron observation and recovery
-contracts, JavaScript-specific workflow requests, and their examples. The shared
-`applicationToolContracts.ts` aggregate stays at the contract root because it also
-owns reconstruction and Android/Apple projection operations. Canonical tool
-aggregation, named handler binding and SDK schema presentation remain unchanged.
-Catalog source paths, compiled verifier/SDK fixtures and recovery CI filters
-follow the domain/contract owners.
-
-`scripts/verify/javascript/` groups application-workflow, runtime-reconciliation,
-large-digest and real-recovery entrypoints. Their existing npm commands retain
-their invocation semantics. Recovery fixture compilation lives beside its
-unchanged sources under `scripts/fixtures/javascript-recovery/`. Its default
-REA entrypoint still resolves to `scripts/rea.mjs`. Managed conformance imports
-the relocated compiled workflow; owning CI source filters follow the new paths.
-
-`src/artifacts/javascript/` owns directory/ASAR reader construction and relevant
-file acquisition, including root/nested byte verification, UTF-8 diagnostics and
-nested reader cleanup. Its narrow factory returns the existing `ArtifactReader`;
-the application retains input admission, inventory, graph construction and its
-original root-reader `finally` close. Pure file facts live in
-`src/domain/javascript/javascriptArtifactFiles.ts`, and the shared immutable
-inventory snapshot lives in `src/domain/artifactInventorySnapshot.ts`. Inventory
-options and integrity policy remain application-owned. Shared stream hashing
-lives in `src/artifacts/ArtifactHash.ts`, preserving complete byte counts and the
-bounded classification prefix. Acquisition/hash guards reject imports from
-application, composition or caller adapters; JavaScript workflows use the factory
-instead of importing concrete ASAR/directory reader classes.
-
-ZIP, native-DMG and Mach-O inventory reader selection keep their existing
-lifecycles. Runtime ports retain their distinct Inspector, passive Electron and
-active Electron effects; shipped Electron hooks remain at their existing
-provider boundary.
-
-## Managed capability ownership
-
-`src/domain/managed/` owns managed artifact and member semantics, reconstruction
-import, native-boundary verification and application graph projection.
-`src/application/managed/` owns their shared Evidence workflows, and
-`src/contracts/managed/` owns their named contracts and examples. Producer
-metadata/IL parsing stays in `src/dotnet/`; target resolution, Evidence, ordering
-and investigation records retain their shared owners. Path-based member
-comparison preserves its actual target/byte-digest admission and existing parser
-helper.
-
-`scripts/verify/managed/` groups the portable conformance entrypoint and its
-support, manifest, oracle and completion-report helpers. Its PE byte fixture
-builder and declaration live in `scripts/fixtures/managed/`, shared with the
-installed-package lane and existing managed conformance tests. `verify:managed`
-keeps its command name and optional caller-cwd manifest resolution. Compiled
-catalog and generator imports follow the owners; document-check cache inputs
-include the relocated runtime verifier and fixture files.
-
-Portable byte fixtures, optional operator-local manifests, actual ILSpy oracles
-and real Ghidra NativeAOT checks retain their distinct proof levels and
-prerequisites. The existing NativeAOT fixture/engine lane keeps its owner. This
-move preserves implementations, Evidence identities and generated commitments.
-
-## Binary application ownership
-
-`src/application/binary/` owns the active session, deep-provider registry and
-evaluation, operation routing, disjoint provider composition, lazy auxiliary
-clients, cancellation and client cleanup. Its records facade and snapshot
-cache/files remain bound to the exact target and analysis profile. Investigation
-records still have their separate owner in `src/application/investigation/`.
-
-`AnalysisProvider.ts` stays shared because its identity/execution types also serve
-nonbinary ports. `BinaryTargetResolver.ts` stays shared because Android, firmware,
-managed and artifact workflows use its target parsing. Production wiring lives
-in `src/composition/binary.ts`; application workflows gain no outward composition
-dependency.
-
-The three colocated application tests move with their owner. Composition cases
-remain in `tests/composition/analysis-sessions/`; filesystem and SDK cases retain
-their boundary lanes. The shared `tests/fixtures/binarySession.ts` factory supports
-several capability families. Existing recursive application globs discover the
-moved tests; bridge assets and real-verifier entrypoints remain at their owners.
-
-## Firmware layer and verification ownership
-
-Firmware workflows and their existing typed port live in
-`src/application/firmware/`, pure request/result semantics in
-`src/domain/firmware/`, and named contracts in `src/contracts/firmware/`.
-`src/firmware/` keeps producer commands, report parsing, source copies, publication
-and cleanup; `src/composition/firmware.ts` supplies a fresh typed factory.
-
-The real lane belongs to `scripts/verify/firmware/analysis.mjs`; the fixture runner
-and its unchanged Python producer belong together in `scripts/fixtures/firmware/`.
-The npm command names and selected `REA_FIRMWARE_FIXTURE_ROOT` are unchanged. The
-runner retains its working-directory-relative default; the verifier retains its
-repository-root default. Both point to `_reference/firmware-integration/generated`
-when invoked through the documented npm commands. Optional ext4/Ghidra lanes keep
-their own prerequisites. Source-fixture generation and synthetic producer tests
-do not establish real Binwalk/Unblob analysis or another host's execution support.
-
-## Apple artifact capability ownership
-
-`src/domain/apple/` owns Apple application anatomy/projection, asset catalog
-facts, Interface Builder graphs, keyed archive semantics and plist values.
-`src/application/apple/AppleApplicationService.ts` retains the shared workflow
-that projects authenticated IPA/macOS inventory Evidence.
-
-`src/artifacts/apple/` owns the actual producer boundary: directory acquisition,
-assetutil invocation, plist/NIB decoding, encoded view-parent interpretation and
-keyed archive inspection. These helpers are used by ArtifactProvider, retain
-its existing typed analysis boundary, injected assetutil seam and original reader
-cleanup, and do not require a new port for each helper. Producer code no longer
-lives in the application layer. Guards reject application/composition/caller
-imports from this owner while admitting pure facts and shared artifact readers.
-Adapter-source tests retain their assertions in the existing forked adapter lane.
-
-`scripts/verify/apple/` groups archive, asset catalog, Interface Builder,
-Objective-C/Swift dispatch and macOS bundle verification. The macOS bundle fixture
-builder lives in `scripts/fixtures/apple/`; NIB byte fixtures stay beside their
-artifact decoder. Existing format-specific conformance sources and goldens keep
-their locations, and relocated verifiers resolve them against their own file
-URLs. Public npm entrypoints and CLI/MCP contracts stay stable; generated-document
-cache inputs include the relocated runtime scripts and fixture builder.
-
-Portable decoder and injected producer tests establish their format/boundary
-claims. Actual Swift/Xcode, assetutil, native NIB, bundle signing and DMG lifecycle
-claims require the real Apple lane. Native binary API/value-flow semantics and
-shared cross-domain contract aggregates keep their separate owners.
-
-## Artifact inventory and extraction ownership
-
-`src/artifacts/inventory/` owns format classification, reader selection, inventory
-policy, canonical scanning and artifact graph construction. The shared artifact
-provider and JavaScript reconstruction workflow consume this owner. Snapshot
-semantics remain in `src/domain/artifactInventorySnapshot.ts`.
-
-`src/artifacts/extraction/` owns member selection, integrity checks and transactional
-materialization through the existing readers and safe output tree. Reader cleanup,
-cancellation, rollback, archive containment and caller-visible results retain their
-existing behavior. Acquisition guards reject imports from these producer owners
-into application workflows, production composition or CLI/MCP adapters.
-
-`src/application/artifacts/ArtifactExtractionDestination.ts` owns the caller's
-default temporary output-root choice for both CLI and MCP. The adapters pass this
-destination to the existing provider operation; format handling and member writes
-remain in the artifact owner.
-
-Add format-specific acquisition behavior beside the inventory readers and exercise
-its actual producer representation in filesystem boundary tests. Add caller
-workflow behavior in the application owner and verify both adapters. The installed
-package lane checks inventory identity and extraction through CLI and MCP; the
-real Apple bundle lane separately establishes DMG mount and detach behavior.
-
-## Binary production composition closure
-
-`src/composition/binary.ts` is the shared production owner for deep candidate
-construction, lazy auxiliary composition and the managed-only session factory.
-It preserves the existing constructor bodies, selection policy and fresh session
-per invocation. Factory registration acquires no engine or target.
-
-`DirectAnalysis` and `DirectAnalysisStatus` receive these two existing factories
-through `DirectAnalysisDependencies`. They retain configuration parsing, selected
-status environment, cancellation, snapshot replay/binding, Evidence projection
-and finally-close. The dependency uses the existing BinarySession type, including
-its replay policy; it adds no universal backend or lifecycle contract.
-
-`src/composition/directAnalysis.ts` binds the production factories for CLI and
-one-shot managed MCP callers. Binding creates no session and stores no retained
-analysis state. MCP startup constructs its connection session through the same
-binary factory. Source and compiled fixtures use these entrypoints. The former
-application runtime path is removed, and the source guard no longer admits its
-outward provider/composition imports.
-
-## Native analyst capability ownership
-
-`src/domain/native/` owns portable native inspection, instruction/data types,
-load-image facts, API boundaries, annotations, metadata recovery, UI observation
-semantics and value/investigation graphs. `src/application/native/` owns shared
-API projection, call routes, dispatch inspection and UI/value tracing. Its tests
-keep the existing service lane. `src/contracts/native/` owns the named native
-adapter contracts; shared official/enhanced aggregates remain at their owners.
-
-Producer interpretation, external commands and host UI lifecycle remain in
-`src/native/`, Hopper, Ghidra and IDA. The shared function dossier still lives in
-`domain/hopperValues.ts`: its historical name does not make its meaning exclusive
-to Hopper. This move retains existing typed ports, exact result schemas,
-observed/derived/unknown distinctions, profiles and Evidence links.
-
-Source and compiled verifier imports follow the new owners. Host UI and real
-native-value verifier locations are retained until their own proof lanes migrate;
-interactive macOS UI success and real dependency tracing require their respective
-host/engine workflows. Portable source fixtures and injected call-route tests
-establish their narrower boundaries, without expanding provider/platform support.
-
-## Process capture and analyst workflow ownership
-
-`src/domain/process/` owns scenario/capture validation, portable process trees,
-trace specifications, observations, comparisons and the canonical process Evidence
-identity. The standalone contract example lives in `src/contracts/process/`;
-shared session contracts retain their broader investigation owner.
-
-`src/process/capture/` owns the actual PTY boundary, terminal rendering, sampling,
-selected child environment, filesystem snapshots/effects, runtime path admission,
-event journal, settlement and resource cleanup. It reuses `src/process/` ownership
-primitives and the Windows host substrate. Its identity import follows the
-existing pure declaration directly. A source guard rejects outward application,
-composition and caller imports; no new provider or lifecycle interface is added.
-
-`src/application/process/` retains Evidence projection and file-backed CLI
-capture/comparison workflows. Capture helper tests use the forked adapter lane;
-Evidence/host integration tests use the serial process-boundary lane. Their
-fixtures and assertions remain unchanged. Installed capability-probe URLs follow
-the new compiled adapter path, including the optional-dependency failure probe.
-
-Windows PTY capture retains its existing unavailable outcome because descendant
-cleanup is not yet verified. Native Job Objects and a PTY binary do not establish
-that capture workflow. Real POSIX capture/cleanup and installed terminal/PTY module
-resolution require their actual host and package lanes; portable comparison
-fixtures establish their separate evidence semantics.

docs/cli.md

@@ -80,7 +80,7 @@ or close. Provider failures are returned with their original reason. For an
 `ambiguous` selection error, choose from `details.candidate_ids`; for
 `provider_unavailable`, run `rea doctor --provider ID --json` to diagnose the
 selected engine. See [task readiness](installation.md#check-readiness-for-your-task)
-and [provider selection](adr/0001-provider-selection-and-analysis-profiles.md).
+and [provider selection](mcp-contracts.md#identity-and-discovery).
 
 The session reports work still in progress through `analysis_activity`.
 A client timeout can end its wait while the provider continues analyzing.
@@ -96,6 +96,12 @@ an exact result when the target bytes, operation, parameters, provider and
 settings match. Mutations and cursor-dependent calls are excluded from the
 cache. Snapshot files are local and use owner-only permissions.
 
+Snapshots retain eligible target-scoped question histories in full, including
+mutation Evidence recorded while another target was active. Observations and
+related questions must still belong to the saved target. If those dependencies
+cannot be retained, the entire history is excluded instead of reverting the
+question to an earlier revision or disposition.
+
 ```bash
 rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program.json
 # Repeat the same query to reuse its saved result.
@@ -147,6 +153,10 @@ from observations of the current app. File names do not automatically exclude
 files. Set `REA_REFERENCE_SECRET_PATTERNS_JSON` to a JSON array of ignore
 patterns when you want to exclude selected paths.
 
+JavaScript and TypeScript import parsing requires valid UTF-8. Malformed source
+bytes retain their original hashes and sizes with a decoding diagnostic; REA
+does not infer module targets from replacement characters.
+
 Historical-source import requires safe no-follow file opens on Linux or
 macOS. Native Windows returns `unsupported_host`; use Linux REA inside WSL
 or another supported host. See

docs/ghidra-provider.md

@@ -0,0 +1,72 @@
+# Ghidra provider semantics
+
+REA imports one target into an ephemeral Ghidra database. Linux/macOS support
+read-only analysis and atomic function-name/entry-comment edits; Windows P0 is
+read-only. GUI controls and persistent database mutation are unavailable.
+Executable bytes remain unchanged.
+
+Use [installation](installation.md#ghidra) for supported hosts, prerequisites,
+configuration, startup deadlines, resource controls, and cleanup recovery.
+[Windows P0](windows-ghidra-p0.md) has its own admission and lifecycle boundary;
+[NativeAOT recovery](ghidra-nativeaot.md) is an optional, separately verified
+extension. Check the [release boundary](installation.md#released-package-and-main)
+when using npm.
+
+Provider selection and profile identity follow
+[MCP contracts](mcp-contracts.md#identity-and-discovery). One deep
+provider stays bound to the target; runtime failure never selects another
+provider automatically. The contracts below describe Ghidra observations,
+not equivalence with another engine's pseudocode or analysis database.
+
+## Admitted inventory semantics
+
+| Concern          | Ghidra contract                                                                                                                                                                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Program identity | One `analyzeHeadless` import produces exactly one Program; `list_documents` therefore returns exactly one name.                                                                                                                                                                                 |
+| Addresses        | Default memory uses lowercase `0x` hexadecimal. Non-default and external spaces use `<percent-encoded-space>:0x<hex>` and remain round-trippable. The handshake commits image base and default address-space name.                                                                              |
+| Symbols          | `list_names` includes address-bearing memory and external symbols, including dynamic symbols, while excluding variable and no-address namespace records. Each item reports primary, dynamic, external, symbol type, and source facts.                                                           |
+| Procedures       | Both non-external and external functions are listed. A local thunk remains distinct from its resolved target; exact and qualified name lookup fails on ambiguity rather than guessing.                                                                                                          |
+| Strings          | Only Ghidra-defined string `Data` is observed. Items report charset, byte length, and whether a required null terminator is missing. The API cannot distinguish a present terminator from fixed/Pascal layouts when no terminator is missing, so that state is named `present_or_not_required`. |
+| Memory           | Memory-block end addresses are exclusive. Read/write/execute, initialization, overlay, address space, and image base are direct Ghidra observations.                                                                                                                                            |
+| Inventory        | Procedure, symbol, and string listings plus searches return the complete matching collection in one response; callers do not provide offsets or result-count limits.                                                                                                                            |
+| Search           | Literal and Java-regex searches scan the complete immutable inventory and return all matching entries inline. Search waits for a reply or caller cancellation; there are no caller-supplied offsets or result-count limits.                                                                     |
+| Analysis state   | The socket is exposed only after default auto-analysis completes. Established operations wait for their reply or caller cancellation; there is no fixed response-size ceiling.                                                                                                                  |
+
+## Admitted function-analysis semantics
+
+| Concern                 | Ghidra contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Decompiler lifetime     | One persistent `DecompInterface` is opened for the imported Program and disposed during bridge shutdown. Native decompilation has no fixed per-function deadline. External functions or functions without bodies return `null`; cancellation and native failure remain distinct.                                                                                                                                                                                                                                                                                                                                           |
+| Serialization           | A FIFO sends one Program request at a time. Caller cancellation removes queued work promptly and is passed to active socket waits. This is an adapter safety commitment, not a claim that every Ghidra API is thread-safe.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Function identity       | Every function result carries the entry address and Ghidra FunctionManager classification for external, thunk, and resolved thunk target. These are observations, not proof that unresolved targetless calls have been recovered.                                                                                                                                                                                                                                                                                                                                                                                          |
+| Assembly and pseudocode | Assembly is complete Ghidra Listing text; pseudocode is Ghidra decompiler output. Neither is original source, and cross-provider comparison never treats Hopper and Ghidra text as equal or unequal semantic facts.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Instruction fast path   | `read_function_instructions` returns every raw Listing instruction for the requested function without invoking the decompiler or whole-program name/string inventories.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Calls and references    | Callers/callees contain only resolved functions. Reference edges preserve exact ReferenceManager type and call/jump/data/read/write/indirect/computed/conditional/terminal/external facts. Targetless computed flow remains unknown. Synthetic entry-point references without actionable memory sources are omitted explicitly.                                                                                                                                                                                                                                                                                            |
+| CFG                     | Dossiers use `BasicBlockModel` and retain only non-call successors inside the function body. CFG topology is address-normalized for comparison; provider-specific block construction remains a declared difference.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| P-code value flow       | Function dossiers include up to 3,000 high-p-code operations, at most 64 inputs per operation, and 12,000 def-use edges. Results identify memory reads/writes, branches, and calls by p-code opcode, and mark decompiler-dead operations. Large results report truncation, an omitted-operation lower bound, and known omitted-input/edge counts. The dossier is an intra-function graph; `trace_native_values` composes derived parameter/argument and return/output dependencies across resolved calls. It does not resolve memory aliasing, call side effects, runtime behavior, persistent state, or business meaning. |
+| Result extent           | Function instruction scans and native API boundary observations remain complete. P-code flow is the explicit bounded exception; its count fields distinguish exact retained counts from lower-bound or known-omitted counts. Caller cancellation and provider failures remain distinct.                                                                                                                                                                                                                                                                                                                                    |
+
+`npm run verify:ghidra` compiles the versioned C oracle into debug and stripped
+host-native targets (x86-64/AArch64 ELF on Linux or Mach-O on macOS), plus a native
+DWARF 4 type-layout object. It proves the admitted operations, external functions, resolved thunks, exports, stripped-name
+behavior, direct and targetless indirect calls, typed references, strings/xrefs,
+multi-block CFG, bounded p-code def-use/effect links, semantic enhanced workflows, cancellation, startup deadlines,
+serialized concurrency, malformed-target rejection, profile identity, and
+process/project cleanup against real Ghidra 12.1.4. Unit fixtures separately
+cover startup deadlines, process exit, queued cancellation, and malformed wire
+output.
+
+`npm run verify:ghidra:cross-format` adds AArch64 ELF, x86-64 PE, and x86-64
+Mach-O target coverage. It requires `clang`, LLD, and `lld-link`; set
+`REA_CLANG`, `REA_LLD`, or `REA_LLD_LINK` to select them. The verifier checks
+these tools before compilation. Keeping this matrix separate lets Linux
+host/provider acceptance run with only the host compiler.
+
+`npm run verify:ghidra:windows` and its `-- --x86` variant check the source-owned native x86 and x86-64 PE
+fixture, all 25 read-only operations, target/snapshot/import SHA-256 linkage,
+and project, endpoint, process, and runtime cleanup. The independent native
+lane checks DACLs, handle admission, cancellation, and Job Object lifecycle.
+`npm run verify:ghidra:windows:package` packs and installs REA into an isolated
+prefix, then checks ordinary-user CLI/MCP operations against canonical contracts.
+All lanes require matching native controls; package startup alone establishes
+only package compatibility.

docs/installation.md

@@ -137,6 +137,16 @@ listed after the table because its connector is not one of these files:
 | Command Code       | `commandcode`    |
 | VS Code            | `vscode`         |
 | Grok Build         | `grok_build`     |
+| OMP                | `omp`            |
+
+For OMP, setup writes a `type: "stdio"` entry to the user-level
+`~/.omp/agent/mcp.json`. It follows `PI_CONFIG_DIR`, an absolute
+`PI_CODING_AGENT_DIR`, and the profile selected by `OMP_PROFILE` or
+`PI_PROFILE` (`~/.omp/profiles/<name>/agent/mcp.json`). Setup also removes
+`rea` from that file's `disabledServers` list, which would otherwise hide the
+registration. Doctor treats an `enabled: false` entry as active when
+`enabledServers` lists `rea`, as OMP does, unless `disabledServers` also lists
+it. Run setup under each profile that should load REA.
 
 For OpenCode, setup writes the V1 `mcp.rea` entry, which OpenCode V1 and V2
 both load. If the configuration already uses OpenCode V2's native
@@ -182,6 +192,19 @@ default. Hopper is a separate optional choice: setup shows its proposed
 installation or connection and requires its own explicit approval. It can also
 save verified paths for an existing Ghidra installation.
 
+The bundled skill is installed where each selected client discovers personal
+skills: Claude Code uses `~/.claude/skills` (or
+`$CLAUDE_CONFIG_DIR/skills` when configured), while other supported clients
+use the shared `~/.agents/skills` directory. A mixed selection plans both
+paths. Selecting the skill without a client uses the shared directory. Setup
+leaves existing skill copies in other locations untouched.
+
+`doctor --skill --json` verifies the selected copies against the bundled
+instructions and references. Consumers should use `identity.skill.state`,
+`installed_version`, and `installed_tool_count` for skill readiness. The
+obsolete `installed_catalog_digest` field has been removed; current catalog
+identity remains available at `identity.catalog`.
+
 After selection, review the plan's exact paths and changes and approve before
 REA writes files or installs Hopper. You can cancel at any prompt.
 
@@ -189,7 +212,7 @@ Before applying changes, REA checks your current configuration. The plan lists:
 
 - an existing Hopper installation, a verified existing Ghidra installation, or the official Hopper package it proposes to install;
 - each detected agent configuration path;
-- the REA skill destination;
+- each selected REA skill destination;
 - external software, network origins, integrity evidence, and package-manager
   commands.
 
@@ -280,7 +303,7 @@ vendor-defined limits, and a paid license is optional. REA reuses any detected
 installation and preserves Hopper during uninstall.
 
 The supported native host baseline is macOS 12+, Ubuntu 24.04+, Fedora 41+,
-64-bit Arch Linux, or CachyOS. Ghidra and IDA have their own provider-specific
+Nobara 44+, 64-bit Arch Linux, or CachyOS. Ghidra and IDA have their own provider-specific
 host requirements; Windows Ghidra uses the [experimental P0 boundary](windows-ghidra-p0.md).
 
 On macOS, approved setup downloads the official DMG, checks its published size
@@ -406,6 +429,17 @@ Closing or switching a target closes its bound Hopper document, shuts down REA's
 bridge and removes its temporary socket directory while preserving the Hopper
 application and unrelated documents. A `cleanup_incomplete`
 result identifies resources whose cleanup could not be verified.
+REA retains unresolved cleanup ownership and any confirmed shutdown phases.
+After addressing the reported failure, retry `close_binary` on the same
+connection. Unconfirmed document or process cleanup retains the target/application
+lease and prevents another client from launching against that owned resource.
+Once document and process closure are confirmed, the lease can be released even
+if temporary-file cleanup fails. Another client can then launch, but the owning
+client must finish its retained cleanup before starting again.
+An unconfirmed external document can be retried while its authenticated bridge
+remains connected. If that bridge has disconnected, another close cannot confirm
+the document: inspect and close the reported document in Hopper before ending
+the owning REA connection.
 
 ### Hopper in CI
 
@@ -438,8 +472,11 @@ and JDK 21. Each installation must include the native decompiler for the host
 architecture in `Ghidra/Features/Decompiler/os/<platform>/` or the corresponding
 `build/os/<platform>/` directory. Linux ARM64 uses `linux_arm_64`; official
 release archives may require you to build that native component separately.
-REA checks the executable prerequisite and does not build or install native
-tools, or change Gatekeeper quarantine settings.
+REA checks the executable prerequisite by inspecting the file's own executable
+header, so a native component built for another platform or architecture is
+reported as incompatible instead of being admitted from its directory name, and
+a header that cannot be read or recognized is reported as unknown. REA does not
+build or install native tools, or change Gatekeeper quarantine settings.
 
 The adapter exposes 25 read-only operations: thirteen inventory/name/search
 operations and twelve function-analysis operations. These cover metadata,
@@ -637,7 +674,8 @@ and other MCP servers. Purging removes only REA's cache and state under
 `~/.rea`. A client configuration that is malformed, unreadable, or at an unsafe
 path stops the operation before anything is removed, and a client that fails
 while being updated stops the remaining removals. A purge path that is a
-symbolic link is retained and reported rather than followed. See the
+symbolic link is retained and reported rather than followed. Uninstall checks
+REA's managed shared and Claude Code personal skill locations. See the
 [CLI guide](cli.md#output-and-exit-status) for exit statuses.
 
 ## MCP Registry
@@ -659,7 +697,7 @@ For a client that requires manual configuration, use:
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@6.2.0", "mcp"]
+      "args": ["-y", "rea-agents@6.3.0", "mcp"]
     }
   }
 }

docs/javascript-application-graph.md

@@ -73,6 +73,18 @@ The directed relation vocabulary is `contains`, `loads`, `imports`, `maps_to`,
 and `changed_from`. Provider names are deliberately absent from both
 vocabularies.
 
+For a `maps_to` edge targeting a source-map node, the edge carries
+`resolved_path` and `declared_url_sha256`. The target node's reference
+observation carries that same digest and the exact `declared_url`; match the
+digest to select the URL belonging to that edge when several references share
+one physical source map. The full URL is kept out of node identity, display
+label, and edge properties, so large inline data URLs are stored once per
+source-map reference.
+
+Consumers previously reading `edge.properties.declared_url` should follow
+`target_node_id` and select the observation by `declared_url_sha256` instead.
+Node labels serve display; the observation preserves the original URL.
+
 For example, a source-owned synthetic fixture proves this path without using a
 third-party application:
 

docs/javascript-application-workflows.md

@@ -23,6 +23,15 @@ artifact digest and structural graph ID. Semantic tracing requires the semantic
 relation graph and reports when it is unavailable rather than treating missing
 data as an empty graph.
 
+The semantic graph wire format stores shared non-location provenance once in
+its required `evidence_contexts` table. Each node, relation, fingerprint, and
+unknown retains its exact `evidence.location` and names the owning context with
+`evidence.context_id`. This is a breaking representation change: consumers
+reading fields such as `evidence.authority` must look up the context by ID and
+combine its fields with the fact's location. Semantic trace results include the
+canonical context subset referenced by their returned facts, so those facts
+remain self-contained in the response.
+
 ## Feature tracing
 
 Select one literal seed kind: node ID, route, string, API, IPC channel, module,
@@ -60,13 +69,12 @@ validation boundaries, and built-in resource acquisition/release.
 
 Mutation tracking covers explicit member assignments, updates, deletion, and
 loop assignment targets, including the supported local aliases and shared
-nested references. Calls such as `Object.assign`, `Reflect.set`, and
-`Reflect.deleteProperty`, and writes reaching a caller's object through another
-function's parameter, are not tracked by this mutation pass. These channels
-can leave an initializer-derived literal in the graph even after the runtime
-value changes. Treat such a result as an uncovered mutation channel, not as
-proof of the current runtime value; a follow-up needs to model that channel
-and verify its caller/alias behavior.
+nested references. Calls conservatively invalidate exposed mutable references;
+callee bodies and built-ins such as `Object.assign`, `Reflect.set`, and
+`Reflect.deleteProperty` are not interpreted to establish exact post-call
+values. This uncertainty does not prove that a call actually mutated a value.
+Interprocedural aliasing beyond the supported call-site references remains
+outside this mutation pass.
 
 Function fingerprints commit normalized syntax, control-flow shape, relation
 shape, literal sets, arity, and detected effects without using local names or
@@ -137,6 +145,15 @@ Direct return expressions, including expression-bodied arrows, are evaluated
 through an execution-free value lattice. Literal object fields and direct
 return sites are represented in the result. Calls, dynamic spreads, computed
 keys, and parser recovery remain partial or unknown.
+Objects and arrays passed to calls, constructors, or tagged templates, or used
+as method receivers, are not assumed unchanged after the invocation. Aliases
+and shared children in spread and rest copies retain that uncertainty; copied
+primitive slots and unrelated containing properties remain known. Object rest
+excludes consumed keys, array rest excludes the consumed prefix for known
+arrays, and later explicit data properties and methods replace earlier object
+spread references. A known array prefix does not expose values from a following
+spread. Accessors, custom or uncertain iteration, unknown computed keys, and
+unknown spread lengths retain conservative uncertainty.
 Nested callable returns are not assigned to their parent callable. Projected
 graph observations carry source ranges but never source text.
 
@@ -162,6 +179,8 @@ value alone does not make an observed property uncertain. `summary.added` and
 `summary.removed` count
 presence-level add/remove as well as literal value add/remove;
 `summary.unknown` does not absorb complete-coverage presence-only gaps.
+A partial comparison still records an unknown in the MCP session when matching
+uncertain projections produce no changes and `summary.unknown` is zero.
 
 The output includes exact selector candidates, omissions, Evidence links,
 coverage, and limitations; it does not execute JavaScript. When runtime
@@ -175,6 +194,10 @@ All five CLI commands accept inline JSON or a path to a JSON file. The CLI
 returns an Evidence record directly. Put the full records in a later CLI input;
 a separate CLI process has no retained MCP connection state.
 
+File inputs must be regular files; symlinks to regular files are accepted.
+Directories, named pipes and device files produce an input error before JSON
+parsing.
+
 For a literal string trace, analyze your supplied tree once, then build the
 input from the saved Evidence (replace the target and seed):
 

docs/javascript-artifact-reconstruction.md

@@ -22,7 +22,7 @@ The tool reads the caller-selected local directory or ASAR path directly:
 ```bash
 rea analyze /absolute/path/to/apps/app.asar --json
 rea analyze-javascript-application /absolute/path/to/apps/app.asar \
-  --json
+  --integrity-policy record-and-continue --json
 ```
 
 Generic `rea analyze` selects this static provider for directories and `.asar`
@@ -47,11 +47,14 @@ The equivalent MCP input is:
 ```json
 {
   "input_path": "/absolute/path/to/apps/app.asar",
-  "format": "auto"
+  "format": "auto",
+  "integrity_policy": "fail"
 }
 ```
 
 `input_path` must be absolute. `format` accepts `auto`, `asar`, or `directory`.
+`integrity_policy` accepts `fail` or `record-and-continue`; both CLI routes and
+the MCP tool default to `fail`.
 The result retains the canonical local path, root artifact digest, artifact
 manifest and graph commitments, JavaScript Application Graph, static
 Electron summary, reconstruction statistics, and explicit limitations. It does
@@ -63,8 +66,12 @@ ASAR inventory checks Electron integrity metadata for embedded archive entries
 and supplied `.asar.unpacked` companion files. An integrity failure identifies
 the logical path, declared and calculated SHA-256 values, and whether the entry
 was unpacked. By default, a mismatch is returned as a failure with its artifact
-context. Requests that support `integrity_policy` can explicitly select
-`record-and-continue` to inspect verified siblings while retaining the mismatch.
+context. Application analysis can explicitly select `record-and-continue` to
+analyze observed bytes while retaining each contradiction's declared and
+observed hashes and `observed-untrusted` trust. Such results mark application
+graph coverage partial and include every contradicted path in the limitations.
+Mismatched nested ASARs stay opaque rather than being expanded. An unpacked
+entry whose companion bytes were not supplied remains `unavailable`.
 
 An unpacked entry whose companion bytes were not supplied remains
 `unavailable`. REA continues analyzing embedded JavaScript and records the
@@ -105,6 +112,23 @@ Field selection remains useful when the caller needs a
 smaller view, for example `--format json --filter-output
 evidence_id,normalized_result.statistics`. Streaming output does not bound the
 memory needed to construct the analysis graph itself.
+
+CLI workflows parse larger JSON input files incrementally from one verified
+regular-file handle, without constructing a document-sized string. Smaller
+files retain native JSON parsing. Both paths require strict JSON and valid
+UTF-8, and return one complete value; the assembled object still needs memory.
+An individual JSON string exceeding the native length limit or the available
+heap headroom for assembly returns
+`resource_constraint` with `input_reason: "too-large"`. Supply a smaller valid
+value; for Evidence workflows, re-analyze a smaller selection of the original
+target and use its complete Evidence. Splitting JSON text or trimming Evidence
+fields does not produce a valid workflow input.
+
+Evidence bundle and analysis snapshot file readers still decode whole
+documents. Their runtime string-limit failures report a resource constraint
+with the selected path, observed bytes and UTF-16 limit, rather than malformed
+JSON.
+
 MCP prepares the complete repeated response incrementally against the pinned
 SDK's 10 MiB stdio receive-buffer budget. Oversized results return an actionable
 transport constraint and the exact same-session Evidence reference. Use
@@ -283,6 +307,8 @@ such as `./web3:app.js` still names a local artifact.
 Package `exports` fallback arrays are supported both at the top level and under
 the root `"."` entry. The resolver selects targets in declared order using the
 same conditional and invalid-entry handling as nested exports arrays.
+For imports and requires, the active Node conditions include `module-sync`;
+earlier active conditions retain precedence over later ones.
 
 ESM relative module paths and selected package exports targets use URL suffix handling
 and one percent-decoding pass. CommonJS relative paths and legacy package main

docs/managed-code-analysis.md

@@ -1,4 +1,4 @@
-# Managed-code analysis and planned extensions
+# Managed-code analysis
 
 REA inspects .NET PE/CLI artifacts without loading or executing their code.
 It can identify an assembly, inspect metadata and CIL, compare members across
@@ -20,12 +20,11 @@ The seven shipped tools are:
 
 Each has a matching CLI command: replace underscores with hyphens and prefix
 the name with `rea`, for example `rea inspect-managed-artifact`.
-Native-body bridge mapping remains planned; managed runtime execution is not
-part of the current tool set.
+Native-body bridge mapping and managed runtime execution are outside the
+current tool set.
 
-This guide describes the implementation and verification of
-[ADR-0003](adr/0003-managed-code-evidence-and-provider-boundary.md). The canonical
-tool inventory is the [build-generated catalog](mcp-contracts.md#generated-catalog).
+The canonical tool inventory is the
+[build-generated catalog](mcp-contracts.md#generated-catalog).
 
 ## Shipped scope
 
@@ -36,10 +35,8 @@ NativeAOT identity from an ordinary native PE. Inputs without admitted CLI
 metadata do not become managed assemblies through naming or routing guesses.
 Inspect separately obtained components explicitly and preserve their identities.
 
-The broader deployment classification and native-body mapping below are design
-goals from ADR-0003, not claims that every row has an implemented parser. A
-valid marker can establish a candidate native boundary, not recovered native
-semantics or runtime behavior.
+A valid implementation marker establishes a candidate native boundary, not
+recovered native semantics or runtime behavior.
 
 ## Analysis objective
 
@@ -57,40 +54,7 @@ collapsing them:
 The ordinary workflow ends at question four. Static analysis never loads or
 executes the target.
 
-## Planned deployment classification
-
-The intended extended classifier proceeds from outermost authenticated bytes inward:
-
-```text
-source path
-  -> canonical path, size, SHA-256
-  -> container inventory
-  -> PE/native header and architecture
-  -> CLI header and metadata root
-  -> deployment/runtime markers
-  -> per-component and per-method implementation availability
-  -> managed-only, native-only, composed, degraded, or unsupported route
-```
-
-The planned result is a vector rather than one label. For example, a single-file modern
-.NET deployment can contain a native host, ordinary CIL assemblies, and
-ReadyToRun components. Each component receives its own digest, classification,
-coverage, and route while retaining the outer bundle commitment.
-
-| Case                  | Required positive observations                                               | Claims that remain unavailable or inferred                                                |
-| --------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| .NET Framework        | Valid CLI metadata plus bounded Framework-specific target/reference evidence | Exact installed CLR and runtime behavior                                                  |
-| Modern .NET           | Valid CLI metadata plus bounded target/reference/runtime-config evidence     | Exact runtime selected on another host                                                    |
-| Unity Mono            | Valid managed assembly plus authenticated Unity context when supplied        | Engine behavior or native integration not represented by metadata                         |
-| ReadyToRun            | Valid managed metadata plus authenticated ReadyToRun header/sections         | Native implementation semantics until a selected deep provider analyzes them              |
-| C++/CLI               | Valid CLI metadata plus mixed-mode PE/header evidence                        | Mapping managed declarations to native implementations without explicit bridge evidence   |
-| Single-file           | Valid authenticated bundle inventory and component extents                   | Components that are compressed or encoded by an unsupported bundle version                |
-| Unity IL2CPP          | Authenticated native image/metadata pairing and supported metadata version   | Canonical CIL and source-equivalent C#                                                    |
-| NativeAOT             | Native image plus bounded NativeAOT evidence                                 | Ordinary CLI metadata/CIL unless independently present                                    |
-| Obfuscated assembly   | Same positive byte observations as its underlying deployment form            | Meaning inferred only from names                                                          |
-| Malformed/unsupported | Exact admitted regions and failure locations                                 | Completeness, successfully skipped rows, or semantics beyond the admitted parser boundary |
-
-### NativeAOT metadata recovery
+## NativeAOT metadata recovery
 
 NativeAOT removes the ordinary CIL method bodies, so a CIL decompiler cannot
 reconstruct those bodies as C# source. The executable remains a native target
@@ -110,28 +74,17 @@ lists supported OS/architecture targets and deployment limitations, while its
 [native library guide](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/libraries)
 describes exported shared-library entry points.
 
-The [Ghidra NativeAOT analyzer](https://github.com/Washi1337/ghidra-nativeaot)
-is a useful optional companion for recovering ReadyToRun metadata. It
-rehydrates the `DEHYDRATED_DATA` section and annotates method tables, type
-relationships, vtable slots, frozen objects, and strings. It does not recover
-original C# method bodies. It is a separate Ghidra extension and interactive
-metadata browser; REA does not currently install or invoke it through its
-headless bridge. Its README describes ReadyToRun header discovery, including
-symbol-based and heuristic paths, so a missed header or unsupported binary
-should remain an explicit limitation rather than a failed claim about the
-binary's contents.
+REA supports an optional headless adapter for the Ghidra NativeAOT analyzer.
+Supply a locally built `REA_GHIDRA_NATIVEAOT_JAR`; REA does not install the
+extension or its toolchain. The verified boundary is .NET 8.0.22 RTR 9.1,
+x86-64 ELF and native Windows PE targets analyzed on Linux x64 with Ghidra
+12.1.4 and JDK 21. Other layouts, architectures, and hosts are unsupported.
+See [NativeAOT recovery](ghidra-nativeaot.md) for build/configuration, recovered
+metadata, derived-memory provenance, and the real verification lane.
 
-The upstream analyzer currently gates its own analysis to x86-64. NativeAOT's
-broader platform matrix does not establish REA coverage: PE/COFF, ELF, Mach-O,
-shared libraries, target architectures, and runtime metadata versions each need
-their own provider verification. REA's experimental Windows Ghidra boundary is
-limited to admitted native x86 and x86-64 PE applications, so it does not currently
-establish coverage for PE DLLs. Mobile NativeAOT targets should remain
-experimental until REA has a matching provider and package-level verification.
-
-For REA's native analysis, preserve the same artifact path and digest used by
-`inspect_managed_artifact`, and report recovered type data as provider
-observations. Linking those types to native function addresses requires verified
+For NativeAOT analysis, preserve the selected native artifact's path and digest
+and report recovered type data as provider observations. Linking those types
+to native function addresses requires verified
 provider evidence; names or vtable similarity alone do not prove that a native
 function implements a specific managed method.
 
@@ -143,43 +96,18 @@ matches the normalized artifact SHA-256. A valid Evidence ID alone does not
 establish that those two identities agree. Evidence without a subject remains
 usable, with no subject digest available to cross-check.
 
-Every planned operation returns a provider result and Evidence with four
-commitment groups:
+Artifact inspection returns the selected path, byte length and SHA-256, observed
+PE/CLI classification, assembly and module identities, and metadata coverage.
+Member inspection binds build-local tokens, signatures, row offsets, method
+bodies, and decoded relationships to that artifact and MVID. Missing or malformed
+facts remain explicit in coverage and per-member status.
 
-### Artifact commitment
+CLI `#GUID` heap values retain their exact 16-byte GUID text. REA does not impose
+RFC 4122 UUID version or variant bits on MVID, EncId, or EncBaseId because
+ECMA-335 metadata does not require those bit patterns. Tokens and RVAs are
+build-local coordinates, not durable cross-build identities or native addresses.
 
-- canonical local path, byte length, and SHA-256;
-- outer-container identity and digest when inspecting a component;
-- component name/path, byte extent, and SHA-256;
-- observed PE machine, CLI flags, and conflicts;
-- classification vector, supporting observations, and unresolved dimensions.
-
-### Module commitment
-
-- assembly simple name, version, culture, public-key/token state, flags, and
-  hash algorithm;
-- module name, generation, and MVID;
-- target framework and runtime/version strings with their exact metadata
-  locations;
-- provider identity, analysis-affecting parameters, and their profile digest.
-
-CLI `#GUID` heap values are committed as their exact 16-byte GUID text. REA
-does not impose RFC 4122 UUID version or variant bits on MVID, EncId, or
-EncBaseId because ECMA-335 metadata does not require those bit patterns.
-
-### Entity commitment
-
-- table kind and build-local token;
-- declaring scope and normalized CLI signature;
-- row/heap/body locations expressed as typed file offsets, RVAs, or CIL
-  offsets;
-- exact raw bytes or bounded value digest;
-- raw CIL digest plus separately reported method-header, locals-token, and
-  exception-region observations where available;
-- a deterministic decoded-instruction-tuple digest for completely decoded
-  CIL, with the limitations below.
-
-### Shipped decoded-CIL fingerprint
+## Decoded-CIL fingerprint
 
 `inspect_managed_members` exposes two method CIL hashes with different byte
 boundaries:
@@ -208,9 +136,7 @@ reproducible decoded-tuple fingerprint, not a canonical semantic CIL identity:
 it does not resolve tokens across MVIDs, does not commit full control flow or
 exception semantics, and does not replace the raw CIL digest. Cross-build
 comparison uses the value only as one unique-only structural tier and reports
-ambiguity when that evidence is insufficient. A future normalized-CIL
-commitment would need canonical token/literal identities,
-complete branch and switch targets, and explicit locals/exception semantics.
+ambiguity when that evidence is insufficient.
 
 For example, a decoded `nop; ret` body serializes exactly as
 `[["nop","none",null],["ret","none",null]]` and has digest
@@ -218,73 +144,10 @@ For example, a decoded `nop; ret` body serializes exactly as
 This vector specifies the tuple order, `null` handling, absence of whitespace,
 UTF-8 encoding, and lowercase hexadecimal output.
 
-### Epistemic commitment
+## Member comparison
 
-- authority: static bytes, reconstruction, structural inference, independent
-  validation, native provider, or future runtime observation;
-- state: observed, inferred, unknown, or unavailable;
-- confidence independent of authority;
-- coverage and admitted/dropped counts;
-- exact supporting Evidence IDs and actionable limitations.
-
-A semantic label such as `score_submission_gate` can annotate an entity, but it
-is never the entity's identity. The same applies to an obfuscated name, token,
-RVA, or decompiler-generated local name.
-
-## Planned static capabilities
-
-The caller-visible grouping and exact tool names are decided with the contracts
-that implement them. The underlying capability slices are:
-
-1. **Triage and inventory**: container/component classification, assembly and
-   module identity, references, files, exported types, resources, attributes,
-   and runtime markers.
-2. **Member inventory**: file-backed types, methods, fields, properties, events,
-   interfaces, nesting, generics, and normalized signatures.
-3. **Method inspection**: headers, max stack, locals, CIL instructions,
-   constants, metadata operands, exception regions, and implementation flags.
-4. **Relationships**: declared overrides, interface implementations, member
-   references, direct CIL callers/callees, field access, construction, and
-   interop declarations. Dynamic dispatch remains qualified.
-5. **Structural search and comparison**: signature/API/constant/flow anchors,
-   exact and normalized hashes, competing candidates, and explicit
-   exact/structural/missing/ambiguous states.
-6. **Managed/native composition**: P/Invoke, unmanaged exports, COM/mixed-mode
-   declarations, ReadyToRun/native bodies, single-file hosts, and authenticated
-   IL2CPP pairs linked to selected Hopper/Ghidra evidence. The shipped
-   verification workflow checks P/Invoke declarations against supplied native
-   export or function Evidence; native-body, thunk, and token-to-address bridge
-   mapping remain unavailable without explicit provider-supported evidence.
-7. **Application graph projection**: managed assembly/module/type/method/field,
-   P/Invoke, and native-implementation declarations enter the same
-   Evidence-backed application graph vocabulary as JavaScript/Electron
-   findings while preserving managed static-analysis authority.
-
-Inventory lists preserve deterministic order and include every fact available
-from the admitted PE/CLI streams. Malformed ranges and unsupported metadata are
-reported as coverage issues instead of being silently omitted. Search exposes
-scanned, matched, returned, and dropped counts. An unresolved indirect call or
-a failed signature decode is not silently omitted from a completeness claim.
-
-## Obfuscation-resistant method slices
-
-Names are one weak feature among many. A behavior slice records the smallest
-bounded set of observations needed to investigate a proposition:
-
-- normalized declaring/member signatures and inheritance/interface shape;
-- framework and application API references;
-- exact strings, numeric constants, enum-like values, and serialization keys;
-- branch, switch, exception, loop, call, and field-flow shape;
-- construction and generic-instantiation sites;
-- raw CIL and decoded-tuple commitments, plus separate header, locals, and
-  exception observations;
-- callers, callees, shared fields, and competing candidates; and
-- limitations from reflection, dynamic dispatch, generated code, protection,
-  native transitions, or incomplete coverage.
-
-The workflow produces separate observation, inference, validation, and unknown
-tables. It may say that a method is a strong candidate for a role; it cannot
-turn that role into the method's durable identity.
+Names and semantic labels do not establish durable member identity. Comparison
+preserves observed differences, structural inferences, and unknowns separately.
 
 Cross-version matching first prefers exact CIL/signature identity. When that
 does not match, it pairs an exact declared type, method name, and raw signature
@@ -310,16 +173,14 @@ Tokens are always remapped through observed structure. A caller cannot carry
 
 ## Managed/native boundary rules
 
-| Boundary                | Managed observation                                                     | Native observation                                                              | Permitted link                                                       |
-| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| P/Invoke                | Module, entry point, charset/calling-convention flags, declaring method | Import/export/symbol/function evidence from the selected deep provider          | Exact declared-name/module link or qualified resolution inference    |
-| COM                     | Interop attributes, GUIDs, imported interfaces, method signatures       | Native registration/vtable evidence when independently available                | Identifier/signature inference with explicit environment limitations |
-| C++/CLI                 | Managed declaration and implementation flags                            | Native body/function evidence                                                   | Only a provider-supported bridge observation; never token-as-address |
-| ReadyToRun              | Component/header and per-method CIL/native availability                 | Native section/function evidence                                                | Authenticated image mapping with format/profile version              |
-| Unmanaged export        | Export metadata/attribute when present                                  | PE export and native thunk/function                                             | Exact export identity plus provider-qualified address                |
-| Single-file host        | Bundle entry/component identity                                         | Host and native component evidence                                              | Outer bundle plus component digest/extent commitment                 |
-| Unity IL2CPP            | Supported metadata entity with authenticated pairing                    | Generated native function/type evidence                                         | Versioned IL2CPP mapping only; no invented CIL                       |
-| Runtime-resolved native | API/constant/data-flow candidate                                        | Loaded-module/symbol observation from an independently collected runtime source | Static candidate remains inference until separately observed         |
+`verify_managed_native_boundaries` compares declared P/Invoke module and entry
+point identities with supplied native export or function evidence. Name/module
+matches establish declaration links; they do not establish that a call executed.
+
+Metadata tokens are not native addresses. Native body mapping for C++/CLI,
+ReadyToRun, NativeAOT, and IL2CPP requires separately verified format and provider
+support. The managed static tools do not recover those mappings. The optional
+[Ghidra NativeAOT extension](ghidra-nativeaot.md) has its own supported boundary.
 
 Declared import inventory supports a bounded positive claim. Its absence does
 not exclude dynamic resolution, generated code, protected code, native helpers,
@@ -333,16 +194,12 @@ fixtures and expected semantic facts. An optional real ILSpy lane runs only when
 its executable is explicitly supplied; the default lane does not establish
 independent pinned-oracle parity. Production inspection needs none of those tools.
 
-- A pinned `System.Reflection.Metadata` differential oracle is planned; it is
-  not part of the current verifier.
 - `ICSharpCode.Decompiler`/`ilspycmd` can supply reconstruction inference.
   A BYO reconstruction import records the supplied version
   and remains non-canonical. When `REA_ILSPY_CMD_PATH` points to an absolute
   runnable `ilspycmd`, `verify:managed` runs a source-owned real ILSpy oracle
   and imports its C# output as reconstruction inference against exact static
   member Evidence.
-- dnlib and Mono.Cecil are potential future differential oracles. Their mutation APIs
-  are not exposed or included in the production parsing boundary.
 - The package contains no .NET runtime, SDK, ILSpy installation, proprietary
   assembly, or compiled conformance fixture.
 - Setup never installs or upgrades those tools. Doctor may inspect an explicit
@@ -360,29 +217,15 @@ they do not claim that the REA application itself supports Windows. Native
 ReadyToRun, C++/CLI, NativeAOT, or IL2CPP coverage is additionally constrained
 by the selected Hopper/Ghidra host and format matrix.
 
-## Source-built conformance corpus
+## Conformance verification
 
 The current lane uses source-owned byte-built fixtures and malformed-input
 regressions, with optional operator-supplied applications and ILSpy verification.
-The table below describes the desired expanded corpus; it is not a report that
-all compiler-generated forms have been independently verified.
 
-Fixture sources are intentionally small and behavior-focused. Build outputs
-are generated outside tracked fixture directories and must not remain after
-verification or packaging.
-
-| Corpus slice           | Required properties                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------------------ |
-| Identity               | Assembly/module/version/culture/public key, references, attributes, resources, MVID        |
-| Signatures             | Nested/generic types, arrays, pointers, by-ref, function pointers where supported, varargs |
-| CIL                    | Short/long branches, switch, prefixes, constants, locals, calls, fields, boxing, tokens    |
-| Exceptions             | Catch, finally, fault/filter where the compiler/toolchain supports them                    |
-| Generated structure    | Async and iterator state machines, lambdas, closures, properties, events                   |
-| Interop                | P/Invoke flags, module/name mapping, managed/unmanaged implementation metadata             |
-| Architecture           | AnyCPU, preferred-32-bit where applicable, x86, x64                                        |
-| Obfuscation resistance | Unicode/meaningless/duplicate-looking names and structure-preserving renames               |
-| Cross-build comparison | At least two builds with changed MVID/token order/layout and known same/changed behaviors  |
-| Malformed/adversarial  | Truncated/overflowing headers, streams, tables, heaps, signatures, bodies, and EH sections |
+Run the deterministic lane with `npm run verify:managed`. See
+[testing](testing.md#real-toolchain-verification-lanes) for prerequisites and
+coverage. Generated outputs belong outside tracked fixture directories and must
+not remain after verification or packaging.
 
 Verification compares semantic facts, not decompiler text. It checks resource
 ceilings, deterministic ordering, complete cleanup, CLI/MCP parity, Evidence
@@ -492,32 +335,7 @@ evidence is collected. A direct process capture can retain declared inputs,
 outputs, filesystem and protocol activity for a target run; it does not prove
 which managed methods executed or how the CLR resolved them.
 
-## Delivery sequence
-
-The managed-code track advances as reviewable pull requests:
-
-1. accepted evidence/provider boundary (this document and ADR);
-2. read-only artifact triage and exact identity (shipped);
-3. file-backed metadata, signatures, method bodies, raw CIL hashes, and the
-   decoded-instruction-tuple fingerprint (shipped; complete normalized-CIL
-   semantics remain planned);
-4. obfuscation-resistant slices and cross-version comparison (shipped for
-   static member observations);
-5. decompiler reconstruction import (shipped as analyst inference; REA does
-   not run ILSpy/dnSpy, and metadata/CIL remain canonical);
-6. managed/native composition and truthful deployment degradation (declaration
-   inventory and native export/function Evidence matching shipped; native-body
-   bridge mapping remains planned);
-7. source-built managed conformance and package/CLI verification (source-owned
-   PE/CLI corpus shipped through `npm run verify:managed`; optional BYO
-   `ilspycmd` real-tool oracle shipped through `REA_ILSPY_CMD_PATH`; dnSpy and
-   pinned Windows checks remain planned); and
-8. managed static Evidence projection into the application graph (shipped).
-
-Each implementation PR updates generated product facts only for behavior it
-actually ships and states which real-tool checks were performed.
-
-### Method metadata during build comparison
+## Method metadata during build comparison
 
 Managed member comparisons report a `metadata` dimension when an observed
 MethodDef flags or implementation flags value differs, including accessibility

docs/mcp-contracts.md

@@ -25,12 +25,16 @@ health transition leaves that catalog unchanged and does not emit
 
 Advertised input and output schemas contain no reachable recursive references.
 Schemas share repeated definitions through schema-local references while
-preserving complete fields and validation rules. Input properties retain their
-descriptions and literal examples. The SDK advertises an object root for
-canonical object unions and retains each branch's requirements and exclusions.
-Tests validate the schemas after SDK conversion and compare advertised
-validation with actual calls. Individual model APIs can impose additional
-nesting limits; complete producer captures can exceed ten structural levels.
+preserving complete nested fields and validation rules. Input properties retain
+their descriptions and literal examples. Root object unions are presented as
+one object without root `anyOf`, `oneOf`, or `allOf` for model API compatibility.
+The projection merges properties, retains shared required fields and
+group-specific field dependencies, and describes the accepted input groups.
+Canonical runtime validation enforces the exact union, including exclusions
+that the advertised projection does not express. Tests validate the schemas
+after SDK conversion and check advertised validation and actual calls.
+Individual model APIs can impose additional nesting limits; complete producer
+captures can exceed ten structural levels.
 
 `compare_web_captures` accepts exactly one of two input shapes:
 
@@ -42,10 +46,11 @@ nesting limits; complete producer captures can exceed ten structural levels.
   `normalization` defaults to `{ "rules": [] }`.
 
 The advertised schema includes complete nested capture fields and rejects
-incomplete pairs, mixed comparison families, and structurally malformed
-captures. Domain validation additionally checks relationships such as event
-sequence references and retained counts; JSON Schema does not express those
-cross-field invariants.
+incomplete pairs and structurally malformed captures. Mixed comparison families
+can pass advertised validation; the SDK rejects them against the canonical
+input schema before invoking the handler. Domain validation additionally checks
+relationships such as event sequence references and retained counts; JSON
+Schema does not express those cross-field invariants.
 
 Call `binary_session` with `{}` and read `result.tool_availability` to choose a
 callable operation for the current target, provider, host, and negotiated client
@@ -339,3 +344,9 @@ Contradictory bytes are quarantined from nested expansion and recorded with
 declared and observed hashes, trust, provenance, path, and unpacked state.
 Verified siblings continue. Comparisons classify the result as a contradiction
 and reconstruction cannot treat it as unchanged.
+
+`analyze_javascript_application` accepts the same policy in MCP and as
+`--integrity-policy` on both JavaScript CLI routes. Its result returns the
+canonical `integrity_contradictions` records and marks application graph
+coverage partial when any mismatch is continued. Contradicted nested ASARs
+remain opaque.

docs/migration-6.2.md

@@ -31,7 +31,7 @@ and carry their typed JSON diagnostic in a text content block; they omit
 if (reply.isError === true) {
   const text = reply.content.find((part) => part.type === "text");
   if (text === undefined) throw new Error("REA error has no text diagnostic");
-  const diagnostic = JSON.parse(text.text);
+  const { error: diagnostic } = JSON.parse(text.text);
   // Handle diagnostic.code, diagnostic.message and diagnostic.details.
 }
 ```

docs/native-investigation.md

@@ -96,8 +96,18 @@ complete observation.
 
   So an external superclass resolves from its `_OBJC_CLASS_$_` bind (for
   example `NSObject`). The `pointer_fixups` coverage facet names the mechanism.
-  Class properties, with parsed attributes, and `__objc_catlist` categories are
-  also decoded. Categories record the extended class, local or external, plus
+  Class properties preserve each encoded attribute as a raw `{name, value}`
+  pair, for example `{ name: "N", value: "" }`, and report atomicity on the
+  property: `N` means `nonatomic`; a complete typed attribute string without
+  `N` means the Objective-C default `atomic`;
+  missing or incomplete attribute metadata leaves `atomicity` and any
+  unestablished read-only value null. `is_meta_class`, `is_root_class`, and
+  `ivar_count` are also nullable when the selected provider exposes only symbol
+  names. Class implementation methods have null `is_required` and `is_optional`
+  fields because those facts apply to protocol declarations; decoded protocol
+  method lists retain their observed required/optional values. Class properties
+  and `__objc_catlist` categories are also decoded. Categories record the
+  extended class, local or external, plus
   their methods, protocols and properties; category methods appear as
   implementations with a `category`. Swift field-offset globals that are only
   initialized at runtime stay unresolved. Generic, resilient, async and

docs/process-capture.md

@@ -130,7 +130,7 @@ run the same owned-process cleanup path. Settlement reports whether the
 sampled process group quiesced or whether cleanup was needed or unverifiable;
 sampling cannot prove that every short-lived or detached descendant was seen.
 
-New captures include `truncation_details`, with separate accounting for:
+Every capture requires `truncation_details`, with separate accounting for:
 
 - `raw_terminal`: original UTF-8 PTY chunk bytes and observed/retained chunk
   counts. A chunk that does not fit `limits.output_bytes` is omitted whole;
@@ -143,20 +143,23 @@ New captures include `truncation_details`, with separate accounting for:
 - `filesystem_before` and `filesystem_after`: file-count/depth limits,
   enumeration failures, whole-file hash budget and bytes successfully hashed.
   Each retained regular file without a digest has an aliased path, size,
-  remaining budget and reason: `file_bytes_budget` or
-  `file_changed_or_short_read`. A file too large for the remaining budget is
+  remaining budget and reason: `file_bytes_budget`,
+  `file_changed_or_short_read`, or `file_unavailable`. Its `system_code` is
+  null unless an OS file operation failed, in which case it preserves the
+  reported error code. A file too large for the remaining budget is
   skipped; a later smaller file can still be hashed. Hash omissions do not
   imply incomplete path enumeration.
 - `process`: sampling limit and whether sampling ended partially. Coverage
   remains `sampled`, including when that limit was not exhausted.
 
-The legacy `truncated` flag summarizes these observations. Comparisons retain
+The aggregate `truncated` flag summarizes these observations. Comparisons retain
 results for unaffected dimensions and mark affected dimensions unknown; an
 incomplete capture cannot locate the first divergence across all dimensions.
 Trace assertions use coverage for the sources they select, so an assertion
 about complete raw terminal output need not fail because rendered snapshots
-were omitted. Older truncated captures without these details retain the
-conservative comparison behavior. These diagnostics use the existing scenario
+were omitted. Captures missing `truncation_details` are rejected on import;
+preserve them as historical files and recapture for current comparisons.
+These diagnostics use the existing scenario
 budgets; they do not introduce a separate file-hashing budget.
 
 When the host withholds an unrelated process’s ownership token, REA leaves that

docs/provider-evaluation.md

@@ -1,219 +0,0 @@
-# Static-analysis provider evaluation
-
-This guide describes repository main. Check the [released package boundary](installation.md#released-package-and-main) when using npm.
-
-Ghidra read-only analysis is available on Linux x64/arm64 and macOS x64/arm64.
-Install a Ghidra 12.1.x release and the 64-bit full JDK that release declares,
-then configure REA to use them. 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.
-Each installation needs the matching native decompiler.
-
-REA imports one target into a temporary project and exposes 25 read-only
-operations after analysis completes. They cover inventories, search,
-decompilation, assembly, function metadata, resolved calls, references, control
-flow, instructions, and recovered types. Results identify the provider version,
-analysis settings, target digest, and any unavailable or incomplete facts.
-On Linux and macOS, `annotate_native_function` additionally edits names and entry
-comments atomically, verifies readback, and returns refreshed function analysis.
-Changes live only in the session database and leave executable bytes unchanged.
-Ghidra does not expose GUI controls; Windows P0 remains read-only.
-
-Windows x64 P0 supports native x86 and x86-64 PE applications on local NTFS with
-bundled Job Object ownership, protected runtime DACLs, and handle-based path
-admission. Real ordinary-user verification covers all 25 read-only operations
-through the packaged CLI and MCP, target integrity, and cleanup. This remains
-an experimental boundary; see [Windows Ghidra P0](windows-ghidra-p0.md) and
-[issue #527](https://github.com/morluto/rea/issues/527).
-
-[ADR-0001](adr/0001-provider-selection-and-analysis-profiles.md) fixes the
-provider registry, deterministic selection, target binding, analysis profile,
-snapshot migration, and compatibility semantics that implementation must
-follow.
-
-## Approved Ghidra v1 boundary
-
-- Keep the existing provider-neutral CLI and MCP tool names.
-- Bind one deep-analysis provider to a target for the target's lifetime; never
-  fail over silently between Hopper and Ghidra.
-- Use an existing Ghidra installation and a compatible Java runtime. Setup must
-  not install or upgrade Ghidra or Java.
-- Run Ghidra headlessly in an owned process with a private temporary project,
-  startup and cleanup deadlines, caller cancellation, and complete replies.
-- Prefer a packaged Java bridge loaded through Ghidra's script path. PyGhidra
-  remains useful for prototypes but is not a mandatory production dependency.
-- Treat authenticated `ping` and `shutdown` as lifecycle proof only. Inventory,
-  xref, CFG, and decompilation claims require separately admitted operation
-  contracts and real-provider conformance.
-- Implement read-only inventories, assembly, decompilation, function metadata,
-  calls, references, containment, and complete inventory search first.
-- Report GUI cursor/navigation and persistent mutation operations as unavailable
-  until their semantics and project ownership are explicitly designed.
-- Verify real claims on Linux with at least two distinct source-owned binaries.
-  Verify the Windows host claim with the deterministic source-owned x86 and x86-64 PE
-  fixtures and all admitted operations; compare normalized semantic facts rather
-  than provider-specific pseudocode text.
-
-## Shipped foundation boundary
-
-`GHIDRA_INSTALL_DIR` must identify an extracted Ghidra 12.1.x release. Optional
-`JAVA_HOME` must identify a 64-bit full JDK inside that installation's
-`application.java.min` and `application.java.max` (JDK 21 or newer, with no
-maximum, when the release leaves those at the 12.1 defaults). Otherwise doctor
-probes `java`/`javac` or `java.exe`/`javac.exe` from `PATH`. Supported Linux and macOS
-hosts accept compatible ELF, PE, and Mach-O executable targets. Host admission
-and target compatibility are separate checks. Windows x64 P0 admits only native,
-non-managed, non-DLL x86 and x86-64 PE applications on fixed local NTFS, with the packaged
-native authority available before launch.
-
-The launcher creates one ephemeral runtime root with project,
-home/cache/config/data/temp, logs, descriptor, endpoint, target snapshot, and
-ownership manifest.
-It passes `-readOnly` and `-deleteProject`, and uses Ghidra's default analysis
-and resource settings; inherited Java option injection variables are cleared.
-On Linux, the mode-0600 descriptor carries the random token without
-exposing it in argv or environment and the Java bridge binds a mode-restricted
-Unix socket. macOS uses the same local transport. The bridge reports actual
-Ghidra/language/compiler/analysis/import-digest metadata and accepts only
-authenticated `ping`, `shutdown`, thirteen read-only inventory/load-image methods,
-and twelve function-analysis methods. Linux/macOS also admits atomic function
-annotation changes in the ephemeral database. Close, cancellation, timeout, malformed protocol,
-or process exit stops the owned process resources, closes the socket, and
-removes the runtime root.
-
-The experimental Windows transport uses authenticated IPv4 loopback with a
-token-free endpoint record. The bundled native authority establishes Job Object
-ownership, protected runtime DACLs, and handle-based path admission before
-launch. If the bundle or an admission constraint is unavailable, the provider
-remains unavailable; a `taskkill` fallback does not establish that authority.
-
-The provider catalog lists 25 read-only Ghidra operations and the Linux/macOS
-session annotation operation. GUI cursor/navigation and persistent mutations
-remain unavailable; Windows P0 admits no database mutation. The router therefore
-reports them unavailable instead of borrowing Hopper semantics or inferring
-capability from a successful import.
-
-## Admitted inventory semantics
-
-| Concern          | Ghidra contract                                                                                                                                                                                                                                                                                 |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Program identity | One `analyzeHeadless` import produces exactly one Program; `list_documents` therefore returns exactly one name.                                                                                                                                                                                 |
-| Addresses        | Default memory uses lowercase `0x` hexadecimal. Non-default and external spaces use `<percent-encoded-space>:0x<hex>` and remain round-trippable. The handshake commits image base and default address-space name.                                                                              |
-| Symbols          | `list_names` includes address-bearing memory and external symbols, including dynamic symbols, while excluding variable and no-address namespace records. Each item reports primary, dynamic, external, symbol type, and source facts.                                                           |
-| Procedures       | Both non-external and external functions are listed. A local thunk remains distinct from its resolved target; exact and qualified name lookup fails on ambiguity rather than guessing.                                                                                                          |
-| Strings          | Only Ghidra-defined string `Data` is observed. Items report charset, byte length, and whether a required null terminator is missing. The API cannot distinguish a present terminator from fixed/Pascal layouts when no terminator is missing, so that state is named `present_or_not_required`. |
-| Memory           | Memory-block end addresses are exclusive. Read/write/execute, initialization, overlay, address space, and image base are direct Ghidra observations.                                                                                                                                            |
-| Inventory        | Procedure, symbol, and string listings plus searches return the complete matching collection in one response; callers do not provide offsets or result-count limits.                                                                                                                            |
-| Search           | Literal and Java-regex searches scan the complete immutable inventory and return all matching entries inline. Search waits for a reply or caller cancellation; there are no caller-supplied offsets or result-count limits.                                                                     |
-| Analysis state   | The socket is exposed only after default auto-analysis completes. Established operations wait for their reply or caller cancellation; there is no fixed response-size ceiling.                                                                                                                  |
-
-## Admitted function-analysis semantics
-
-| Concern                 | Ghidra contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Decompiler lifetime     | One persistent `DecompInterface` is opened for the imported Program and disposed during bridge shutdown. Native decompilation has no fixed per-function deadline. External functions or functions without bodies return `null`; cancellation and native failure remain distinct.                                                                                                                                                                                                                                                                                                                                           |
-| Serialization           | A FIFO sends one Program request at a time. Caller cancellation removes queued work promptly and is passed to active socket waits. This is an adapter safety commitment, not a claim that every Ghidra API is thread-safe.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Function identity       | Every function result carries the entry address and Ghidra FunctionManager classification for external, thunk, and resolved thunk target. These are observations, not proof that unresolved targetless calls have been recovered.                                                                                                                                                                                                                                                                                                                                                                                          |
-| Assembly and pseudocode | Assembly is complete Ghidra Listing text; pseudocode is Ghidra decompiler output. Neither is original source, and cross-provider comparison never treats Hopper and Ghidra text as equal or unequal semantic facts.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Instruction fast path   | `read_function_instructions` returns every raw Listing instruction for the requested function without invoking the decompiler or whole-program name/string inventories.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Calls and references    | Callers/callees contain only resolved functions. Reference edges preserve exact ReferenceManager type and call/jump/data/read/write/indirect/computed/conditional/terminal/external facts. Targetless computed flow remains unknown. Synthetic entry-point references without actionable memory sources are omitted explicitly.                                                                                                                                                                                                                                                                                            |
-| CFG                     | Dossiers use `BasicBlockModel` and retain only non-call successors inside the function body. CFG topology is address-normalized for comparison; provider-specific block construction remains a declared difference.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| P-code value flow       | Function dossiers include up to 3,000 high-p-code operations, at most 64 inputs per operation, and 12,000 def-use edges. Results identify memory reads/writes, branches, and calls by p-code opcode, and mark decompiler-dead operations. Large results report truncation, an omitted-operation lower bound, and known omitted-input/edge counts. The dossier is an intra-function graph; `trace_native_values` composes derived parameter/argument and return/output dependencies across resolved calls. It does not resolve memory aliasing, call side effects, runtime behavior, persistent state, or business meaning. |
-| Result extent           | Function instruction scans and native API boundary observations remain complete. P-code flow is the explicit bounded exception; its count fields distinguish exact retained counts from lower-bound or known-omitted counts. Caller cancellation and provider failures remain distinct.                                                                                                                                                                                                                                                                                                                                    |
-
-`npm run verify:ghidra` compiles the versioned C oracle into debug and stripped
-host-native targets (x86-64/AArch64 ELF on Linux or Mach-O on macOS), plus a native
-DWARF 4 type-layout object. It proves the admitted operations, external functions, resolved thunks, exports, stripped-name
-behavior, direct and targetless indirect calls, typed references, strings/xrefs,
-multi-block CFG, bounded p-code def-use/effect links, semantic enhanced workflows, cancellation, startup deadlines,
-serialized concurrency, malformed-target rejection, profile identity, and
-process/project cleanup against real Ghidra 12.1.4. Unit fixtures separately
-cover startup deadlines, process exit, queued cancellation, and malformed wire
-output.
-
-`npm run verify:ghidra:cross-format` adds AArch64 ELF, x86-64 PE, and x86-64
-Mach-O target coverage. It requires `clang`, LLD, and `lld-link`; set
-`REA_CLANG`, `REA_LLD`, or `REA_LLD_LINK` to select them. The verifier checks
-these tools before compilation. Keeping this matrix separate lets Linux
-host/provider acceptance run with only the host compiler.
-
-`npm run verify:ghidra:windows` and its `-- --x86` variant check the source-owned native x86 and x86-64 PE
-fixture, all 25 read-only operations, target/snapshot/import SHA-256 linkage,
-and project, endpoint, process, and runtime cleanup. The independent native
-lane checks DACLs, handle admission, cancellation, and Job Object lifecycle.
-`npm run verify:ghidra:windows:package` packs and installs REA into an isolated
-prefix, then checks ordinary-user CLI/MCP operations against canonical contracts.
-All lanes require matching native controls; package startup alone establishes
-only package compatibility.
-
-## Shared provider-process foundation
-
-`src/process/` now provides the mechanisms that a long-lived Hopper or Ghidra
-adapter shares: POSIX run-token-authenticated process-group ownership,
-ephemeral temporary runtime roots, one absolute startup deadline, correlated
-request cancellation and lifecycle-deadline cleanup, bounded stdout and stderr retention with
-exact byte counts, process-exit diagnostics, and bounded TERM-to-KILL shutdown.
-Reusable fixtures exercise exit, timeout, cancellation, graceful termination,
-forced termination, double-close, spawn failure, and resource release. Windows
-Ghidra uses its native Job Object, private runtime, and path-admission boundary;
-generic process-tree termination alone cannot establish provider availability.
-
-The foundation does not define a bridge schema, socket framing, health payload,
-analysis model, or shutdown acknowledgement. Hopper keeps its authenticated
-NDJSON-over-Unix-socket protocol in `src/hopper/`; Ghidra has a separate strict
-NDJSON protocol implemented by the packaged Java `HeadlessScript` and reuses
-only the generic process mechanisms.
-
-## Shortlist
-
-| Provider                                                                                    | License / automation surface                                                                                                                                           | What it brings                                                                                                                                          | REA fit and blockers                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Ghidra](https://github.com/NationalSecurityAgency/ghidra)                                  | Apache-2.0 source license; `analyzeHeadless`, Java APIs, and PyGhidra                                                                                                  | Static analysis, multiple processors and formats, scripting, and project/database workflows                                                             | 25 read-only operations shipped on Linux/macOS with installation checks, temporary projects, a serial API queue, and real ELF/PE/Mach-O conformance. Experimental Windows x64 P0 supports native x86 and x86-64 PE on local NTFS with bundled native controls and ordinary-user CLI/MCP verification; Linux/macOS additionally support atomic session function annotations; Windows mutation and all Ghidra GUI operations are unavailable. |
-| [Rizin](https://github.com/rizinorg/rizin) / [rz-pipe](https://github.com/rizinorg/rz-pipe) | Rizin repository contains LGPL-3.0 and GPL-3.0 components; `rizin`, `rz-bin`, and language bridges through `rzpipe`                                                    | Portable CLI analysis, disassembly/debugging, many architectures and file formats, JSON command output                                                  | Good candidate for a process-backed Linux provider and fast metadata fallback. License/component inventory must be preserved; command output needs version-pinned parsers and semantic conformance before evidence is trusted.                                                                                                                                                                                                              |
-| [LIEF](https://github.com/lief-project/LIEF)                                                | Apache-2.0; C++, Python, and other bindings                                                                                                                            | Deterministic parsing and modification of ELF, PE, Mach-O, COFF, and related executable formats; headers, sections, symbols, relocations, and functions | Best near-term complement, not a decompiler replacement. It can cover format metadata and artifact evidence without a long-lived analysis process; function semantics, pseudocode, CFG, and cross-reference parity remain out of scope unless separately demonstrated.                                                                                                                                                                      |
-| [Binary Ninja](https://docs.binary.ninja/dev/index.html)                                    | API/documentation components are MIT, while the analysis product is licensed by edition; commercial, Ultimate, or Headless license is required for headless automation | Python/Core/C++/Rust APIs, headless loading, IL layers, function analysis, plugins, and configurable analysis                                           | Strong technical fit for a native provider, especially function dossiers. Commercial licensing, license-secret handling, native runtime packaging, and multithreaded lifecycle rules are material deployment blockers.                                                                                                                                                                                                                      |
-
-## Recommended order
-
-1. Use the implemented explicit provider registry and target binding without
-   changing Hopper behavior.
-2. Maintain the admitted Ghidra function boundary through the shared
-   conformance corpus and add formats or semantics only after real proof.
-3. Connect Electron/native-add-on application findings to the selected native
-   analysis provider without introducing provider-prefixed tools.
-4. Evaluate LIEF or Rizin later as complementary metadata/disassembly providers,
-   and Binary Ninja as an optional licensed provider, using the same admission
-   gate.
-
-## Required admission gate
-
-Before implementation, an adapter proposal must provide:
-
-- a capability matrix covering supported, unsupported, and degraded results;
-- provider identity, version, analysis profile, target digest, authority,
-  limitations, and deterministic locations in every Evidence record;
-- bounded subprocess or library lifetime, cancellation, timeouts, and cleanup;
-- actionable local diagnostics that retain paths, digests, mismatch locations,
-  and provider metadata while redacting credentials, authorization headers,
-  license secrets, and other genuine secrets;
-- the same source-owned fixture corpus across architectures and formats;
-- repeatable checks for function identity, addresses, strings, names, xrefs,
-  CFG, and pseudocode wherever those capabilities are claimed.
-
-These gates turn the accepted direction into verified capabilities rather than
-prematurely claiming equivalence or redistribution support.
-
-## Primary-source notes
-
-- Ghidra 12.1.4 documents headless batch mode and its Java runtime requirements
-  in its [release-specific Getting Started guide](https://github.com/NationalSecurityAgency/ghidra/blob/Ghidra_12.1.4_build/GhidraDocs/GettingStarted.md);
-  the [official release](https://github.com/NationalSecurityAgency/ghidra/releases/tag/Ghidra_12.1.4_build)
-  supplies the corresponding distribution and checksums.
-- Rizin lists supported formats, architectures, tools, and `rzpipe` bridges in
-  its [repository README](https://github.com/rizinorg/rizin); `rz-pipe` documents
-  JSON command transport and pipe backends.
-- LIEF's [format tutorial](https://lief.re/doc/stable/tutorials/01_play_with_formats.html)
-  and [Python API](https://lief.re/doc/latest/api/binary_abstraction/python.html)
-  document parsing and format-agnostic binary access.
-- Binary Ninja documents its [headless automation model](https://docs.binary.ninja/dev/batch.html),
-  [edition licenses](https://docs.binary.ninja/about/license.html), and the
-  [MIT license for API/documentation components](https://docs.binary.ninja/about/open-source.html).

docs/roadmap.md

@@ -1,125 +1,35 @@
 # REA roadmap
 
-## Tool direction
+The [platform tracker](https://github.com/morluto/rea/issues/32),
+[process/Hopper tracker](https://github.com/morluto/rea/issues/48), and
+[browser tracker](https://github.com/morluto/rea/issues/39) track capability and
+verification work. Available tools and setup are documented in the
+[investigation guides](https://rea.tools/guides/),
+[installation guide](installation.md), and
+[generated catalog](mcp-contracts.md#generated-catalog).
 
-REA provides inspection, capture, and comparison tools that return evidence
-directly. Agents choose commands, paths, browser actions, scripts, and local
-fixture servers, then compose experiments from those results. CLI and MCP must
-expose equivalent behavior and preserve observations, inferences, and unknowns.
+## Priorities
 
-[#555](https://github.com/morluto/rea/pull/555) removed REA permission grants,
-scope ceilings, elicitation, and repeated approval fields.
-[#572](https://github.com/morluto/rea/pull/572) removed the replay engines,
-Node characterization prepare/execute flow, and plan-only managed runtime
-correlation tool. Those systems are retired roadmap items. Existing evidence
-authority labels remain readable as provenance; they do not imply a current
-replay executor.
+- Expand native architecture, type, and indirect-call verification.
+- Connect static findings and runtime observations across application layers.
+- Improve obfuscated managed-code comparisons and verified native links.
+- Extend process, protocol, filesystem, reconnect, and build-comparison coverage.
+- Evaluate additional providers and targets when an analyst workflow demonstrates
+  a capability gap.
 
-Local operations use the current user's OS permissions. Input and protocol
-validation, provider prerequisites, target identity, cancellation, and owned
-resource cleanup remain part of each tool's contract. Setup still discloses
-installation changes and requires approval before writing or installing.
+## Admission criteria
 
-## Planned work
+New capabilities must return useful evidence through shared CLI/MCP workflows,
+preserve observations and unknowns, and declare actual authority and lifecycle
+constraints. Agents compose experiments using ordinary commands, scripts, and
+fixture servers; custom orchestration needs a demonstrated requirement.
 
-The [website guides](https://rea.tools/guides/) and
-[generated catalog](product-catalog.json) describe available workflows.
-Current development priorities are:
+Provider and platform claims require their corresponding
+[real verification lanes](testing.md#real-toolchain-verification-lanes).
+See [tool design](tool-design.md) for choosing a tool boundary and
+[Ghidra semantics](ghidra-provider.md) for the existing deep-provider contract.
 
-- Keep generated metadata and narrative documentation aligned with tools,
-  providers, setup options and releases.
-- Expand native architecture, type and indirect-call verification across
-  Hopper and Ghidra.
-- Connect additional static extractors and runtime observations to
-  cross-layer feature traces.
-- Improve obfuscated .NET comparisons and links between managed findings
-  and verified native analysis.
-- Extend process, protocol, filesystem, reconnect and build-comparison
-  coverage, plus browser and Electron scenario actions.
-- Evaluate native runtime observation through LLDB, Frida, system logs and
-  API tracing, and additional tools and targets such as Binary Ninja, Rizin,
-  LIEF, Windows-native workflows, mobile applications and firmware.
-
-Provider additions and platform support require the corresponding real
-verification lanes; see [testing](testing.md) and
-[provider evaluation](provider-evaluation.md).
-
-## Remaining evidence and provider work
-
-The [platform roadmap](https://github.com/morluto/rea/issues/32),
-[process and Hopper fidelity tracker](https://github.com/morluto/rea/issues/48),
-and [browser tracker](https://github.com/morluto/rea/issues/39) track remaining
-capabilities and proof. Their scope follows direct tools and agent-composed
-experiments; custom replay languages and grant systems are not completion gates.
-
-[Inline Evidence composition](https://github.com/morluto/rea/pull/585) now returns
-the complete record accepted by comparison tools. Managed inspection uses an
-explicit PE/CLI target independently of the native provider selection. Comparisons
-preserve unknowns when observation is incomplete, and PTY diagnostics retain the
-actual loader or startup failure. Browser cleanup reports incomplete teardown
-alongside the primary failure; transient documents invalidate only the affected
-frame's WebMCP registrations. Real-provider and platform claims still require
-their corresponding verification lanes.
-
-## Shipped behavior
-
-REA setup lets you select agent integration and optional Hopper installation.
-It installs the bundled workflow, configures detected agents, and can save
-verified paths for an existing Ghidra installation. It configures Claude Code,
-Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, Devin, OpenCode, Antigravity,
-GitHub Copilot CLI, Command Code, VS Code, and Grok Build using each client's configuration format. Grok Bot is detected locally, but its connector is added from the Grok Bot chat because the signed-in account store is not a data-directory file.
-
-Ghidra analysis supports Linux x64/arm64 and macOS x64/arm64 with Ghidra 12.1.x and the
-64-bit full JDK that installation declares. 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.
-Each installation requires the matching native decompiler. The
-adapter exposes thirteen inventory operations and twelve function-analysis
-operations, for 25 read-only operations total. Linux and macOS additionally support
-atomic function-name and entry-comment edits with refreshed analysis; metadata
-is discarded on close and executable bytes stay unchanged. Approved setup saves verified
-installation paths in agent configurations without installing or changing
-Ghidra or Java.
-
-Real-provider verification uses host-native debug and stripped fixtures plus
-a native type-layout object. A separate lane covers AArch64 ELF, PE, and
-Mach-O cross-target fixtures. See [testing](testing.md) for the prerequisites
-and exact commands.
-
-Experimental Windows x64 P0 now supplies bundled Job Object ownership,
-protected runtime DACLs, and handle-based admission for native x86 and x86-64 PE
-applications on local NTFS. Real ordinary-user CLI/MCP verification covers
-all 25 read-only operations and cleanup. The [Windows P0 guide](windows-ghidra-p0.md)
-describes this boundary and unverified broader coverage.
-
-## Ghidra maintenance boundary
-
-Extend formats or semantics only with normalized provider-neutral contracts and
-real source-owned conformance. Hopper and Ghidra pseudocode or assembly text is
-not expected to match; unresolved targetless flow remains unknown. Automatic
-Ghidra acquisition, if ever added, remains a separately planned and approved
-related-tool change; setup must never install Java.
-
-Maintain Windows P0 with independent DACL readback, handle-based admission,
-private authenticated IPC, and Job Object assignment before provider execution.
-Process capture, Hopper, and broad filesystem-sensitive workflows remain
-separate Windows projects; P0 does not imply their parity.
-
-## Capability-selective setup
-
-Setup already lets users select agent integration and Hopper installation.
-Once REA supports installing additional analysis tools, it can expand these
-choices to match the work a user wants to do. It may ask whether the operator wants to investigate
-native binaries, websites, mobile applications, firmware, or runtime protocols,
-then propose only the tools needed for the selected work.
-
-That future installer must preserve the current safety boundary:
-
-- detect and reuse existing tools;
-- disclose every source, destination, license, command, and system effect;
-- prefer user-local installation;
-- install only explicitly selected toolchains;
-- require tool-specific authorization for unattended system changes;
-- verify each installed tool before reporting readiness.
-
-No placeholder tool choices or speculative installer registry are implemented
-until another supported toolchain makes the abstraction concrete.
+Setup remains additive, reuses existing tools, and requires approval for disclosed
+configuration and Hopper installation changes. Additional installer choices need
+an implemented toolchain and explicit scope; setup does not install or upgrade
+unrelated runtimes or dependencies.

docs/testing.md

@@ -1,76 +1,36 @@
 # Testing REA
 
-Prefer evidence in this order: full end-to-end workflows through the public
-CLI or MCP with real production providers and no mocked dependencies,
-integration across production data/API boundaries, then golden regressions
-from real captured inputs. Keep a focused module test only for a distinct
-failure or semantic case that stronger workflows cannot reliably reproduce.
-A test's path, compiled imports, or suite name does not establish its depth.
+Use this guide when choosing coverage, pruning tests, or running a verification
+lane. For commands, jump to [developer commands](#developer-commands); for engine
+prerequisites, use [real-toolchain lanes](#real-toolchain-verification-lanes).
 
-Delete tests that only mirror getters, serialization helpers, enum mappings,
-fixture helpers, prescribed call sequences, arbitrary counts or snapshots,
-or cache object identity without a caller-visible contract. Do not retain a
-weaker test merely because it is fast when a stronger workflow already proves
-the same claim. Keep format-specific malformed representations and actual
-capacity, cleanup, permission and target-identity regressions.
-Prefer representative workflows over a Cartesian matrix when rows cross the
-same boundary. Retain combinations that exercise a distinct interaction, such as
-filtering within a full-output envelope. Keep distinct command handlers,
-producer representations, failure reasons, and lifecycle states covered.
-Consolidate their shared setup without hiding the inputs or expected evidence.
+Prefer real public CLI/MCP workflows, then production-boundary integration,
+then goldens captured from real producers. Keep module tests for distinct
+failures or semantics that stronger workflows cannot reliably reproduce.
+Paths, compiled imports, and suite names do not establish test depth.
 
-Tests are grouped into Vitest projects so ownership, allowed dependencies and
-runtime cost are visible from their paths. Before pruning a distinct boundary
-regression, identify the replacement scenario and its assertions; passing
-success journeys do not replace malformed input, cancellation, permission or
-cleanup coverage. Trivial helper checks do not need a replacement. If only
-tests consume a production module, trace CLI/MCP and verifier imports,
-including imports of compiled files, and remove abandoned scaffolding with its
-tests when it has no runtime consumer.
+Prune tests that mirror implementation details or duplicate a stronger claim.
+Before deleting a distinct regression, identify the replacement scenario and
+assertions. Preserve malformed formats, cancellation, cleanup, permissions,
+capacity, target identity, and combinations with distinct interactions.
+Trivial helper assertions need no replacement. Remove abandoned production
+scaffolding only after checking runtime and verifier consumers, including
+compiled imports.
 
-When a test expects a `Result` to succeed, throw its error before asserting the
-returned value. An `.ok` assertion immediately before the same throwing guard
-adds no coverage and hides the typed failure. A removed parser matrix can leave
-one golden malformed-input case and a real filesystem lifecycle that proves
-configure, update, readback, and removal; an add-only journey does not cover the
-whole lifecycle.
+Use representative scenarios rather than Cartesian matrices of equivalent
+cases. Share setup without hiding inputs or expected evidence. For successful
+`Result` values, throw the typed error before asserting the value; a preceding
+`.ok` assertion adds no coverage. Protocol fixtures must reject unmodeled
+commands and preserve actual producer reply shapes.
 
-Protocol fixtures must model the commands they support and their producer reply
-shapes. Reject unmodeled commands instead of returning a generic success; an
-empty result is appropriate only for a supported command with no result fields.
+Report unavailable authority as a named skip. Await owned cleanup before a
+verifier reports success. Native process inspectors are released at Vitest
+worker teardown; fork termination does not run Node exit hooks, and per-file
+teardown would retire inspectors still needed by other files.
 
-Keep transport-only in-memory MCP sessions in the MCP boundary lane and direct
-filesystem workflows in the filesystem boundary lane. Real process-tree capture
-belongs in the serial process boundary lane, including captures invoked through
-MCP. Report unavailable capture authority as a named skip rather than returning
-from the test without assertions. Reserve acceptance paths for journeys
-through the compiled public CLI or MCP runtime. Calling a compiled private
-workflow or injecting a provider still establishes its narrower integration
-claim, even if a directory name calls it acceptance.
-
-Emit a verifier's final success report only after awaited cleanup. Observe final
-process lineage after closing its owned resources.
-
-Owned JavaScript semantic graphs capture and schema-parse caller input before
-returning an iterator. Whole-graph hashing, batched integrity checks and sealing
-run through the application cancellation driver; only full completion grants
-the private immutable-graph proof. Regression coverage checks canonical IDs,
-validation diagnostics, nested caller mutations across yields, cancellation
-before result validation and subsequent SDK requests. Single-file parsing,
-schema cloning and canonical sorting remain synchronous phases; measure them
-separately when assessing cancellation latency on real applications.
-
-The Vitest runner releases cached native process inspectors during awaited
-worker teardown. Fork termination does not run Node's normal exit hooks; a
-per-file teardown would instead retire shared inspectors before later files
-can use them.
-
-Measure slow files before removing capacity regressions. Optimize repeated
-process startup, fixture construction, and production algorithms when they
-dominate runtime. Keep at least one input beyond each formerly failing size or
-depth; smaller fixtures do not establish that truncation or stack exhaustion
-has been fixed. Record the toolchain, coverage mode, and cache conditions when
-comparing durations.
+Measure slow cases before pruning capacity coverage. Retain inputs beyond the
+formerly failing size/depth and distinguish cold runs, warm builds, coverage,
+and toolchain conditions when comparing timings.
 
 ## Behavioral depths
 
@@ -93,12 +53,6 @@ registries but do not cross production filesystem, process, socket, or browser b
 Boundary tests cross one production boundary. Only acceptance tests assemble
 the complete runtime or invoke the compiled product surface.
 
-Binary session, registry, lazy-client and snapshot module cases live under
-`src/application/binary/`. Their composition cases stay in
-`tests/composition/analysis-sessions/`; snapshot persistence and actual SDK calls
-stay in the filesystem and MCP boundary lanes. The shared injected session fixture
-serves several capabilities and remains under `tests/fixtures/`.
-
 Focused immutable builders and recording ports shared by one test family live
 beside their production owner as `src/**/*.fixture.ts`. They are typechecked
 with the suite and excluded from package builds; broader runtime and provider
@@ -165,29 +119,6 @@ an empty versioned scan or a suffix that only repeats the original path.
 
 It runs in macOS CI.
 
-Apple artifact verifiers live in `scripts/verify/apple/`, with the macOS bundle
-builder under `scripts/fixtures/apple/` and NIB byte fixtures beside the decoder
-in `src/artifacts/apple/`. The npm entrypoints are unchanged. Format-specific
-Swift/XIB/asset sources and goldens retain their locations; real Apple workflows
-resolve them from the verifier file URL and run in the macOS CI lane.
-
-Portable native semantics and their tests live in `src/domain/native/`; shared
-analyst workflows and service-lane tests live in `src/application/native/`.
-Named native contracts live in `src/contracts/native/`. Provider protocol and
-host UI tests retain their adapter/boundary lanes, and real verifier command
-names remain unchanged.
-The existing Apple CI job also runs the host Swift-demangling CLI/MCP regression
-suites, including option-like symbols, carriage returns and multiline rejection.
-
-Process semantics/tests live in `src/domain/process/`; PTY capture implementation
-and forked helper tests live in `src/process/capture/`. Evidence projection and
-file workflows live in `src/application/process/`; producer-backed Evidence/host
-cases run in the serial `tests/boundary/process/` lane. Installed-package probes
-load the compiled capture capability owner, including the missing-optional-module
-case. Real capture tests preserve actual descendant and cleanup checks.
-The existing Apple job also exercises the relocated filesystem snapshot identity,
-cancellation and descriptor cleanup regressions on macOS.
-
 Prepare the native inspector before cases that measure producer output or exit
 behavior; keep startup deadlines and cancellation in distinct cases. Run real
 process-capture verification separately from package or build checks. On macOS,
@@ -198,8 +129,7 @@ MCP SDK transport tests with recording providers remain integration tests.
 They are useful for schema drift and failure projection but do not prove that
 Hopper, Ghidra or another substituted engine works. `verify:package` proves
 packaging/install behavior and fake-provider integration; use the corresponding
-real-provider lanes for engine claims. Packed-bridge checks verify shipped files
-and Python syntax without deleted mock fixtures or source-spelling assertions.
+real-provider lanes for engine claims. Packed-bridge checks verify shipped files and Python syntax.
 Real Apple dispatch and Interface
 Builder verifiers currently prove format integration through production readers.
 
@@ -274,13 +204,18 @@ Do not call handcrafted utility output or synthetic binary builders real-data
 goldens. Keep unsupported binary layouts and malformed boundaries as targeted
 regressions until a real fixture establishes equivalent coverage.
 
-`verify:browser` exercises source-map failure isolation and expanded-output limits through the compiled CLI and stdio MCP with real Chrome. It also submits five 2 MiB source-map annotations, checks retained script identities and explicit map omissions, and closes its owned fixture target. These public workflows replace redundant metadata-admission assertions; replacement and document-reset boundaries remain focused producer regressions.
+`verify:browser` exercises source-map failure isolation and expanded-output limits through the compiled CLI and stdio MCP with real Chrome. It also submits five 2 MiB source-map annotations, checks retained script identities and explicit map omissions, and closes its owned fixture target. Replacement and document-reset behavior has separate producer-boundary coverage.
 
 `verify:browser` also captures a source-owned noise canvas as a real PNG above
 8 MiB through the CLI and stdio MCP, with complete byte/digest parity and real PNG
 decoding. Its SDK client explicitly permits the larger inline JSON response;
 this lane does not establish large image-comparison request transport coverage.
 
+The scenario checks read locale, timezone, device scale and viewport dimensions
+from actual page JavaScript through CLI and stdio MCP DOM captures. They also
+verify that attached-page emulation is released after success, initialization
+failure, action failure and cancellation while the external target stays open.
+
 `verify:browser:network` is a focused real-browser lane for transaction identity,
 selected request/response bytes, binary and compressed responses, duplicate
 headers, credential and declared-secret redaction, redirects, streaming cutoff,
@@ -394,9 +329,7 @@ Instruction inspection and containing-function lookup also agree across
 hexadecimal case, leading zeros, and encoded default address-space spellings.
 The same source-acquisition workflow exercises missing and directory-replaced
 inputs, plus real read-permission denial on a non-root host. Root runs report
-that permission-denial check as unverified. A focused filesystem integration
-check retains selected-platform routing and exclusive creation; two copy/digest
-checks duplicated by the real workflow have been removed.
+that permission-denial check as unverified. Filesystem integration separately checks selected-platform routing and exclusive creation.
 Namespace annotation probes compile a separate host C fixture with C++ ABI
 symbols, avoiding a C++ runtime prerequisite. Real Ghidra demangling supplies
 duplicate leaf names in two top-level namespaces and a nested namespace. The
@@ -411,8 +344,7 @@ Successful-result and oversized-error delivery constraints must identify their
 successfully retained Evidence records;
 export must recover every source byte, complete annotation and original error
 diagnostic, with CLI parity
-and an unchanged executable. The focused formatter check retains only the
-separate case where recording was not acknowledged.
+and an unchanged executable. Formatter integration separately checks unacknowledged Evidence recording.
 Long ordinary procedure names and encoded address-space selectors must produce
 normal validation errors without exhausting Java's regex stack or losing the
 private bridge connection. Each rejection is followed by a real provider lookup;
@@ -452,14 +384,9 @@ the CLI and stdio MCP, including special filenames, unresolved discovery
 locations, and independently resolved loaded scripts. Double-quote filenames
 are tested on POSIX only because Windows does not support them.
 
-Inspector adapters live in `src/inspector/`, with loopback fixtures under
-`tests/fixtures/inspector/` and forked producer boundaries under
-`tests/boundary/inspector/`. The real lane is owned by
-`scripts/verify/inspector/runtime-observation.mjs` and
-`tests/conformance/inspector/`. Browser and Inspector deliberately share the
-existing browser CDP transport/value and file-location helpers. Node fixture
-success proves this Inspector workflow on the tested host; it does not prove
-Electron GUI behavior or another engine.
+Node Inspector verification does not establish Electron GUI or other engine
+behavior. Browser and Inspector share CDP transport/value and file-location
+helpers; their producer workflows remain distinct.
 
 ## Android APK analysis
 
@@ -481,14 +408,6 @@ See [Android analysis](android-analysis.md) for boundaries and resource budgets.
 Authenticated IPA and macOS application inventory projection is documented in
 [Apple application analysis](apple-application-analysis.md).
 
-The lane and owned-process cancellation helper live in `scripts/verify/android/`.
-The explicit downloader and fixed manifest live in `scripts/fixtures/android/`;
-their default remains repository-root `_reference/apk-integration/`. Producer
-fixtures live in `tests/fixtures/android/`, boundary cases in
-`tests/boundary/android/`, and inventory projection composition cases in
-`tests/composition/android/`. Real engine success and synthetic protocol success
-are separate proof levels.
-
 Synthetic producer regressions run independently:
 
 ```sh
@@ -593,6 +512,17 @@ not make native host acceptance unavailable.
 
 ## Native platform baseline in CI
 
+Pull requests that change only root `README*.md` files, `docs/`, `AGENTS.md`,
+or `CONTRIBUTING.md` run formatting and generated-document validation without
+the source-test shards or native package lanes. Classification compares the PR
+head with its merge base, so later base-branch changes do not expand that scope.
+The required static and coverage aggregate jobs remain present and fail if
+classification fails. Mixed changes, unknown paths and CI configuration changes
+retain full checks. Main pushes retain the full baseline, including after
+documentation merges; newer commits cancel superseded CI for the same PR or
+main branch. Release publication has its own concurrency group and retains its
+package verification and public-registry canary.
+
 CI exercises the pinned Node.js runtime on native hosted runners:
 
 | Host                  | Runner             | Baseline checks                                                                          |
@@ -603,18 +533,14 @@ CI exercises the pinned Node.js runtime on native hosted runners:
 | macOS 15 x64          | `macos-15-intel`   | Installed package and real Node Inspector CLI/MCP                                        |
 | Windows x64           | `windows-latest`   | Curated capabilities, native controls, installed package and real Node Inspector CLI/MCP |
 
-Package and Inspector matrices assert the actual Node platform/architecture
-before verification and record those values with the Node version. Each matrix
+Package lanes assert the actual Node platform/architecture before verification
+and record those values with the Node version. The four-host package matrix
 runs at most two jobs concurrently with explicit timeouts and Node heap/thread
-limits. Package checks cover installation, CLI/MCP discovery, target-free
+limits; Windows retains its curated capability lane. Package checks cover
+installation, CLI/MCP discovery, target-free
 analysis, configuration backups/recovery, Evidence and owned lifecycle; Inspector
 checks execute source-owned loopback targets and special filename cases.
 
-macOS uses one OS version with one native baseline job per architecture. Each job
-runs package and Inspector checks after a single dependency installation. The
-separate Inspector matrix covers Linux and Windows; Apple artifact checks retain
-their own macOS 15 arm64 job for Xcode-dependent workflows.
-
 These native baseline checks complement the Linux source-test shards and the
 separate Apple-artifact and real-provider lanes. Actual Hopper, Ghidra, IDA,
 browser and managed-tool claims require their corresponding verification lanes.
@@ -684,23 +610,15 @@ broad changes or diagnosing CI, rather than after every edit. Package/install
 changes additionally need package verification; provider changes need actual
 provider evidence.
 
-Each Vitest project uses up to two workers, bounded by available host parallelism.
-Default-group projects can run together. Only `process-boundary` runs in the
-later sequence group and serializes its files because process-tree observations
-share host sampling resources. Tests that launch the real process harness belong
-in `tests/boundary/process/`, including CLI command and environment tests.
-Acceptance and process-global files retain isolated
-forks but are not serialized; isolation does not imply serial scheduling. CI uses
-the same per-project worker bound.
-The pure domain/contracts and recording-port service projects share one worker
-module context because their tests own no mutable runtime resources. MCP
-boundary files also share the immutable server module graph while creating and
-closing independent in-memory sessions. Adapter, composition, acceptance,
-process-global, and other boundary projects retain per-file isolation.
-Build and documentation writers use checkout-local locks for their respective
-output files. `npm test` delegates its build to the build lock; the Vitest suite
-does not hold a test-command lock. `check:pr` runs its test task before starting
-generated-document validation.
+Vitest projects use up to two workers, bounded by host parallelism.
+`process-boundary` runs later with serial files because process-tree sampling
+shares host resources. Acceptance and process-global cases use isolated forks
+without serial scheduling. Pure domain/service and MCP boundary projects share
+immutable module graphs; each MCP session still owns its resources. Other
+projects retain per-file isolation. See `vitest.config.ts` for current settings.
+
+Build/documentation writers hold checkout-local output locks. Tests do not
+hold a broad command lock; `check:pr` finishes tests before document validation.
 
 Vitest and Node persistent compile caches are deliberately not enabled by
 default. To evaluate repeated local runs, opt in for both cold and warm
@@ -716,13 +634,9 @@ instrumentation remains equivalent.
 
 ## Coverage and timing
 
-CI owns coverage. The aggregate floors are 65% statements, 60% branches, 60%
-functions, and 68% lines. `src/domain/**` must reach 80% statements, 75%
-branches, 75% functions, and 80% lines. `src/contracts/**` must reach 85%
-statements, 80% branches, 80% functions, and 85% lines. Thresholds are
-glob-specific rather than per-file and are never updated automatically.
-Coverage does not replace named boundary, acceptance, or real-provider scenario
-matrices.
+CI owns coverage; aggregate and domain/contract thresholds are maintained in
+`vitest.config.ts`. They are glob-specific and never updated automatically.
+Coverage does not replace named boundary or real-provider scenarios.
 
 CI runs four native Vitest shards without retries. Each shard emits a blob
 report; the merge job produces aggregate coverage plus JUnit and JSON timing
@@ -796,12 +710,6 @@ unknown chunks, depth limits and extracted child digests. The optional
 Neither optional toolchain is a base-lane prerequisite. See
 [firmware analysis](firmware-analysis.md) for limits and unverified formats.
 
-The real entrypoint is `scripts/verify/firmware/analysis.mjs`; the fixture runner
-and unchanged Python producer belong together in `scripts/fixtures/firmware/`.
-Producer fixtures and boundaries remain in `tests/fixtures/firmware/` and
-`tests/boundary/firmware/`. Source-fixture generation proves the runner and
-independent oracle; actual Binwalk/Unblob CLI/MCP proof requires selected tools.
-
 ### JavaScript source recovery
 
 Build once with `npm run build:cached`, then run `npm run verify:javascript:recovery`.

docs/tool-design.md

@@ -1,106 +1,87 @@
 # MCP tool design
 
-Design tools around analyst tasks. A provider API is an implementation detail;
-expose it directly when it gives agents a useful, reusable capability that
-cannot be expressed through an existing contract. Do not impose caller-facing
-limits merely to make work fit an assumed agent budget. Keep real input-format,
-protocol, authority, and resource-safety constraints, and report their effects.
-
-## Choose the tool shape
-
-| Shape                 | Use it for                                                           | Contract should return                                                                                         |
-| --------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `inspect`             | Facts about one explicit target, address, object, or resource        | Relevant fields, source locations, and facet-level availability                                                |
-| `search` / `list`     | Finding candidate targets or entities                                | Stable ordering and useful result context; expose pagination when the result format or caller's query needs it |
-| `trace`               | Relationships across code, metadata, UI resources, or observations   | Typed edges, supporting evidence, and unresolved paths; identify any genuine traversal boundary                |
-| `compare`             | Two explicitly identified artifacts, versions, or evidence sets      | Paired identity, comparable coverage, and deltas with evidence                                                 |
-| `workflow`            | A distinct analyst outcome that benefits from composition inside REA | A useful inline result, contributing evidence, and partial/unavailable facets                                  |
-| `observe` / `capture` | A question that requires runtime behavior                            | Required authority, launch/attach behavior, real operational constraints, lifecycle, and cleanup status        |
-
-These are task shapes, not required prefixes. Name a tool for the action and
-object agents reason about; keep the name distinct from nearby alternatives.
-
-## Prefer primitives; compose workflows
-
-Start with a primitive when one call can report a reusable fact about one
-identified object or relationship, such as an instruction decode, a type
-layout, a reference, a dispatch target, or a resource graph. The same primitive
-should be useful across different applications or analyst questions. A
-format-specific decoder can still be a primitive when it describes a reusable
-format rather than one application's product behavior.
-
-Add a workflow when repeated analysis shows that callers need the same
-multi-source result and REA can join the evidence without hiding important
-choices or uncertainty. A useful check is whether the workflow remains
-meaningful for different applications that share the relevant evidence types.
-If its purpose depends on one application's business rules or product concepts,
-keep that interpretation outside the general tool contract and expose the
-underlying evidence through reusable primitives.
-
 ## Decide whether to add a tool
 
-1. State the user intent and the smallest result that answers it.
-2. Inspect the canonical tool contracts, current provider capabilities, and
-   representative CLI/MCP traces. Record the nearest competing tool.
-3. Extend an existing contract when the intent and result are the same. Add a
-   batch or composed workflow when it materially improves a demonstrated task;
-   do not force agents through extra calls or collapse distinct tasks into one
-   tool. Add a tool when it answers a distinct analyst question or has a
-   materially different authority or result contract.
-4. Keep public tool names and result semantics provider-neutral. Put engine-
-   specific parsing and protocol handling in adapters. Advertise exact support
-   per provider; do not create parallel tools just because engines differ.
-5. Keep prompts optional and concise. They may point out useful tools, but must
-   not prescribe a call sequence when the task can be answered directly.
+Design around the analyst question. Inspect the current canonical contracts,
+provider capabilities, and nearest existing tool before changing the surface.
+Extend a tool when intent and result contract match; add one for a distinct
+outcome or materially different authority. Public names and semantics remain
+provider-neutral, with exact coverage reported per provider.
 
-Avoid opaque mode flags and mega-tools that combine unrelated discovery,
-execution, and mutation. Prefer a useful direct tool call over a tool sequence
-or model-authored loop when one call can answer the question.
+Keep the catalog complete; report capability/session availability instead of
+truncating schemas. Serialized bytes alone do not establish agent usability.
+
+## Choose the tool shape
+
+| Shape                 | Use it for                                  | Result                                                                    |
+| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
+| `inspect`             | Facts about one target, object, or resource | Relevant fields, locations, and facet availability                        |
+| `search` / `list`     | Candidate discovery                         | Stable ordering and context; pagination when the query or format needs it |
+| `trace`               | Relationships across evidence               | Typed edges, supporting facts, and unresolved paths                       |
+| `compare`             | Explicitly paired artifacts or observations | Identity, comparable coverage, and supported deltas                       |
+| `workflow`            | A recurring outcome needing composition     | Inline answer, contributing evidence, and partial facets                  |
+| `observe` / `capture` | Runtime behavior                            | Authority, launch/attach effects, lifecycle, and cleanup status           |
+
+These are task shapes, not mandatory prefixes. Name tools for the action and
+object callers reason about. Avoid unrelated discovery/execution/mutation modes
+inside one tool.
+
+## Prefer primitives; compose workflows
+
+A primitive reports a reusable fact about an identified object or relationship.
+A format-specific decoder qualifies; one application's business interpretation
+belongs outside the general contract. Expose provider APIs when they add a
+useful capability that existing tools cannot express.
+
+Compose a workflow when repeated use demonstrates a multi-source outcome REA
+can join without hiding caller choices or uncertainty. Batch homogeneous reads
+when that removes repeated work while preserving per-item outcomes. Keep prompts
+optional and avoid prescribing call sequences that a direct tool can replace.
+
+Agents can compose experiments with ordinary commands, scripts, and local
+fixture servers. Custom orchestration languages, replay engines, or separate
+prepare/execute plans need an observed requirement those primitives cannot
+satisfy. A plan without execution does not establish runtime behavior.
 
 ## Define the contract
 
-- Use strict object inputs with explicit required fields and enums. Add numeric
-  bounds only when the format, protocol, authority, or a measured resource
-  constraint requires them.
-- Return complete results by default. Make real pagination, truncation, partial
-  failure, cancellation, and unavailable states explicit. Missing evidence is
-  unknown, not empty or false.
-- Return task-oriented results inline with artifact identity, provider/version,
-  addresses or resource paths, Evidence references, confidence, and relevant
-  limitations. Do not require agents to fetch a resource or dereference an
-  opaque Evidence link to understand a tool result.
-- Separate observed facts from derived and inferred edges. Cite the evidence
-  supporting every important relationship; preserve unresolved edges.
-- Declare read-only, mutation, process, filesystem, network, and UI effects
-  truthfully in the contract and enforce the target and lifecycle named in the
-  request.
-- Keep provider-specific types out of provider-neutral domain and application
-  layers. Normalize supported provider results without implying equal coverage.
+- Use strict inputs with explicit target identity and required fields. Preserve
+  meaningful target, action, capture, and output choices; remove ignored options
+  and repeated permission declarations.
+- Return complete evidence inline, with artifact/provider identity, source
+  locations, Evidence references, and relevant confidence and limitations.
+  Missing coverage is unknown, not absence. Avoid extra lookups solely to
+  understand the answer or its provenance.
+- Keep observed, derived, and inferred relationships distinct. Preserve
+  unresolved edges and partial provider facts instead of requiring every
+  provider to supply the same metadata.
+- Declare process, filesystem, network, UI, and mutation effects truthfully;
+  enforce the requested target and lifecycle.
+- Add limits only for real format, protocol, authority, or measured resource
+  constraints. Report pagination, truncation, cancellation, and partial failure.
+  An assumed agent budget is insufficient justification for a limit.
 
 ## Implement and evaluate
 
-- Put shared user workflows in the application layer; keep MCP translation in
-  the server adapter and CLI behavior aligned with the same workflow. Share
-  Evidence provenance, unknown projection, and eligible snapshot binding through
-  application/session owners. Matching result payloads alone do not establish
-  equivalent retention or replay behavior.
-- Derive each facet's coverage from examined records, unsupported representations,
-  and exhaustiveness. Keep issues structured until presentation; do not select a
-  facet by matching diagnostic prose or infer completeness from an empty failure
-  list. Preserve available observations independently of cleanup success.
-- Measure the resource consumed before choosing a limit. Value alternatives,
-  retained records, trace-frame products, output bytes, and temporary-file growth
-  need different accounting. Enforce a justified budget before the costly step
-  and report its effect; an input-byte or graph-node cap does not bound every stage.
-- Update the canonical contract inventory, output schemas, examples, generated
-  catalog, and relevant docs together.
-- Verify valid, malformed, boundary, unavailable, cancellation, and partial
-  results at the owning boundaries. Use real-provider checks for claims that
-  depend on external analysis engines.
-- Evaluate representative broad and direct task prompts on the intended MCP
-  host when tool selection is the question. Record the host, model-facing tool
-  catalog, selected tool, arguments, errors, retries, and task outcome.
-  Schema validity or word-overlap heuristics do not prove discoverability.
+Put provider protocols/parsing in adapters and shared CLI/MCP workflows in the
+application layer. Share Evidence provenance, unknown projection, and session
+retention semantics; matching payloads alone do not establish parity.
 
-See [mcp-contracts.md](mcp-contracts.md) for shipped runtime behavior and
-[testing.md](testing.md) for test boundaries and verification lanes.
+Measure the resource before choosing a budget and enforce it before the costly
+step. Account for value alternatives, trace-frame products, retained records,
+serialization expansion, and temporary-file growth separately. Derive facet
+completeness from examined records and exhaustiveness, rather than diagnostic
+prose or an empty failure list. Preserve observations independently of cleanup
+success.
+
+Update canonical contracts, output schemas, examples, generated artifacts, and
+relevant docs together. Verify converted advertised schemas and success,
+malformed, unavailable, cancellation, and partial outcomes through affected
+consumers. Real-engine claims require the matching provider lane; see
+[testing.md](testing.md).
+
+When discoverability changes, evaluate representative broad, direct, and negative
+tasks on the intended host. Record host/model/catalog, selected tools, arguments,
+errors, retries, and task outcomes. Schema validity and keyword heuristics do not
+establish successful tool selection. See [mcp-contracts.md](mcp-contracts.md) for
+shipped runtime behavior.

docs/user-visible-errors.csv

@@ -56,7 +56,7 @@ harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implement
 46,src/application/Uninstall.ts:removeManagedPath symlink,Managed cache/state/skill path is a symbolic link,Refused to follow symlink {path}.,Exposes local path and does not explain manual safety check,"REA did not remove this item because its managed path is a symbolic link. Verify the link target before removing it manually.",implemented,focused assertion passed
 47,src/application/Uninstall.ts:removeManagedPath failure,Managed item removal fails,{path} could not be removed.,Exposes local path and gives no recovery,"This item could not be removed. Check file permissions, then rerun uninstall.",implemented,verified by injected managed-path removal failure test
 48,src/application/DoctorDiagnostics.ts:node,Runtime version is outside supported ranges,"Install Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+.",Low risk; exact dependency recovery,Keep current copy,unchanged,verified by doctor unit test
-49,src/application/Doctor.ts:host,Host OS/distribution is unsupported,"REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and CachyOS.",Low risk; clearly states supported choices,Keep current copy,unchanged,verified by doctor unit tests
+49,src/application/Doctor.ts:host,Host OS/distribution is unsupported,"REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, and CachyOS.",Low risk; clearly states supported choices,Keep current copy,unchanged,verified by doctor unit tests
 50,src/application/Doctor.ts:analysis engine,Optional deep-analysis executable cannot be found,"Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",Low risk in setup-specific diagnostic; exact recovery paths,Keep current copy,unchanged,verified by doctor unit tests
 51,src/application/Doctor.ts:target,Optional target path fails shared validation,Supply a readable local app or program path.,Low risk; tells caller valid target class,Keep current copy,unchanged,verified by doctor unit test
 52,src/application/Setup.ts:approval,Setup plan lacks approval,"Review the setup plan, then rerun interactively or with --yes.",Low risk; exact authorization recovery,Keep current copy,unchanged,verified by setup unit tests
@@ -67,7 +67,7 @@ harm_rank,location,trigger,current_copy,user_risk,proposed_replacement,implement
 57,src/application/Setup.ts:unsupported platform,Platform is neither macOS nor Linux,REA supports Hopper on macOS and selected 64-bit Linux distributions.,Low risk; states support boundary,Keep current copy,unchanged,verified by setup unit test
 58,src/application/SetupHost.ts:unsupported Node,Runtime version cannot run setup,"Install Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+ and rerun setup.",Low risk; exact dependency and retry,Keep current copy,unchanged,verified by setup host tests
 59,src/application/Setup.ts:unsupported macOS,macOS version is missing or older than 12,Upgrade to macOS 12 or newer.,Low risk; exact support floor,Keep current copy,unchanged,verified by setup host tests
-60,src/application/Setup.ts:unsupported Linux,Linux distribution is outside supported set,"REA supports Hopper on Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, and CachyOS.",Low risk; exact supported alternatives,Keep current copy,unchanged,verified by setup unit test
+60,src/application/Setup.ts:unsupported Linux,Linux distribution is outside supported set,"REA supports Hopper on Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, and CachyOS.",Low risk; exact supported alternatives,Keep current copy,unchanged,verified by setup unit test
 61,src/application/process/ProcessCli.ts:readJson read,Process scenario or evidence file cannot be read,Raw filesystem exception through CLI framework,Can expose local paths/codes and no recovery,"Process input file could not be read. Check that the path exists and is readable.",implemented,verified by focused CLI test
 62,src/application/process/ProcessCli.ts:readJson size,Process scenario or evidence file exceeds 64 MiB,Process JSON input exceeds byte limit,Does not state limit or recovery,"Process input file is too large. Reduce it below 64 MiB, then try again.",implemented,verified by focused sparse-file CLI test
 63,src/application/process/ProcessCli.ts:readJson parse,Process scenario or evidence file is malformed JSON,Raw JSON parser exception through CLI framework,Can expose parser implementation and lacks recovery,"Process input file is not valid JSON. Repair the file, then try again.",implemented,verified by focused CLI test

docs/website-script-export.md

@@ -12,6 +12,10 @@ For passive inspection, select `include_script_sources: true` (CLI:
 `capture.network.response_body: true`. Save either the complete Evidence record
 or its normalized result as UTF-8 JSON. MCP `structuredContent` contains the complete Evidence record.
 
+The capture must be a regular file. A symlink to a regular file is accepted;
+directories, named pipes and device files are rejected before reading capture
+bytes or creating output.
+
 ```sh
 rea export-web-scripts /analysis/capture.json /analysis/exported-scripts --json
 rea analyze-javascript-application /analysis/exported-scripts/files --json

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "rea-agents",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "rea-agents",
-      "version": "6.2.0",
+      "version": "6.3.0",
       "license": "MIT",
       "dependencies": {
         "@babel/parser": "8.0.4",
@@ -38,6 +38,7 @@
         "plist": "5.0.0",
         "semver": "7.8.5",
         "smol-toml": "1.9.0",
+        "stream-json": "3.7.0",
         "write-file-atomic": "7.0.0",
         "ws": "8.21.0",
         "zod": "4.4.3"
@@ -7070,6 +7071,27 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/stream-chain": {
+      "version": "4.2.6",
+      "resolved": "https://registry.npmjs.org/stream-chain/-/stream-chain-4.2.6.tgz",
+      "integrity": "sha512-1zeJ8CrtJfmiba26ui8jXkq/xLRFvhzkdH02D5QLO9Cnovgeb28IJxg88DdraWnjnkbOol/++uIAybJbJhk7ig==",
+      "license": "BSD-3-Clause",
+      "funding": {
+        "url": "https://github.com/sponsors/uhop"
+      }
+    },
+    "node_modules/stream-json": {
+      "version": "3.7.0",
+      "resolved": "https://registry.npmjs.org/stream-json/-/stream-json-3.7.0.tgz",
+      "integrity": "sha512-rCSBdcBP/bPk6T8QFcxAj1MSzAuc5i49cYW6IE7sYObNEPccBJIUiL6fU9c9BWt40aJK0siVynLX7lWaW8alXw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "stream-chain": "^4.2.5"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/uhop"
+      }
+    },
     "node_modules/string_decoder": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "rea-agents",
   "mcpName": "io.github.morluto/rea",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -88,7 +88,7 @@
     "prebuild": "npm run deps:check",
     "build": "node scripts/run-exclusive.mjs artifacts turbo run artifacts:skills --force",
     "precheck": "npm run deps:check",
-    "check": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check",
+    "check": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check && npm run verify:architecture-guards",
     "precheck:fast": "npm run deps:check",
     "check:fast": "turbo run typecheck lint --output-logs=errors-only",
     "precheck:changed": "npm run deps:check",
@@ -98,7 +98,7 @@
     "precheck:pr": "npm run deps:check",
     "check:pr": "node scripts/run-exclusive.mjs artifacts 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": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check jscpd scan:todos",
+    "check:ci": "node scripts/run-exclusive.mjs artifacts turbo run typecheck lint format:check knip metadata:check jscpd scan:todos && npm run verify:architecture-guards",
     "build:cached": "node scripts/check-dependency-install.mjs && node scripts/run-exclusive.mjs artifacts turbo run artifacts:skills",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
@@ -144,6 +144,8 @@
     "verify:native-ui": "npm run build:cached && node scripts/verify-native-ui.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:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs",
+    "verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",
     "verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs",
     "verify:ghidra:swift": "npm run build:cached && node scripts/verify-real-ghidra-swift.mjs",
     "verify:ida": "npm run build:cached && node scripts/verify-real-ida.mjs",
@@ -263,6 +265,7 @@
     "plist": "5.0.0",
     "semver": "7.8.5",
     "smol-toml": "1.9.0",
+    "stream-json": "3.7.0",
     "write-file-atomic": "7.0.0",
     "ws": "8.21.0",
     "zod": "4.4.3",

scripts/fixtures/browser-verifier-site.mjs

@@ -11,6 +11,30 @@ export async function startBrowserVerifierSite() {
       response.destroy();
       return;
     }
+    const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+    if (requestUrl.pathname === "/scenario-environment") {
+      const requestedRun = requestUrl.searchParams.get("run");
+      const run = ["A", "B", "C"].includes(requestedRun)
+        ? requestedRun
+        : "default";
+      response.setHeader("content-type", "text/html");
+      response.end(`<!doctype html><html><body data-run="${run}"><pre id="environment"></pre>
+        <button id="refresh-environment">Refresh environment</button><script>
+        const refresh = () => document.querySelector('#environment').textContent = JSON.stringify({
+          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+          locale: Intl.DateTimeFormat().resolvedOptions().locale,
+          dpr: devicePixelRatio, width: innerWidth, height: innerHeight
+        });
+        document.querySelector('#refresh-environment').onclick = refresh;
+        window.releaseScenario = () => {
+          const release = document.createElement('span');
+          release.id = 'release-' + document.body.dataset.run;
+          document.body.append(release);
+        };
+        refresh();
+      </script></body></html>`);
+      return;
+    }
     if (request.url === "/slow-json") {
       response.setHeader("content-type", "application/json");
       response.write('{"pending":');

scripts/fixtures/managed/function-dossier.mjs

@@ -0,0 +1,35 @@
+import { functionDossierSchema } from "../../../dist/domain/hopperValues.js";
+
+/** Validated synthetic native observations shared by managed verification lanes. */
+export const functionDossier = (name) =>
+  functionDossierSchema.parse({
+    procedure: {
+      address: "0x401000",
+      name,
+      classification: {
+        external: false,
+        thunk: false,
+        thunk_target: null,
+        provenance: "synthetic-provider",
+      },
+      body: {
+        available: false,
+        reason: "Synthetic provider does not supply function body ranges.",
+      },
+      signature: null,
+      locals: [],
+    },
+    pseudocode: "",
+    assembly: [],
+    comments: [],
+    callers: [],
+    callees: [],
+    incoming_references: [],
+    outgoing_references: [],
+    referenced_strings: [],
+    referenced_names: [],
+    basic_blocks: [],
+    native_api: null,
+    native_value_flow: null,
+    limitations: [],
+  });

scripts/generate-skill-metadata.mjs

@@ -16,8 +16,12 @@ const check = arguments_.has("--check");
 const current = (
   await readFile(join(sourceRoot, "SKILL.md"), "utf8")
 ).replaceAll("\r\n", "\n");
+const cacheBust = String(Date.now());
 const { CATALOG_IDENTITY } = await import(
-  `${pathToFileURL(join(root, "dist/catalogIdentity.js")).href}?${String(Date.now())}`
+  `${pathToFileURL(join(root, "dist/catalogIdentity.js")).href}?${cacheBust}`
+);
+const { PRODUCT_IDENTITY } = await import(
+  `${pathToFileURL(join(root, "dist/identity.js")).href}?${cacheBust}`
 );
 if (/^\s{2}(?:tool_count|catalog_digest):/mu.test(current))
   throw new Error(
@@ -26,10 +30,15 @@ if (/^\s{2}(?:tool_count|catalog_digest):/mu.test(current))
 const versionLine = /^ {2}version: "[^"\r\n]+"$/mu;
 if (!versionLine.test(current))
   throw new Error("Missing authored skill version");
-const source = current.replace(
-  versionLine,
-  `$&\n  tool_count: ${String(CATALOG_IDENTITY.counts.mcp_tools)}`,
-);
+// A shipped skill must run the version it ships with, not whatever `@latest` resolves to.
+const latestSpecifier = PRODUCT_IDENTITY.packageSpecifier;
+const pinnedSpecifier = PRODUCT_IDENTITY.registrationPackageSpecifier;
+const source = current
+  .replace(
+    versionLine,
+    `$&\n  tool_count: ${String(CATALOG_IDENTITY.counts.mcp_tools)}`,
+  )
+  .replaceAll(latestSpecifier, pinnedSpecifier);
 const paths = await filePaths(sourceRoot);
 // Rebuild this owned output directory so removed references cannot survive a build.
 if (!check) await rm(outputRoot, { recursive: true, force: true });

scripts/lib/browser-scenario-environment-e2e.mjs

@@ -0,0 +1,364 @@
+import assert from "node:assert/strict";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+
+import { CdpConnection } from "../../dist/browser/CdpConnection.js";
+import { createBrowserScenarioProvider } from "../../dist/composition/browserScenario.js";
+import { browserScenarioSchema } from "../../dist/domain/browserScenario.js";
+import { runScenarioCli } from "./browser-scenario-verifier.mjs";
+import { requireMcpEvidenceResult } from "./mcp-verifier-results.mjs";
+
+const expected = {
+  timezone: "Pacific/Honolulu",
+  locale: "fr-FR",
+  dpr: 2,
+  width: 900,
+  height: 600,
+};
+const alternate = {
+  timezone: "UTC",
+  locale: "en-US",
+  dpr: 1,
+  width: 700,
+  height: 500,
+};
+const expression = `JSON.stringify({
+  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  locale: Intl.DateTimeFormat().resolvedOptions().locale,
+  dpr: devicePixelRatio, width: innerWidth, height: innerHeight
+})`;
+
+const environmentScenario = ({ endpoint, targetId, origin, values, run }) =>
+  browserScenarioSchema.parse({
+    browser: { mode: "connect", cdp_endpoint: endpoint, target_id: targetId },
+    start_url: {
+      url: `${origin}/scenario-environment${run === undefined ? "" : `?run=${run}`}`,
+    },
+    environment: {
+      locale: values.locale,
+      timezone: values.timezone,
+      viewport: {
+        width: values.width,
+        height: values.height,
+        device_scale_factor: values.dpr,
+      },
+    },
+    actions:
+      run === undefined
+        ? [
+            {
+              step_id: "refresh",
+              action: "click",
+              locator: { kind: "css", selector: "#refresh-environment" },
+            },
+          ]
+        : [
+            {
+              step_id: `gate_${run}`,
+              action: "wait_for",
+              locator: { kind: "css", selector: `#release-${run}` },
+              state: "attached",
+              timeout_ms: 30_000,
+            },
+            {
+              step_id: `refresh_${run}`,
+              action: "click",
+              locator: { kind: "css", selector: "#refresh-environment" },
+            },
+          ],
+    capture: { after_each_step: ["dom"], at_end: ["dom"] },
+  });
+
+const assertCapture = (capture, values = expected) => {
+  assert.equal(capture.browser.cleanup, "disconnected-external");
+  for (const step of capture.steps) {
+    assert.equal(step.artifacts.dom.state, "captured");
+    const text = step.artifacts.dom.value.text;
+    const observed = /<pre id="environment">([^<]+)<\/pre>/u.exec(text);
+    assert.ok(observed, "DOM omitted the page's actual environment values");
+    assert.deepEqual(JSON.parse(observed[1]), values);
+  }
+};
+
+/** Verify actual attached-page emulation and restoration across scenario outcomes. */
+export async function verifyScenarioEnvironment(endpoint, targetId, origin) {
+  const targets = await (await fetch(`${endpoint}/json/list`)).json();
+  const target = targets.find(({ id }) => id === targetId);
+  assert.ok(target, "External fixture target is missing");
+  const connection = await CdpConnection.connect(
+    target.webSocketDebuggerUrl,
+    "capture_browser_scenario",
+  );
+  const readEnvironment = async () => {
+    const value = await connection.send("Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+    });
+    assert.equal(value.result.type, "string");
+    return JSON.parse(value.result.value);
+  };
+  const baseline = await readEnvironment();
+  const scenario = environmentScenario({
+    endpoint,
+    targetId,
+    origin,
+    values: expected,
+  });
+  const assertRestored = async () => {
+    assert.deepEqual(await readEnvironment(), baseline);
+    const remaining = await (await fetch(`${endpoint}/json/list`)).json();
+    assert.ok(remaining.some(({ id }) => id === targetId));
+  };
+  try {
+    assertCapture((await runScenarioCli(scenario)).normalized_result);
+    await assertRestored();
+    const transport = new StdioClientTransport({
+      command: process.execPath,
+      args: [fileURLToPath(new URL("../rea.mjs", import.meta.url)), "mcp"],
+      env: process.env,
+      stderr: "pipe",
+    });
+    const client = new Client({
+      name: "browser-environment-e2e",
+      version: "1",
+    });
+    try {
+      await client.connect(transport);
+      const definition = (await client.listTools()).tools.find(
+        ({ name }) => name === "capture_browser_scenario",
+      );
+      assert.ok(definition, "Scenario tool is absent from the current catalog");
+      assertCapture(
+        requireMcpEvidenceResult(
+          await client.callTool(
+            { name: "capture_browser_scenario", arguments: scenario },
+            { toolDefinition: definition },
+          ),
+          "capture_browser_scenario",
+        ),
+      );
+      await verifyConcurrentMcpCapture({
+        client,
+        definition,
+        connection,
+        endpoint,
+        targetId,
+        origin,
+        readEnvironment,
+        assertRestored,
+      });
+    } finally {
+      await client.close();
+      await transport.close();
+    }
+    await assertRestored();
+    const provider = createBrowserScenarioProvider(process.env);
+    const initializationFailure = await provider.captureScenario({
+      ...scenario,
+      environment: { ...scenario.environment, timezone: "REA/Invalid" },
+    });
+    assert.equal(initializationFailure.ok, false);
+    await assertRestored();
+    const waiting = browserScenarioSchema.parse({
+      ...scenario,
+      actions: [
+        {
+          step_id: "missing",
+          action: "wait_for",
+          locator: { kind: "css", selector: "#missing-environment-element" },
+          state: "visible",
+          timeout_ms: 100,
+        },
+      ],
+    });
+    const actionFailure = await provider.captureScenario(waiting);
+    assert.equal(actionFailure.ok, true);
+    assertCapture(actionFailure.value);
+    assert.equal(actionFailure.value.steps.at(-1).status, "failed");
+    await assertRestored();
+    await verifyCancelledEnvironment(
+      provider,
+      connection,
+      waiting,
+      readEnvironment,
+    );
+    await assertRestored();
+    return {
+      mocked: false,
+      cli: true,
+      stdio_mcp: true,
+      observed: expected,
+      restored: baseline,
+      initialization_failure_cleanup: true,
+      action_failure_cleanup: true,
+      cancellation_cleanup: true,
+      external_target_preserved: true,
+    };
+  } finally {
+    await connection.close();
+  }
+}
+
+const verifyConcurrentMcpCapture = async ({
+  client,
+  definition,
+  connection,
+  endpoint,
+  targetId,
+  origin,
+  readEnvironment,
+  assertRestored,
+}) => {
+  const firstScenario = environmentScenario({
+    endpoint,
+    targetId,
+    origin,
+    values: expected,
+    run: "A",
+  });
+  const secondScenario = environmentScenario({
+    endpoint,
+    targetId,
+    origin,
+    values: alternate,
+    run: "B",
+  });
+  const firstCancellation = new AbortController();
+  const secondCancellation = new AbortController();
+  const cancellation = new AbortController();
+  const pendingCalls = [];
+  const callTool = (arguments_, signal) => {
+    const pending = client.callTool(
+      { name: "capture_browser_scenario", arguments: arguments_ },
+      { signal, timeout: 60_000, toolDefinition: definition },
+    );
+    void pending.catch(() => {});
+    pendingCalls.push(pending);
+    return pending;
+  };
+
+  try {
+    const first = callTool(firstScenario, firstCancellation.signal);
+    await waitForEnvironment(readEnvironment, connection, expected, "A");
+
+    const second = callTool(secondScenario, secondCancellation.signal);
+    await client.ping();
+    assert.deepEqual(await readEnvironment(), expected);
+    assert.equal(await readScenarioRun(connection), "A");
+
+    const cancelled = callTool(
+      environmentScenario({
+        endpoint,
+        targetId,
+        origin,
+        values: alternate,
+        run: "C",
+      }),
+      cancellation.signal,
+    );
+    await client.ping();
+    cancellation.abort(new Error("cancel queued browser scenario"));
+    await assert.rejects(cancelled, /cancel queued browser scenario/u);
+    assert.deepEqual(await readEnvironment(), expected);
+    assert.equal(await readScenarioRun(connection), "A");
+
+    await releaseScenario(connection);
+    assertCapture(
+      requireMcpEvidenceResult(await first, "capture_browser_scenario"),
+      expected,
+    );
+
+    await waitForEnvironment(readEnvironment, connection, alternate, "B");
+    await releaseScenario(connection);
+    assertCapture(
+      requireMcpEvidenceResult(await second, "capture_browser_scenario"),
+      alternate,
+    );
+    await client.ping();
+    await assertRestored();
+  } finally {
+    firstCancellation.abort();
+    secondCancellation.abort();
+    cancellation.abort();
+    await releaseScenario(connection).catch(() => undefined);
+    await Promise.allSettled(pendingCalls);
+  }
+};
+
+const waitForEnvironment = async (
+  readEnvironment,
+  connection,
+  expectedValues,
+  run,
+) => {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (
+      JSON.stringify(await readEnvironment()) ===
+        JSON.stringify(expectedValues) &&
+      (await readScenarioRun(connection)) === run
+    )
+      return;
+    await delay(25);
+  }
+  throw new Error(`Scenario ${run} never reached its page-controlled gate`);
+};
+
+const readScenarioRun = async (connection) => {
+  const value = await connection.send("Runtime.evaluate", {
+    expression: "document.body.dataset.run ?? null",
+    returnByValue: true,
+  });
+  return value.result.value;
+};
+
+const releaseScenario = async (connection) => {
+  await connection.send("Runtime.evaluate", {
+    expression: "window.releaseScenario()",
+    returnByValue: true,
+  });
+};
+
+async function verifyCancelledEnvironment(
+  provider,
+  connection,
+  scenario,
+  readEnvironment,
+) {
+  const controller = new AbortController();
+  const priorNavigation = await connection.send("Runtime.evaluate", {
+    expression: "performance.timeOrigin",
+    returnByValue: true,
+  });
+  const pending = provider.captureScenario(
+    { ...scenario, actions: [{ ...scenario.actions[0], timeout_ms: 30_000 }] },
+    { signal: controller.signal },
+  );
+  try {
+    const deadline = Date.now() + 10_000;
+    while (true) {
+      const navigation = await connection.send("Runtime.evaluate", {
+        expression: "performance.timeOrigin",
+        returnByValue: true,
+      });
+      if (
+        navigation.result.value !== priorNavigation.result.value &&
+        JSON.stringify(await readEnvironment()) === JSON.stringify(expected)
+      )
+        break;
+      assert.ok(Date.now() < deadline, "Scenario never applied emulation");
+      await delay(25);
+    }
+    await delay(100);
+  } finally {
+    controller.abort();
+  }
+  const cancelled = await pending;
+  assert.ok(
+    !cancelled.ok ||
+      cancelled.value.steps.some(({ status }) => status === "cancelled"),
+    "Cancellation unexpectedly completed every action",
+  );
+}

scripts/lib/browser-verifier-assertions.mjs

@@ -209,10 +209,16 @@ export function assertSensitiveShapes(result) {
     (item) =>
       item.url.includes("/api") &&
       item.body_shapes.request?.properties.some(
-        ({ path }) => path === "/token",
+        ({ path }) =>
+          path.length === 1 &&
+          path[0].kind === "property" &&
+          path[0].name === "token",
       ) &&
       item.body_shapes.response?.properties.some(
-        ({ path }) => path === "/secret",
+        ({ path }) =>
+          path.length === 1 &&
+          path[0].kind === "property" &&
+          path[0].name === "secret",
       ),
   );
   if (request === undefined)
@@ -244,7 +250,10 @@ export function assertSensitiveShapes(result) {
       (event) =>
         event.payload_shape?.format === "json" &&
         event.payload_shape.json_shape?.properties.some(
-          ({ path }) => path === "/token",
+          ({ path }) =>
+            path.length === 1 &&
+            path[0].kind === "property" &&
+            path[0].name === "token",
         ),
     )
   )

scripts/lib/catalog-cli.d.mts

@@ -0,0 +1,12 @@
+export function createCliInventory(cli: unknown): {
+  readonly primary: readonly string[];
+  readonly aliases: readonly {
+    readonly name: string;
+    readonly target: string;
+  }[];
+};
+export function cliCommandOptionNames(
+  cli: unknown,
+  name: string,
+): readonly string[];
+export function cliCommandDescriptionIssues(cli: unknown): readonly string[];

scripts/lib/ghidra-reference-snapshot-e2e.mjs

@@ -51,11 +51,10 @@ export async function verifyLegacyGhidraReferenceSnapshot(
     legacyParameters,
   );
   assert.notEqual(legacyProfile.digest, observed.analysis_profile.digest);
-  const parsed = await parseBinaryTarget(
-    target.path,
-    process.cwd(),
-    process.arch,
-  );
+  const parsed = await parseBinaryTarget(target.path, {
+    cwd: process.cwd(),
+    hostArchitecture: process.arch,
+  });
   if (!parsed.ok) throw parsed.error;
   const nativeTarget = parsed.value;
   const result = structuredClone(observed.normalized_result);

scripts/lib/product-catalog.d.mts

@@ -26,10 +26,6 @@ export interface ProductCatalog {
     readonly format: string;
     readonly configuration: string;
   }[];
-  readonly schemas: readonly {
-    readonly id: string;
-    readonly version: string | number;
-  }[];
   readonly cli: {
     readonly primary_count: number;
     readonly commands: readonly string[];
@@ -45,21 +41,6 @@ export interface ProductCatalog {
 }
 
 export function createProductCatalog(root: string): Promise<ProductCatalog>;
-export function providerCatalogDigest(
-  providers: ProductCatalog["providers"],
-): string;
-export function createCliInventory(cli: unknown): {
-  readonly primary: readonly string[];
-  readonly aliases: readonly {
-    readonly name: string;
-    readonly target: string;
-  }[];
-};
-export function cliCommandOptionNames(
-  cli: unknown,
-  name: string,
-): readonly string[];
-export function cliCommandDescriptionIssues(cli: unknown): readonly string[];
 export function serializeProductCatalog(
   catalog: ProductCatalog,
 ): Promise<string>;

scripts/lib/product-catalog.mjs

@@ -1,22 +1,9 @@
 import { formatGeneratedFile } from "./format-generated-file.mjs";
 
 import { assertSameNames, digest, loadSources } from "./catalog-core.mjs";
-import {
-  createCliInventory,
-  cliCommandDescriptionIssues,
-  cliCommandOptionNames,
-} from "./catalog-cli.mjs";
+import { createCliInventory } from "./catalog-cli.mjs";
 import { providerCatalog, toolFamilyCatalog } from "./catalog-builders.mjs";
 
-export {
-  createCliInventory,
-  cliCommandDescriptionIssues,
-  cliCommandOptionNames,
-};
-
-/** Return the stable digest for the source-derived provider projection. */
-export const providerCatalogDigest = (providers) => digest(providers);
-
 /** Project current runtime contracts into deterministic, machine-readable facts. */
 export const createProductCatalog = async (root) => {
   const sources = await loadSources(root);
@@ -59,7 +46,7 @@ export const createProductCatalog = async (root) => {
       counts: sources.catalogIdentity.CATALOG_IDENTITY.counts,
       digests: {
         // Full runtime schema digests belong to server identity, not this facts projection.
-        providers_sha256: providerCatalogDigest(providers),
+        providers_sha256: digest(providers),
       },
     },
   };

scripts/lib/real-hopper-navigation.mjs

@@ -58,6 +58,12 @@ async function verifyNavigation(
     procedure: address,
   });
   const info = await call("procedure_info", { procedure: address });
+  assert.equal(info.classification, null);
+  assert.equal(info.body.available, false);
+  assert.match(
+    info.body.reason,
+    /public Python API does not expose complete function body ranges/u,
+  );
   assert.ok(info.locals.length > 0, "fixture omitted real stack locals");
   for (const local of info.locals) {
     assert.equal(typeof local.name, "string");
@@ -68,19 +74,46 @@ async function verifyNavigation(
   }
   const dossier = await call("analyze_function", { procedure: address });
   assert.deepEqual(dossier.procedure.locals, info.locals);
+  assert.equal(dossier.procedure.classification, null);
+  assert.equal(dossier.procedure.body.available, false);
+  assert.match(
+    dossier.procedure.body.reason,
+    /public Python API does not expose complete function body ranges/u,
+  );
+  assert.equal(dossier.native_api, null);
+  assert.equal(dossier.native_value_flow, null);
+  assert.ok(
+    Array.isArray(dossier.limitations) && dossier.limitations.length > 0,
+    "function dossier omitted Hopper's unsupported-facet limitations",
+  );
   const coordinates = instructions.instructions.map(
     (line) => /^0x[0-9a-f]+/u.exec(line)?.[0],
   );
   assert.equal(coordinates[0], address);
   assert.ok(coordinates[1], "fixture omitted a second instruction");
-  const interior = `0x${(BigInt(address) + 1n).toString(16)}`;
-  assert.equal(await call("goto_address", { address: interior }), address);
-  assert.equal(await call("current_address"), address);
+  // The host toolchain controls the prologue encoding: without endbr64-style
+  // padding the first instruction is one byte, so address + 1 is itself an
+  // instruction boundary. Probe from inside the first multi-byte instruction
+  // so the interior coordinate is never an analyzed-object boundary.
+  let anchor = 0;
+  while (anchor + 1 < coordinates.length) {
+    if (BigInt(coordinates[anchor + 1]) - BigInt(coordinates[anchor]) > 1n)
+      break;
+    anchor += 1;
+  }
+  assert.ok(
+    anchor + 1 < coordinates.length,
+    "fixture omitted a multi-byte instruction for interior navigation",
+  );
+  const containing = coordinates[anchor];
+  const interior = `0x${(BigInt(containing) + 1n).toString(16)}`;
+  assert.equal(await call("goto_address", { address: interior }), containing);
+  assert.equal(await call("current_address"), containing);
   assert.equal(
     await call("next_address", { address: interior }),
-    coordinates[1],
+    coordinates[anchor + 1],
   );
-  assert.equal(await call("prev_address", { address: interior }), address);
+  assert.equal(await call("prev_address", { address: interior }), containing);
   for (const unmapped of ["0x0", "0xfffffffffffffffe"]) {
     for (const operation of ["goto_address", "next_address", "prev_address"])
       await invalid(
@@ -88,7 +121,7 @@ async function verifyNavigation(
         { address: unmapped },
         /Address is outside every segment/u,
       );
-    assert.equal(await call("current_address"), address);
+    assert.equal(await call("current_address"), containing);
     for (const operation of [
       "set_address_name",
       "set_bookmark",

scripts/lib/real-hopper-semantic.mjs

@@ -11,15 +11,28 @@ export const requireTruthfulMemoryRegions = (segments) => {
     ...(Array.isArray(segment.sections) ? segment.sections : []),
   ]);
   for (const region of regions) {
+    if (
+      typeof region?.name !== "string" ||
+      region.name.length === 0 ||
+      typeof region.start !== "string" ||
+      typeof region.end !== "string"
+    ) {
+      throw new Error(
+        "list_segments omitted observed region identity or bounds",
+      );
+    }
     for (const permission of ["readable", "writable", "executable"]) {
-      if (![true, false, null].includes(region?.[permission])) {
-        throw new Error(`list_segments omitted tri-state ${permission}`);
+      if (region[permission] !== null) {
+        throw new Error(
+          `list_segments invented or omitted unknown ${permission}`,
+        );
       }
     }
     if (
       region.provenance !== "hopper-public-python-api" ||
       region.permissions?.available !== false ||
-      typeof region.permissions.reason !== "string"
+      typeof region.permissions.reason !== "string" ||
+      region.permissions.reason.length === 0
     ) {
       throw new Error("list_segments omitted permission provenance");
     }
@@ -141,6 +154,15 @@ export async function verifyRealHopperFixture({
     "procedure_references",
   );
   assert.deepEqual(entryDossier.unresolved_calls, observed.unresolved_calls);
+  assert.equal(
+    observed.reference_kinds_available,
+    false,
+    "Hopper's partial CallReference observations do not expose detailed reference kinds",
+  );
+  assert.ok(
+    Array.isArray(observed.unresolved_calls),
+    "procedure_references omitted its observed unresolved CallReference results",
+  );
   for (const call of calls) {
     assert.equal(call.call.provider_type, 2);
     assert.equal(

scripts/lib/verify-package-core.mjs

@@ -69,32 +69,3 @@ export const pathExists = async (path) => {
     throw cause;
   }
 };
-
-/** Synthetic function dossier for managed/native verification fixtures. */
-export const functionDossier = (name) => {
-  return {
-    procedure: {
-      address: "0x401000",
-      name,
-      classification: {
-        external: false,
-        thunk: false,
-        thunk_target: null,
-        provenance: "synthetic-provider",
-      },
-      signature: null,
-      locals: [],
-    },
-    pseudocode: "",
-    assembly: [],
-    comments: [],
-    callers: [],
-    callees: [],
-    incoming_references: [],
-    outgoing_references: [],
-    referenced_strings: [],
-    referenced_names: [],
-    basic_blocks: [],
-    limitations: [],
-  };
-};

scripts/verify-native-calls.mjs

@@ -95,8 +95,8 @@ const checkScenario = async (binary) => {
   });
   const greet = result.events.filter(({ symbol }) => symbol === GREET);
   const add = result.events.filter(({ symbol }) => symbol === "rea_call_add");
-  assert.equal(greet.length, 3);
-  assert.equal(add.length, 3);
+  assert.equal(greet.length, 3, JSON.stringify(result));
+  assert.equal(add.length, 3, JSON.stringify(result));
   for (const [index, event] of greet.entries()) {
     assert.equal(event.receiver_class, "ReaCallGreeter");
     assert.equal(event.selector, "greet:times:");

scripts/verify-package-environment.mjs

@@ -81,6 +81,10 @@ export async function verifyPackageEnvironment({
     COPILOT_HOME: join(home, ".copilot"),
     GROK_HOME: join(home, ".grok"),
     SAND_DATA_ROOT: join(home, ".grokbot"),
+    OMP_PROFILE: undefined,
+    PI_CODING_AGENT_DIR: undefined,
+    PI_CONFIG_DIR: undefined,
+    PI_PROFILE: undefined,
     OPENCODE_CONFIG: undefined,
     XDG_CONFIG_HOME: join(home, ".config"),
     PATH: `${fakeBin}:${process.env.PATH ?? ""}`,

scripts/verify-package-managed.mjs

@@ -3,7 +3,8 @@ import { join } from "node:path";
 
 import { createEvidence } from "../dist/domain/evidence.js";
 import { buildManagedPeFixture } from "./fixtures/managed/pe.mjs";
-import { functionDossier, json, run } from "./lib/verify-package-core.mjs";
+import { functionDossier } from "./fixtures/managed/function-dossier.mjs";
+import { json, run } from "./lib/verify-package-core.mjs";
 
 const buildManagedFixtures = async (workspace) => {
   const managedPath = join(workspace, "managed-fixture.exe");

scripts/verify-package-update.mjs

@@ -103,6 +103,10 @@ export async function verifyPackageUpdate({
       COPILOT_HOME: join(home, ".copilot"),
       GROK_HOME: join(home, ".grok"),
       SAND_DATA_ROOT: join(home, ".grokbot"),
+      OMP_PROFILE: undefined,
+      PI_CODING_AGENT_DIR: undefined,
+      PI_CONFIG_DIR: undefined,
+      PI_PROFILE: undefined,
       XDG_CONFIG_HOME: join(home, ".config"),
       OPENCODE_CONFIG: join(home, ".config", "opencode", "opencode.json"),
       npm_config_prefix: prefix,

scripts/verify-published-package.mjs

@@ -106,6 +106,10 @@ async function verifyPublishedUpdate({ version: targetVersion, canaryRoot }) {
     COPILOT_HOME: join(home, ".copilot"),
     GROK_HOME: join(home, ".grok"),
     SAND_DATA_ROOT: join(home, ".grokbot"),
+    OMP_PROFILE: undefined,
+    PI_CODING_AGENT_DIR: undefined,
+    PI_CONFIG_DIR: undefined,
+    PI_PROFILE: undefined,
     XDG_CONFIG_HOME: join(home, ".config"),
     OPENCODE_CONFIG: join(home, ".config", "opencode", "opencode.json"),
     npm_config_cache: join(canaryRoot, "update-cache"),

scripts/verify-real-browser.mjs

@@ -44,6 +44,7 @@ import { verifyBrowserModules } from "./lib/browser-module-e2e.mjs";
 import { verifyBrowserDomDestinations } from "./lib/browser-dom-destinations-e2e.mjs";
 import { verifyBrowserCaptureMetadataBudget } from "./lib/browser-capture-metadata-budget-e2e.mjs";
 import { artifactCliEvidence, artifactMcpResult } from "./lib/artifact-e2e.mjs";
+import { verifyScenarioEnvironment } from "./lib/browser-scenario-environment-e2e.mjs";
 
 const REAL_BROWSER_STARTUP_TIMEOUT_MS = 60_000;
 const SCENARIO_SECRET_VALUE = "rea-browser-verifier-secret";
@@ -274,6 +275,11 @@ try {
     throw new Error("Scenario attachment terminated its external browser");
 
   const profilesBefore = await scenarioProfiles();
+  const scenarioEnvironment = await verifyScenarioEnvironment(
+    endpoint,
+    target,
+    site.origin,
+  );
   const launchedScenario = await createBrowserScenarioProvider(
     process.env,
   ).captureScenario(
@@ -366,6 +372,7 @@ try {
     browserScenarioAttachCleanup: "disconnected-external",
     browserScenarioLaunchCleanup: "terminated-owned-process",
     scenarioFailure,
+    scenarioEnvironment,
     verified: true,
   };
 } finally {

scripts/verify-real-ghidra-function.mjs

@@ -153,14 +153,15 @@ export async function verifyDebugFunctionOperations(
   const denseSwitchDossier = await functionCall(client, "analyze_function", {
     procedure: denseSwitchProcedure.address,
   });
-  if (process.platform === "linux" && process.arch === "x64")
-    assertDenseSwitchDossier(denseSwitchDossier, denseSwitchProcedure.address);
-  else
-    assertDossier(denseSwitchDossier, {
-      address: denseSwitchProcedure.address,
-      requireAssembly: true,
-      requireMultiBlock: true,
-    });
+  // The debug fixture is compiled -O0, and GCC 16 and later lower dense
+  // switches to compare chains at -O0, so this dossier asserts only its
+  // complete shape; the optimized jump-table variant proves dense jump-table
+  // completeness through assertDenseSwitchDossier.
+  assertDossier(denseSwitchDossier, {
+    address: denseSwitchProcedure.address,
+    requireAssembly: true,
+    requireMultiBlock: true,
+  });
   assertIndirectDossier(indirectDossier, leaf.address);
 
   const { cancellation, timeout } = await verifyRequestCancellationAndTimeout(
@@ -372,6 +373,19 @@ async function verifyConcurrentRequests(client, entry, leaf) {
   return "serialized-two-results";
 }
 
+/** Prove dense jump-table completeness on the optimized jump-table fixture. */
+export async function verifyJumpTableDenseSwitch(client, procedures) {
+  const denseSwitchProcedure = requireProcedure(
+    procedures,
+    "rea_ghidra_inventory_dense_switch",
+  );
+  const dossier = await functionCall(client, "analyze_function", {
+    procedure: denseSwitchProcedure.address,
+  });
+  assertDenseSwitchDossier(dossier, denseSwitchProcedure.address);
+  return { dense_switch: dossierSummary(dossier) };
+}
+
 export async function verifyStrippedFunctionOperations(client, entryString) {
   const stringXrefs = await functionCall(client, "xrefs", {
     document: null,

scripts/verify-real-ghidra.mjs

@@ -35,6 +35,7 @@ import { hasTypedSwitchEvidence } from "./verify-real-ghidra-switch-assertions.m
 
 import {
   verifyDenseDefaultReturn,
+  verifyJumpTableDenseSwitch,
   verifyNativeTypeLayout,
   verifyRelativeSwitch,
   verifyNativeValueTrace,
@@ -80,6 +81,7 @@ const crossFormatSourcePath = fileURLToPath(
 const debugPath = join(fixtureRoot, "rea-ghidra-inventory-debug");
 const layoutPath = join(fixtureRoot, "rea-ghidra-layout.o");
 const strippedPath = join(fixtureRoot, "rea-ghidra-inventory-stripped");
+const jumpTablePath = join(fixtureRoot, "rea-ghidra-inventory-jump");
 const arm64ElfPath = join(fixtureRoot, "rea-ghidra-cross-arm64");
 const peObjectPath = join(fixtureRoot, "rea-ghidra-cross-x86_64.obj");
 const pePath = join(fixtureRoot, "rea-ghidra-cross-x86_64.exe");
@@ -134,6 +136,14 @@ try {
   if (expectedNativeTarget.format === "mach-o")
     strippedFlags.push("-fvisibility=hidden");
   await exec(compiler, [...strippedFlags, sourcePath, "-o", strippedPath]);
+  // The dense jump-table oracle needs the switch lowered to a table: GCC 16 and
+  // later expand dense switches as compare chains at -O0, so the CLI oracle
+  // runs against an optimized build while the debug fixture keeps its -O0
+  // stack-local and DWARF shape.
+  const jumpTableFlags = ["-O2", "-g", "-fno-inline"];
+  if (expectedNativeTarget.format === "elf")
+    jumpTableFlags.push("-fno-pie", "-no-pie");
+  await exec(compiler, [...jumpTableFlags, sourcePath, "-o", jumpTablePath]);
   const crossTargets = [];
   if (aarch64JumpTableOnly) {
     const relativeSource = fileURLToPath(
@@ -253,6 +263,11 @@ try {
     expectedNativeTarget,
   );
   assertStrippedFixture(stripped);
+  const jumpTable = await verifyTarget(
+    jumpTablePath,
+    "jump-table",
+    expectedNativeTarget,
+  );
   const crossResults = [];
   for (const [targetPath, variant, expectedTarget] of crossTargets) {
     const result = await verifyTarget(targetPath, variant, expectedTarget);
@@ -277,11 +292,13 @@ try {
       crossFormat || aarch64JumpTableOnly
         ? [sourcePath, crossFormatSourcePath]
         : [sourcePath],
-    fixtures: [debug, stripped, layout, ...crossResults].map(summary),
+    fixtures: [debug, stripped, layout, jumpTable, ...crossResults].map(
+      summary,
+    ),
     malformed_target: "rejected-before-provider-start",
     native_api_cli: aarch64JumpTableOnly
       ? (crossResults[0]?.native_api_cli ?? null)
-      : debug.native_api_cli,
+      : jumpTable.native_api_cli,
     native_value_e2e: debug.native_values,
     custom_target: custom === null ? null : summary(custom),
     cleanup: "complete",
@@ -493,7 +510,7 @@ async function verifyTarget(targetPath, variant, expectedTarget = null) {
     const crossArm64Elf =
       variant === "cross-arm64-elf" || variant === "aarch64-jump-table";
     const nativeApiCli =
-      variant === "debug" || crossArm64Elf
+      variant === "jump-table" || crossArm64Elf
         ? await verifyNativeApiCli(parsedTarget.value.path, procedures, {
             requireDenseJumpTable:
               crossArm64Elf ||
@@ -513,15 +530,17 @@ async function verifyTarget(targetPath, variant, expectedTarget = null) {
         )
       : variant === "type-layout"
         ? await verifyNativeTypeLayout(client, names)
-        : variant === "custom" || variant === "aarch64-jump-table"
-          ? null
-          : await verifyInventoryOperations({
-              client,
-              variant,
-              procedures,
-              names,
-              strings,
-            });
+        : variant === "jump-table"
+          ? await verifyJumpTableDenseSwitch(client, procedures)
+          : variant === "custom" || variant === "aarch64-jump-table"
+            ? null
+            : await verifyInventoryOperations({
+                client,
+                variant,
+                procedures,
+                names,
+                strings,
+              });
     const nativeValues =
       variant === "debug"
         ? await verifyNativeValueTrace(client, procedures, parsedTarget.value)

scripts/verify-windows-package.mjs

@@ -115,6 +115,10 @@ try {
     COPILOT_HOME: join(home, ".copilot"),
     GROK_HOME: join(home, ".grok"),
     SAND_DATA_ROOT: join(home, ".grokbot"),
+    OMP_PROFILE: undefined,
+    PI_CODING_AGENT_DIR: undefined,
+    PI_CONFIG_DIR: undefined,
+    PI_PROFILE: undefined,
   };
   await mkdir(join(home, ".config", "opencode"), { recursive: true });
   await writeFile(

scripts/verify/apple/dispatch.mjs

@@ -1,3 +1,4 @@
+import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -6,6 +7,12 @@ import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { parseBinaryTarget } from "../../../dist/application/BinaryTargetResolver.js";
 import { inspectAppleDispatchMetadata } from "../../../dist/native/AppleDispatchMetadata.js";
+import {
+  artifactCliEvidence,
+  artifactMcpResult,
+  withArtifactMcp,
+} from "../../lib/artifact-e2e.mjs";
+import { nativeDispatchMetadataResultSchema } from "../../../dist/domain/native/objcSwiftMetadata.js";
 
 if (process.platform !== "darwin")
   throw new Error(
@@ -61,6 +68,30 @@ const checkObjc = (metadata, mode) => {
   const objcCoverage = metadata.coverage.find(
     ({ facet }) => facet === "objc_class_method_ivar_metadata",
   );
+  assert.equal(fixture?.is_meta_class, false);
+  assert.equal(fixture?.is_root_class, false);
+  assert.equal(
+    fixture?.properties.find(({ name }) => name === "fixtureName")?.atomicity,
+    "nonatomic",
+  );
+  assert.equal(
+    fixture?.properties.find(({ name }) => name === "atomicValue")?.atomicity,
+    "atomic",
+  );
+  for (const method of fixture.methods) {
+    assert.equal(method.is_required, null);
+    assert.equal(method.is_optional, null);
+  }
+  for (const property of fixture.properties)
+    for (const attribute of property.attributes)
+      assert.deepEqual(Object.keys(attribute).sort(), ["name", "value"]);
+  const protocol = metadata.objc_protocols.find(
+    ({ name }) => name === "ReaDispatchProtocol",
+  );
+  assert.equal(protocol?.methods[0]?.is_required, true);
+  assert.equal(protocol?.methods[0]?.is_optional, false);
+  assert.equal(protocol?.optional_methods[0]?.is_required, false);
+  assert.equal(protocol?.optional_methods[0]?.is_optional, true);
   if (
     !metadata.objc_dispatch_implementations.some(
       (item) =>
@@ -162,6 +193,25 @@ try {
         await exec("/usr/bin/strip", ["-x", objcPath]);
       const { target, metadata } = await inspect(objcPath);
       checkObjc(metadata, mode);
+      if (mode.mode === "chained" && variant === "stripped") {
+        const cli = await artifactCliEvidence(
+          "inspect-native-dispatch-metadata",
+          objcPath,
+        );
+        const cliResult = nativeDispatchMetadataResultSchema.parse(
+          cli.normalized_result,
+        );
+        assert.equal(cliResult.target_sha256, target.sha256);
+        checkObjc(cliResult.result, mode);
+        await withArtifactMcp(objcPath, async (client) => {
+          const mcpResult = nativeDispatchMetadataResultSchema.parse(
+            await artifactMcpResult(client, "inspect_native_dispatch_metadata"),
+          );
+          assert.equal(mcpResult.target_sha256, target.sha256);
+          checkObjc(mcpResult.result, mode);
+          assert.deepEqual(mcpResult.result, cliResult.result);
+        });
+      }
       results.push({
         variant: `objc-${mode.mode}-${variant}`,
         target_sha256: target.sha256,

scripts/verify/apple/keyed-archive.mjs

@@ -148,8 +148,27 @@ try {
         target,
         status,
       })),
-      [{ source: null, path: ["UID"], target: 1, status: "resolved" }],
+      [
+        { source: null, path: ["CF$UID"], target: 1, status: "resolved" },
+        { source: null, path: ["UID"], target: 1, status: "resolved" },
+      ],
     );
+    const selected = await artifactCli("inspect-keyed-archive", path, [
+      "--root",
+      "UID",
+    ]);
+    assert.deepEqual(
+      selected.references,
+      uidGraph.references.filter(({ path }) => path[0] === "UID"),
+    );
+    await withArtifactMcp(path, async (client) => {
+      assert.deepEqual(
+        await artifactMcpResult(client, "inspect_keyed_archive", {
+          root: "UID",
+        }),
+        selected,
+      );
+    });
   }
   const numericTests = spawnSync(
     "npm",

scripts/verify/apple/legacy-simulator.mjs

@@ -0,0 +1,142 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import {
+  artifactCliEvidence,
+  artifactMcpResult,
+  withArtifactMcp,
+} from "../../lib/artifact-e2e.mjs";
+
+const exec = promisify(execFile);
+
+if (process.platform !== "darwin")
+  throw new Error(
+    "Legacy simulator verification requires a macOS host with full Xcode.",
+  );
+for (const tool of ["clang", "ld", "vtool", "otool"])
+  await exec("/usr/bin/xcrun", ["--find", tool], { timeout: 30_000 });
+const { stdout: sdk } = await exec(
+  "/usr/bin/xcrun",
+  ["--sdk", "iphonesimulator", "--show-sdk-path"],
+  { timeout: 30_000 },
+);
+const sdkPath = sdk.trim();
+assert.ok(sdkPath.length > 0, "iPhoneSimulator SDK path is empty");
+
+const root = await mkdtemp(join(tmpdir(), "rea-legacy-simulator-"));
+const xcrun = (...args) =>
+  exec("/usr/bin/xcrun", args, {
+    timeout: 120_000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+try {
+  // Source-owned fixture, never executed: a legacy deployment target makes
+  // the Apple driver emit LC_VERSION_MIN_IPHONEOS (no simulator flag), while
+  // the modern dylib carries LC_BUILD_VERSION with an explicit simulator ID.
+  await writeFile(join(root, "library.c"), "int fixture(void) { return 7; }\n");
+  await writeFile(
+    join(root, "main.c"),
+    "extern int fixture(void);\nint main(void) { return fixture(); }\n",
+  );
+  for (const [source, deployment] of [
+    ["library", "14.0"],
+    ["main", "9.0"],
+  ]) {
+    await xcrun(
+      "clang",
+      "-target",
+      `x86_64-apple-ios${deployment}-simulator`,
+      "-isysroot",
+      sdkPath,
+      "-c",
+      join(root, `${source}.c`),
+      "-o",
+      join(root, `${source}.o`),
+    );
+  }
+  const common = ["-arch", "x86_64", "-syslibroot", sdkPath, "-lSystem"];
+  await xcrun(
+    "ld",
+    ...common,
+    "-dylib",
+    "-platform_version",
+    "ios-simulator",
+    "14.0",
+    "14.0",
+    "-install_name",
+    "@rpath/libFixture.dylib",
+    join(root, "library.o"),
+    "-o",
+    join(root, "libFixture.dylib"),
+  );
+  await xcrun(
+    "clang",
+    "-target",
+    "x86_64-apple-ios9.0-simulator",
+    "-isysroot",
+    sdkPath,
+    "-e",
+    "_main",
+    "-rpath",
+    "@loader_path",
+    join(root, "main.o"),
+    join(root, "libFixture.dylib"),
+    "-o",
+    join(root, "Main"),
+  );
+
+  // Apple oracle: the executable really uses the legacy command, the dylib
+  // really declares the modern simulator platform.
+  const { stdout: legacyBuild } = await xcrun(
+    "vtool",
+    "-show-build",
+    join(root, "Main"),
+  );
+  assert.match(legacyBuild, /LC_VERSION_MIN_IPHONEOS/u);
+  assert.doesNotMatch(legacyBuild, /LC_BUILD_VERSION/u);
+  const { stdout: modernBuild } = await xcrun(
+    "vtool",
+    "-show-build",
+    join(root, "libFixture.dylib"),
+  );
+  assert.match(modernBuild, /IOSSIMULATOR/u);
+
+  // Real CLI over the fixture: the target is the executable file (plain
+  // directories are not binary targets); @loader_path resolves against its
+  // directory. The legacy x86 image must classify as iOS simulator
+  // (platform 7) and resolve against the modern dylib.
+  // The fixture is inspected, never executed or loaded into this process.
+  const mainPath = join(root, "Main");
+  const trace = (await artifactCliEvidence("trace-dylib-resolution", mainPath))
+    .normalized_result;
+  const main = trace.images.find(({ path }) => path === "Main");
+  assert.ok(main, "trace omitted the Main image");
+  assert.equal(main.parse_status, "parsed");
+  assert.deepEqual(main.slices[0]?.platforms, [7]);
+  const edge = trace.edges.find(
+    ({ loader, install_name: name }) =>
+      loader === "Main" && name === "@rpath/libFixture.dylib",
+  );
+  assert.ok(edge, "trace omitted the @rpath edge");
+  assert.deepEqual(edge.resolution, {
+    status: "resolved",
+    image: "libFixture.dylib",
+  });
+
+  await withArtifactMcp(mainPath, async (client) => {
+    assert.deepEqual(
+      await artifactMcpResult(client, "trace_dylib_resolution"),
+      trace,
+    );
+  });
+  console.log(
+    "Legacy simulator verification passed against Apple clang, ld, vtool, and otool.",
+  );
+} finally {
+  await rm(root, { recursive: true, force: true });
+}

scripts/verify/architecture-guards.mjs

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Architecture guards for the strict-identity / best-effort-inference split.
+// - Evidence ordering must be locale-independent (ICU varies by host), so
+//   src/domain orders with compareUnicodeCodePoints, never localeCompare.
+// - Composite dedup keys must not NUL-join variable-length or free-form
+//   MIDDLE fields: ["a\0b"] collapses with ["a", "b"] and drops a finding.
+//   compositeKey (JSON tuple) is the single owner for composite keys.
+// - Transparent wrappers unwrap in exactly one place
+//   (javascriptAstValues.unwrapJavaScriptExpression); direct isTS* unwrapping
+//   elsewhere drifts (the `satisfies` class of bug).
+// - AST walks go through traverseJavaScriptAst/childNodes: bespoke
+//   Object.values walkers diverge on loc/comment fields and overflow the
+//   stack on deep generated chains.
+
+const root = fileURLToPath(new URL("../../", import.meta.url));
+
+const listFiles = async (dir) => {
+  const output = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) output.push(...(await listFiles(path)));
+    else if (
+      entry.name.endsWith(".ts") &&
+      !entry.name.endsWith(".test.ts") &&
+      !entry.name.endsWith(".fixture.ts")
+    )
+      output.push(path);
+  }
+  return output;
+};
+
+const stripComments = (content) =>
+  content
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("//"))
+    .join("\n")
+    .replace(/\/\*[\s\S]*?\*\//gu, "");
+
+const sources = await listFiles(join(root, "src"));
+const files = await Promise.all(
+  sources.map(async (path) => ({
+    path: relative(root, path).split(sep).join("/"),
+    content: stripComments(await readFile(path, "utf8")),
+  })),
+);
+const inDir = (dir) => files.filter((file) => file.path.startsWith(dir));
+
+const failures = [];
+const check = (label, selected, pattern, allow = []) => {
+  const offenders = selected.filter(
+    (file) => pattern.test(file.content) && !allow.includes(file.path),
+  );
+  if (offenders.length > 0)
+    failures.push(
+      `${label}:\n${offenders.map((file) => `  ${file.path}`).join("\n")}`,
+    );
+};
+
+check(
+  "src/domain uses localeCompare (use compareUnicodeCodePoints)",
+  inDir("src/domain/"),
+  /\.localeCompare\(/,
+);
+
+check(
+  "NUL-joined list key (use compositeKey)",
+  files,
+  /\.join\(["']\\0["']\)/,
+  [
+    // Sorted pair of constrained trace IDs; documented in plan.
+    "src/domain/process/processTraceSpecification.ts",
+  ],
+);
+
+check(
+  "direct transparent-wrapper unwrap outside javascriptAstValues (use unwrapJavaScriptExpression)",
+  files,
+  /isTSAsExpression|isTSSatisfiesExpression|isTSNonNullExpression|isTSTypeAssertion|isTSInstantiationExpression|isParenthesizedExpression/,
+  ["src/domain/javascript/javascriptAstValues.ts"],
+);
+
+check(
+  "bespoke AST child walker (use traverseJavaScriptAst/childNodes)",
+  files,
+  /VISITOR_KEYS/,
+  ["src/domain/javascript/javascriptSemanticTraversal.ts"],
+);
+
+// Fixed-arity backtick keys audited 2026-10-10: every prefix field is NUL-free
+// (hex digests, file paths, enums, numbers, or compositeKey JSON which escapes
+// NUL), with free-form source strings only in final position. New backtick-\0
+// keys must either meet that shape (and extend this list with justification)
+// or use compositeKey.
+check(
+  "new backtick-NUL composite key (audit against the rule above)",
+  files,
+  /`[^`\n]*\\0/,
+  [
+    "src/application/javascript/ElectronBoundaryAnalysis.ts",
+    "src/application/javascript/ElectronBoundaryGraphContext.ts",
+    "src/application/javascript/JavaScriptArtifactGraphContext.ts",
+    "src/browser/CdpCaptureCompleteness.ts",
+    "src/browser/CdpCaptureEventHandlers.ts",
+    "src/browser/CdpPageCapture.ts",
+    "src/browser/WebSourceMapFetcher.ts",
+    "src/domain/javascript/electronStaticAnalysisBrowser.ts",
+    "src/domain/javascript/electronStaticAnalysisIpc.ts",
+    "src/domain/javascript/javascriptApplicationChangeGraph.ts",
+    "src/domain/javascript/javascriptApplicationVersionItems.ts",
+    "src/domain/javascript/javascriptApplicationVersionKeys.ts",
+    "src/domain/javascript/javascriptExportShapeSelection.ts",
+    "src/domain/javascript/javascriptFeatureSeed.ts",
+    "src/domain/javascript/javascriptFeatureTraversal.ts",
+    "src/domain/javascript/javascriptNativeHandoff.ts",
+    "src/domain/javascript/javascriptRuntimeReconciliationMatching.ts",
+    "src/domain/javascript/javascriptRuntimeReconciliationSchemas.ts",
+    "src/domain/javascript/javascriptSemanticQuery.ts",
+    "src/domain/javascript/javascriptStaticAnalysisBundler.ts",
+    "src/domain/javascript/javascriptStaticAnalysisCalls.ts",
+    "src/domain/javascript/javascriptStaticAnalysisFindings.ts",
+    "src/domain/localPath.ts",
+    "src/domain/process/processTraceEvaluation.ts",
+    "src/domain/process/processTraceSpecification.ts",
+    "src/domain/unicodeCodePointOrder.ts",
+    "src/domain/webBundleAnalyzerInspection.ts",
+  ],
+);
+
+if (failures.length > 0) {
+  console.error(`Architecture guards failed:\n\n${failures.join("\n\n")}\n`);
+  process.exit(1);
+}
+console.log(`Architecture guards passed across ${files.length} source files.`);

scripts/verify/javascript/digests.mjs

@@ -4,7 +4,7 @@ import assert from "node:assert/strict";
 import { constants } from "node:buffer";
 import { createHash } from "node:crypto";
 
-import { canonicalDigest } from "../../../dist/domain/comparisonSemantics.js";
+import { digestCanonicalValue } from "../../../dist/domain/canonicalDigest.js";
 import {
   createEvidence,
   parseEvidence,
@@ -23,7 +23,7 @@ for (let index = 0; index < count; index += 1) {
   expected.update(encodedLeaf);
 }
 expected.update("]}");
-assert.equal(canonicalDigest(value), expected.digest("hex"));
+assert.equal(digestCanonicalValue(value), expected.digest("hex"));
 
 const evidence = createEvidence(
   undefined,

scripts/verify/managed/config.mjs

@@ -50,31 +50,3 @@ export const comparisonLimits = {
 export const defaultIlBody = Buffer.from([
   0x32, 0x02, 0x7b, 0x01, 0x00, 0x00, 0x04, 0x28, 0x01, 0x00, 0x00, 0x0a, 0x2a,
 ]);
-
-export function functionDossier(name) {
-  return {
-    procedure: {
-      address: "0x401000",
-      name,
-      classification: {
-        external: false,
-        thunk: false,
-        thunk_target: null,
-        provenance: "synthetic-provider",
-      },
-      signature: null,
-      locals: [],
-    },
-    pseudocode: "",
-    assembly: [],
-    comments: [],
-    callers: [],
-    callees: [],
-    incoming_references: [],
-    outgoing_references: [],
-    referenced_strings: [],
-    referenced_names: [],
-    basic_blocks: [],
-    limitations: [],
-  };
-}

scripts/verify/managed/conformance.mjs

@@ -13,6 +13,7 @@ import { projectManagedApplicationGraphEvidence } from "../../../dist/applicatio
 import { traceApplicationFeatureEvidence } from "../../../dist/application/javascript/JavaScriptApplicationWorkflowService.js";
 import { MANAGED_STATIC_PROVIDER } from "../../../dist/application/InvestigationProviders.js";
 import { createEvidence } from "../../../dist/domain/evidence.js";
+import { functionDossier } from "../../fixtures/managed/function-dossier.mjs";
 import {
   alternateMvid,
   buildNativePeFixture,
@@ -21,7 +22,6 @@ import { createManagedConformanceSupport } from "./support.mjs";
 import {
   comparisonLimits,
   defaultIlBody,
-  functionDossier,
   inspectionLimits,
   memberLimits,
   nativeBoundaryLimits,

server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/morluto/rea",
     "source": "github"
   },
-  "version": "6.2.0",
+  "version": "6.3.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "rea-agents",
-      "version": "6.2.0",
+      "version": "6.3.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

skill-src/reverse-engineer-anything/SKILL.md

@@ -31,7 +31,7 @@ When tools are absent or registration is stale:
    `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`, `vscode`, `grok_build`, or `grok_bot`. `grok_bot` has no local
+   `commandcode`, `vscode`, `grok_build`, `omp`, or `grok_bot`. `grok_bot` has no local
    file registration: doctor reports the Grok Bot chat step, and setup does not
    write `mcp.json`. If the client is unknown, use `doctor --json` and
    inspect its registration results before choosing a setup scope.

skill-src/reverse-engineer-anything/references/native-and-artifacts.md

@@ -60,6 +60,15 @@ use inclusive ends and can contain gaps. Do not treat the enclosing span as code
 For packed targets, retain the original and separately derived artifact identities;
 decompiling an unpacking stub does not recover the unpacked program.
 
+When reading Objective-C dispatch metadata, distinguish class implementation
+methods from protocol requirements: class methods report null requirement
+flags, while decoded protocol declarations retain required and optional facts.
+Property attributes remain raw name/value tokens; use the property's
+`atomicity` field for the decoded `N` marker or the default atomic behavior.
+Null class/meta flags, ivar counts, atomicity, or read-only values mean the
+selected provider did not establish that fact. Symbol names alone do not prove
+that a class is a root class or has no ivars.
+
 ## Managed PE/CLI
 
 Start with `inspect_managed_artifact`. REA's canonical managed inspection is

src/android/JadxProvider.ts

@@ -123,24 +123,25 @@ const cleanup = async (
     resources.session = undefined;
   } catch (cause) {
     // Retain an uncertain workspace until the caller can resolve process ownership.
-    return err(
-      new ProviderCleanupError(
-        "jadx",
-        [
-          session?.transport.runId ?? "unknown",
-          ...(root === undefined ? [] : [root.path]),
-        ],
-        {
-          ...diagnostics,
-          reason: cause instanceof Error ? cause.message : String(cause),
-          provider_cleanup:
-            cause instanceof ProviderCleanupError
-              ? (cause.diagnostics ?? null)
-              : null,
-        },
-        { cause: previousError ?? cause },
-      ),
+    const error = new ProviderCleanupError(
+      "jadx",
+      [
+        session?.transport.runId ?? "unknown",
+        ...(root === undefined ? [] : [root.path]),
+      ],
+      {
+        ...diagnostics,
+        reason: cause instanceof Error ? cause.message : String(cause),
+        provider_cleanup:
+          cause instanceof ProviderCleanupError
+            ? (cause.diagnostics ?? null)
+            : null,
+      },
+      { cause: previousError ?? cause },
     );
+    if (previousError?.partialObservation !== undefined)
+      error.retainPartialObservation(previousError.partialObservation);
+    return err(error);
   }
   try {
     await root?.close();
@@ -396,6 +397,9 @@ export class JadxProvider implements AndroidAnalysisPort {
         signal: options?.signal,
         session,
       });
+      const partialObservation = session?.partialObservation();
+      if (partialObservation !== undefined)
+        previousError.retainPartialObservation(partialObservation);
       // Admission can fail before selecting an existing session for execution.
       root ??= this.#retained?.root;
       session ??= this.#retained?.session;

src/android/JadxSession.ts

@@ -4,6 +4,7 @@ import {
   type AnalysisExecution,
 } from "../application/AnalysisProvider.js";
 import type { AndroidRequest } from "../domain/android/androidAnalysis.js";
+import type { AndroidPartialObservation } from "../domain/android/androidPartialObservation.js";
 import {
   AnalysisCapabilityUnavailableError,
   AnalysisInputError,
@@ -35,6 +36,23 @@ export class JadxSession {
   readonly #client = new Client({ name: "rea-android-adapter", version: "1" });
   #loaded: ReturnType<typeof jadxLoadSchema.parse> | undefined;
   #connected = false;
+  #partialContext:
+    | {
+        readonly operation: AndroidRequest["operation"];
+        readonly selectedPath: string;
+        readonly target: BinaryTarget;
+        readonly jarHash: string;
+        readonly bridgeHash: string;
+      }
+    | undefined;
+  #observedCalls: {
+    readonly operation: string;
+    readonly input: Readonly<Record<string, JsonValue>>;
+    readonly response: JsonValue;
+  }[] = [];
+  #serverName: string | null = null;
+  #serverVersion: string | null = null;
+  #engineVersion: string | null = null;
 
   constructor(
     options: Omit<OwnedProviderProcessSpawnOptions, "runId" | "stdin">,
@@ -53,6 +71,17 @@ export class JadxSession {
     readonly signal: AbortSignal;
   }): Promise<AnalysisExecution> {
     const { request, target, snapshot, jarHash, signal } = context;
+    this.#partialContext = {
+      operation: request.operation,
+      selectedPath: request.input.path,
+      target,
+      jarHash,
+      bridgeHash: context.bridgeHash,
+    };
+    this.#observedCalls = [];
+    this.#serverName = null;
+    this.#serverVersion = null;
+    this.#engineVersion = null;
     const abort = () => {
       void this.transport.close().catch(() => undefined);
     };
@@ -60,12 +89,13 @@ export class JadxSession {
     try {
       signal.throwIfAborted();
       this.transport.beginOperation();
-      const raw: JsonValue[] = [];
       if (!this.#connected) {
         await this.#client.connect(this.transport, { timeout: 30_000 });
         this.#connected = true;
       }
       const server = this.#client.getServerVersion();
+      this.#serverName = server?.name ?? null;
+      this.#serverVersion = server?.version ?? null;
       if (
         server?.name !== JADX_BRIDGE_IDENTITY.name ||
         server.version !== JADX_BRIDGE_IDENTITY.version
@@ -75,10 +105,11 @@ export class JadxSession {
           request.operation,
           `Expected ${JADX_BRIDGE_IDENTITY.name} ${JADX_BRIDGE_IDENTITY.version}; server reported ${server?.name ?? "unknown"} ${server?.version ?? "unknown"}.`,
         );
-      const tools = this.#tools(request, target, signal, raw);
+      const tools = this.#tools(request, target, signal);
       const runtime = jadxRuntimeSchema.parse(
         await tools.json("rea_jvm_status", {}),
       );
+      this.#engineVersion = runtime.engine_reported_version;
       if (runtime.engine_reported_version !== JADX_RELEASE.version)
         throw new AnalysisCapabilityUnavailableError(
           "jadx",
@@ -117,7 +148,7 @@ export class JadxSession {
           bridge_sha256: context.bridgeHash,
           jar_sha256: jarHash,
           loaded,
-          calls: raw,
+          calls: this.#observedCalls,
         },
         subject: target,
         limitations: JADX_LIMITATIONS,
@@ -131,6 +162,32 @@ export class JadxSession {
     }
   }
 
+  /** Facts and upstream replies retained if a later request step fails. */
+  partialObservation(): AndroidPartialObservation | undefined {
+    const context = this.#partialContext;
+    if (context === undefined) return undefined;
+    return {
+      provider_id: "jadx",
+      operation: context.operation,
+      target: {
+        selected_path: context.selectedPath,
+        path: context.target.path,
+        sha256: context.target.sha256,
+        format: "apk",
+      },
+      provider_facts: {
+        jar_sha256: context.jarHash,
+        bridge_sha256: context.bridgeHash,
+        bridge_name: JADX_BRIDGE_IDENTITY.name,
+        bridge_version: JADX_BRIDGE_IDENTITY.version,
+        server_name: this.#serverName,
+        server_version: this.#serverVersion,
+        engine_version: this.#engineVersion,
+      },
+      calls: this.#observedCalls,
+    };
+  }
+
   /** Whether the selected Java runtime established the REA bridge protocol. */
   initialized(): boolean {
     return this.#connected;
@@ -149,7 +206,6 @@ export class JadxSession {
     request: AndroidRequest,
     target: BinaryTarget,
     signal: AbortSignal,
-    raw: JsonValue[],
   ): JadxToolPort {
     const call = async (
       name: string,
@@ -160,12 +216,10 @@ export class JadxSession {
         { name, arguments: input },
         { timeout: 120_000, signal },
       );
+      const observedResponse = jsonValueSchema.parse(response);
+      const call = { operation: name, input, response: observedResponse };
+      this.#observedCalls.push(call);
       const envelope = parseJadxEnvelope(response, request.operation);
-      raw.push({
-        operation: name,
-        input,
-        response: jsonValueSchema.parse(response),
-      });
       if (envelope.failed) {
         if (envelope.text.startsWith("{")) {
           const failure = jadxInputFailureSchema.safeParse(

src/application/BinaryTargetResolver.ts

@@ -2,7 +2,7 @@ import { constants } from "node:fs";
 import { createHash } from "node:crypto";
 import {
   access,
-  open,
+  lstat,
   realpath,
   stat,
   type FileHandle,
@@ -10,6 +10,11 @@ import {
 import { extname, isAbsolute, resolve } from "node:path";
 
 import { BinaryTargetError } from "../domain/configurationErrors.js";
+import {
+  openRegularFile,
+  sameRegularFileState,
+} from "../filesystem/RegularFile.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
 import { err, ok, type Result } from "../domain/result.js";
 import {
@@ -32,6 +37,15 @@ import {
   type ExecutableMetadata,
 } from "../domain/binaryTarget.js";
 
+/** Options for resolving a local binary target and its stable identity. */
+export interface BinaryTargetResolverOptions {
+  readonly cwd?: string;
+  readonly hostArchitecture?: NodeJS.Architecture;
+  readonly targetKind?: BinaryTarget["kind"];
+  readonly formatHint?: ExecutableFormatHint;
+  readonly signal?: AbortSignal;
+}
+
 /**
  * Resolve and classify a readable local target before a provider is selected.
  * FAT Mach-O inputs select only a host-compatible architecture so setup remains
@@ -39,24 +53,34 @@ import {
  */
 export const parseBinaryTarget = async (
   input: string,
-  cwd = process.cwd(),
-  hostArchitecture: NodeJS.Architecture = process.arch,
-  targetKind?: BinaryTarget["kind"],
-  formatHint?: ExecutableFormatHint,
-): Promise<Result<BinaryTarget, BinaryTargetError>> => {
+  options: BinaryTargetResolverOptions = {},
+): Promise<
+  Result<BinaryTarget, BinaryTargetError | AnalysisCancelledError>
+> => {
+  const cwd = options.cwd ?? process.cwd();
+  const hostArchitecture = options.hostArchitecture ?? process.arch;
+  const { targetKind, formatHint, signal } = options;
   const candidate = isAbsolute(input) ? input : resolve(cwd, input);
   try {
+    throwIfTargetResolutionCancelled(signal);
     await access(candidate, constants.R_OK);
+    throwIfTargetResolutionCancelled(signal);
     const canonical = await realpath(candidate);
+    throwIfTargetResolutionCancelled(signal);
     const resolved = await resolveAppBundle(canonical);
+    throwIfTargetResolutionCancelled(signal);
     if (!resolved.ok) return err(resolved.error);
     const { executable: path, infoPlist } = resolved.value;
     const bundle =
       infoPlist === undefined ? {} : { bundleInfoPlist: infoPlist };
-    const handle = await open(path, "r");
+    const handle = await openRegularFile(path, {
+      symlinks: "reject",
+      signal,
+    });
     try {
-      if (!(await handle.stat()).isFile())
-        return err(new BinaryTargetError(path, "target is not a regular file"));
+      throwIfTargetResolutionCancelled(signal);
+      const metadata = await handle.stat();
+      throwIfTargetResolutionCancelled(signal);
       if (formatHint === "dos-com") {
         if (targetKind !== undefined && targetKind !== "executable")
           return err(
@@ -65,12 +89,12 @@ export const parseBinaryTarget = async (
               "DOS COM format requires an executable target kind",
             ),
           );
-        const length = validateDosComLength((await handle.stat()).size);
+        const length = validateDosComLength(metadata.size);
         if (!length.ok) return err(new BinaryTargetError(path, length.error));
         return ok({
           path,
           sourcePath: canonical,
-          sha256: await sha256Handle(handle),
+          sha256: await sha256Handle(handle, path, metadata, signal),
           kind: "executable",
           format: "dos-com",
           architecture: "x86",
@@ -84,28 +108,32 @@ export const parseBinaryTarget = async (
         return ok({
           path,
           sourcePath: process.platform === "win32" ? candidate : canonical,
-          sha256: await sha256Handle(handle),
+          sha256: await sha256Handle(handle, path, metadata, signal),
           kind: "database",
           format: "analysis-database",
         });
-      const artifactFormat = await detectArtifactFormat(path, handle);
+      const artifactFormat = await detectArtifactFormat(path, handle, signal);
       if (artifactFormat !== undefined) {
         const identity = {
           path,
           sourcePath: process.platform === "win32" ? candidate : canonical,
-          sha256: await sha256Handle(handle),
+          sha256: await sha256Handle(handle, path, metadata, signal),
         };
         return isArchiveFormat(artifactFormat)
           ? ok({ ...identity, kind: "archive", format: artifactFormat })
           : ok({ ...identity, kind: "artifact", format: artifactFormat });
       }
-      const detected = await readExecutableMetadata(handle, hostArchitecture);
+      const detected = await readExecutableMetadata(
+        handle,
+        hostArchitecture,
+        signal,
+      );
       if (!detected.ok) return err(new BinaryTargetError(path, detected.error));
       return ok({
         path,
         sourcePath: process.platform === "win32" ? candidate : canonical,
         ...bundle,
-        sha256: await sha256Handle(handle),
+        sha256: await sha256Handle(handle, path, metadata, signal),
         kind: "executable",
         ...detected.value,
       });
@@ -113,6 +141,8 @@ export const parseBinaryTarget = async (
       await handle.close();
     }
   } catch (cause: unknown) {
+    if (cause instanceof AnalysisCancelledError) return err(cause);
+    if (cause instanceof BinaryTargetError) return err(cause);
     if (!(cause instanceof Error)) throw cause;
     const code = filesystemErrorCode(cause);
     if (code === undefined) throw cause;
@@ -141,14 +171,24 @@ const targetFailureReason = (code: string, detail: string): string => {
       return `permission denied while reading target: ${detail}`;
     case "EISDIR":
       return `target is a directory, not a readable file: ${detail}`;
+    case "ENOTFILE":
+      return "target is not a regular file";
+    case "ELOOP":
+      return `target changed while being opened: ${detail}`;
     default:
       return `target could not be read (${code}): ${detail}`;
   }
 };
 
+const throwIfTargetResolutionCancelled = (signal?: AbortSignal): void => {
+  if (signal?.aborted === true)
+    throw new AnalysisCancelledError("resolve_binary_target");
+};
+
 const detectArtifactFormat = async (
   path: string,
   handle: FileHandle,
+  signal?: AbortSignal,
 ): Promise<
   | Exclude<
       BinaryTarget["format"],
@@ -156,9 +196,11 @@ const detectArtifactFormat = async (
     >
   | undefined
 > => {
+  throwIfTargetResolutionCancelled(signal);
   const lower = path.toLowerCase();
   const magic = Buffer.alloc(8);
   const observed = await handle.read(magic, 0, magic.length, 0);
+  throwIfTargetResolutionCancelled(signal);
   if (hasZipSignature(magic.subarray(0, observed.bytesRead))) {
     return zipPackageFormatForPath(lower) ?? "zip";
   }
@@ -171,10 +213,13 @@ const detectArtifactFormat = async (
   )
     return "pkg";
   if (lower.endsWith(".dmg")) {
+    throwIfTargetResolutionCancelled(signal);
     const size = (await handle.stat()).size;
+    throwIfTargetResolutionCancelled(signal);
     if (size >= 512) {
       const trailer = Buffer.alloc(4);
       const read = await handle.read(trailer, 0, trailer.length, size - 512);
+      throwIfTargetResolutionCancelled(signal);
       if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
         return "dmg";
     }
@@ -199,16 +244,31 @@ const isArchiveFormat = (
 ): format is Extract<BinaryTarget, { kind: "archive" }>["format"] =>
   ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(format);
 
-const sha256Handle = async (handle: FileHandle): Promise<string> => {
+const sha256Handle = async (
+  handle: FileHandle,
+  path: string,
+  initial: Awaited<ReturnType<FileHandle["stat"]>>,
+  signal?: AbortSignal,
+): Promise<string> => {
   const hash = createHash("sha256");
   const chunk = Buffer.allocUnsafe(64 * 1024);
   let position = 0;
   while (true) {
+    throwIfTargetResolutionCancelled(signal);
     const observed = await handle.read(chunk, 0, chunk.length, position);
+    throwIfTargetResolutionCancelled(signal);
     if (observed.bytesRead === 0) break;
     hash.update(chunk.subarray(0, observed.bytesRead));
     position += observed.bytesRead;
   }
+  throwIfTargetResolutionCancelled(signal);
+  const [opened, currentPath] = await Promise.all([handle.stat(), lstat(path)]);
+  if (
+    !sameRegularFileState(initial, opened) ||
+    !sameRegularFileState(initial, currentPath) ||
+    position !== initial.size
+  )
+    throw new BinaryTargetError(path, "target changed while being read");
   return hash.digest("hex");
 };
 
@@ -233,19 +293,23 @@ const resolveAppBundle = async (
 const readExecutableMetadata = async (
   handle: FileHandle,
   hostArchitecture: NodeJS.Architecture,
+  signal?: AbortSignal,
 ): Promise<Result<ExecutableMetadata, string>> => {
+  throwIfTargetResolutionCancelled(signal);
   const prefix = Buffer.alloc(4096);
   const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
+  throwIfTargetResolutionCancelled(signal);
   const bytes = prefix.subarray(0, prefixRead.bytesRead);
   // Header commitments such as Mach-O load commands and FAT slices are
   // checked against the whole file, not the probed prefix.
   const fileSize = (await handle.stat()).size;
+  throwIfTargetResolutionCancelled(signal);
   if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
     const offset = mzWindowsHeaderOffset(bytes);
     if (offset !== null) {
       if (offset < 64)
         return err("invalid Windows new-header offset in MZ image");
-      return readPeMetadata(handle, offset);
+      return readPeMetadata(handle, offset, signal);
     }
     // MZ relocation records may extend past the initial probe; their format
     // bounds are at most 65535 records inside a 65535-paragraph header.
@@ -261,6 +325,7 @@ const readExecutableMetadata = async (
     ) {
       const table = Buffer.alloc(tableEnd);
       const observed = await handle.read(table, 0, table.length, 0);
+      throwIfTargetResolutionCancelled(signal);
       return parseExecutableHeader(
         table.subarray(0, observed.bytesRead),
         hostArchitecture,
@@ -278,6 +343,7 @@ const readExecutableMetadata = async (
       if (count <= 128 && required > bytes.length) {
         const header = Buffer.alloc(required);
         const headerRead = await handle.read(header, 0, header.length, 0);
+        throwIfTargetResolutionCancelled(signal);
         return parseExecutableHeader(
           header.subarray(0, headerRead.bytesRead),
           hostArchitecture,
@@ -292,7 +358,9 @@ const readExecutableMetadata = async (
 const readPeMetadata = async (
   handle: FileHandle,
   offset: number,
+  signal?: AbortSignal,
 ): Promise<Result<ExecutableMetadata, string>> => {
+  throwIfTargetResolutionCancelled(signal);
   const fileHeader = Buffer.alloc(24);
   const fileHeaderRead = await handle.read(
     fileHeader,
@@ -300,6 +368,7 @@ const readPeMetadata = async (
     fileHeader.length,
     offset,
   );
+  throwIfTargetResolutionCancelled(signal);
   if (fileHeaderRead.bytesRead !== fileHeader.length)
     return err("invalid or truncated PE header");
   const signature = fileHeader.toString("ascii", 0, 2);
@@ -309,6 +378,7 @@ const readPeMetadata = async (
   if (optionalHeaderSize > 4096) return err("invalid PE optional header size");
   const record = Buffer.alloc(24 + optionalHeaderSize);
   const recordRead = await handle.read(record, 0, record.length, offset);
+  throwIfTargetResolutionCancelled(signal);
   return recordRead.bytesRead === record.length
     ? parsePeRecord(record)
     : err("invalid or truncated PE header");

src/application/BrowserScenarioEvidence.ts

@@ -1,4 +1,4 @@
-import { canonicalDigest } from "../domain/comparisonSemantics.js";
+import { digestCanonicalValue } from "../domain/canonicalDigest.js";
 import type { ProviderIdentity } from "./AnalysisProvider.js";
 import type { BrowserScenario } from "../domain/browserScenario.js";
 import type { BrowserScenarioCapture } from "../domain/browserScenarioCapture.js";
@@ -13,7 +13,7 @@ const browserScenarioParameters = (
   scenario: BrowserScenario,
 ): EvidenceObservation["parameters"] => ({
   ...jsonObjectSchema.parse(scenario),
-  scenario_sha256: canonicalDigest(scenario, "Browser scenario"),
+  scenario_sha256: digestCanonicalValue(scenario, "Browser scenario"),
 });
 
 /** Create Evidence without retaining resolved scenario secret values. */

src/application/ClientConfigurationDocument.ts

@@ -1037,6 +1037,47 @@ export const grokServerListedDisabled = (
   Array.isArray(document.disabled_mcp_servers) &&
   document.disabled_mcp_servers.includes(serverKey);
 
+/**
+ * OMP's user `disabledServers` denylist hides a server by name regardless of
+ * its entry, so a listed REA registration is not loaded.
+ */
+export const OMP_DISABLED_SERVERS_KEY = "disabledServers";
+
+/** Whether OMP's root `disabledServers` denylist names `serverKey`. */
+export const ompServerListedDisabled = (
+  document: Record<string, unknown>,
+  serverKey: string,
+): boolean => {
+  const listed = document[OMP_DISABLED_SERVERS_KEY];
+  return Array.isArray(listed) && listed.includes(serverKey);
+};
+
+/** OMP's user `enabledServers` allowlist overrides an entry's `enabled: false`. */
+const OMP_ENABLED_SERVERS_KEY = "enabledServers";
+
+/**
+ * Whether OMP's allowlist forces `serverKey` on despite its entry's
+ * `enabled: false`. The `disabledServers` denylist still wins over it.
+ */
+export const clientServerForcedEnabled = (
+  parsed: ClientConfigurationDocument,
+  serverKey: string,
+): boolean => {
+  if (parsed.dialect !== "omp") return false;
+  const listed = parsed.document[OMP_ENABLED_SERVERS_KEY];
+  return Array.isArray(listed) && listed.includes(serverKey);
+};
+
+/** Whether a client's own disable list suppresses `serverKey`. */
+export const clientServerListedDisabled = (
+  parsed: ClientConfigurationDocument,
+  serverKey: string,
+): boolean =>
+  (parsed.dialect === "grok" &&
+    grokServerListedDisabled(parsed.document, serverKey)) ||
+  (parsed.dialect === "omp" &&
+    ompServerListedDisabled(parsed.document, serverKey));
+
 /** Keep an existing Grok document intact aside from the REA server tables. */
 const serializeGrokConfiguration = (
   document: Record<string, unknown>,
@@ -1289,6 +1330,7 @@ export const clientRegistrationEntry = (
           : { environment: { ...environment } }),
       };
     case "vscode":
+    case "omp":
       return {
         type: "stdio",
         command: executable,

src/application/ClientRegistrationStatus.ts

@@ -1,6 +1,7 @@
 import {
+  clientServerForcedEnabled,
+  clientServerListedDisabled,
   effectiveClientServer,
-  grokServerListedDisabled,
   parseClientConfiguration,
 } from "./ClientConfigurationDocument.js";
 import { access, readFile } from "node:fs/promises";
@@ -85,7 +86,11 @@ export const readClientRegistrationStatuses = async (
           CODEX_HOME: options.environment.CODEX_HOME,
           COPILOT_HOME: options.environment.COPILOT_HOME,
           GROK_HOME: options.environment.GROK_HOME,
+          OMP_PROFILE: options.environment.OMP_PROFILE,
           OPENCODE_CONFIG: options.environment.OPENCODE_CONFIG,
+          PI_CODING_AGENT_DIR: options.environment.PI_CODING_AGENT_DIR,
+          PI_CONFIG_DIR: options.environment.PI_CONFIG_DIR,
+          PI_PROFILE: options.environment.PI_PROFILE,
           SAND_DATA_ROOT: options.environment.SAND_DATA_ROOT,
           XDG_CONFIG_HOME: options.environment.XDG_CONFIG_HOME,
         },
@@ -132,14 +137,9 @@ export const readClientRegistrationStatuses = async (
             client,
             currentCommandPath,
             options.platform ?? process.platform,
+            clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey),
           ) &&
-            !(
-              client.format === "grok" &&
-              grokServerListedDisabled(
-                parsed.document,
-                PRODUCT_IDENTITY.mcpServerKey,
-              )
-            )
+            !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
             ? "aligned"
             : "stale",
         ),
@@ -164,9 +164,13 @@ const registrationAligned = (
   client: SetupClient,
   currentCommandPath: string,
   platform: NodeJS.Platform,
+  forcedEnabled = false,
 ): boolean => {
   const command = [registration.command, ...registration.args];
-  if (registration.disabled === true || registration.enabled === false)
+  if (
+    registration.disabled === true ||
+    (registration.enabled === false && !forcedEnabled)
+  )
     return false;
   if (!isOwnedClientRegistrationCommand(command, currentCommandPath))
     return false;
@@ -177,6 +181,13 @@ const registrationAligned = (
   )
     return false;
   if (client.format === "vscode" && registration.type !== "stdio") return false;
+  // OMP infers stdio for a command entry without an explicit type.
+  if (
+    client.format === "omp" &&
+    registration.type !== undefined &&
+    registration.type !== "stdio"
+  )
+    return false;
   if (
     client.format === "copilot_cli" &&
     (registration.type !== "stdio" ||
@@ -233,6 +244,12 @@ const parseRegistration = (
     throw new TypeError("Expected an stdio registration");
   if (client.format === "commandcode" && registration.transport !== "stdio")
     throw new TypeError("Expected an stdio registration");
+  if (
+    client.format === "omp" &&
+    registration.type !== undefined &&
+    registration.type !== "stdio"
+  )
+    throw new TypeError("Expected an stdio registration");
   return registration;
 };
 

src/application/DirectAnalysis.ts

@@ -201,6 +201,7 @@ const runAnalysis = async (
       const prepared = await prepareSnapshot({
         path,
         snapshotPath,
+        signal,
         ...(options.formatHint === undefined
           ? {}
           : { formatHint: options.formatHint }),
@@ -268,7 +269,8 @@ const runAnalysis = async (
       });
       if (evidence !== undefined) {
         const recorded = session.recordEvidence(evidence);
-        if (!recorded.ok) return cliError(recorded.error);
+        if (!recorded.ok)
+          return cliError(recorded.error.retainPartialObservation(evidence));
         if (isWorkflowEvidenceTool(tool)) {
           const unknowns = recordWorkflowUnknowns({
             name: tool,
@@ -276,7 +278,8 @@ const runAnalysis = async (
             evidenceId: evidence.evidence_id,
             recordUnknown: (unknown) => session.recordUnknown(unknown),
           });
-          if (!unknowns.ok) return cliError(unknowns.error);
+          if (!unknowns.ok)
+            return cliError(unknowns.error.retainPartialObservation(evidence));
         }
       }
       if (
@@ -289,7 +292,8 @@ const runAnalysis = async (
         const workflowRecord = workflowSnapshotRecord(evidence, tool);
         if (workflowRecord !== undefined) {
           const recorded = session.recordWorkflowSnapshot(workflowRecord);
-          if (!recorded.ok) return cliError(recorded.error);
+          if (!recorded.ok)
+            return cliError(recorded.error.retainPartialObservation(evidence));
         }
       }
       if (
@@ -298,13 +302,15 @@ const runAnalysis = async (
         evidence !== undefined
       ) {
         const snapshot = session.exportAnalysisSnapshot();
-        if (!snapshot.ok) return cliError(snapshot.error);
+        if (!snapshot.ok)
+          return cliError(snapshot.error.retainPartialObservation(evidence));
         const written = await writeAnalysisSnapshot(
           snapshot.value,
           snapshotPath,
           true,
         );
-        if (!written.ok) return cliError(written.error);
+        if (!written.ok)
+          return cliError(written.error.retainPartialObservation(evidence));
       }
       return output;
     },
@@ -434,6 +440,7 @@ const prepareSnapshot = async (options: {
   readonly path: string;
   readonly formatHint?: ExecutableFormatHint;
   readonly snapshotPath: string | undefined;
+  readonly signal: AbortSignal;
 }): Promise<
   Result<
     { readonly snapshot?: AnalysisSnapshot; readonly target?: BinaryTarget },
@@ -445,13 +452,12 @@ const prepareSnapshot = async (options: {
     return ok({});
   const loaded = await readAnalysisSnapshot(snapshotPath);
   if (!loaded.ok) return loaded;
-  const target = await parseBinaryTarget(
-    path,
-    process.cwd(),
-    process.arch,
-    undefined,
-    options.formatHint,
-  );
+  const target = await parseBinaryTarget(path, {
+    signal: options.signal,
+    ...(options.formatHint === undefined
+      ? {}
+      : { formatHint: options.formatHint }),
+  });
   if (!target.ok) return target;
   if (!snapshotMatchesTarget(loaded.value.target, target.value))
     return err(

src/application/DirectAnalysisCleanup.ts

@@ -55,7 +55,6 @@ export const directAnalysisCleanupFailure = (
             "execution_failure" in primary.data.details
               ? (primary.data.details.execution_failure ?? primary.data.code)
               : primary.data.code,
-          primary_error: projection,
           cleanup_error: cleanup,
         },
       };

src/application/DirectAnalysisStatus.ts

@@ -5,7 +5,8 @@ import { silentLogger } from "../logger.js";
 import type { Logger } from "pino";
 import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
 
-const runSessionStatus = async (
+/** Read target-free provider status and operation availability. */
+export const runSessionStatus = async (
   dependencies: Pick<
     DirectAnalysisDependencies,
     "createBinarySession" | "readConfiguration"
@@ -26,21 +27,3 @@ const runSessionStatus = async (
     await session.close();
   }
 };
-
-/** List binary-session provider candidates and auxiliary operation availability. */
-export const runProviderStatus = (
-  dependencies: Pick<
-    DirectAnalysisDependencies,
-    "createBinarySession" | "readConfiguration"
-  >,
-  logger: Logger = silentLogger,
-) => runSessionStatus(dependencies, logger);
-
-/** List binary-session operation descriptors; this is not the full MCP catalog. */
-export const runCapabilityStatus = (
-  dependencies: Pick<
-    DirectAnalysisDependencies,
-    "createBinarySession" | "readConfiguration"
-  >,
-  logger: Logger = silentLogger,
-) => runSessionStatus(dependencies, logger);

src/application/Doctor.fixture.ts

@@ -27,7 +27,6 @@ export const createDoctorHostFixture = (
     Promise.resolve({
       version: PRODUCT_IDENTITY.skillVersion,
       toolCount: CATALOG_IDENTITY.counts.mcp_tools,
-      catalogDigest: null,
       canonical: true,
     }),
   ...overrides,

src/application/Doctor.test.ts

@@ -22,7 +22,7 @@ describe("doctor", () => {
       ),
     ).toEqual({
       node: `Install ${SUPPORTED_NODE_VERSION_PROSE}.`,
-      host: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
+      host: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
       hopper: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
       target: "Supply a readable local app or program path.",
     });
@@ -176,7 +176,6 @@ describe("doctor installation identity", () => {
           Promise.resolve({
             version: "10",
             toolCount: null,
-            catalogDigest: null,
             canonical: false,
           }),
       }),

src/application/Doctor.ts

@@ -1,9 +1,10 @@
 import { constants } from "node:fs";
-import { access, readFile, readdir } from "node:fs/promises";
+import { access, readdir } from "node:fs/promises";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { join } from "node:path";
 
 import { analysisErrorRemediationAction } from "../domain/analysisErrorPresentation.js";
+import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { parseBinaryTarget } from "./BinaryTargetResolver.js";
 import { execFileOutput } from "../process/ExecFileOutput.js";
 import type { JsonValue } from "../domain/jsonValue.js";
@@ -14,7 +15,11 @@ import {
   readLinuxDistribution,
   type LinuxDistribution,
 } from "./LinuxHopper.js";
-import { canonicalSkillNeedsInstall } from "./SetupSkill.js";
+import {
+  claudeCodeSkillsDirectory,
+  readInstalledSkillIdentity,
+  type InstalledSkillIdentity,
+} from "./SetupSkill.js";
 import { CATALOG_IDENTITY } from "../catalogIdentity.js";
 import { PRODUCT_IDENTITY, SDK_IDENTITY } from "../identity.js";
 import {
@@ -91,20 +96,13 @@ export interface DoctorHost {
   manualHopperPaths(): Promise<readonly string[]>;
   providerInspections?(): Promise<readonly DoctorProviderInspection[]>;
   installationPaths?(): Promise<readonly string[]>;
-  installedSkillIdentity?(): Promise<InstalledSkillIdentity | undefined>;
+  installedSkillIdentity?(
+    clientIds: readonly string[],
+  ): Promise<InstalledSkillIdentity | undefined>;
   clientRegistrations?(): Promise<readonly ClientRegistrationStatus[]>;
   ilspyCmdVersion?(path: string): Promise<string | undefined>;
 }
 
-/** Observed skill metadata and comparison with the packaged instruction bundle. */
-interface InstalledSkillIdentity {
-  readonly version: string | null;
-  readonly toolCount: number | null;
-  readonly catalogDigest: string | null;
-  /** Whether all managed instruction and reference files match this package. */
-  readonly canonical: boolean;
-}
-
 /** Structured result returned by the read-only doctor workflow. */
 export interface DoctorReport {
   readonly healthy: boolean;
@@ -142,8 +140,6 @@ interface DoctorIdentity {
   readonly skill: {
     readonly installed_version: string | null;
     readonly installed_tool_count: number | null;
-    /** Legacy catalog digest observed in older bundles; current bundles omit it. */
-    readonly installed_catalog_digest: string | null;
     readonly state: "aligned" | "stale" | "missing";
     readonly remediation: string | null;
   };
@@ -160,12 +156,13 @@ export const runDoctor = async (
   host: DoctorHost = systemDoctorHost(),
   requestedScope?: DoctorScope,
 ): Promise<DoctorReport> => {
+  const scope = normalizeDoctorScope(requestedScope, target);
   const {
     checks: diagnosticChecks,
     hopperPath,
     providerInspections,
   } = await collectDoctorDiagnostics(target, host);
-  const identity = await collectDoctorIdentity(host);
+  const identity = await collectDoctorIdentity(host, scope);
   const checks = [...diagnosticChecks, ...identity.checks];
   const providers = {
     hopperAvailable:
@@ -177,7 +174,6 @@ export const runDoctor = async (
     providerInspections,
   };
   const environmentHealthy = doctorHealthy(checks, providers);
-  const scope = normalizeDoctorScope(requestedScope, target);
   const scoped = scopeDoctorChecks({
     checks,
     registrations: identity.value.registrations,
@@ -201,14 +197,20 @@ export const runDoctor = async (
 
 const collectDoctorIdentity = async (
   host: DoctorHost,
+  scope: DoctorScopeReport,
 ): Promise<{
   readonly checks: readonly DoctorCheck[];
   readonly value: DoctorIdentity;
 }> => {
   const installationPaths = (await host.installationPaths?.()) ?? [];
-  const installedSkillIdentity = await host.installedSkillIdentity?.();
-  const skillAligned = skillIdentityAligned(installedSkillIdentity);
   const registrations = (await host.clientRegistrations?.()) ?? [];
+  const skillClientIds =
+    scope.mode === "audit-wide"
+      ? registrations.map(({ client }) => client)
+      : scope.clients;
+  const installedSkillIdentity =
+    await host.installedSkillIdentity?.(skillClientIds);
+  const skillAligned = skillIdentityAligned(installedSkillIdentity);
   return {
     checks: [
       ...(skillAligned ? [] : [skillIdentityCheck(installedSkillIdentity)]),
@@ -236,7 +238,6 @@ const collectDoctorIdentity = async (
       skill: {
         installed_version: installedSkillIdentity?.version ?? null,
         installed_tool_count: installedSkillIdentity?.toolCount ?? null,
-        installed_catalog_digest: installedSkillIdentity?.catalogDigest ?? null,
         state:
           installedSkillIdentity === undefined
             ? "missing"
@@ -324,10 +325,18 @@ export const systemDoctorHost = (
       readMacosVersion(hostExecFileOutput, commandEnvironment),
     linuxDistribution: readLinuxDistribution,
     async validTarget(path) {
-      return (await parseBinaryTarget(path, process.cwd(), architecture)).ok;
+      return (
+        await parseBinaryTarget(path, {
+          cwd: process.cwd(),
+          hostArchitecture: architecture,
+        })
+      ).ok;
     },
     async inspectTarget(path) {
-      const result = await parseBinaryTarget(path, process.cwd(), architecture);
+      const result = await parseBinaryTarget(path, {
+        cwd: process.cwd(),
+        hostArchitecture: architecture,
+      });
       if (result.ok)
         return {
           name: "target",
@@ -336,19 +345,21 @@ export const systemDoctorHost = (
           detail: path,
         };
       const error = result.error;
+      const targetError =
+        error instanceof BinaryTargetError ? error : undefined;
       return {
         name: "target",
         ok: false,
         classification:
-          error.constraint === "directory_requires_file"
+          targetError?.constraint === "directory_requires_file"
             ? "unsupported_target"
             : "config_drift",
         detail: path,
         details: {
-          reason: error.reason,
-          ...(error.constraint === undefined
+          reason: targetError?.reason ?? error.message,
+          ...(targetError?.constraint === undefined
             ? {}
-            : { constraint: error.constraint }),
+            : { constraint: targetError.constraint }),
         },
         remediation: analysisErrorRemediationAction(error),
       };
@@ -426,7 +437,12 @@ export const systemDoctorHost = (
         return [];
       }
     },
-    installedSkillIdentity: () => installedSkillIdentity(homeDirectory),
+    installedSkillIdentity: (clientIds) =>
+      readInstalledSkillIdentity(
+        homeDirectory,
+        clientIds,
+        claudeCodeSkillsDirectory(homeDirectory, environment),
+      ),
     clientRegistrations: () =>
       readClientRegistrationStatuses(homeDirectory, undefined, {
         platform,
@@ -491,34 +507,6 @@ const manualHopperPaths = async (home: string): Promise<readonly string[]> => {
   return paths;
 };
 
-const readInstalledSkill = (home: string): Promise<string> =>
-  readFile(
-    join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
-    "utf8",
-  );
-
-const installedSkillIdentity = async (
-  home: string,
-): Promise<InstalledSkillIdentity | undefined> => {
-  try {
-    const content = await readInstalledSkill(home);
-    const countText = /^\s{2}tool_count:\s*(\d+)\s*$/mu.exec(content)?.[1];
-    return {
-      canonical: !(await canonicalSkillNeedsInstall(home)),
-      version: /^\s{2}version:\s*"([^"]+)"\s*$/mu.exec(content)?.[1] ?? null,
-      toolCount:
-        countText === undefined ? null : Number.parseInt(countText, 10),
-      catalogDigest:
-        /^\s{2}catalog_digest:\s*"([a-f0-9]{64})"\s*$/mu.exec(content)?.[1] ??
-        null,
-    };
-  } catch (cause: unknown) {
-    // best-effort cleanup: optional skill probing; failure means unknown.
-    void cause;
-    return undefined;
-  }
-};
-
 const uniqueLines = (value: string): string[] => [
   ...new Set(
     value

src/application/DoctorDiagnostics.ts

@@ -113,7 +113,7 @@ const hostCheck = async (host: DoctorHost): Promise<DoctorCheck> => {
       : `${linuxDistribution.id} ${linuxDistribution.versionId ?? "unknown"}`);
   return check("host", supported, detail, {
     remediation:
-      "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
+      "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, Nobara 44+, 64-bit Arch Linux, CachyOS, and the experimental Windows x64 Ghidra P0 boundary.",
     classification: "unsupported_host",
   });
 };

src/application/EvidenceBundleFiles.ts

@@ -9,7 +9,10 @@ import {
   EvidenceIntegrityError,
 } from "../domain/evidenceErrors.js";
 import { err, ok, type Result } from "../domain/result.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import {
+  AnalysisCancelledError,
+  type AnalysisResourceConstraintError,
+} from "../domain/analysisErrorCore.js";
 import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
 import {
   bufferedJsonParts,
@@ -17,7 +20,10 @@ import {
 } from "../domain/jsonSerialization.js";
 import { readJsonFile, writeTextParts } from "./JsonFiles.js";
 
-type EvidenceReadFailure = EvidenceFileError | EvidenceIntegrityError;
+type EvidenceReadFailure =
+  | EvidenceFileError
+  | EvidenceIntegrityError
+  | AnalysisResourceConstraintError;
 type EvidenceWriteFailure =
   | EvidenceFileError
   | EvidenceIntegrityError

src/application/InvestigationProviders.ts

@@ -24,18 +24,18 @@ export const workflowAnalysisProfile = (
   });
 
 /** Provider identity for deterministic artifact inventories. */
-export const ARTIFACT_GRAPH_PROVIDER = {
+export const ARTIFACT_GRAPH_PROVIDER = Object.freeze({
   id: "rea-artifact-graph",
   name: "REA safe artifact graph provider",
   version: "1",
-} as const;
+} as const);
 
 /** Provider identity for execution-free managed PE/CLI analysis. */
-export const MANAGED_STATIC_PROVIDER = {
+export const MANAGED_STATIC_PROVIDER = Object.freeze({
   id: "rea-dotnet-static",
   name: "REA managed static analysis provider",
   version: "1",
-} as const;
+} as const);
 
 /** Provider identity for deterministic managed-code comparison workflows. */
 export const MANAGED_WORKFLOW_PROVIDER = {