fix(docs): update browser capture guide link after move (#2820 )

Refresh gettext protected-link comments alongside the authored href. Co-authored-by: Codex <noreply@openai.com>
chore(merge): refresh PR #2791 with CI repair checkpoint
2026-10-14 06:55:59 +08:00 · 2026-10-14 03:10:44 +08:00 · 2026-10-14 02:39:03 +08:00 · 2026-10-14 02:30:44 +08:00 · 2026-10-14 02:23:57 +08:00 · 2026-10-14 02:17:57 +08:00
581 changed files with 26894 additions and 3847 deletions
@@ -6,7 +6,7 @@ description: Prepare or rewrite REA release changelogs and GitHub release notes
 # REA changelog update

 Use this for release-note preparation and contributor attribution. Read
-[docs/releasing.md](../../../docs/releasing.md) from the repository root for
+[docs/development/releasing.md](../../../docs/development/releasing.md) from the repository root for
 publication authority and the existing checkpoint checks. This skill prepares
 notes; it does not authorize merging, tagging, or publishing.

@@ -0,0 +1,112 @@
+---
+name: rea-ci-tests-audit
+description: Audit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.
+---
+
+# REA CI and tests audit
+
+Establish which checks still catch real regressions and which costs can be
+removed without losing that protection. The outcome may be a verified fix,
+an evidence-backed recommendation, or an explicit decision to stop.
+
+Follow the checkout's `AGENTS.md`, [testing guide](../../../docs/development/testing.md),
+and [contribution rules](../../../CONTRIBUTING.md). Use their current commands
+and pinned toolchain, rather than commands remembered from an earlier audit.
+Preserve the requested scope: investigation alone does not authorize edits;
+this skill does not grant permission to publish issues, push, or merge. Existing
+user authorization still applies. Keep audit notes and raw results outside the
+tracked tree, normally in a task-specific `/tmp` directory.
+
+## Establish the executed baseline
+
+Fetch when the user asks for latest main. Pin the baseline SHA and inspected
+workflow revision; use an isolated worktree when changing or comparing code.
+Do not modify another task's checkout. Record dirty changes and the exact
+command, toolchain, host, selected tests, instrumentation, and prerequisites.
+An old run is evidence for its executed revision, even if main advances.
+
+Trace workflow triggers, changed-path selection, job dependencies, reusable
+actions, package scripts, test discovery, artifact producers, and report gates
+through to the commands that actually execute. Include scripts, generated data,
+runtime registration, and subprocess boundaries missing from import graphs.
+Check positive and negative selection paths: required files must be discovered
+once per intended test configuration; deliberate platform/configuration repeats
+are separate coverage. A missing explicit test or missing required report must
+not turn green. Optional lanes may skip; preserve their stated prerequisites.
+
+Use existing timing and failure artifacts to select suspicious families. Run
+relevant checks to establish a baseline; reserve a full local suite for broad
+CI diagnosis or uncertainty that focused checks cannot resolve. Do not rebuild
+or rerun an unchanged complete suite after every documentation edit.
+
+## Prove the failure or protection
+
+For each candidate, state the expected observable behavior and its owner,
+then construct the smallest reproduction against production behavior. Follow
+the producer and affected consumers before deciding where to fix it.
+
+- For drift, compare fixtures with current admission requirements, protocol
+  replies, named contracts, tool versions, and actual public entrypoints. A
+  plausible-looking mock can fail before the behavior its test claims to cover.
+  Search the whole affected fixture family, including other version strings.
+  Preserve intentionally malformed fixtures and test their intended rejection.
+- For a suspicious green test, perturb the relevant behavior in an isolated
+  copy or inject a controlled failure. Verify that the existing assertion or
+  gate detects it. A test may merely repeat its mock, import abandoned code,
+  or hide a subprocess/checker failure. Restore mutations after the experiment.
+- For shared setup or pruning, map distinct assertions to their retained
+  scenarios. Preserve malformed inputs, cancellation, cleanup failure,
+  permissions, capacity, identity, and meaningful concurrency interactions.
+  A faster run that skips a case or weakens its oracle is not an improvement.
+- For provider coverage, separate fake-producer, boundary, and actual-engine
+  evidence. Inspect named skips and prerequisites; fixtures do not establish
+  real Ghidra, LLDB, browser, or other provider behavior.
+
+Classify findings as reproduced defects, supported costs, hypotheses, or
+unavailable evidence. Record the baseline command, observed output/exit status,
+expected result, affected scope, and competing explanation. A failure on main
+may be pre-existing; that does not by itself make it irrelevant to a CI audit.
+Attribute PR failures using the executed revision and a clean baseline, not
+just their resemblance to a previous failure. Retry only to test a specific
+transient explanation; retain the original failure and stop when repetition
+adds no evidence. A passing retry does not establish a root cause or a fix.
+
+## Assess efficiency without losing the gate
+
+Read [measurement and CI checks](references/measurement-and-ci.md) when
+investigating slowness, caching, runner waits, shared artifacts, or log noise.
+Compare equivalent completed work before claiming a speedup. Distinguish
+setup/build time, test execution, coverage instrumentation, dependency waits,
+and runner scheduling; state which costs remain unmeasured.
+
+Prefer removing proven duplicate preparation, reusing immutable setup, and
+reducing repeated subprocess work before shrinking correctness coverage.
+Preserve independent sessions where lifecycle or concurrency is the oracle.
+Keep live tests fresh; a cached previous pass cannot validate current host,
+installed provider contents, permissions, or external state.
+
+## Fix, verify, and hand off within scope
+
+If implementation is authorized, make the smallest structural change at the
+owning boundary and add a regression that fails on the baseline for the right
+reason. Retest affected consumers and meaningful negative paths; verify cache
+invalidation or discovery when those mechanisms change. Read the installed
+Turbo documentation before changing its configuration or commands.
+
+Run the repository's applicable checks and inspect complete current-head CI
+results before an authorized merge. Preserve required coverage and discovery
+gates. Do not suppress a failure, add blanket retries, raise timeouts, or delete
+distinct assertions solely to make CI green. Changes to these controls need
+their own demonstrated reason and retained failure detection.
+
+Report each confirmed issue with exact revision, reproduction, consequence,
+proposed correction, and validation limits. Report performance with workload
+and measurements, not just a percentage. Use English issue/PR records when
+requested; follow the user's assignment, commit identity, review, and merge
+preferences without assuming them for other users. Open ready-for-review PRs
+only when that lifecycle is authorized. Resolve necessary review findings and
+check final main against the tested tree after merging.
+
+Stop when the authorized work is verified, remaining benefits are unproven,
+or further changes would trade correctness for speculative speed. List genuine
+uncertainties without turning them into additional optimization rounds.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "REA CI and tests audit"
+  short_description: "Audit CI/test correctness and measured performance"
+  default_prompt: "Use $rea-ci-tests-audit to investigate CI and test correctness, drift, and performance before proposing changes."
@@ -0,0 +1,65 @@
+# Measurement and CI checks
+
+## Equivalent completed work
+
+Record the source/workflow SHA, command, test identities and counts, skips,
+assertions or output contract, exit status, coverage scope and thresholds,
+toolchain/provider versions, host resources, and prepared artifacts. Inspect
+both the child result and its report: a profiling wrapper may exit successfully
+after the measured command failed. Focused tests can pass while global coverage
+thresholds fail; describe both rather than calling the command green.
+
+Measure wall time, user/system CPU, and peak process-family memory for relevant
+completed tasks. Parent-only RSS misses workers and their children. On Linux,
+summed RSS can double-count shared pages; report RSS/PSS semantics, sampling
+interval, missing samples, and observed cleanup limits. Use equivalent host
+tools elsewhere. State unknown costs, including agent tokens; fewer log bytes
+alone prove neither fewer tokens nor faster tests.
+
+Separate cold execution, warm build/file caches, and warm runtime caches.
+Use repeated or alternating runs when variance affects the decision, with
+enough observations to distinguish the proposed benefit from noise. Keep
+workload, instrumentation, and host conditions comparable; record interference.
+A run with fewer tests, early rejection, lost coverage, or a different runner
+does not prove suite acceleration. CI-wide claims need end-to-end measurements,
+not an extrapolation from one improved family.
+
+## Workflow, caches, and shared artifacts
+
+Trace each reused result from producer to consumers and identify its lifetime.
+Check key/input coverage against the actual file inventory and result-affecting
+configuration, environment, generated data, tool versions, and host state.
+Exercise an affected input change to prove invalidation; exercise an irrelevant
+change to support reuse where useful. Cache deterministic preparation and
+static analysis only when their inputs fully describe the result.
+
+Verify downloaded artifacts match the expected revision, platform, runtime,
+and schema. Check restore misses, failed/partial producers, stale reports,
+removed output files, and consumers after producer failures. Shared writers
+need output ownership or locks; tests need isolated state, not an unnecessary
+global lock. Worker counts do not bound children spawned within each test.
+Preserve intentionally concurrent scenarios while bounding unrelated batches.
+
+Check matrix expansion and all job pages before saying CI passed. Inspect
+required gates after failed, cancelled, and skipped dependencies. `always()`
+alone does not preserve failures; inspect the aggregation logic. Test/report
+uploads should retain available diagnostics after failure, while absent or
+malformed required results must fail closed. Do not demand an optional report
+from a lane intentionally excluded by the selector.
+
+## Runner waits and console noise
+
+Use per-job and per-step timestamps where available. Workflow creation to job
+start includes dependencies and other delays; it is not necessarily runner
+queue time. Identify when the job became eligible before attributing waits to
+runner capacity. If eligibility/queue timestamps are unavailable, report the
+combined delay and unknown split. Compare equivalent lanes and runner types
+across enough runs; a single busy runner is not a workflow regression.
+
+For console reductions, retain checker exit codes, actionable errors, useful
+summary counts, and complete machine-readable artifacts. Verify authored code
+remains in the actual checker inventory when excluding generated outputs.
+Introduce an authored error as a control; it must still fail. An ignore pattern
+can hide real source as well as noise. Show that cached reports are restored,
+stale successful reports cannot mask current failures, and report parse errors
+remain failures. Measure readability or byte reduction separately from runtime.
@@ -5,7 +5,7 @@ description: Design or change REA investigation tools, CLI/MCP contracts, provid

 # REA tool design

-Use the [tool-design guide](../../../docs/tool-design.md) for tool boundaries,
+Use the [tool-design guide](../../../docs/development/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.
@@ -14,7 +14,7 @@ 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 implementation or verification, consult [testing](../../../docs/development/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.
@@ -56,7 +56,7 @@ explicit path or endpoint and do not need it.
 - Firmware image: `inspect_firmware_regions` when advertised. Use
  `extract_firmware` when extraction is requested, with a caller-selected new
  absolute output directory. These tools use caller-supplied Binwalk/Unblob on
-  Linux; see the [firmware guide](https://github.com/morluto/rea/blob/main/docs/firmware-analysis.md).
+  Linux; see the [firmware guide](https://github.com/morluto/rea/blob/main/docs/guides/firmware/firmware-analysis.md).
 - .NET NativeAOT PE/ELF: native Ghidra analysis. Native code can yield pseudocode;
  consult the NativeAOT workflow in `references/native-and-artifacts.md` for
  optional metadata recovery and its supported host/layout boundary.
@@ -68,7 +68,7 @@ explicit path or endpoint and do not need it.
 - Retained HAR/SAZ/native mitmproxy/aioquic qlog capture: `inspect_web_network_capture`. Select
  original record ordinals when useful; inspect producer fields and byte/number
  sidecars without fetching recorded URLs or claiming live attribution. See
-  [historical captures](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md) for the exact upstream
+  [historical captures](https://github.com/morluto/rea/blob/main/docs/guides/web/web-network-captures.md) for the exact upstream
  profile and credential exclusions. Qlog support starts with aioquic 1.5.0
  JSON 0.3; stream coverage and endpoint loss declarations do not recover bodies
  or establish network loss. Prefer detail summary, then kind qlog trace/stream
@@ -81,7 +81,7 @@ explicit path or endpoint and do not need it.
  Query/page the relevant records; registrations do not establish observed traffic.
 - Recorded packet captures: `inspect_packet_capture` with selected TShark fields,
  display filters and decode-as rules. Requires Linux, util-linux prlimit and `REA_TSHARK_COMMAND`; see
-  [capture guide](https://github.com/morluto/rea/blob/main/docs/packet-captures.md).
+  [capture guide](https://github.com/morluto/rea/blob/main/docs/guides/data/packet-captures.md).
  Packet limits count input packets before filtering. Output defaults to 50 matching
  frames; use `match_offset` / `match_limit` for later pages, or explicit null
  limit for complete matching output. Preserve the source digest across pages.
@@ -89,7 +89,7 @@ explicit path or endpoint and do not need it.
  For address/DNS/SNI/protocol summaries use `inspect_pcap_capture` with MCP
  detail summary, then retained kind pcap pages. Requires Wireshark 4.x tshark
  and capinfos, with Linux prlimit or Windows Job Objects; see
-  [packet summaries](https://github.com/morluto/rea/blob/main/docs/pcap-analysis.md).
+  [packet summaries](https://github.com/morluto/rea/blob/main/docs/guides/data/pcap-analysis.md).
  Select an exact DNS question for address pages; page exhaustion does not prove
  network completeness. This reads recordings and does not acquire traffic.
 - Decoder discovery: `inspect_signal_decoders` searches installed decoder IDs
@@ -97,7 +97,7 @@ explicit path or endpoint and do not need it.
  relevant details before choosing settings; this does not scan hardware.
 - Recorded logic/signal traces: `decode_signal_recording` with explicit decoder,
  channel and protocol settings. On Linux with util-linux prlimit, supply sigrok-cli 0.7.2 through
-  `REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/signal-recordings.md).
+  `REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/guides/signals/signal-recordings.md).
  Output defaults to 50 literal lines; select annotation classes and page with
  `line_offset` / `line_limit`, or explicit null for all remaining output.
  Window counts are display lines, not annotations or samples. Preserve source digests across pages.
@@ -106,7 +106,7 @@ explicit path or endpoint and do not need it.
  through `REA_WABT_BIN_DIRECTORY`; retain exact byte/tool identity and decoded WAT.
  Select JavaScript glue and candidate paths explicitly and preserve URL/path
  ambiguity. No implicit fetch or target execution; WAT is not original source.
-  See the [WASM guide](https://github.com/morluto/rea/blob/main/docs/wasm-artifacts.md).
+  See the [WASM guide](https://github.com/morluto/rea/blob/main/docs/guides/wasm/wasm-artifacts.md).
 - Explicit local EVM bytecode carrier: `inspect_evm_interface` with caller-selected
  `raw` or `hex` encoding. Preserve carrier/decoded digests and treat selectors,
  argument strings and mutability as inferred candidates; this performs no chain
@@ -115,13 +115,13 @@ explicit path or endpoint and do not need it.
  Evidence stays retained under its original identity. Use the returned
  `parent_evidence_id` for exact function or `bytecode_hex`/stdout/stderr pages.
  Candidate coverage does not establish interface completeness. See the
-  [EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/evm-bytecode.md).
+  [EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/guides/evm/evm-bytecode.md).
 - Embedded Go compiler, module or build-setting metadata: `inspect_go_binary`
  with the explicit local file. This built-in target-free inspection requires no
  Go installation or disassembler. Preserve raw module bytes and source ranges;
  absent metadata does not prove a binary is not Go, and unparsed text records
  remain explicit. See the
-  [Go binary guide](https://github.com/morluto/rea/blob/main/docs/go-binaries.md).
+  [Go binary guide](https://github.com/morluto/rea/blob/main/docs/guides/native/go-binaries.md).

 - Explicit local SQLite database snapshot: `inspect_sqlite_database`. Inspect
  with Node.js 24.x >=24.15 or 26+ providing native SQLite limits. Read schema
@@ -130,17 +130,17 @@ explicit path or endpoint and do not need it.
  20 rows; request `schema_scope: "database"` for the complete stored schema. Preserve both database and existing sibling WAL identity; row samples
  report truncation and have unspecified order. Use a quiescent snapshot rather
  than assuming a live database/WAL pair was copied atomically. See the
-  [SQLite guide](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
+  [SQLite guide](https://github.com/morluto/rea/blob/main/docs/guides/data/sqlite-databases.md).
 - Explicit Linux ELF file for offline layout, symbols, relocations or static
  mitigation evidence: `inspect_binary_layout`. This target-free operation uses
  caller-supplied pwntools without opening a disassembler database. Preserve its
  raw locations and inference/coverage limits; see the
-  [offline binary guide](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
+  [offline binary guide](https://github.com/morluto/rea/blob/main/docs/guides/native/binary-diagnostics.md).
 - Supplied Linux x86-64 ELF core: `inspect_recorded_crash`. Read every recorded
  thread, raw note and source-bound register without opening a live target.
  Historical PIDs do not select live processes. Request `include_debugger_context`
  only when core-only mapping candidates help; see the
-  [recorded crash guide](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md).
+  [recorded crash guide](https://github.com/morluto/rea/blob/main/docs/guides/native/recorded-crashes.md).
 - PE resource type/name/language trees and static icon group references:
  `inspect_pe_resources` with an explicit path. This portable operation requires
  no active target or engine; opaque payloads retain file ranges and SHA-256.
@@ -154,7 +154,7 @@ The legacy attached profile binds the already-open GUI input by SHA-256 and
 leaves its database open. The modern headless profile creates and closes an
 owned private database without saving. Installation and registration reuse
 [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp); see the
-[IDA provider guide](https://github.com/morluto/rea/blob/main/docs/ida-provider.md).
+[IDA provider guide](https://github.com/morluto/rea/blob/main/docs/providers/ida-provider.md).
 Proceed directly to `analyze_function`, pseudocode, or function/string searches
 after opening; IDA does not supply `binary_overview`. Consult session availability
 when composing broader workflows. Modern direct callers and unsupported dossier
@@ -6,7 +6,7 @@ For captured or bundled JavaScript that needs readable source recovery, use
 `additional_paths` when advertised, then analyze the returned `analysis_input`
 directory together. Each input retains its own snapshot, digest and byte-range
 provenance; inputs and recovered code are never executed. Recovery requires a
-caller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/javascript-recovery.md).
+caller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/guides/javascript/javascript-recovery.md).

 Use `analyze_javascript_application` directly on the operator-supplied ASAR or
 extracted tree. When the question concerns known source paths and the connected
@@ -24,7 +24,7 @@ Choose `row_limit` when a finite sample is useful and keep truncation and
 unspecified row order explicit. Virtual tables, shadow tables and views are
 schema facts, not row-read targets. REA inspects private copies and leaves
 the source files untouched; obtain a coherent quiescent database/WAL snapshot
-before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
+before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/guides/data/sqlite-databases.md).

 ## Recorded Linux crashes

@@ -39,7 +39,7 @@ The optional `include_debugger_context` facet adds mapping candidates through
 caller-supplied GDB/pwndbg in an owned core-only session. Display names do not
 establish current file identity; zero reported flags leave permissions unknown.
 Requested unavailable context fails with setup guidance. See
-[recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
+[recorded crashes](https://github.com/morluto/rea/blob/main/docs/guides/native/recorded-crashes.md)
 for exact upstream profiles, bounds and verification coverage.

 ## Offline ELF layout
@@ -175,8 +175,10 @@ additional evidence only when the provider accepts and matches them.
 REA has a built-in read-only snapshot parser for x64 PE targets with .NET 8 RTR
 9.1 metadata. An optional headless Ghidra adapter adds database annotations and
 broader metadata recovery on Linux; it requires an explicitly configured
-NativeAOT JAR. These are separate routes. See the
-[NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/ghidra-nativeaot.md)
+NativeAOT JAR. These are separate routes. The built-in parser also runs on
+Windows Ghidra P0; read frozen literals from its report, because
+`search_strings` does not include them. See the
+[NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-nativeaot.md)
 for setup, supported layouts, and host restrictions. Preserve binary identity
 and distinguish derived metadata from Ghidra database observations. Recovered
 types and native pseudocode are not original C# source. Windows Ghidra P0 has
@@ -205,7 +207,7 @@ every executable in the bundle. It also lists missing or weak loads and earlier
 provides them.

 Use `extract_artifact` when materialized files are needed. It extracts the active
-target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md).
+target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/reference/mcp-contracts.md).
 It materializes all regular files into a fresh temporary directory chosen by
 REA. Symlinks and encrypted entries are inventory facts, not extractable files.
 The result reports the materialized directory; callers do not choose the
@@ -220,7 +222,7 @@ separate filesystem-writing operation.
 For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
 `--target-format dos-com`). Inspect the load image before trusting function
 analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
-context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
+context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/providers/ghidra-dos.md).

 For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ
 headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`,
@@ -230,7 +232,7 @@ that address. Hopper and IDA refuse this interpretation; Ghidra uses
 and Cortex-M variants are unsupported. `6502` selects NMOS 6502; the entry and
 complete file mapping must fit within `0x0000..0xffff`. 65C02, 65816, cartridge
 containers, bank switching, and mapper semantics are unsupported. Windows
-Ghidra P0 admits raw images only for `6502`. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md).
+Ghidra P0 admits raw images only for `6502`. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/providers/raw-binary.md).

 ### Function annotations in Ghidra

@@ -246,4 +248,10 @@ code pages, payload hashes and static icon-group references. Same-language icon
 resolution is explicit; missing references and size mismatch remain visible.
 Other payloads are opaque, and this operation does not decode images or simulate
 Windows resource loading. Consult the budgets and supported tree profile in
-[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
+[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/guides/native/binary-diagnostics.md).
+
+For exact core-module import/export differences, use `compare_wasm_interfaces`
+with two complete inspection Evidence records (or current-session retained
+references) and explicit scope. Preserve unknown types/duplicate names; static
+interface equality is not runtime compatibility. CLI accepts complete inline
+Evidence in `rea compare-wasm-interfaces input.json --json`.
@@ -39,5 +39,5 @@ Inspect native `.saz` snapshots with `inspect_web_network_capture` and
 traffic analysis, connect Everywhere's separate MCP server and use its
 advertised session tools with an explicit `sessionsSource` (`LiveTraffic` or
 `AgentCalls`). Preserve existing sessions and filters when inspecting a
-recorded run. See the [capture and MCP guide](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md)
+recorded run. See the [capture and MCP guide](https://github.com/morluto/rea/blob/main/docs/guides/web/web-network-captures.md)
 for the workflow and Telerik's public setup and traffic-debugging skills.
@@ -20,7 +20,7 @@ body:
    attributes:
      label: Documentation location
      description: Link the page, section, command, API, skill, or inline comment.
-      placeholder: README.md#quick-start or docs/mcp-contracts.md
+      placeholder: README.md#quick-start or docs/reference/mcp-contracts.md
    validations:
      required: true

@@ -12,7 +12,7 @@ runs:
  steps:
    - name: Download portable build outputs from this workflow run
      if: inputs.build_cache_artifact != ''
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
      with:
        name: ${{ inputs.build_cache_artifact }}
        path: .turbo/cache/
@@ -39,14 +39,14 @@ runs:
          ' >> "$GITHUB_OUTPUT"
    - name: Restore portable build outputs
      if: inputs.build_cache_artifact == '' && inputs.save != 'true'
-      uses: actions/cache/restore@v4
+      uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
      with:
        path: .turbo/cache/
        key: ${{ steps.plan.outputs.key }}
        restore-keys: ${{ steps.plan.outputs.prefix }}
    - name: Restore and save portable build outputs
      if: inputs.build_cache_artifact == '' && inputs.save == 'true'
-      uses: actions/cache@v4
+      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
      with:
        path: .turbo/cache/
        key: ${{ steps.plan.outputs.key }}
@@ -85,7 +85,7 @@ limits, security/privacy/containment implications, and meaningful proof gaps. --
  its new behavior and migration, and why compatibility/deprecation cannot
  preserve it. Every release increments minor, including breaking changes;
  keep breaking markers and migration notes so callers can assess compatibility.
-  See docs/releasing.md. -->
+  See docs/development/releasing.md. -->
 - Real Hopper/Ghidra, browser, or OS coverage:
 - Package or release metadata impact:
 - Security, privacy, process, or containment review:
@@ -20,11 +20,11 @@ jobs:
    timeout-minutes: 5
    steps:
      # Consume only API data and execute batch code from the trusted default branch.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          ref: ${{ github.event.repository.default_branch }}
          persist-credentials: false
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Record queue, execution, and matched step timing
@@ -36,7 +36,7 @@ jobs:
      - name: Upload CI timing artifacts
        if: always() && hashFiles('.cache/ci-job-timings/*') != ''
        continue-on-error: true
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: ci-job-timings-batch
          path: .cache/ci-job-timings/
@@ -33,7 +33,7 @@ env:
 jobs:
  changes:
    name: Classify changes
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
    timeout-minutes: 5
    permissions:
      contents: read
@@ -63,11 +63,11 @@ jobs:
      matrix: ${{ steps.plan.outputs.matrix }}
      test_selection: ${{ steps.plan.outputs.test_selection }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          ref: ${{ inputs.source_sha || github.sha }}
          fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Bind qualification to the caller revision
@@ -118,8 +118,8 @@ jobs:
        env:
          CHANGES_RESULT: ${{ needs.changes.result }}
        run: test "${CHANGES_RESULT}" = "success"
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -138,7 +138,7 @@ jobs:
        run: npm run format:check
      - name: Upload complete static diagnostics
        if: always() && needs.changes.outputs.code == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: static-check-reports
          path: .cache/static-checks/
@@ -157,13 +157,13 @@ jobs:
      matrix:
        shard: [1/6, 2/6, 3/6, 4/6, 5/6, 6/6]
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: rea-test-runtime
          path: .
@@ -177,7 +177,7 @@ jobs:
        run: npm run test:run -- --reporter=default --reporter=blob --shard=${{ matrix.shard }}
        env:
          REA_CI_TEST_HISTORY: .cache/ci-test-history/test-results.json
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: ${{ !cancelled() }}
        with:
          name: vitest-report-${{ strategy.job-index }}
@@ -208,8 +208,8 @@ jobs:
      contents: read
      actions: read
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -231,13 +231,13 @@ jobs:
      - name: Download previous timing report
        if: steps.history.outputs.run-id != ''
        continue-on-error: true
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: test-timings
          run-id: ${{ steps.history.outputs.run-id }}
          github-token: ${{ github.token }}
          path: .cache/ci-test-history
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: rea-test-runtime
          path: |
@@ -254,7 +254,7 @@ jobs:
      # test:prepare caches only portable JS, skill, and catalog outputs.
      # Native package jobs still run their build and prepack checks; Turbo
      # restores matching outputs or rebuilds when their inputs differ.
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: rea-build-cache
          path: .turbo/cache/
@@ -280,24 +280,29 @@ jobs:
        env:
          CHANGES_RESULT: ${{ needs.changes.result }}
        run: test "${CHANGES_RESULT}" = "success"
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        if: needs.changes.outputs.code == 'true' && success()
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        if: needs.changes.outputs.code == 'true' && success()
        with:
          node-version-file: .nvmrc
          cache: npm
      - if: needs.changes.outputs.code == 'true' && success()
        run: npm ci
-      - uses: actions/download-artifact@v4
-        if: needs.changes.outputs.code == 'true' && success()
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        if: >-
+          !cancelled() && needs.changes.outputs.code == 'true' &&
+          (needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
        with:
          path: .vitest/blob
          pattern: vitest-report-*
          merge-multiple: true
      - name: Merge coverage, JUnit, and timing reports
        id: merge
-        if: needs.changes.outputs.code == 'true' && needs.changes.outputs.tier == 'full' && success()
+        if: >-
+          !cancelled() && needs.changes.outputs.code == 'true' &&
+          needs.changes.outputs.tier == 'full' &&
+          (needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
        run: >-
          npm run test:ci:merge --
          --coverage.reportsDirectory=coverage
@@ -312,7 +317,10 @@ jobs:
          --outputFile.json=test-results.json
      - name: Merge fast-suite JUnit and timing reports
        id: merge-fast
-        if: needs.changes.outputs.code == 'true' && needs.changes.outputs.tier == 'fast' && success()
+        if: >-
+          !cancelled() && needs.changes.outputs.code == 'true' &&
+          needs.changes.outputs.tier == 'fast' &&
+          (needs.test-shard.result == 'success' || needs.test-shard.result == 'failure')
        run: >-
          npm exec -- vitest --merge-reports
          --reporter=default
@@ -330,7 +338,7 @@ jobs:
          CI_TEST_SELECTION: ${{ needs.changes.outputs.test_selection }}
          CI_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: node scripts/ci/test-report.mjs
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: needs.changes.outputs.code == 'true' && !cancelled() && hashFiles('test-results.json') != ''
        with:
          name: test-results
@@ -345,7 +353,7 @@ jobs:
          retention-days: 30
      - name: Publish successful timing history
        if: needs.changes.outputs.code == 'true' && needs.changes.outputs.tier == 'full' && success() && needs.test-shard.result == 'success'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: test-timings
          path: .cache/ci-test-history/test-results.json
@@ -366,7 +374,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
      - name: Verify fixtures from a clean checkout
        run: npm run verify:fixtures

@@ -377,8 +385,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Prepare cross compiler
@@ -395,12 +403,27 @@ jobs:
      - run: npm run build:windows-native
      - run: npm run verify:windows-native:artifact
      - run: node scripts/build-windows-native.mjs --inspection-fixture
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: windows-native-inspection-fixture
          path: .cache/windows-native-inspection-fixture/
          if-no-files-found: error
-      - uses: actions/upload-artifact@v4
+      # The process boundary observations are independent of the addon: they
+      # report the caller's and child's own token, environment and breakaway
+      # results from a separate executable. Cross-build it in the lane that
+      # already has MinGW so the Windows job can observe them too.
+      - name: Build Windows process boundary fixture
+        run: |
+          mkdir -p .cache/windows-process-boundary
+          x86_64-w64-mingw32-g++ -municode -std=c++17 -O2 -static -Wall -Wextra \
+            -o .cache/windows-process-boundary/process-boundary.exe \
+            tests/fixtures/windows/processBoundary.cc -ladvapi32
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: windows-process-boundary-fixture
+          path: .cache/windows-process-boundary/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: windows-native-controls
          path: native/windows/build/
@@ -423,8 +446,8 @@ jobs:
      NODE_OPTIONS: "--max-old-space-size=1024"
      UV_THREADPOOL_SIZE: "2"
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -438,11 +461,11 @@ jobs:
          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
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: rea-build-cache
          path: .turbo/cache/
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: windows-native-controls
          path: native/windows/build/
@@ -463,7 +486,7 @@ jobs:
        run: npm run verify:inspector
      - name: Retain the exact qualified release package
        if: needs.changes.outputs.tier == 'full' && matrix.platform == 'linux' && matrix.architecture == 'x64'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: verified-release-package
          path: .cache/verified-package/
@@ -479,13 +502,13 @@ jobs:
    runs-on: macos-15
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: rea-build-cache
          path: .turbo/cache/
@@ -527,8 +550,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -539,7 +562,7 @@ jobs:
        run: |
          set -o pipefail
          npm run verify:readiness | tee readiness-summary.json
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: ${{ !cancelled() }}
        with:
          name: reconstruction-readiness
@@ -556,18 +579,18 @@ jobs:
    runs-on: windows-latest
    timeout-minutes: 25
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: rea-build-cache
          path: .turbo/cache/
      - run: npm run build:cached
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: windows-native-controls
          path: native/windows/build/
@@ -596,6 +619,7 @@ jobs:
          tests/boundary/providers/native/artifactProvider.extractionCompleteness.test.ts
          tests/boundary/filesystem/setupUnavailableProvider.test.ts
          tests/boundary/filesystem/windowsNpxRegistration.test.ts
+          tests/boundary/android/workspaceGuardianRetry.test.ts
          tests/acceptance/setup/homeDirectoryFallback.test.ts
          tests/boundary/filesystem/javascriptApplicationWorkflows.test.ts
          tests/boundary/filesystem/webScriptManifestPaths.test.ts
@@ -622,8 +646,17 @@ jobs:
          src/application/Update.test.ts
          tests/process-global/updateMaintenance.test.ts
          tests/conformance/providers/ghidra/realGhidraWindowsWorkflow.test.ts
-      - run: npm run verify:windows-native
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: windows-process-boundary-fixture
+          path: .cache/windows-process-boundary/
+      # Passing the fixture adds the breakaway, caller/child token, environment
+      # semantics and ancestor reparse observations, which the lane skips
+      # entirely when it is absent.
+      - run: >-
+          npm run verify:windows-native -- .
+          "${{ github.workspace }}\.cache\windows-process-boundary\process-boundary.exe"
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: windows-native-inspection-fixture
          path: .cache/windows-native-inspection-fixture/
@@ -642,7 +675,7 @@ jobs:
          tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts
          tests/boundary/filesystem/javascriptPackagePrecedence.test.ts
          tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: 22.19.0
      - name: Verify native path boundaries on Node 22
@@ -652,7 +685,7 @@ jobs:
          tests/boundary/filesystem/javascriptPackagePrecedence.test.ts
          tests/boundary/filesystem/javascriptArtifactContentIdentity.test.ts
          tests/boundary/process/sourceMapUncHosts.test.ts
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: always()
        with:
          name: windows-capabilities
@@ -666,16 +699,18 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
      - run: npm run docs:check
+      - name: Verify published routes, source links and local anchors
+        run: npm run verify:docs:routes
      - name: Generation leaves authored files unchanged
        run: git diff --exit-code
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: generated-docs
          path: |
@@ -752,7 +787,8 @@ jobs:

  required:
    name: CI required
-    if: ${{ always() }}
+    # Report failed dependencies, but release superseded PR concurrency slots.
+    if: ${{ !cancelled() }}
    needs:
      [
        changes,
@@ -779,11 +815,11 @@ jobs:
        nativeaot,
        website,
      ]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
    timeout-minutes: 5
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Require every selected lane to pass
@@ -794,7 +830,7 @@ jobs:
        run: node scripts/ci/required.mjs
      - name: Upload full qualification receipt artifact
        if: needs.changes.outputs.tier == 'full' && success()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: ${{ steps.gate.outputs.receipt_name }}
          path: ${{ steps.gate.outputs.receipt_path }}
@@ -19,16 +19,16 @@ jobs:
      DOTNET_PROCESSOR_COUNT: "1"
      COMPlus_GCHeapHardLimit: "30000000"
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
-      - uses: actions/setup-dotnet@v4
+      - uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
        with:
          dotnet-version: "8.0.416"
      - name: Build benign fixture and independent byte oracle
        run: node scripts/generate-nativeaot-fixtures.mjs
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: nativeaot-win-x64-${{ github.event.pull_request.head.sha || github.sha }}
          path: |
@@ -19,10 +19,10 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
-      - run: npm run docs:build
+      - run: npm run verify:docs:routes
@@ -14,7 +14,7 @@ concurrency:
 jobs:
  pr-title:
    name: Conventional PR title
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
    timeout-minutes: 2
    steps:
      - name: Validate title for Release Please
@@ -28,8 +28,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -21,8 +21,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -22,8 +22,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -43,3 +43,5 @@ jobs:
          echo "REA_VERIFY_SOLC_MODULE=${evm_fixture_root}/node_modules/solc/index.js" >> "${GITHUB_ENV}"
      - name: Verify source-owned compiled bytecode through public CLI and MCP
        run: npm run verify:evm:interface
+      - name: Verify content-hash-free and CBOR-free owned compiler artifacts
+        run: npm run verify:solidity:metadata
@@ -16,8 +16,8 @@ jobs:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Prepare cross compiler
@@ -31,11 +31,25 @@ jobs:
          sudo apt-get install --no-install-recommends -y g++-mingw-w64-x86-64
      - run: npm run build:windows-native
      - run: npm run verify:windows-native:artifact
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: real-ghidra-windows-native
          path: native/windows/build/
          if-no-files-found: error
+      # The boundary observations need a separate Windows executable, which the
+      # native lane skips when it is absent. Cross-build it here, where MinGW is
+      # already installed, so the proof run observes them too.
+      - name: Build Windows process boundary fixture
+        run: |
+          mkdir -p .cache/windows-process-boundary
+          x86_64-w64-mingw32-g++ -municode -std=c++17 -O2 -static -Wall -Wextra \
+            -o .cache/windows-process-boundary/process-boundary.exe \
+            tests/fixtures/windows/processBoundary.cc -ladvapi32
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: real-ghidra-windows-process-boundary
+          path: .cache/windows-process-boundary/
+          if-no-files-found: error

  verify:
    name: Real Ghidra 12.1.4 Windows x64 PE proof
@@ -45,17 +59,23 @@ jobs:
    runs-on: [self-hosted, Windows, x64, ghidra-12-1-2]
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - run: npm ci
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: real-ghidra-windows-native
          path: native/windows/build/
      - run: npm run verify:windows-native:artifact
-      - run: npm run verify:windows-native
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: real-ghidra-windows-process-boundary
+          path: .cache/windows-process-boundary/
+      - run: >-
+          npm run verify:windows-native -- .
+          "${{ github.workspace }}\.cache\windows-process-boundary\process-boundary.exe"
      - name: Verify all admitted Windows Ghidra operations
        env:
          REA_ANALYSIS_PROVIDER: ghidra
@@ -88,7 +108,7 @@ jobs:
        env:
          REA_ANALYSIS_PROVIDER: ghidra
        run: npm run verify:ghidra:windows:package -- --x86 --dll | Tee-Object -FilePath windows-ghidra-x86-dll-package-proof.log
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        if: always()
        with:
          name: windows-ghidra-proof
@@ -44,12 +44,12 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5.6.0
        with:
          go-version: "1.26.1"
          cache: false
@@ -15,8 +15,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 25
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -36,8 +36,8 @@ jobs:
    runs-on: [self-hosted, Linux, hopper]
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -15,8 +15,8 @@ jobs:
    runs-on: [self-hosted, macOS, hopper]
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -23,8 +23,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -43,8 +43,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -25,8 +25,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -36,8 +36,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -18,7 +18,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
      - name: Download the pinned Termux app and verify its release checksum
        shell: bash
        run: |
@@ -38,7 +38,7 @@ jobs:
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm
      - name: Build and capture a page inside Termux
-        uses: reactivecircus/android-emulator-runner@4c44018e59b437e86cdfc41da381398f93ed8808 # v2
+        uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
        with:
          api-level: 30
          arch: x86_64
@@ -50,7 +50,7 @@ jobs:
          script: bash scripts/verify/termux/emulator.sh
      - name: Upload Termux and Android diagnostics
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: termux-browser-diagnostics
          path: ${{ runner.temp }}/rea-termux/diagnostics
@@ -22,8 +22,8 @@ jobs:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -17,8 +17,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -17,8 +17,8 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
          cache: npm
@@ -48,7 +48,7 @@ jobs:
            echo "frozen=true" >> "$GITHUB_OUTPUT"
          fi

-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
        if: steps.editorial.outputs.frozen != 'true'
        with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
@@ -70,13 +70,13 @@ jobs:
      sha: ${{ steps.release.outputs.sha }}
    steps:
      - name: Check out reviewed release merge
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ github.event.pull_request.merge_commit_sha }}
          fetch-depth: 0
          persist-credentials: false

-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .nvmrc
          package-manager-cache: false
@@ -104,7 +104,7 @@ jobs:
          node scripts/release-notes.mjs publication --repository "$GH_REPO" \
            --source "$SOURCE_SHA" --pr "$RELEASE_PR"

-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
        id: release
        with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
@@ -191,14 +191,14 @@ jobs:
          fi

      - name: Check out release controller and Git history
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ github.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Node.js for checkpoint validation
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .nvmrc
          package-manager-cache: false
@@ -226,7 +226,7 @@ jobs:
          node scripts/release-notes.mjs publication --repository "$GH_REPO" \
            --source "$SOURCE_SHA"

-      - uses: googleapis/release-please-action@v4
+      - uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
        id: release
        with:
          # A dedicated credential starts PR CI automatically; the built-in
@@ -255,7 +255,7 @@ jobs:

      - name: Check out release pull request
        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
          fetch-depth: 0
@@ -263,7 +263,7 @@ jobs:

      - name: Set up Node.js for generated documentation
        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .nvmrc
          package-manager-cache: false
@@ -314,12 +314,12 @@ jobs:
      contents: read
      id-token: write
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ needs.merged-release.outputs.sha || needs.release-please.outputs.sha }}
          persist-credentials: false

-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
        with:
          node-version-file: .nvmrc
          package-manager-cache: false
@@ -328,7 +328,7 @@ jobs:
      - run: npm ci

      - name: Download the exact qualified package
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: verified-release-package
          path: .cache/verified-package/
@@ -392,7 +392,7 @@ jobs:
      contents: read
      id-token: write
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          ref: ${{ needs.merged-release.outputs.sha || needs.release-please.outputs.sha }}
          persist-credentials: false
@@ -22,14 +22,14 @@ jobs:
        # The repository-pinned Node 24 version also runs the complete test suite.
        node: ["22.x", "24.15.0", "24.x", "26.x"]
    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: ${{ matrix.node }}
          check-latest: true
          cache: npm
      - run: npm ci
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: rea-test-runtime
          path: .
@@ -14,9 +14,9 @@ jobs:
    timeout-minutes: 10
    steps:
      - name: Check out the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
      - name: Set up Python for website assets
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"
          cache: pip
@@ -47,9 +47,9 @@ jobs:
            exit 1
          fi
      - name: Check out the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
      - name: Set up Python for website assets
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
        with:
          python-version: "3.12"
          cache: pip
@@ -74,9 +74,9 @@ jobs:
          )
          PY
      - name: Configure Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
      - name: Upload the website
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
        with:
          path: website/_site

@@ -95,15 +95,15 @@ jobs:
    steps:
      - name: Check out publishing configuration
        if: inputs.target == 'both'
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
      - name: Set up Node.js for Wrangler
        if: inputs.target == 'both'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version-file: .nvmrc
      - name: Download the verified website
        if: inputs.target == 'both'
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: github-pages
          path: ${{ runner.temp }}/website-archive
@@ -114,7 +114,7 @@ jobs:
          tar -xf "$RUNNER_TEMP/website-archive/artifact.tar" -C "$RUNNER_TEMP/rea-website-public"
      - name: Publish the website to Cloudflare
        if: inputs.target == 'both'
-        uses: cloudflare/wrangler-action@v4
+        uses: cloudflare/wrangler-action@953926a2e2182532811c01a25e53647d93bf07c0 # v4.1.3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
@@ -123,7 +123,7 @@ jobs:
          command: deploy --cwd website --env production --assets "${{ runner.temp }}/rea-website-public"
      - name: Publish to GitHub Pages
        id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5
      - name: Verify the selected published revisions
        env:
          PAGES_URL: ${{ steps.deployment.outputs.page_url }}
@@ -14,7 +14,7 @@ Preserve caller-selected inputs and local evidence, including output, URLs, path

 ## Architecture and Cleanup

-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.
+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/architecture.mermaid](docs/architecture/architecture.mermaid) when changing composition.

 Give each interpretation and resource a clear owner. Consumers must use that owner's parsed facts rather than reinterpret raw source. 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.

@@ -57,6 +57,12 @@ do not establish fewer tokens or faster analysis.

 ## Development

+Documentation ownership and authoring conventions live in
+[docs/development/documentation.md](docs/development/documentation.md). A feature
+uses `docs/specs/<domain>/<feature-slug>/spec.md`, one `plan.md` and `tasks.md`;
+individual architectural decisions use `docs/adr/<domain>/<decision-slug>.md`.
+Consult the [documentation directory](docs/README.md) before adding a guide.
+
 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`.

 - `npm ci`: install locked dependencies.
@@ -72,9 +78,9 @@ Use relevant checks for the change. The complete local gate, `npm run check:pr`,

 ## Tool and Test Changes

-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.
+For tool design, follow [docs/development/tool-design.md](docs/development/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.

-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.
+For test changes or provider claims, use [docs/development/testing.md](docs/development/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.

 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.

@@ -69,7 +69,7 @@ Full contribution record: [336 commits and 163 merged PRs](https://github.com/mo

 ### ⚠ 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))
+* **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/guides/runtime/process-capture.md) and [browser scenario contract](docs/guides/web/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.
@@ -237,7 +237,7 @@ Full contribution record: [336 commits and 163 merged PRs](https://github.com/mo

 ### ⚠ BREAKING CHANGES

-Read the [6.1 to 6.2 migration guide](docs/migration-6.2.md) before upgrading. REA's `always-bump-minor` policy includes breaking changes; 6.2 is not a backward-compatibility promise. Preserve original saved files and regenerate missing observations rather than fabricating identities or facts.
+Read the [6.1 to 6.2 migration guide](docs/migrations/migration-6.2.md) before upgrading. REA's `always-bump-minor` policy includes breaking changes; 6.2 is not a backward-compatibility promise. Preserve original saved files and regenerate missing observations rather than fabricating identities or facts.

 * **MCP / Evidence / snapshots / artifacts:** Success results are direct canonical Evidence; read `normalized_result` rather than the old `result`/`evidence` wrapper. Evidence requires nullable `analysis_profile`, session provider aliases are removed, snapshots require complete profile-bound query records, and artifact roles/permissions belong to occurrences. Recreate incompatible saved data; adding fields without recomputing their semantic identity is invalid. ([63bf914](https://github.com/morluto/rea/commit/63bf91405cf97b114a84f337fb1272d98a267999))
 * **Process captures:** Legacy v3 conversion is removed. Explicit executable identity and `event_journal` are required; retain old captures and recapture when current comparisons are needed instead of inventing launch identity or event order. ([2a77469](https://github.com/morluto/rea/commit/2a7746998d47446c4db6d4f524e0f183d6803f3f))
@@ -11,7 +11,7 @@ incorrect user instructions warrant standalone corrections. Collect other
 cosmetic-only suggestions in an issue rather than separate PRs.

 For capability organization and provider composition, use the
-[architecture map](docs/architecture.mermaid). Production factories in
+[architecture map](docs/architecture/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
@@ -22,7 +22,7 @@ For analysis workflows and agent interfaces, follow the
 scope, reuse/cache decisions, and relevant before/after measurements when these
 costs change.

-When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.
+When adding or changing an MCP tool, follow the [tool design guide](docs/development/tool-design.md) and preserve the canonical contracts and generated catalog.

 ## Contribution scope

@@ -124,7 +124,7 @@ guarantee.
 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).
+[installation](docs/getting-started/installation.md#start-setup).

 ```bash
 npm ci
@@ -159,6 +159,10 @@ verification prerequisites. Keep the generated addon and manifest uncommitted.

 ## Documentation website

+Use the [documentation directory](docs/README.md) and
+[authoring guide](docs/development/documentation.md) for document ownership,
+domain-based feature specifications and architectural decision records.
+
 The VitePress site uses the Markdown files in `docs/`. Run `npm run docs:dev`
 for live editing, `npm run docs:build` to check the production build and
 links, and `npm run docs:preview` to preview that build at `/rea/`.
@@ -181,6 +185,10 @@ The separate GitHub Pages host uses only the manual

 ## Development feedback and PR verification

+For routine merges, wait for the required checks to pass for the current PR
+revision. Administrators retain an override for deliberate maintainer recovery.
+If `main` is broken, prioritize a focused repair before updating affected PRs.
+
 Select checks for the behavior changed. For a source edit:

 ```bash
@@ -191,7 +199,7 @@ npm run check:fast
 `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)
+select relevant boundary tests explicitly. See [testing](docs/development/testing.md#developer-commands)
 for commands, test placement, pruning, and real-provider prerequisites.

 Before requesting review, run relevant tests and `npm run check`; add
@@ -202,6 +210,10 @@ 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.

+For CI/test correctness, drift, or performance investigations, use the
+[`rea-ci-tests-audit` contributor skill](.agents/skills/rea-ci-tests-audit/SKILL.md).
+It guides reproduction and comparable measurements before changing checks.
+
 `check:pr` reuses build and static-check outputs while executing the test suite
 fresh, including the fast Python producer checks. `docs:check` also runs the
 onboarding example consistency suite for README-only changes.
@@ -254,8 +266,8 @@ 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)
+[real-toolchain verification](docs/development/testing.md#end-to-end-integration-and-golden-evidence)
+for prerequisites and scope, and [Hopper setup](docs/getting-started/installation.md#hopper)
 for supported hosts and unattended startup.

 Use the default `build/conformance/manifest.json` unless explicitly verifying
@@ -264,7 +276,7 @@ Generated fixtures and manifests remain ignored.

 ## Maintainer release checklist

-Use the [release guide](docs/releasing.md). Main pushes automatically refresh a
+Use the [release guide](docs/development/releasing.md). Main pushes automatically refresh a
 Release Please PR with the next version and changelog. Review its migration
 notes, wait for the current CI checks to pass, and merge it into main to publish.

@@ -1,6 +1,6 @@
 <div align="center">

-**English** · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
+**English** · [简体中文](docs/readme/README_zh.md) · [繁體中文](docs/readme/README_zh-TW.md) · [日本語](docs/readme/README_ja.md) · [한국어](docs/readme/README_ko.md) · [Türkçe](docs/readme/README_tr.md) · [Русский](docs/readme/README_ru.md) · [Tiếng Việt](docs/readme/README_vi.md) · [ไทย](docs/readme/README_th.md) · [Deutsch](docs/readme/README_de.md) · [Español](docs/readme/README_es.md) · [Français](docs/readme/README_fr.md) · [Українська](docs/readme/README_uk.md) · [Polski](docs/readme/README_pl.md) · [Português (Brasil)](docs/readme/README_pt-BR.md) · [العربية](docs/readme/README_ar.md) · [فارسی](docs/readme/README_fa.md) · [Bahasa Indonesia](docs/readme/README_id.md) · [Italiano](docs/readme/README_it.md)

 # REA: Reverse Engineer Anything

@@ -9,7 +9,7 @@
 **See a feature you like. Understand how it works, down to the binary level.**

 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
-[![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/mcp-contracts.md#generated-catalog)
+[![MCP tool catalog](https://img.shields.io/badge/MCP-tool_catalog-5c4ee5?style=flat-square)](docs/reference/mcp-contracts.md#generated-catalog)
 [![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)
@@ -70,8 +70,8 @@ REA's MCP server and matching workflow instructions, with backups of existing
 configuration. Restart your agent afterward.

 Setup supports Claude Code, Codex, Cursor, Gemini CLI, Grok Build and
-[other agents](docs/installation.md#supported-agents). See
-[installation and setup](docs/installation.md) for provider configuration and
+[other agents](docs/getting-started/installation.md#supported-agents). See
+[installation and setup](docs/getting-started/installation.md) for provider configuration and
 manual MCP registration.

 ### Ask your agent
@@ -102,7 +102,7 @@ rea --help
 ```

 For native analysis, configure a provider first. See the
-[CLI and Evidence guide](docs/cli.md) for native commands, provider selection,
+[CLI and Evidence guide](docs/getting-started/cli.md) for native commands, provider selection,
 snapshots and scripting.

 ### Update REA
@@ -150,30 +150,30 @@ CLI commands use the same workflows.
 REA requires Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+, plus npm.
 Additional tools and host support depend on the target:

-| Target                 | What REA returns                                                                     | Requirements and guide                                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| Native binaries        | Pseudocode, assembly, strings, symbols, calls and references                         | Hopper, Ghidra or IDA; [native analysis](https://rea.tools/guides/native/)                                                            |
-| Offline ELF layout     | Sections, segments, original symbols/relocations and static mitigation candidates    | Caller-supplied pwntools on Linux x64; [binary diagnostics](docs/binary-diagnostics.md)                                               |
-| Go binaries            | Embedded compiler version, modules, replacements and build settings                  | Built-in static ELF/PE/thin Mach-O inspection; no Go installation required                                                            |
-| WASM artifact          | Validation, sections, exact import/export WAT forms and decoded WAT                  | Caller-supplied WABT 1.0.42; `inspect_wasm_artifact`                                                                                  |
-| EVM bytecode           | Dispatch selectors, byte offsets, inferred arguments and mutability                  | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md)                                                         |
-| SQLite databases       | Tables, columns, indexes, views, triggers and selected ordinary-table rows           | Local database/WAL snapshot; Node.js 24.x >=24.15 or 26+ with native SQLite limits                                                    |
-| Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools on Linux x64; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md)                              |
-| 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 or Fiddler Everywhere SAZ; mitmdump on Linux for native mitmproxy; [capture guide](docs/web-network-captures.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)                                    |
-| Android devices        | Devices, packages, processes, logs, dumps, screen captures, and APK/file transfers   | Caller-supplied adb (emulator or hardware); [ADB guide](docs/adb-device-analysis.md)                                                  |
-| JEB projects           | Engine-backed project units, artifact digests and type/method pseudo-code            | A caller-started JEB client serving MCP, selected with REA_JEB_MCP_URL; [JEB guide](docs/jeb-analysis.md)                             |
-| Android resources      | Decoded manifest, string tables, locales and version facts                           | Caller-supplied Apktool launcher; [resource guide](docs/apktool-resource-analysis.md)                                                 |
-| Flutter apps           | Dart snapshot hash, per-ABI library digests and engine build provenance              | None (static APK parsing); [Flutter guide](docs/flutter-analysis.md)                                                                  |
-| Firmware               | Regions, extraction results and native-analysis handoffs                             | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md)                                                                |
-| Recorded packets       | Selected fields, repeated values, filters and decode-as rules                        | Linux: TShark 4.x + prlimit; [capture guide](docs/packet-captures.md)                                                                 |
-| Packet summaries       | Endpoints, DNS, TLS SNI, protocol distribution and HTTP requests                     | Caller-supplied tshark and capinfos (Linux-verified); [pcap guide](docs/pcap-analysis.md)                                             |
-| Recorded logic signals | Decoder annotations, sample ranges and diagnostics                                   | Linux: sigrok-cli 0.7.2 + prlimit; [signal recordings](docs/signal-recordings.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) |
-| Process behavior       | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md)                                                             |
+| Target                 | What REA returns                                                                     | Requirements and guide                                                                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Native binaries        | Pseudocode, assembly, strings, symbols, calls and references                         | Hopper, Ghidra or IDA; [native analysis](https://rea.tools/guides/native/)                                                                                           |
+| Offline ELF layout     | Sections, segments, original symbols/relocations and static mitigation candidates    | Caller-supplied pwntools on Linux x64; [binary diagnostics](docs/guides/native/binary-diagnostics.md)                                                                |
+| Go binaries            | Embedded compiler version, modules, replacements and build settings                  | Built-in static ELF/PE/thin Mach-O inspection; no Go installation required                                                                                           |
+| WASM artifact          | Validation, sections, exact import/export WAT forms and decoded WAT                  | Caller-supplied WABT 1.0.42; `inspect_wasm_artifact`                                                                                                                 |
+| EVM bytecode           | Dispatch selectors, byte offsets, inferred arguments and mutability                  | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/guides/evm/evm-bytecode.md)                                                                             |
+| SQLite databases       | Tables, columns, indexes, views, triggers and selected ordinary-table rows           | Local database/WAL snapshot; Node.js 24.x >=24.15 or 26+ with native SQLite limits                                                                                   |
+| Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools on Linux x64; optional GDB/pwndbg; [recorded crashes](docs/guides/native/recorded-crashes.md)                                               |
+| 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 or Fiddler Everywhere SAZ; mitmdump on Linux for native mitmproxy; [capture guide](docs/guides/web/web-network-captures.md)                                      |
+| .NET assemblies        | Metadata, CIL instructions, declared native dependencies and build comparisons       | None (static only); [managed-code guide](docs/guides/managed/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/guides/android/android-analysis.md)                                                    |
+| Android devices        | Devices, packages, processes, logs, dumps, screen captures, and APK/file transfers   | Caller-supplied adb (emulator or hardware); [ADB guide](docs/guides/android/adb-device-analysis.md)                                                                  |
+| JEB projects           | Engine-backed project units, artifact digests and type/method pseudo-code            | A caller-started JEB client serving MCP, selected with REA_JEB_MCP_URL; [JEB guide](docs/providers/jeb-analysis.md)                                                  |
+| Android resources      | Decoded manifest, string tables, locales and version facts                           | Caller-supplied Apktool launcher; [resource guide](docs/guides/android/apktool-resource-analysis.md)                                                                 |
+| Flutter apps           | Dart snapshot hash, per-ABI library digests and engine build provenance              | None (static APK parsing); [Flutter guide](docs/guides/android/flutter-analysis.md)                                                                                  |
+| Firmware               | Regions, extraction results and native-analysis handoffs                             | Binwalk / Unblob on Linux; [firmware guide](docs/guides/firmware/firmware-analysis.md)                                                                               |
+| Recorded packets       | Selected fields, repeated values, filters and decode-as rules                        | Linux: TShark 4.x + prlimit; [capture guide](docs/guides/data/packet-captures.md)                                                                                    |
+| Packet summaries       | Endpoints, DNS, TLS SNI, protocol distribution and HTTP requests                     | Caller-supplied tshark and capinfos (Linux-verified); [pcap guide](docs/guides/data/pcap-analysis.md)                                                                |
+| Recorded logic signals | Decoder annotations, sample ranges and diagnostics                                   | Linux: sigrok-cli 0.7.2 + prlimit; [signal recordings](docs/guides/signals/signal-recordings.md)                                                                     |
+| Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources      | [Artifact and JavaScript guide](docs/guides/javascript/javascript-artifact-reconstruction.md), [Apple applications](docs/guides/apple/apple-application-analysis.md) |
+| Process behavior       | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/guides/runtime/process-capture.md)                                                                             |

 Static JavaScript and .NET inspection read the supplied files without running
 the application. Runtime capture runs or interacts with the selected target
@@ -182,14 +182,14 @@ using your user permissions; each runtime guide describes its effects.
 <a id="choosing-a-deep-analysis-provider"></a>

 Native formats and host support vary by provider. See
-[Hopper and Ghidra setup](docs/installation.md#hopper), the
-[IDA guide](docs/ida-provider.md) (including an optional native MCP bridge), and
-[experimental Windows Ghidra support](docs/windows-ghidra-p0.md).
-Ghidra also supports [16-bit DOS analysis](docs/ghidra-dos.md).
+[Hopper and Ghidra setup](docs/getting-started/installation.md#hopper), the
+[IDA guide](docs/providers/ida-provider.md) (including an optional native MCP bridge), and
+[experimental Windows Ghidra support](docs/providers/windows-ghidra-p0.md).
+Ghidra also supports [16-bit DOS analysis](docs/providers/ghidra-dos.md).
 For large binaries, raise the provider's startup deadline with
 `REA_GHIDRA_STARTUP_TIMEOUT_MS` or `REA_HOPPER_STARTUP_TIMEOUT_MS`.
-For provider selection, see the [CLI guide](docs/cli.md#choose-a-provider).
-Check [release availability](docs/installation.md#released-package-and-main)
+For provider selection, see the [CLI guide](docs/getting-started/cli.md#choose-a-provider).
+Check [release availability](docs/getting-started/installation.md#released-package-and-main)
 for features added since the latest npm release.

 ## Showcases
@@ -232,8 +232,8 @@ your question, how REA helped, and what you found.
 <summary><strong>Which agents can use REA?</strong></summary>

 Any agent that supports local MCP servers. Setup configures the
-[supported agents](docs/installation.md#supported-agents); other clients can use
-[manual MCP registration](docs/installation.md#mcp-registry).
+[supported agents](docs/getting-started/installation.md#supported-agents); other clients can use
+[manual MCP registration](docs/getting-started/installation.md#mcp-registry).

 </details>

@@ -242,7 +242,7 @@ Any agent that supports local MCP servers. Setup configures the

 Deep native analysis uses one of them. Static JavaScript and .NET inspection
 work without a native analysis engine. Setup can install Hopper after approval;
-Ghidra and IDA use your existing installations. See [provider setup](docs/installation.md#hopper).
+Ghidra and IDA use your existing installations. See [provider setup](docs/getting-started/installation.md#hopper).

 </details>

@@ -253,7 +253,7 @@ REA starts Hopper when an operation needs it. On macOS, a first-run dialog may
 ask you to choose demo mode or activate your license. Complete that prompt in the
 same user session before your first CLI/MCP operation or unattended job. Open
 Hopper manually if needed. See
-[Hopper startup and troubleshooting](docs/installation.md#launcher-paths-and-troubleshooting).
+[Hopper startup and troubleshooting](docs/getting-started/installation.md#launcher-paths-and-troubleshooting).

 </details>

@@ -262,7 +262,7 @@ Hopper manually if needed. See

 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).
+your agent. See [skill-only installation](docs/getting-started/installation.md#skill-only-installation).

 </details>

@@ -311,18 +311,18 @@ with your REA version, target type, steps to reproduce and error output.
 Start with the website's [worked guides](https://rea.tools/guides/).
 For exact options, prerequisites and result contracts:

- [Installation and setup](docs/installation.md): agent registration, provider configuration, updates and uninstall.
- [Readiness and troubleshooting](docs/installation.md#check-readiness-for-your-task): diagnose one agent or analysis engine.
- [CLI and Evidence](docs/cli.md): commands, provider selection, snapshots, import/export and exit statuses.
- [MCP contracts](docs/mcp-contracts.md) and [agent prompts](docs/mcp-prompts.md): tool results, sessions and guided investigations.
- [Tool catalog](docs/mcp-contracts.md#generated-catalog): generated inventory of tools, providers and CLI commands.
- [Roadmap](docs/roadmap.md): planned work and capability trackers.
+- [Installation and setup](docs/getting-started/installation.md): agent registration, provider configuration, updates and uninstall.
+- [Readiness and troubleshooting](docs/getting-started/installation.md#check-readiness-for-your-task): diagnose one agent or analysis engine.
+- [CLI and Evidence](docs/getting-started/cli.md): commands, provider selection, snapshots, import/export and exit statuses.
+- [MCP contracts](docs/reference/mcp-contracts.md) and [agent prompts](docs/getting-started/mcp-prompts.md): tool results, sessions and guided investigations.
+- [Tool catalog](docs/reference/mcp-contracts.md#generated-catalog): generated inventory of tools, providers and CLI commands.
+- [Roadmap](docs/development/roadmap.md): planned work and capability trackers.

 Report vulnerabilities through [SECURITY.md](SECURITY.md).

 ## Star history

-🎉 **170,000 GitHub stars — thank you!**
+🎉 **180,000 GitHub stars — thank you!**

 Thanks to everyone using REA, reporting bugs, requesting features, testing builds, and contributing fixes.

@@ -351,8 +351,8 @@ report a bug or suggest a feature, or [send a pull request](https://github.com/m
 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.
+[testing](docs/development/testing.md) for verification lanes, and the
+[architecture map](docs/architecture/architecture.mermaid) for the project structure.

 ## License

@@ -27,7 +27,7 @@ provider-dependent behavior to be reproduced safely.
 REA authenticates its Hopper and Ghidra bridges with per-session random
 capability tokens. POSIX uses current-user Unix sockets; Windows Ghidra uses
 authenticated loopback TCP with a private NTFS runtime whose DACL admits only
-the current user and SYSTEM. See [Windows Ghidra P0](docs/windows-ghidra-p0.md#private-runtime-transport-and-lifecycle).
+the current user and SYSTEM. See [Windows Ghidra P0](docs/providers/windows-ghidra-p0.md#private-runtime-transport-and-lifecycle).
 Tokens are transferred through private session descriptors rather than process
 arguments or environment variables.
 This is not a sandbox and does not protect against malicious processes already
@@ -3,8 +3,14 @@ import com.google.gson.*;
 import io.modelcontextprotocol.kotlin.sdk.server.*;
 import io.modelcontextprotocol.kotlin.sdk.types.*;
 import jadx.api.*;
+import jadx.api.plugins.input.data.ICodeReader;
+import jadx.api.plugins.input.data.IMethodRef;
+import jadx.api.plugins.input.insns.InsnIndexType;
+import jadx.api.plugins.input.insns.Opcode;
+import jadx.core.dex.info.MethodInfo;
 import jadx.core.dex.nodes.*;
 import java.io.PrintStream;
+import java.nio.charset.StandardCharsets;
 import java.util.*;
 import java.util.concurrent.CountDownLatch;
 import java.util.stream.Collectors;
@@ -79,11 +85,17 @@ class ReaJadxBridge {
          ordered.sort(Comparator.comparing(MethodNode::getAlias));
          List<MethodSnapshot> methods = ordered.stream().map(method -> {
            String name = method.getAlias();
+            String shortId = method.getMethodInfo().getShortId();
+            String rawName = method.getMethodInfo().getName();
+            if (!shortId.startsWith(rawName + "("))
+              throw new IllegalStateException("JADX method ID has no raw-name prefix: " + shortId);
+            String descriptor = shortId.substring(rawName.length());
            String signature = name + "(" + method.getArgTypes().stream()
                .map(Object::toString).collect(Collectors.joining(", "))
                + "): " + method.getReturnType().toString();
-            return new MethodSnapshot(name, method.getMethodInfo().getShortId(), Map.of(
+            return new MethodSnapshot(name, shortId, Map.of(
                "name", name, "signature", signature,
+                "dex_descriptor", descriptor,
                "is_constructor", method.isConstructor(), "def_pos", 0));
          }).toList();
          List<Map<String, Object>> fields = node.getFields().stream()
@@ -140,6 +152,57 @@ class ReaJadxBridge {
        "smali", true, List.of("static_initializer_disassembly"));
  }

+  // The local transport admits 8 MiB frames. Reserve 1 KiB for the fixed
+  // JSON-RPC/CallToolResult envelope and generated numeric request id, and
+  // account for JSON text being escaped again inside TextContent.
+  private static final int MAX_XREF_TEXT_BYTES = 8 * 1024 * 1024 - 1024;
+  private static int escapedJsonBytes(Object value) {
+    return JSON.toJson(JSON.toJson(value)).getBytes(StandardCharsets.UTF_8).length;
+  }
+  private static final class InvokeBudget {
+    long remaining;
+    InvokeBudget(long remaining) { this.remaining = Math.max(0, remaining); }
+    boolean admit(Map<String, Object> site) {
+      // Check a conservative two-layer escape bound before serialization.
+      long bound = 256;
+      for (Object value : site.values())
+        if (value instanceof String text) bound += 12L * text.length();
+      if (bound > remaining) return false;
+      long bytes = escapedJsonBytes(site) - 2L + 1L;
+      if (bytes > remaining) return false;
+      remaining -= bytes;
+      return true;
+    }
+  }
+  private record DirectInvokes(List<Map<String, Object>> sites, boolean exhaustive) {}
+
+  /** Raw DEX invokes within one JADX using method; offsets are code units from its code start. */
+  private static DirectInvokes directInvokes(JavaMethod source, MethodInfo target, InvokeBudget budget) {
+    MethodNode node = source.getMethodNode();
+    ICodeReader code = node.getCodeReader();
+    if (code == null) return null;
+    List<Map<String, Object>> sites = new ArrayList<>();
+    boolean[] exhaustive = {true};
+    code.visitInstructions(insn -> {
+      insn.decode();
+      if (insn.getIndexType() != InsnIndexType.METHOD_REF) return;
+      Opcode opcode = insn.getOpcode();
+      if (!opcode.name().startsWith("INVOKE_")) return;
+      IMethodRef ref = insn.getIndexAsMethod();
+      ref.load();
+      if (!MethodInfo.fromRef(node.root(), ref).getRawFullId().equals(target.getRawFullId())) return;
+      Map<String, Object> site = Map.of(
+          "dex_entry", node.getInputFileName(),
+          "source_raw_method_id", node.getMethodInfo().getRawFullId(),
+          "dex_code_unit_offset", insn.getOffset(),
+          "dex_method_index", insn.getIndex(),
+          "opcode", opcode.name());
+      if (budget.admit(site)) sites.add(site);
+      else exhaustive[0] = false;
+    });
+    return new DirectInvokes(sites, exhaustive[0]);
+  }
+
  private CallToolResult handle(String name, JsonObject args) {
    if (name.equals("rea_jvm_status")) return json(Map.of(
        "engine_reported_version", BuildInfo.VERSION,
@@ -173,17 +236,52 @@ class ReaJadxBridge {
    }
    List<JavaNode> uses;
    String target = string(args, "class_name");
+    MethodSnapshot selectedMethod = null;
+    int overloadIndex = 0;
    if (name.equals("get_xrefs_to_class")) uses = cls.node().getUseIn();
    else {
      List<MethodSnapshot> overloads = methods(cls, args);
-      if (overloads.size() != 1) throw new InputFailure("method_name", "Method references require a unique overload");
-      target += "." + overloads.get(0).name();
-      uses = method(cls, overloads.get(0)).getUseIn();
+      if (overloads.size() != 1 && !args.containsKey("overload_index"))
+        throw new InputFailure("overload_index", "Select one of " + overloads.size() + " method overloads");
+      overloadIndex = integer(args, "overload_index", 0);
+      if (overloadIndex >= overloads.size())
+        throw new InputFailure("overload_index", "overload_index out of range: " + overloadIndex);
+      selectedMethod = overloads.get(overloadIndex);
+      target += "." + selectedMethod.name();
+      uses = method(cls, selectedMethod).getUseIn();
    }
    // REA consumes all references without materializing source line information.
-    List<Map<String, Object>> items = uses.stream().map(node -> current.describeUsage(node, false)).toList();
-    return json(Map.of("target", target, "total", uses.size(), "count", items.size(),
-        "resolve_line", false, "items", items));
+    MethodInfo targetInfo = selectedMethod == null ? null : method(cls, selectedMethod).getMethodNode().getMethodInfo();
+    List<Map<String, Object>> items = uses.stream().map(node -> {
+      Map<String, Object> item = new LinkedHashMap<>(current.describeUsage(node, false));
+      if (targetInfo != null && node instanceof JavaMethod) {
+        item.put("direct_invokes", List.of());
+        item.put("direct_invokes_exhaustive", false);
+      }
+      return item;
+    }).toList();
+    Map<String, Object> result = new LinkedHashMap<>(Map.of("target", target,
+        "total", uses.size(), "count", items.size(), "resolve_line", false, "items", items));
+    if (selectedMethod != null) {
+      result.put("overload_index", overloadIndex);
+      result.put("reported_signature", selectedMethod.summary().get("signature"));
+    }
+    if (targetInfo != null) {
+      InvokeBudget budget = new InvokeBudget(MAX_XREF_TEXT_BYTES - escapedJsonBytes(result));
+      for (int index = 0; index < uses.size(); index++) {
+        if (!(uses.get(index) instanceof JavaMethod source)) continue;
+        DirectInvokes invokes = directInvokes(source, targetInfo, budget);
+        Map<String, Object> item = items.get(index);
+        if (invokes == null) {
+          item.remove("direct_invokes");
+          item.remove("direct_invokes_exhaustive");
+        } else {
+          item.put("direct_invokes", invokes.sites());
+          item.put("direct_invokes_exhaustive", invokes.exhaustive());
+        }
+      }
+    }
+    return json(result);
  }

  public static void main(String[] args) throws Exception {
@@ -217,7 +315,7 @@ class ReaJadxBridge {
      List<String> fields = switch (name) {
        case "list_classes" -> List.of("offset", "limit");
        case "get_method_body" -> List.of("class_name", "method_name", "overload_index");
-        case "get_xrefs_to_method" -> List.of("class_name", "method_name");
+        case "get_xrefs_to_method" -> List.of("class_name", "method_name", "overload_index");
        default -> List.of("class_name");
      };
      Map<String, kotlinx.serialization.json.JsonElement> properties = new LinkedHashMap<>();
@@ -226,7 +324,7 @@ class ReaJadxBridge {
        case "list_classes" -> "Indexed pages of all top-level class names, with offset and limit.";
        case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
        case "get_method_body" -> "Source for an exact class and stable same-name overload index; static initializers use smali to preserve folded field initialization.";
-        default -> "Complete static references to an exact class or unique method; source lines are unresolved.";
+        default -> "Complete static using-node inventory for an exact class or selected method overload; one node may contain multiple invoke instructions, and source lines are unresolved.";
      };
      Tool narrowed = new Tool(name, new ToolSchema(null, new JsonObject(properties),
          tool.getInputSchema().getRequired(), null), description, null, null, null, null, null, null);
@@ -28,6 +28,7 @@ import java.util.ArrayDeque;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Comparator;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.IdentityHashMap;
 import java.util.Iterator;
@@ -56,6 +57,8 @@ import ghidra.app.decompiler.DecompiledFunction;
 import ghidra.app.decompiler.ClangCaseToken;
 import ghidra.app.decompiler.ClangNode;
 import ghidra.framework.Application;
+import ghidra.app.util.bin.format.pdb.PdbParserConstants;
+import ghidra.framework.options.Options;
 import ghidra.program.model.address.Address;
 import ghidra.program.model.address.AddressIterator;
 import ghidra.program.model.address.AddressSet;
@@ -110,6 +113,8 @@ import ghidra.program.util.SymbolicPropogator;
 import ghidra.program.util.VarnodeContext;

 public final class ReaGhidraBridge extends HeadlessScript {
+    // At most 24 KiB after worst-case JSON escaping (six bytes per UTF-16 unit).
+    private static final int PDB_ATTRIBUTE_UTF16_BUDGET = 4096;
    private static final int MAX_HIGH_PCODE_OPS = 3000;
    private static final int MAX_HIGH_PCODE_INPUTS_PER_OP = 64;
    private static final int MAX_HIGH_PCODE_DEF_USE_EDGES = 12000;
@@ -137,6 +142,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
        "set_addresses_names",
        "inspect_native_load_image",
        "read_bytes",
+        "search_bytes",
        "address_to_file_offset",
        "ping",
        "shutdown",
@@ -374,6 +380,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
        return switch (request.method) {
            case "inspect_native_load_image" -> inspectNativeLoadImage(request.params);
            case "read_bytes" -> readMemoryBytes(request.params);
+            case "search_bytes" -> searchMemoryBytes(request.params, descriptor);
            case "address_to_file_offset" -> addressToFileOffset(request.params);
            case "address_name" -> addressName(request.params);
            case "list_documents" -> listDocuments(request.params);
@@ -454,6 +461,7 @@ public final class ReaGhidraBridge extends HeadlessScript {
                .toArray(String[]::new)
        ));
        result.add("target", target);
+        result.add("pdb", pdbObservation());
        JsonArray extensions = analysisExtensions.reports();
        if (extensions.size() > 0) result.add("analysis_extensions", extensions);
        // Written by ReaGhidraApplySeeds before auto-analysis; REA checks it
@@ -469,6 +477,41 @@ public final class ReaGhidraBridge extends HeadlessScript {
        return result;
    }

+    /** Read loader/analyzer-owned facts without searching for or applying companions. */
+    private JsonObject pdbObservation() {
+        Options info = currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO);
+        JsonObject pdb = new JsonObject();
+        String[] names = {"file", "guid", "age", "signature", "version"};
+        String[] attributes = {
+            PdbParserConstants.PDB_FILE, PdbParserConstants.PDB_GUID,
+            PdbParserConstants.PDB_AGE, PdbParserConstants.PDB_SIGNATURE,
+            PdbParserConstants.PDB_VERSION
+        };
+        int remaining = PDB_ATTRIBUTE_UTF16_BUDGET;
+        JsonArray omitted = new JsonArray();
+        for (int index = 0; index < names.length; index++) {
+            String value = info.getString(attributes[index], null);
+            if (value != null && value.length() > remaining) {
+                omitted.add(names[index]);
+                pdb.add(names[index], JsonNull.INSTANCE);
+            } else {
+                pdb.addProperty(names[index], value);
+                if (value != null) remaining -= value.length();
+            }
+        }
+        if (omitted.size() > 0) {
+            JsonObject limit = new JsonObject();
+            limit.addProperty("utf16_budget", PDB_ATTRIBUTE_UTF16_BUDGET);
+            limit.add("omitted_attributes", omitted);
+            pdb.add("resource_limit", limit);
+        }
+        if (info.contains(PdbParserConstants.PDB_LOADED))
+            pdb.addProperty("loaded", info.getBoolean(PdbParserConstants.PDB_LOADED, false));
+        else
+            pdb.add("loaded", JsonNull.INSTANCE);
+        return pdb;
+    }
+
    private static String bytesHex(byte[] bytes) {
        return java.util.HexFormat.of().formatHex(bytes);
    }
@@ -644,6 +687,160 @@ public final class ReaGhidraBridge extends HeadlessScript {
        return result;
    }

+    private JsonObject searchMemoryBytes(JsonObject params, SessionDescriptor descriptor) throws Exception {
+        // mask, start, end, and cursor are omitted when absent; JSON encoding drops those keys.
+        Set<String> keys = params.keySet();
+        if (!keys.containsAll(Set.of("document", "pattern", "limit")) ||
+            !Set.of("document", "pattern", "mask", "start", "end", "limit", "cursor").containsAll(keys))
+            throw new RequestFailure("invalid_request", "Bridge request fields are invalid");
+        requireDocument(params);
+        // Public input validation owns the grammar; validate again at the socket boundary.
+        String pattern = requireString(params, "pattern").replaceAll("[\\s\\p{Z}\\uFEFF]", "");
+        String mask = params.has("mask") ? requireString(params, "mask") : null;
+        if (mask != null) mask = mask.replaceAll("[\\s\\p{Z}\\uFEFF]", "");
+        if (pattern.isEmpty() || pattern.length() % 2 != 0 ||
+            (mask != null && mask.length() != pattern.length()))
+            throw new RequestFailure("invalid_request", "Mask length must equal a nonempty byte pattern length");
+        byte[] bytes = new byte[pattern.length() / 2];
+        byte[] masks = new byte[bytes.length];
+        boolean constrained = false;
+        for (int index = 0; index < bytes.length; index++) {
+            monitor.checkCancelled();
+            String pair = pattern.substring(index * 2, index * 2 + 2);
+            if ((!pair.equals("??") && !isHexadecimal(pair, 0, 2)) ||
+                (mask != null && !isHexadecimal(mask, index * 2, index * 2 + 2)))
+                throw new RequestFailure("invalid_request", "Use hexadecimal byte pairs or ?? wildcards");
+            int selected = mask == null ? 255 : Integer.parseInt(mask.substring(index * 2, index * 2 + 2), 16);
+            bytes[index] = (byte) (pair.equals("??") ? 0 : Integer.parseInt(pair, 16));
+            masks[index] = (byte) (pair.equals("??") ? 0 : selected);
+            constrained |= masks[index] != 0;
+        }
+        if (!constrained) throw new RequestFailure("invalid_request", "Pattern must constrain at least one bit");
+        int limit = requireBoundedInteger(params, "limit", 1, 1000);
+        Address start = params.has("start") ? requireAddress(params, "start") : null;
+        Address end = params.has("end") ? requireAddress(params, "end") : null;
+        if (start != null && end != null &&
+            (!start.getAddressSpace().equals(end.getAddressSpace()) || start.compareTo(end) > 0))
+            throw new RequestFailure("invalid_request", "Search bounds must be ordered in one address space");
+        JsonArray identity = new JsonArray();
+        for (String value : new String[] { descriptor.targetSha256, descriptor.profileDigest,
+                bytesHex(bytes), bytesHex(masks), start == null ? "" : canonicalAddress(start),
+                end == null ? "" : canonicalAddress(end), optionalString(params, "document") }) identity.add(value);
+        String binding = bytesHex(MessageDigest.getInstance("SHA-256").digest(identity.toString().getBytes(StandardCharsets.UTF_8)));
+        String cursor = params.has("cursor") ? requireString(params, "cursor") : null;
+        Address resume = null;
+        if (cursor != null) {
+            if (!cursor.startsWith(binding + ":"))
+                throw new RequestFailure("invalid_request", "Byte search cursor does not match the target and query");
+            resume = parseReaAddress(cursor.substring(binding.length() + 1));
+            MemoryBlock resumedBlock = currentProgram.getMemory().getBlock(resume);
+            Address bound = start == null ? end : start;
+            if (resumedBlock == null || !resumedBlock.isInitialized() ||
+                (bound != null && !bound.getAddressSpace().equals(resume.getAddressSpace())) ||
+                (start != null && resume.compareTo(start) < 0) ||
+                (end != null && resume.compareTo(end) > 0))
+                throw new RequestFailure("invalid_request", "Byte search cursor lies outside initialized query memory");
+        }
+        List<MemoryBlock> ordered = new ArrayList<>(List.of(currentProgram.getMemory().getBlocks()));
+        ordered.sort(Comparator.comparing(MemoryBlock::getStart));
+        JsonArray matches = new JsonArray();
+        JsonArray blocks = new JsonArray();
+        JsonArray skipped = new JsonArray();
+        JsonArray notLoaded = new JsonArray();
+        long covered = 0;
+        String next = null;
+        for (MemoryBlock block : ordered) {
+            monitor.checkCancelled();
+            Address low = block.getStart();
+            Address high = block.getEnd();
+            Address bound = start == null ? end : start;
+            if (bound != null && !bound.getAddressSpace().equals(low.getAddressSpace())) continue;
+            // Without bounds, search loaded memory only. Non-loaded file parts
+            // (such as .symtab) and overlays stay reachable through explicit bounds.
+            if (bound == null && (!block.isLoaded() || block.isOverlay())) {
+                notLoaded.add(byteSearchCoverage(block, low, high));
+                continue;
+            }
+            if (start != null && low.compareTo(start) < 0) low = start;
+            if (end != null && high.compareTo(end) > 0) high = end;
+            if (low.compareTo(high) > 0) continue;
+            if (!block.isInitialized()) {
+                skipped.add(byteSearchCoverage(block, low, high));
+                continue;
+            }
+            if (next != null) continue;
+            if (resume != null && low.compareTo(resume) < 0) low = resume;
+            if (low.compareTo(high) > 0 || !low.getAddressSpace().equals(high.getAddressSpace())) continue;
+            Address at = low;
+            Address examinedEnd = high;
+            while (at != null && at.compareTo(high) <= 0 && high.subtract(at) >= bytes.length - 1L) {
+                monitor.checkCancelled();
+                // Ghidra's end address bounds candidate starts, not the final matched byte.
+                Address found = currentProgram.getMemory().findBytes(at, high.subtract(bytes.length - 1L), bytes, masks, true, monitor);
+                monitor.checkCancelled();
+                if (found == null || high.subtract(found) < bytes.length - 1L) break;
+                if (matches.size() == limit) {
+                    next = binding + ":" + canonicalAddress(found);
+                    examinedEnd = found.addNoWrap(bytes.length - 1L);
+                    break;
+                }
+                JsonObject match = new JsonObject();
+                match.addProperty("address", canonicalAddress(found));
+                match.addProperty("segment", block.getName());
+                Long offset = targetFileOffset(block, found).offset();
+                match.add("file_offset", offset == null ? JsonNull.INSTANCE : GSON.toJsonTree(offset));
+                Function function = currentProgram.getFunctionManager().getFunctionContaining(found);
+                JsonObject procedure = new JsonObject();
+                if (function != null) {
+                    procedure.addProperty("address", canonicalAddress(function.getEntryPoint()));
+                    procedure.addProperty("name", function.getName(true));
+                }
+                match.add("procedure", function == null ? JsonNull.INSTANCE : procedure);
+                matches.add(match);
+                at = found.next();
+            }
+            JsonObject coverage = byteSearchCoverage(block, low, examinedEnd);
+            covered = Math.addExact(covered, coverage.get("bytes").getAsLong());
+            blocks.add(coverage);
+        }
+        JsonObject searched = new JsonObject();
+        searched.add("blocks", blocks);
+        searched.addProperty("bytes", covered);
+        searched.add("skipped_uninitialized", skipped);
+        searched.add("skipped_not_loaded", notLoaded);
+        JsonObject result = new JsonObject();
+        result.add("matches", matches);
+        result.add("searched", searched);
+        result.addProperty("complete", next == null);
+        result.add("next_cursor", next == null ? JsonNull.INSTANCE : GSON.toJsonTree(next));
+        return result;
+    }
+
+    private static JsonObject byteSearchCoverage(MemoryBlock block, Address low, Address high) {
+        JsonObject result = new JsonObject();
+        result.addProperty("segment", block.getName());
+        result.addProperty("start", canonicalAddress(low));
+        result.addProperty("end", canonicalAddress(high));
+        result.addProperty("bytes", high.subtract(low) + 1);
+        return result;
+    }
+
+    private record TargetFileOffset(Long offset, int mappings) {}
+
+    private TargetFileOffset targetFileOffset(MemoryBlock block, Address address) throws Exception {
+        Long offset = null;
+        int mappings = 0;
+        for (MemoryBlockSourceInfo source : block.getSourceInfos()) {
+            if (!source.contains(address) || source.getFileBytes().isEmpty() ||
+                !isTargetSource(source.getFileBytes().get())) continue;
+            long candidate = source.getFileBytesOffset(address);
+            if (candidate < 0) continue;
+            offset = candidate;
+            mappings++;
+        }
+        return new TargetFileOffset(mappings == 1 && offset <= 9007199254740991L ? offset : null, mappings);
+    }
+
    private JsonObject addressToFileOffset(JsonObject params) throws Exception {
        requireKeys(params, Set.of("document", "address"));
        requireDocument(params);
@@ -651,18 +848,12 @@ public final class ReaGhidraBridge extends HeadlessScript {
        MemoryBlock block = currentProgram.getMemory().getBlock(address);
        if (block == null || !block.isInitialized())
            throw new RequestFailure("invalid_request", "Address has no initialized file-backed memory: " + canonicalAddress(address));
-        Long fileOffset = null;
-        int mappings = 0;
-        for (MemoryBlockSourceInfo source : block.getSourceInfos()) {
-            if (!source.contains(address) || source.getFileBytes().isEmpty() ||
-                !isTargetSource(source.getFileBytes().get())) continue;
-            long offset = source.getFileBytesOffset(address);
-            if (offset < 0) continue;
-            fileOffset = offset;
-            mappings++;
-        }
-        if (mappings != 1)
-            throw new RequestFailure("invalid_request", "Address has " + mappings + " authoritative target-file mappings: " + canonicalAddress(address));
+        TargetFileOffset mapping = targetFileOffset(block, address);
+        if (mapping.mappings() != 1)
+            throw new RequestFailure("invalid_request", "Address has " + mapping.mappings() + " authoritative target-file mappings: " + canonicalAddress(address));
+        Long fileOffset = mapping.offset();
+        if (fileOffset == null)
+            throw new RequestFailure("invalid_request", "Address lacks a safe file offset: " + canonicalAddress(address));
        JsonObject result = new JsonObject();
        result.addProperty("address", canonicalAddress(address));
        result.addProperty("file_offset", fileOffset);
@@ -11,6 +11,12 @@ import sys

 PROFILE = "pwntools@4.15.0;pyelftools@0.33;unicorn@2.1.2"

+# Linux ET_CORE machine identifiers whose PRSTATUS layout is interpreted with
+# unchanged pwntools 4.15.0 ctypes. Both share pr_cursig@12, pr_pid@32 and
+# pr_reg@112; only the register window differs: amd64 is 27 x 8 bytes for a
+# 336-byte descriptor, AArch64 is 34 x 8 bytes for a 392-byte descriptor.
+CORE_MACHINES = (62, 183)
+

 class CoreFailure(Exception):
    def __init__(self, reason, message):
@@ -51,12 +57,27 @@ def inspect_core(path, cache):
    # Other declared OSABIs must never select Linux note ctypes.
    if content[7] not in (0, 3) or content[8] != 0:
        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires System V or GNU/Linux OSABI with ABI version zero; selected OSABI=" + str(content[7]) + ", ABI version=" + str(content[8]) + ".")
-    if int.from_bytes(content[16:18], "little") != 4 or int.from_bytes(content[18:20], "little") != 62:
-        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires x86-64 ET_CORE.")
+    machine = int.from_bytes(content[18:20], "little")
+    if int.from_bytes(content[16:18], "little") != 4 or machine not in CORE_MACHINES:
+        raise CoreFailure("unsupported-target", "Initial recorded-core profile requires ET_CORE for x86-64 or AArch64; selected ET_TYPE=" + str(int.from_bytes(content[16:18], "little")) + ", e_machine=" + str(machine) + ".")
    from elftools.common.exceptions import ELFError
    from elftools.common.utils import struct_parse
    from elftools.elf.elffile import ELFFile
-    from pwnlib.elf.datatypes import elf_prstatus_amd64, elf_siginfo_64, user_regs_struct_amd64
+    from pwnlib.elf.datatypes import (
+        elf_prstatus_aarch64,
+        elf_prstatus_amd64,
+        elf_siginfo_64,
+        user_regs_struct_aarch64,
+        user_regs_struct_amd64,
+    )
+    if machine == 62:
+        profile_label = "x86-64"
+        architecture = "x86_64-little-endian"
+        prstatus_type, registers_type = elf_prstatus_amd64, user_regs_struct_amd64
+    else:
+        profile_label = "AArch64"
+        architecture = "aarch64-little-endian"
+        prstatus_type, registers_type = elf_prstatus_aarch64, user_regs_struct_aarch64
    try:
        image = ELFFile(io.BytesIO(content))
        header = image.header
@@ -107,17 +128,17 @@ def inspect_core(path, cache):
                if owner != b"CORE\0":
                    continue
                if note.n_type == "NT_PRSTATUS":
-                    if len(descriptor) < ctypes.sizeof(elf_prstatus_amd64):
-                        raise CoreFailure("format", "Linux amd64 NT_PRSTATUS descriptor is truncated.")
-                    status = elf_prstatus_amd64.from_buffer_copy(descriptor)
+                    if len(descriptor) < ctypes.sizeof(prstatus_type):
+                        raise CoreFailure("format", "Linux " + profile_label + " NT_PRSTATUS descriptor is truncated.")
+                    status = prstatus_type.from_buffer_copy(descriptor)
                    registers = []
-                    for name, kind in user_regs_struct_amd64._fields_:
-                        relative = elf_prstatus_amd64.pr_reg.offset + getattr(user_regs_struct_amd64, name).offset
+                    for name, kind in registers_type._fields_:
+                        relative = prstatus_type.pr_reg.offset + getattr(registers_type, name).offset
                        registers.append({"name": name, "value": hex(getattr(status.pr_reg, name)), "location": location(descriptor_start + relative, ctypes.sizeof(kind), end)})
                    threads.append({"note_index": note_index, "historical_pid": ctypes.c_int32(status.pr_pid).value, "recorded_current_signal": status.pr_cursig, "registers": registers})
                elif note.n_type == "NT_SIGINFO":
                    if len(descriptor) < ctypes.sizeof(elf_siginfo_64):
-                        raise CoreFailure("format", "Linux amd64 NT_SIGINFO descriptor is truncated.")
+                        raise CoreFailure("format", "Linux " + profile_label + " NT_SIGINFO descriptor is truncated.")
                    signal = elf_siginfo_64.from_buffer_copy(descriptor)
                    number = ctypes.c_int32(signal.si_signo).value
                    code = ctypes.c_int32(signal.si_code).value
@@ -125,7 +146,7 @@ def inspect_core(path, cache):
                    signals.append({"note_index": note_index, "number": number, "code": code, "errno": ctypes.c_int32(signal.si_errno).value,
                                    "fault_address": hex(signal.sigfault_addr) if known else None,
                                    "fault_address_meaning": "recorded-sigsegv-address" if known else "unknown", "thread_association": "unknown"})
-        return {"format": "elf-core", "architecture": "x86_64-little-endian", "target_execution": "not-performed", "live_process_identity": "unknown",
+        return {"format": "elf-core", "architecture": architecture, "target_execution": "not-performed", "live_process_identity": "unknown",
                "segments": segments, "notes": notes, "note_padding": padding, "threads": threads, "signals": signals,
                "note_interpretation_completeness": "unknown",
                "limitations": ["The initial Linux note profile accepts System V/unspecified or GNU/Linux OSABI with ABI version zero; an unspecified OSABI alone does not prove operating-system origin.",
@@ -1,4 +1,18 @@
 import { defineConfig } from "vitepress";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  documentationRewrites,
+  documentationSections,
+} from "./documentation.js";
+
+const documentationRoot = fileURLToPath(new URL("..", import.meta.url));
+const rewrites: Record<string, string> = {
+  ...documentationRewrites,
+  "README.md": "documentation.md",
+  "specs/README.md": "specs/index.md",
+  "adr/README.md": "adr/index.md",
+};

 export default defineConfig({
  title: "REA",
@@ -6,79 +20,92 @@ export default defineConfig({
    "Reverse engineer binaries, applications, and runtime behavior with one CLI and MCP server.",
  lang: "en-US",
  base: "/rea/",
+  rewrites,
+  markdown: {
+    config(md) {
+      // Repository links resolve from their physical source. Render them from
+      // the stable public route instead, including links across categories.
+      md.core.ruler.after("inline", "documentation-source-links", (state) => {
+        const physicalPath =
+          state.env.realPath ??
+          (state.env.relativePath
+            ? resolve(documentationRoot, state.env.relativePath)
+            : null);
+        if (physicalPath === null) return;
+        const renderedPath =
+          state.env.path ??
+          resolve(
+            documentationRoot,
+            rewrites[state.env.relativePath] ?? state.env.relativePath,
+          );
+        for (const block of state.tokens) {
+          for (const token of block.children ?? []) {
+            const attribute =
+              token.type === "link_open"
+                ? "href"
+                : token.type === "image"
+                  ? "src"
+                  : null;
+            if (attribute === null) continue;
+            const destination = token.attrGet(attribute);
+            if (
+              !destination ||
+              /^(?:[a-z][a-z\d+.-]*:|[/#])/iu.test(destination)
+            )
+              continue;
+            const separator = destination.search(/[?#]/u);
+            const path =
+              separator === -1 ? destination : destination.slice(0, separator);
+            const suffix = separator === -1 ? "" : destination.slice(separator);
+            const source = relative(
+              documentationRoot,
+              resolve(dirname(physicalPath), path),
+            )
+              .split(sep)
+              .join("/");
+            const rendered = relative(
+              dirname(renderedPath),
+              resolve(
+                documentationRoot,
+                source.startsWith("public/")
+                  ? source.slice("public/".length)
+                  : (rewrites[source] ?? source),
+              ),
+            )
+              .split(sep)
+              .join("/");
+            token.attrSet(attribute, rendered + suffix);
+          }
+        }
+      });
+    },
+  },
+  srcExclude: ["readme/**"],
  themeConfig: {
    nav: [
      { text: "Get started", link: "/installation" },
+      { text: "Documentation", link: "/documentation" },
      { text: "Reference", link: "/mcp-contracts" },
      { text: "Roadmap", link: "/roadmap" },
    ],
    sidebar: [
      {
-        text: "Getting started",
+        text: "Documentation directory",
        items: [
-          { text: "Installation and setup", link: "/installation" },
-          { text: "Client configuration", link: "/client-configuration" },
-          { text: "CLI and Evidence", link: "/cli" },
-          { text: "Agent prompts", link: "/mcp-prompts" },
-          { text: "Roadmap", link: "/roadmap" },
-        ],
-      },
-      {
-        text: "Investigation guides",
-        items: [
-          { text: "Native binaries", link: "/native-investigation" },
-          { text: "Go build metadata", link: "/go-binaries" },
-          {
-            text: "JavaScript and Electron",
-            link: "/javascript-artifact-reconstruction",
-          },
-          {
-            text: "JavaScript workflows",
-            link: "/javascript-application-workflows",
-          },
-          { text: "Browser observation", link: "/browser-observation" },
-          {
-            text: "Web network captures",
-            link: "/web-network-captures",
-          },
-          { text: "Electron observation", link: "/electron-observation" },
-          { text: "Process capture", link: "/process-capture" },
-          { text: ".NET assemblies", link: "/managed-code-analysis" },
-          { text: "Android applications", link: "/android-analysis" },
-          { text: "Apple applications", link: "/apple-application-analysis" },
-          { text: "Firmware", link: "/firmware-analysis" },
-          { text: "SQLite databases", link: "/sqlite-databases" },
-          { text: "Packet captures", link: "/packet-captures" },
-          { text: "Signal recordings", link: "/signal-recordings" },
-        ],
-      },
-      {
-        text: "Provider guides",
-        collapsed: true,
-        items: [
-          { text: "IDA", link: "/ida-provider" },
-          { text: "Ghidra on Windows", link: "/windows-ghidra-p0" },
-          { text: "Ghidra DOS analysis", link: "/ghidra-dos" },
-          { text: "Ghidra raw binary", link: "/raw-binary" },
-          { text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
-          { text: "Ghidra semantics", link: "/ghidra-provider" },
-        ],
-      },
-      {
-        text: "Reference and development",
-        collapsed: true,
-        items: [
-          { text: "MCP contracts", link: "/mcp-contracts" },
-          { text: "Tool design", link: "/tool-design" },
-          { text: "Testing", link: "/testing" },
-          { text: "Client verification", link: "/client-verification" },
-          {
-            text: "Reconstruction readiness",
-            link: "/reconstruction-readiness",
-          },
-          { text: "Releasing", link: "/releasing" },
+          { text: "All guides", link: "/documentation" },
+          { text: "Authoring conventions", link: "/development/documentation" },
+          { text: "Feature specifications", link: "/specs/" },
+          { text: "Architecture decisions", link: "/adr/" },
        ],
      },
+      ...documentationSections.map((section) => ({
+        text: section.text,
+        collapsed: section.text !== "Getting started",
+        items: section.items.map((item) => ({
+          text: item.text,
+          link: item.route,
+        })),
+      })),
    ],
    search: { provider: "local" },
    socialLinks: [
@@ -0,0 +1,384 @@
+// Authored guide ownership: physical sources and stable public routes.
+export const documentationSections = [
+  {
+    text: "Getting started",
+    items: [
+      {
+        text: "Installation and setup",
+        source: "getting-started/installation.md",
+        route: "/installation",
+      },
+      {
+        text: "Client configuration and troubleshooting",
+        source: "getting-started/client-configuration.md",
+        route: "/client-configuration",
+      },
+      {
+        text: "CLI and Evidence",
+        source: "getting-started/cli.md",
+        route: "/cli",
+      },
+      {
+        text: "Guided MCP prompts and completion",
+        source: "getting-started/mcp-prompts.md",
+        route: "/mcp-prompts",
+      },
+    ],
+  },
+  {
+    text: "Native binaries",
+    items: [
+      {
+        text: "Native binary investigation",
+        source: "guides/native/native-investigation.md",
+        route: "/native-investigation",
+      },
+      {
+        text: "Go binary build metadata",
+        source: "guides/native/go-binaries.md",
+        route: "/go-binaries",
+      },
+      {
+        text: "Offline binary diagnostics",
+        source: "guides/native/binary-diagnostics.md",
+        route: "/binary-diagnostics",
+      },
+      {
+        text: "Recorded crash evidence",
+        source: "guides/native/recorded-crashes.md",
+        route: "/recorded-crashes",
+      },
+    ],
+  },
+  {
+    text: "JavaScript and Electron",
+    items: [
+      {
+        text: "JavaScript Application Graph",
+        source: "guides/javascript/javascript-application-graph.md",
+        route: "/javascript-application-graph",
+      },
+      {
+        text: "Cross-layer JavaScript application workflows",
+        source: "guides/javascript/javascript-application-workflows.md",
+        route: "/javascript-application-workflows",
+      },
+      {
+        text: "JavaScript artifact reconstruction",
+        source: "guides/javascript/javascript-artifact-reconstruction.md",
+        route: "/javascript-artifact-reconstruction",
+      },
+      {
+        text: "JavaScript source recovery",
+        source: "guides/javascript/javascript-recovery.md",
+        route: "/javascript-recovery",
+      },
+      {
+        text: "Passive Node and Electron runtime observation",
+        source: "guides/javascript/javascript-runtime-observation.md",
+        route: "/javascript-runtime-observation",
+      },
+      {
+        text: "JavaScript static/runtime reconciliation",
+        source: "guides/javascript/javascript-runtime-reconciliation.md",
+        route: "/javascript-runtime-reconciliation",
+      },
+      {
+        text: "Electron file-page observation",
+        source: "guides/javascript/electron-observation.md",
+        route: "/electron-observation",
+      },
+    ],
+  },
+  {
+    text: "Browser and captured websites",
+    items: [
+      {
+        text: "Website observation with CDP",
+        source: "guides/web/browser-observation.md",
+        route: "/browser-observation",
+      },
+      {
+        text: "Browser scenario contract",
+        source: "guides/web/browser-scenario-contract.md",
+        route: "/browser-scenario-contract",
+      },
+      {
+        text: "Website runtime source attribution",
+        source: "guides/web/web-runtime.md",
+        route: "/web-runtime",
+      },
+      {
+        text: "Historical web network captures",
+        source: "guides/web/web-network-captures.md",
+        route: "/web-network-captures",
+      },
+      {
+        text: "Captured website source locations",
+        source: "guides/web/web-source-location.md",
+        route: "/web-source-location",
+      },
+      {
+        text: "Captured website module relationships",
+        source: "guides/web/website-module-trace.md",
+        route: "/website-module-trace",
+      },
+      {
+        text: "Captured website scripts and static JavaScript analysis",
+        source: "guides/web/website-script-export.md",
+        route: "/website-script-export",
+      },
+    ],
+  },
+  {
+    text: "Android applications",
+    items: [
+      {
+        text: "Static Android APK analysis",
+        source: "guides/android/android-analysis.md",
+        route: "/android-analysis",
+      },
+      {
+        text: "Apktool resource decoding",
+        source: "guides/android/apktool-resource-analysis.md",
+        route: "/apktool-resource-analysis",
+      },
+      {
+        text: "ADB device inspection and acquisition",
+        source: "guides/android/adb-device-analysis.md",
+        route: "/adb-device-analysis",
+      },
+      {
+        text: "Flutter build identification",
+        source: "guides/android/flutter-analysis.md",
+        route: "/flutter-analysis",
+      },
+    ],
+  },
+  {
+    text: "Apple applications",
+    items: [
+      {
+        text: "Apple Application Inventory Projection",
+        source: "guides/apple/apple-application-analysis.md",
+        route: "/apple-application-analysis",
+      },
+    ],
+  },
+  {
+    text: ".NET assemblies",
+    items: [
+      {
+        text: "Managed-code analysis",
+        source: "guides/managed/managed-code-analysis.md",
+        route: "/managed-code-analysis",
+      },
+    ],
+  },
+  {
+    text: "Firmware",
+    items: [
+      {
+        text: "Firmware analysis",
+        source: "guides/firmware/firmware-analysis.md",
+        route: "/firmware-analysis",
+      },
+    ],
+  },
+  {
+    text: "HarmonyOS packages",
+    items: [
+      {
+        text: "Static HarmonyOS package inventory",
+        source: "guides/harmony/harmony-analysis.md",
+        route: "/harmony-analysis",
+      },
+    ],
+  },
+  {
+    text: "WebAssembly",
+    items: [
+      {
+        text: "Offline WebAssembly artifacts",
+        source: "guides/wasm/wasm-artifacts.md",
+        route: "/wasm-artifacts",
+      },
+    ],
+  },
+  {
+    text: "EVM contracts",
+    items: [
+      {
+        text: "Offline EVM bytecode",
+        source: "guides/evm/evm-bytecode.md",
+        route: "/evm-bytecode",
+      },
+    ],
+  },
+  {
+    text: "Databases and recorded packets",
+    items: [
+      {
+        text: "SQLite database snapshots",
+        source: "guides/data/sqlite-databases.md",
+        route: "/sqlite-databases",
+      },
+      {
+        text: "Recorded packet capture inspection",
+        source: "guides/data/packet-captures.md",
+        route: "/packet-captures",
+      },
+      {
+        text: "Packet capture summaries",
+        source: "guides/data/pcap-analysis.md",
+        route: "/pcap-analysis",
+      },
+    ],
+  },
+  {
+    text: "Process capture and instrumentation",
+    items: [
+      {
+        text: "Process capture",
+        source: "guides/runtime/process-capture.md",
+        route: "/process-capture",
+      },
+      {
+        text: "Frida instrumentation",
+        source: "guides/runtime/frida-instrumentation.md",
+        route: "/frida-instrumentation",
+      },
+    ],
+  },
+  {
+    text: "Provider setup and formats",
+    items: [
+      {
+        text: "Ghidra provider semantics",
+        source: "providers/ghidra-provider.md",
+        route: "/ghidra-provider",
+      },
+      {
+        text: "DOS MZ and COM analysis with Ghidra",
+        source: "providers/ghidra-dos.md",
+        route: "/ghidra-dos",
+      },
+      {
+        text: "Optional NativeAOT metadata recovery",
+        source: "providers/ghidra-nativeaot.md",
+        route: "/ghidra-nativeaot",
+      },
+      {
+        text: "MIPS ELF analysis through Ghidra",
+        source: "providers/ghidra-mips.md",
+        route: "/ghidra-mips",
+      },
+      {
+        text: "PSP static ELF analysis through Ghidra",
+        source: "providers/ghidra-psp.md",
+        route: "/ghidra-psp",
+      },
+      {
+        text: "RISC-V ELF analysis through Ghidra",
+        source: "providers/ghidra-riscv.md",
+        route: "/ghidra-riscv",
+      },
+      {
+        text: "Windows Ghidra P0",
+        source: "providers/windows-ghidra-p0.md",
+        route: "/windows-ghidra-p0",
+      },
+      {
+        text: "Headerless raw-binary analysis with Ghidra",
+        source: "providers/raw-binary.md",
+        route: "/raw-binary",
+      },
+      {
+        text: "IDA provider",
+        source: "providers/ida-provider.md",
+        route: "/ida-provider",
+      },
+      {
+        text: "JEB instrumentation and analysis",
+        source: "providers/jeb-analysis.md",
+        route: "/jeb-analysis",
+      },
+    ],
+  },
+  {
+    text: "Contracts and evidence",
+    items: [
+      {
+        text: "MCP runtime contracts",
+        source: "reference/mcp-contracts.md",
+        route: "/mcp-contracts",
+      },
+      {
+        text: "Reconstruction obligation ledgers",
+        source: "reference/reconstruction-obligation-ledgers.md",
+        route: "/reconstruction-obligation-ledgers",
+      },
+    ],
+  },
+  {
+    text: "Development and verification",
+    items: [
+      {
+        text: "MCP tool design",
+        source: "development/tool-design.md",
+        route: "/tool-design",
+      },
+      {
+        text: "Testing REA",
+        source: "development/testing.md",
+        route: "/testing",
+      },
+      {
+        text: "Client and agent verification",
+        source: "development/client-verification.md",
+        route: "/client-verification",
+      },
+      {
+        text: "Reconstruction readiness conformance",
+        source: "development/reconstruction-readiness.md",
+        route: "/reconstruction-readiness",
+      },
+      {
+        text: "Releasing REA",
+        source: "development/releasing.md",
+        route: "/releasing",
+      },
+      {
+        text: "REA roadmap",
+        source: "development/roadmap.md",
+        route: "/roadmap",
+      },
+    ],
+  },
+  {
+    text: "Release migrations",
+    items: [
+      {
+        text: "Upgrading from REA 6.1 to 6.2",
+        source: "migrations/migration-6.2.md",
+        route: "/migration-6.2",
+      },
+    ],
+  },
+  {
+    text: "Signal recordings",
+    items: [
+      {
+        text: "Recorded signal inspection",
+        source: "guides/signals/signal-recordings.md",
+        route: "/signal-recordings",
+      },
+    ],
+  },
+];
+
+export const documentationRewrites = Object.fromEntries(
+  documentationSections.flatMap((section) =>
+    section.items.map((item) => [item.source, `${item.route.slice(1)}.md`]),
+  ),
+);
@@ -0,0 +1,138 @@
+# Documentation directory
+
+REA documentation is organized by reader task and document owner. This directory
+links every authored guide; the [site](https://rea.tools/) also serves separate
+product pages. The VitePress documentation source is this `docs/` tree.
+
+## Getting started
+
+- [Installation and setup](getting-started/installation.md)
+- [Client configuration and troubleshooting](getting-started/client-configuration.md)
+- [CLI and Evidence](getting-started/cli.md)
+- [Guided MCP prompts and completion](getting-started/mcp-prompts.md)
+
+## Native binaries
+
+- [Native binary investigation](guides/native/native-investigation.md)
+- [Go binary build metadata](guides/native/go-binaries.md)
+- [Offline binary diagnostics](guides/native/binary-diagnostics.md)
+- [Recorded crash evidence](guides/native/recorded-crashes.md)
+
+## JavaScript and Electron
+
+- [JavaScript Application Graph](guides/javascript/javascript-application-graph.md)
+- [Cross-layer JavaScript application workflows](guides/javascript/javascript-application-workflows.md)
+- [JavaScript artifact reconstruction](guides/javascript/javascript-artifact-reconstruction.md)
+- [JavaScript source recovery](guides/javascript/javascript-recovery.md)
+- [Passive Node and Electron runtime observation](guides/javascript/javascript-runtime-observation.md)
+- [JavaScript static/runtime reconciliation](guides/javascript/javascript-runtime-reconciliation.md)
+- [Electron file-page observation](guides/javascript/electron-observation.md)
+
+## Browser and captured websites
+
+- [Website observation with CDP](guides/web/browser-observation.md)
+- [Browser scenario contract](guides/web/browser-scenario-contract.md)
+- [Website runtime source attribution](guides/web/web-runtime.md)
+- [Historical web network captures](guides/web/web-network-captures.md)
+- [Captured website source locations](guides/web/web-source-location.md)
+- [Captured website module relationships](guides/web/website-module-trace.md)
+- [Captured website scripts and static JavaScript analysis](guides/web/website-script-export.md)
+
+## Android applications
+
+- [Static Android APK analysis](guides/android/android-analysis.md)
+- [Apktool resource decoding](guides/android/apktool-resource-analysis.md)
+- [ADB device inspection and acquisition](guides/android/adb-device-analysis.md)
+- [Flutter build identification](guides/android/flutter-analysis.md)
+
+## Apple applications
+
+- [Apple Application Inventory Projection](guides/apple/apple-application-analysis.md)
+
+## .NET assemblies
+
+- [Managed-code analysis](guides/managed/managed-code-analysis.md)
+
+## Firmware
+
+- [Firmware analysis](guides/firmware/firmware-analysis.md)
+
+## HarmonyOS packages
+
+- [Static HarmonyOS package inventory](guides/harmony/harmony-analysis.md)
+
+## WebAssembly
+
+- [Offline WebAssembly artifacts](guides/wasm/wasm-artifacts.md)
+
+## EVM contracts
+
+- [Offline EVM bytecode](guides/evm/evm-bytecode.md)
+
+## Databases and recorded packets
+
+- [SQLite database snapshots](guides/data/sqlite-databases.md)
+- [Recorded packet capture inspection](guides/data/packet-captures.md)
+- [Packet capture summaries](guides/data/pcap-analysis.md)
+
+## Process capture and instrumentation
+
+- [Process capture](guides/runtime/process-capture.md)
+- [Frida instrumentation](guides/runtime/frida-instrumentation.md)
+
+## Signal recordings
+
+- [Recorded signal inspection](guides/signals/signal-recordings.md)
+
+## Provider setup and formats
+
+- [Ghidra provider semantics](providers/ghidra-provider.md)
+- [DOS MZ and COM analysis with Ghidra](providers/ghidra-dos.md)
+- [Optional NativeAOT metadata recovery](providers/ghidra-nativeaot.md)
+- [MIPS ELF analysis through Ghidra](providers/ghidra-mips.md)
+- [PSP static ELF analysis through Ghidra](providers/ghidra-psp.md)
+- [RISC-V ELF analysis through Ghidra](providers/ghidra-riscv.md)
+- [Windows Ghidra P0](providers/windows-ghidra-p0.md)
+- [Headerless raw-binary analysis with Ghidra](providers/raw-binary.md)
+- [IDA provider](providers/ida-provider.md)
+- [JEB instrumentation and analysis](providers/jeb-analysis.md)
+
+## Contracts and evidence
+
+- [MCP runtime contracts](reference/mcp-contracts.md)
+- [Reconstruction obligation ledgers](reference/reconstruction-obligation-ledgers.md)
+
+## Development and verification
+
+- [MCP tool design](development/tool-design.md)
+- [Testing REA](development/testing.md)
+- [Client and agent verification](development/client-verification.md)
+- [Reconstruction readiness conformance](development/reconstruction-readiness.md)
+- [Releasing REA](development/releasing.md)
+- [REA roadmap](development/roadmap.md)
+
+## Release migrations
+
+- [Upgrading from REA 6.1 to 6.2](migrations/migration-6.2.md)
+
+## Architecture and authoring
+
+- [Architecture map](https://github.com/morluto/rea/blob/main/docs/architecture/architecture.mermaid)
+- [Documentation ownership and contribution model](development/documentation.md)
+- [Feature specifications](specs/README.md)
+- [Architectural decision records](adr/README.md)
+
+## Machine-owned documentation
+
+| Path                                      | Owner and update command                                                                  |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `public/product-catalog.json`             | Ignored contract projection; `npm run docs:generate`                                      |
+| `verification/managed-conformance-*.json` | Ignored managed conformance projections; `npm run evidence:generate`                      |
+| `error-contract.schema.json`              | Tracked schema from contracts; `npm run docs:error-schema`                                |
+| `user-visible-errors.csv`                 | Authored error classification inventory; preserve its schema                              |
+| `releases/<version>.contributions.json`   | Durable release contribution record; follow the [release guide](development/releasing.md) |
+| `assets/`                                 | Shared authored images referenced by guides                                               |
+
+Do not edit generated catalogs or evidence to change product facts. Change their
+canonical contracts or producer and regenerate. Historical release records retain
+the exact commit messages and references from the release they describe.
@@ -0,0 +1,9 @@
+# Architectural decision records
+
+Store one actual decision per `docs/adr/<domain>/<decision-slug>.md`, without a
+global sequence number. Use meaningful names and the Michael Nygard sections:
+Status, Context, Decision and Consequences. Link each decision from its owning
+feature specification.
+
+See [the authoring guide](../development/documentation.md#feature-lifecycle) for
+the distinction between specifications, roadmaps and isolated decisions.
@@ -406,7 +406,7 @@ existing static JavaScript analysis through CLI and stdio MCP, including
 manifest readback, competing query variants, and resolved relative imports.
 It uses an installed browser and accepts an optional installed REA entrypoint.
 The complete `verify:browser` lane also exercises passive script export through
-both public adapters. See [website script export](website-script-export.md).
+both public adapters. See [website script export](../guides/web/website-script-export.md).

 `verify:browser:modules` compares CLI and stdio MCP traces against an independent
 real Chromium module-loading fixture: import-map scopes, package prefixes,
@@ -414,7 +414,7 @@ null/backtracking rejection, query/fragment identities, repeated module instance
 lazy and computed unknowns, exact source/map identities and no implicit refetch.
 Set `REA_BROWSER_EXECUTABLE`; the optional script argument selects an installed
 package entrypoint. The complete `verify:browser` lane and existing conditional
-Chrome CI include this verifier. See [module relationships](website-module-trace.md).
+Chrome CI include this verifier. See [module relationships](../guides/web/website-module-trace.md).

 ## Agent evaluation and conformance records

@@ -458,7 +458,7 @@ artifact path. Its `expectedFirstTool` is `null`, and
 `targetClarificationPassed` grades that limited routing outcome independently
 of analysis prose heuristics. Analyzing a nearby example cannot pass this case.

-The packaged desktop and parser-comparison scenarios now assess a closed set of
+The packaged desktop, parser-comparison, and managed scenarios assess a closed set of
 known fixture claims. Each final answer must be a strict JSON manifest containing
 exactly the requested claim IDs, values, Evidence IDs, and Evidence authority and
 confidence. Golden values are not included in the prompt. The evaluator checks
@@ -475,15 +475,24 @@ analyses and use the requested module and export selectors. Boundary tests packa
 the same source-owned desktop fixture and compare the same source-owned parser
 files through actual MCP tool results, then verify that fabricated answers fail.

+The managed rubric checks the exact public top-level type set and the CLI entry
+point's declaring type and method name. The exact type-set claim requires an
+unfiltered member inventory: `selection` must be null and the Evidence parameters
+must omit `type_names`. A selected inventory can still ground the entry-point
+claim. Both inspections must describe the freshly built DLL's SHA-256. Entry-point
+resolution additionally requires complete artifact and member metadata, matching
+non-null module MVIDs, and a unique method at the header's metadata token. These are
+static metadata claims, not runtime behavior;
+compiler-generated member counts, token values, and MVIDs are not golden answers.
+
 Per-scenario `factualCorrectness` is `passed`, `failed`, or `not_assessed` within
 the `configured_fixture_claims` scope. A pass establishes only the configured
-claims, not unrestricted factual correctness. Native, managed, browser,
+claims, not unrestricted factual correctness. Native, browser,
 navigation-context, and address-context scenarios have no factual rubric and
-remain `not_assessed`; the managed workflow requires both artifact and member
-inspection to answer its type and entry-point question.
+remain `not_assessed`.

 The closed factual scenarios request complete producer Evidence on the initial
-analysis so their source selectors can authenticate all configured facts.
+inspection or analysis so their source selectors can authenticate all configured facts.
 Summary/page/item workflows are exercised separately by `javascript-module-view`;
 its heuristic gate does not establish full-producer factual correctness.

@@ -0,0 +1,82 @@
+# Documentation ownership and authoring
+
+Use the [documentation directory](../README.md) to find existing material before
+adding another guide. Preserve one canonical owner for each contract or workflow;
+link to that owner instead of copying its claims into several guides.
+
+## Choose a destination
+
+| Document                                                 | Destination                            |
+| -------------------------------------------------------- | -------------------------------------- |
+| Installation, client setup and first CLI/MCP steps       | `docs/getting-started/`                |
+| Analyst workflows and evidence interpretation            | `docs/guides/<domain>/`                |
+| Analysis-engine configuration and format prerequisites   | `docs/providers/`                      |
+| Shared runtime contracts and evidence semantics          | `docs/reference/`                      |
+| Development, testing, release and authoring instructions | `docs/development/`                    |
+| Composition diagrams                                     | `docs/architecture/`                   |
+| Compatibility changes for a released version             | `docs/migrations/`                     |
+| One feature specification, plan and tasks                | `docs/specs/<domain>/<feature-slug>/`  |
+| One architectural decision                               | `docs/adr/<domain>/<decision-slug>.md` |
+
+Use meaningful, lowercase domain and feature slugs. Global numeric prefixes are
+unnecessary: different domains can add features independently, and branches do
+not compete for the next sequence number. Check the existing domain directory
+and linked issues before creating a feature with the same slug.
+
+Guides describe existing behavior and limitations. Specs define one proposed
+feature or domain change; an existing guide does not become a specification by
+moving it into `specs/`.
+
+## Feature lifecycle
+
+Create the specification before implementation. Each feature directory contains:
+
+- `spec.md`: problem, desired behavior, requirements, acceptance and non-goals.
+- `plan.md`: the single implementation plan, contracts and architectural choices.
+- `tasks.md`: incremental, testable steps linked to requirements and verification.
+
+Split independent domains or separately reviewable features before writing their
+specs. A broad `ROADMAP.md`, when useful, only lists child specifications, order
+and dependencies; requirements and implementation tasks belong to each child.
+Cross-repository contracts have one producer-owned specification. Consumers link
+to that contract instead of maintaining competing copies.
+
+Record an isolated architectural decision separately in
+`docs/adr/<domain>/<decision-slug>.md`, with **Status**, **Context**,
+**Decision** and **Consequences**. Link the ADR from affected specifications.
+Do not create decision records for routine file moves or invent past decisions.
+
+Specs do not replace the contribution-scope decision required for a new provider
+or expanded execution authority. Follow
+[contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope).
+
+## Links and public routes
+
+Use relative links to physical Markdown files so GitHub readers can follow them.
+Link repository files outside `docs/` with their full GitHub URLs. Preserve
+existing heading anchors when moving a guide.
+
+[`documentation.ts`](https://github.com/morluto/rea/blob/main/docs/.vitepress/documentation.ts)
+owns categorized site navigation and the existing guides' stable public routes.
+Update it when adding or moving a guide. VitePress rewrites categorized sources
+to the existing public paths; its Markdown hook resolves repository links from
+the physical source and renders them against those public routes. Keep basenames
+and route assignments unique. Edit links use the physical source file.
+
+For a move, search for both the basename and its old full path. Update README
+translations, authored skills, verification instructions, documentation-fact
+readers and release configuration when they consume that path. Preserve
+historical release records and references bound to earlier commits or tags.
+
+## Generated ownership and checks
+
+The [documentation directory](../README.md#machine-owned-documentation) identifies
+the machine-owned outputs and their producers. Their existing paths are retained
+because scripts, package consumers and release history depend on them. Change
+canonical sources and regenerate; do not fix a generated projection by hand.
+
+Run `npm run docs:check` for documentation facts and generated consistency, and
+`npm run verify:docs:routes` to build the complete production site and check local
+links, anchors and physical edit targets.
+When a physical path moves, also run the tests that read it. Follow
+[development checks](testing.md#developer-commands) before requesting review.
@@ -84,7 +84,7 @@ registry metadata or changelog disagrees with that version before creating a tag

 ### Compatibility and version selection

-For the 6.2 candidate, review the [6.1 to 6.2 migration guide](migration-6.2.md)
+For the 6.2 candidate, review the [6.1 to 6.2 migration guide](../migrations/migration-6.2.md)
 alongside the changelog before publication.

 REA uses Release Please's `always-bump-minor` strategy: every release increments
@@ -5,8 +5,8 @@ The [platform tracker](https://github.com/morluto/rea/issues/32),
 [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).
+[installation guide](../getting-started/installation.md), and
+[generated catalog](../reference/mcp-contracts.md#generated-catalog).

 ## Priorities

@@ -27,7 +27,7 @@ fixture servers; custom orchestration needs a demonstrated requirement.
 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.
+[Ghidra semantics](../providers/ghidra-provider.md) for the existing deep-provider contract.

 Setup remains additive, reuses existing tools, and requires approval for disclosed
 configuration and Hopper installation changes. Additional installer choices need
@@ -237,7 +237,7 @@ logic.
 reconstruction, native-boundary relationships and application graphs without
 executing fixture PE files. Operator-local manifests and actual ILSpy oracles
 remain optional, separately reported checks; the real Ghidra NativeAOT lane has
-its own toolchain prerequisites. See [the managed guide](managed-code-analysis.md)
+its own toolchain prerequisites. See [the managed guide](../guides/managed/managed-code-analysis.md)
 for those configurations. Generated completion-ledger checks use the same owning
 entrypoint and include its verifier/fixture files in their cache inputs.

@@ -514,14 +514,14 @@ fixed public ApiDemos v6.0.18 fixture. Obtain both with the explicit
 kept under ignored `_reference/`. No Gradle build, Android SDK, emulator or
 application execution is required. The lane compares real CLI/MCP package,
 class search, class inventory, method decompilation and incoming references.
-See [Android analysis](android-analysis.md) for boundaries and resource budgets.
+See [Android analysis](../guides/android/android-analysis.md) for boundaries and resource budgets.

 `verify:jeb` requires a caller-started JEB client serving MCP at
 `REA_JEB_MCP_URL` (default `http://127.0.0.1:8425/mcp`) with a project
 already open, and verifies real CLI client inspection, unit listing coverage,
 and method decompilation. The script records the engine's exact response to
 `open_jeb_project`; JEB 5.48.0 headless instances do not advertise that tool.
-REA does not install or launch JEB; see [JEB analysis](jeb-analysis.md) for
+REA does not install or launch JEB; see [JEB analysis](../providers/jeb-analysis.md) for
 the bring-your-own boundary. Verified against JEB 5.48.0 serving
 `jeb-mcp-server` 1.3.0 at four scales: a compiled Java class fixture, a
 locally built signed probe APK with a launcher activity (manifest, v1/v2/v3
@@ -535,7 +535,7 @@ CLI and MCP with explicit unit selection, plus the thin Java wrapper and
 decoded manifest. The dedicated Dart snapshot processor and `run_script`
 remain GUI-only surfaces in JEB 5.48.0 headless.
 Authenticated IPA and macOS application inventory projection is documented in
-[Apple application analysis](apple-application-analysis.md).
+[Apple application analysis](../guides/apple/apple-application-analysis.md).

 `npm run verify:harmony` requires no SDK or engine. It projects the pinned
 harmony-next-pipeline 1.0.1 release HAP from an MIT-licensed source repository,
@@ -545,7 +545,7 @@ The lane exercises `inspect_artifact`, projection determinism, Stage-model
 path hints, exact component sets, signing-entry limitations, and CLI/MCP parity.
 The release artifact has no independently established compiler/SDK or
 reproducible source build; the default lane does not verify an installed package.
-See [HarmonyOS package inventory](harmony-analysis.md) for those proof boundaries.
+See [HarmonyOS package inventory](../guides/harmony/harmony-analysis.md) for those proof boundaries.
 HarmonyOS `.har` libraries are deliberately not suffix-classified because
 `.har` also names HTTP Archive JSON.

@@ -566,7 +566,7 @@ with the reported target identity, apktool.yml metadata projection
 (1.2.3, SDK 24–34), manifest package agreement, and both the default and
 `de` string tables projected through the locale option. Parser goldens in
 `src/apktool/ApktoolDecodeOutput.test.ts` come from the same decode. See
-[Apktool resource analysis](apktool-resource-analysis.md) for boundaries and
+[Apktool resource analysis](../guides/android/apktool-resource-analysis.md) for boundaries and
 budgets.

 ## Flutter build identification
@@ -596,7 +596,7 @@ documented Gallery APK to assert its pinned digest, hash, exact engine labels
 and per-ABI URI counts. The verifier requires complete structural snapshot
 coverage, reports bounded pool coverage as partial/unverified, and reports
 exact labels/counts on other APKs unverified without an expectations file.
-See [Flutter build identification](flutter-analysis.md) for boundaries and
+See [Flutter build identification](../guides/android/flutter-analysis.md) for boundaries and
 budgets.

 ## ADB device acquisition
@@ -627,7 +627,7 @@ removal. System-package pulls whose APKs keep non-`base.apk` names report
 the `unknown` role with the file-name basis, verified with
 `com.android.settings` (single 73.9 MB APK). Parser goldens for
 `adb devices -l`, `getprop`, `pm list packages -f`, and `pm path` come from
-the same device. See [ADB device analysis](adb-device-analysis.md) for
+the same device. See [ADB device analysis](../guides/android/adb-device-analysis.md) for
 boundaries and budgets.

 ## Optional NativeAOT Ghidra analysis
@@ -646,6 +646,12 @@ records independent symbol/directory/SHA oracles; it never executes the target.
 Linux also builds stripped, ordinary-native and small malformed/ambiguous/layout
 negative inputs. The optional Windows fixture workflow builds a PE on a Windows
 runner; analyzing that PE on Linux does not verify a Windows Ghidra host.
+On a local Windows host, the .NET 8 ILCompiler finds the linker only through
+Visual Studio 2019 or 2022 (`vswhere -version [16,18)`). With only Visual
+Studio Build Tools 2026 installed, open its x64 Developer Command Prompt.
+In that same `cmd.exe` session, run `set IlcUseEnvironmentalTools=true` and
+then `npm run build:fixtures:nativeaot`. Running `vcvars64.bat` as a child of
+PowerShell does not preserve its environment in the parent PowerShell session.

 Build the clean pinned upstream adapter with `build:ghidra:nativeaot`, then set
 `REA_GHIDRA_NATIVEAOT_JAR`. Run `verify:ghidra:nativeaot -- symbols`, `-- stripped`,
@@ -665,7 +671,7 @@ with `REA_NATIVEAOT_PROOF_CAPTURE_DIR` (absolute paths).
 Keep builds/imports sequential on small hosts; scope `GHIDRA_HEADLESS_MAXMEM`
 (e.g. `768M`) to this command and use CPU affinity if needed. REA does not install
 or upgrade Java, Ghidra, .NET or native toolchains. See
-[the supported layout and provenance](ghidra-nativeaot.md).
+[the supported layout and provenance](../providers/ghidra-nativeaot.md).

 ## IDA MCP adapter

@@ -705,11 +711,11 @@ symbols carry a leading underscore). Before the headless session waited out
 the transient `busy` health a worker can report right after opening, that lane
 failed intermittently on that host. Linux headless, modern attached GUI tools,
 other engine versions and architectures remain unverified; see the
-[provider guide](ida-provider.md).
+[provider guide](../providers/ida-provider.md).

 Native IDA MCP verification uses `"protocol": "native"` with an already-running native plugin and requires `--second-procedure other_function --second-marker unique_second_body_text` to exercise GUI function switching and a return to the first function. These options remain optional for other profiles. The literal marker must appear in the second function's pseudocode and be absent from the first. Native cloud/widget failures are reported without hidden retries.

-The initial Linux x64 IDA Free 9.4 run used native MCP 1.1.2 with a local navigation correction. Windows x64 verification uses **IDA Pro 9.3**, the two-function public fixture, and the shipped Windows `whoami.exe` application. The native plugin was built from upstream `c9d15d98e8a143fc74f6e14037c48f63889b6d6c`, including the merged navigation fix, with a local loopback-listener change. Production CLI/MCP parity, switching, identity and cleanup passed. Correctness and performance measurements are recorded in the [Windows native verification notes](https://github.com/morluto/rea/blob/main/experiments/analysis-efficiency/ida-native-windows.md). Stock 1.1.2 switching, native macOS, and Windows IDA Free remain unverified. See the [native bridge prerequisites](ida-provider.md#optional-native-ida-mcp-bridge).
+The initial Linux x64 IDA Free 9.4 run used native MCP 1.1.2 with a local navigation correction. Windows x64 verification uses **IDA Pro 9.3**, the two-function public fixture, and the shipped Windows `whoami.exe` application. The native plugin was built from upstream `c9d15d98e8a143fc74f6e14037c48f63889b6d6c`, including the merged navigation fix, with a local loopback-listener change. Production CLI/MCP parity, switching, identity and cleanup passed. Correctness and performance measurements are recorded in the [Windows native verification notes](https://github.com/morluto/rea/blob/main/experiments/analysis-efficiency/ida-native-windows.md). Stock 1.1.2 switching, native macOS, and Windows IDA Free remain unverified. See the [native bridge prerequisites](../providers/ida-provider.md#optional-native-ida-mcp-bridge).

 ## DOS Ghidra analysis

@@ -721,7 +727,7 @@ stable CLI/MCP observations, unchanged source bytes, and owned process/project
 cleanup. Raw p-code address-space selector tokens are reported separately from
 the stable observation comparison. Linux x64 and macOS arm64 are verified;
 macOS x64 remains unverified. This lane is separate from host-native and optional cross-format
-verification. See [DOS analysis](ghidra-dos.md).
+verification. See [DOS analysis](../providers/ghidra-dos.md).

 `npm run verify:ghidra:com` uses a generated headerless fixture with no compiler,
 DOS emulator or game data. It exercises explicit admission, BinaryLoader entry
@@ -752,7 +758,7 @@ the entry changes without `provider_id`, unchanged source bytes, and owned
 cleanup. Six-byte x86 and x86_64 controls also verify supported compiler
 specifications, independent mappings, unchanged bytes, and decompilation of a
 known return value. AArch64 remains covered by deterministic tests rather than
-this real-provider lane. See [raw binary analysis](raw-binary.md).
+this real-provider lane. See [raw binary analysis](../providers/raw-binary.md).

 `npm run verify:ghidra:address-context` runs on Linux with a caller-installed
 Ghidra, full JDK, and an x86-64 ELF GCC toolchain (`CC` selects another compatible
@@ -1044,7 +1050,7 @@ status, and Android logcat on success or failure. The emulator is disposable.
 capinfos against a saved capture. Linux verification uses Wireshark 4.6.6
 and captures containing DNS, TLS and HTTP traffic. Native Windows and macOS
 engine behavior remains unverified; process fixtures do not establish it.
-See [Packet capture analysis](pcap-analysis.md) for contracts and budgets.
+See [Packet capture analysis](../guides/data/pcap-analysis.md) for contracts and budgets.

 ## Apple native metadata and UI

@@ -1064,7 +1070,7 @@ conformance/vtable fixture.
  allows a host-permission-boundary-only result and explicitly reports
  `positive_e2e: false`; it must not be reported as capture/action proof.
  Both commands reject a changed executable digest and clean up the fixture
-  process and helper. These lanes require an interactive macOS desktop. See [native investigation](native-investigation.md)
+  process and helper. These lanes require an interactive macOS desktop. See [native investigation](../guides/native/native-investigation.md)

 `npm run verify:native-calls` needs macOS with Command Line Tools (`clang`,
 `lldb`, `codesign`, `nm`) and actual debugger access to the owned fixtures.
@@ -1102,7 +1108,7 @@ unknown chunks, depth limits and extracted child digests. The optional
 `REA_FIRMWARE_VERIFY_EXT4=1` lane requires existing mke2fs/debugfs; the separate
 `REA_FIRMWARE_VERIFY_GHIDRA=1` lane checks a selected host ELF through real Ghidra.
 Neither optional toolchain is a base-lane prerequisite. See
-[firmware analysis](firmware-analysis.md) for limits and unverified formats.
+[firmware analysis](../guides/firmware/firmware-analysis.md) for limits and unverified formats.

 ### JavaScript source recovery

@@ -1143,7 +1149,7 @@ npm run verify:browser:source-maps
 checks an installed package after building the verifier dependencies. The separate
 conditional `real-web-source-map` CI job supplies Chrome and an isolated pinned
 fixture compiler; static/unit checks do not acquire a browser. See
-[the source location guide](web-source-location.md) for the verified decoder profile.
+[the source location guide](../guides/web/web-source-location.md) for the verified decoder profile.

 ### JavaScript large-output lane

@@ -1170,7 +1176,7 @@ An optional entrypoint argument to `scripts/verify-browser-runtime.mjs` runs the
 same checks through an isolated installed package. The conditional
 `real-web-runtime` CI job runs only for relevant changes and needs no fixture
 compiler. Ordinary unit/static gates acquire no browser. See
-[website runtime attribution](web-runtime.md) for effects, resource bounds and
+[website runtime attribution](../guides/web/web-runtime.md) for effects, resource bounds and
 coverage limits.

 ### Offline binary layout
@@ -90,5 +90,5 @@ consumers. Real-engine claims require the matching provider lane; see
 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
+establish successful tool selection. See [mcp-contracts.md](../reference/mcp-contracts.md) for
 shipped runtime behavior.
@@ -17,7 +17,7 @@ Use an extracted application directory or an ASAR as the target. Static
 JavaScript analysis returns the application graph and Evidence directly.
 Generic `rea analyze PATH` selects this workflow for directories and `.asar`
 files when neither `--provider` nor `--snapshot` is supplied. See
-[JavaScript artifact reconstruction](javascript-artifact-reconstruction.md)
+[JavaScript artifact reconstruction](../guides/javascript/javascript-artifact-reconstruction.md)
 for results, integrity checks and coverage.

 The complete application Evidence can be hundreds of megabytes for a real
@@ -34,7 +34,7 @@ For example, a 334 MB Obsidian application Evidence file yields a summary view
 of about 10 KB. Replace the view with
 `{"kind": "page", "collection": "modules", "offset": 0, "limit": 32}` for a
 module page. See
-[JavaScript application workflows](javascript-application-workflows.md) for
+[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md) for
 views, feature traces and comparisons that take the same saved Evidence.

 ## Managed assemblies (.NET)
@@ -59,7 +59,7 @@ assembly-wide inventory, so the output can still be large.
 Choose the workflow from the artifact's contents rather than its `.exe` or
 `.dll` extension. The managed parser requires PE/CLI metadata; it does not
 unpack .NET single-file hosts or decode IL2CPP metadata. NativeAOT method bodies
-require native analysis. See the [managed-code guide](managed-code-analysis.md)
+require native analysis. See the [managed-code guide](../guides/managed/managed-code-analysis.md)
 for supported deployment forms, selection semantics, and coverage limits.

 ## SQLite snapshots
@@ -67,7 +67,7 @@ for supported deployment forms, selection semantics, and coverage limits.
 For a local database snapshot, use `rea inspect-sqlite-database PATH --json`.
 Add `--table NAME --row-limit 20` to read a bounded sample from an ordinary
 table. This command does not require a native analysis provider. See
-[SQLite database snapshots](sqlite-databases.md) for database/WAL identity,
+[SQLite database snapshots](../guides/data/sqlite-databases.md) for database/WAL identity,
 source-file handling and row-value semantics.

 ## Native analysis
@@ -80,11 +80,11 @@ rea inspect-go-binary /absolute/path/to/program --json
 ```

 The shared CLI/MCP workflow reports compiler version, modules, replacements,
-build settings, original bytes and SHA-256. See [Go binaries](go-binaries.md)
+build settings, original bytes and SHA-256. See [Go binaries](../guides/native/go-binaries.md)
 for supported containers and absent or malformed metadata.

 Configure [Hopper or Ghidra](installation.md#hopper), or the
-[IDA adapter](ida-provider.md), before analyzing a native target. Substitute
+[IDA adapter](../providers/ida-provider.md), before analyzing a native target. Substitute
 your target, search text and function name or address in these examples:

 ```bash
@@ -101,11 +101,11 @@ a function dossier; `decompile` returns pseudocode. For assembly instructions
 alone, use `rea instructions`. A macOS `.app` bundle can be supplied directly.

 Run `rea --help` or a command's `--help` for arguments and output options.
-The [generated catalog](mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
+The [generated catalog](../reference/mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
 tools. Provider-specific target support is described in the
-[native guide](native-investigation.md), [DOS guide](ghidra-dos.md),
-[raw binary guide](raw-binary.md), and
-[Windows Ghidra guide](windows-ghidra-p0.md).
+[native guide](../guides/native/native-investigation.md), [DOS guide](../providers/ghidra-dos.md),
+[raw binary guide](../providers/raw-binary.md), and
+[Windows Ghidra guide](../providers/windows-ghidra-p0.md).

 ## Choose a provider

@@ -142,13 +142,13 @@ 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](mcp-contracts.md#identity-and-discovery).
+and [provider selection](../reference/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.
 `cleanup_incomplete` identifies resources whose shutdown or removal could not
-be verified. See [MCP contracts](mcp-contracts.md) for session lifecycle and
-[Ghidra first-query deadlines](mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
+be verified. See [MCP contracts](../reference/mcp-contracts.md) for session lifecycle and
+[Ghidra first-query deadlines](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
 for import, client timeouts and recovery.

 ## Save and reuse analysis snapshots
@@ -204,8 +204,8 @@ rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/righ

 Exports preserve an existing destination unless `--overwrite` is explicit.
 For application traces and version comparisons, see
-[JavaScript application workflows](javascript-application-workflows.md).
-MCP [retained Evidence references](mcp-contracts.md#retained-application-evidence-inputs)
+[JavaScript application workflows](../guides/javascript/javascript-application-workflows.md).
+MCP [retained Evidence references](../reference/mcp-contracts.md#retained-application-evidence-inputs)
 belong to one connection. Separate CLI calls consume full saved records.

 ## Import historical source
@@ -214,8 +214,36 @@ Import an older source tree to compare with the current artifact:

 ```bash
 rea import-reference-source /absolute/path/to/source
+rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json
 ```

+The default (`--detail full`) returns the complete `HistoricalSourceGraph`.
+Choose `--detail summary` for a `HistoricalSourceSummary` of that same committed
+inventory: its `HistoricalSourceManifest` contains the full graph and root
+digests, with provenance, VCS facts, languages, manifest paths, entry and
+relationship counts, parse-failure counts, file/directory states, exclusions
+and limitations. The summary is a presentation view, not a graph accepted by
+source-to-bundle comparison; keep the full output for that workflow.
+
+`--outline-depth` requires `--detail summary` and accepts a nonnegative safe
+integer. Depth 1 shows root children, depth 2 (the default) also shows their
+children, and depth 0 omits all outline entries. Paths retain canonical Unicode
+code-point order. `outline.omitted_entry_count` counts only inventoried entries
+hidden by the chosen depth; it does not count unexamined children of excluded or
+unreadable directories, or change `inventory_state`. Exclusions and source
+limitations remain separate from this presentation omission.
+
+`file_sizes.known_bytes` is the exact sum of known inventoried file sizes as
+decimal text, so large sums cannot lose integer precision. Unknown sizes count
+in `file_sizes.unknown_file_count`; excluded or unexamined paths are not included
+in that total. A zero known-byte sum therefore does not establish an empty source
+tree. Full output retains individual file hashes, relationships and parse-failure
+diagnostics. Summary mode performs the same import and cleanup, then projects
+the committed result without rereading source files. It reduces the selected
+output, not the amount of source examined. A shallow tree or many exclusions can
+still produce a large summary; depth 0 removes the outline but preserves the
+other facts. No fixed output-size or runtime improvement is promised.
+
 The import records hashes and metadata for the supplied files, separately
 from observations of the current app. For a directory inside a Git checkout,
 it records the HEAD of the nearest enclosing repository; whether the working
@@ -237,18 +265,18 @@ 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
-[source-to-bundle comparison](javascript-application-workflows.md#historical-source-to-bundle-comparison)
+[source-to-bundle comparison](../guides/javascript/javascript-application-workflows.md#historical-source-to-bundle-comparison)
 for mapping identities, inferences and unknowns.

 ## Capture runtime behavior

 Choose the guide for the target and intended interaction:

- [Browser observation](browser-observation.md): inspect a selected page through CDP.
- [Browser scenarios](browser-scenario-contract.md): run declared interactions and capture their results.
- [Electron observation](electron-observation.md): inspect an Electron renderer or capture an application scenario.
- [Node/Electron Inspector](javascript-runtime-observation.md): record script locations and execution contexts.
- [Process capture](process-capture.md): run an executable and compare terminal, exit and filesystem observations.
+- [Browser observation](../guides/web/browser-observation.md): inspect a selected page through CDP.
+- [Browser scenarios](../guides/web/browser-scenario-contract.md): run declared interactions and capture their results.
+- [Electron observation](../guides/javascript/electron-observation.md): inspect an Electron renderer or capture an application scenario.
+- [Node/Electron Inspector](../guides/javascript/javascript-runtime-observation.md): record script locations and execution contexts.
+- [Process capture](../guides/runtime/process-capture.md): run an executable and compare terminal, exit and filesystem observations.

 Runtime requests name the target and actions. Launched targets run with your
 user permissions; consult the chosen guide for host requirements and effects.
@@ -10,7 +10,7 @@ acceptance is verified only where explicitly recorded.

 Connect Fiddler Everywhere's MCP server separately for HTTP traffic debugging,
 preserving your REA client entry. See the
-[setup instructions and public skills](web-network-captures.md#fiddler-everywhere-mcp-and-public-skills).
+[setup instructions and public skills](../guides/web/web-network-captures.md#fiddler-everywhere-mcp-and-public-skills).

 ## GitHub Copilot CLI

@@ -31,7 +31,72 @@ tool inventory on Linux using a loopback model fixture. After setup, add
 settings, then restart the client. Compact advertisements can reduce nested
 schema constraints; REA still validates complete canonical inputs. Full-profile
 `gpt-5.4` metadata is also verified locally. Live model API acceptance and
-Windows remain unverified; see [native client verification](testing.md).
+Windows remain unverified; see [native client verification](../development/testing.md).
+
+## Claude Desktop
+
+Setup registers `mcpServers.rea` in `claude_desktop_config.json`: under
+`~/Library/Application Support/Claude` on macOS, under
+`$XDG_CONFIG_HOME/Claude` (default `~/.config/Claude`) on Linux, and on Windows
+in the file the installed app reads:
+
+- Without Claude Desktop's MSIX package storage, setup uses
+  `%APPDATA%\Claude\claude_desktop_config.json`.
+- The MSIX build (package family `Claude_pzs8sxrjxfjjc`, installed under
+  `C:\Program Files\WindowsApps\Claude_<version>_x64__pzs8sxrjxfjjc`)
+  virtualizes AppData writes. Once it has saved its configuration, it reads
+  the package-private copy
+  `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
+  and ignores the `%APPDATA%` file. Setup, doctor and uninstall use that
+  private copy when it exists. Before the package has saved one, they use the
+  `%APPDATA%` file it still reads; with neither file, setup creates the
+  private copy.
+- If `%LOCALAPPDATA%\Packages` holds a `Claude_<publisher ID>` package from
+  another publisher, or cannot be read, REA cannot establish which file Claude
+  Desktop reads. Setup, doctor and uninstall report that instead of falling
+  back to `%APPDATA%`. Doctor then reports `claude_desktop` as invalid, and
+  uninstall stops before removing anything for any client.
+
+Quit Claude Desktop fully before approving setup; closing its window is not
+enough. A running Claude Desktop can rewrite its configuration from memory and
+drop the registration. This was observed with the Windows MSIX build. Start
+Claude Desktop again after setup. If the package saves its private copy after
+setup planned to write the `%APPDATA%` file, setup makes no change and asks you
+to rerun it.
+
+A process that the MSIX app started, such as a terminal in Claude Desktop's
+Code tab, sees the package's private files at their `%APPDATA%` paths even
+though it reports no package identity. Setup compares one of those files at
+both paths. When it finds that redirected view, the app is running, so setup
+and uninstall refuse to change Claude Desktop's configuration; rerun them from
+a terminal that Claude Desktop did not start. If the package has no private
+file to compare, setup and uninstall cannot rule that out and also refuse; open
+Claude Desktop once if it has never run, quit it fully, then rerun. Doctor
+reads the same file from either kind of process.
+
+The same process also writes everything under `%APPDATA%` and
+`%LOCALAPPDATA%` into the package's private storage, where other apps never
+read it. From that redirected view, setup and uninstall refuse to change other
+clients' files there (VS Code, Trae, Devin and Hermes) and skill directories
+there. `npm install -g` run from such a process installs into the package's
+`LocalCache\Roaming\npm`, which other processes cannot see at the `%APPDATA%`
+path. Setup refuses to register a launcher stored in any MSIX package's
+private storage. Install REA from an ordinary terminal and rerun setup there.
+
+Uninstall removes REA's entry from both the private copy and the `%APPDATA%`
+file, including registrations that earlier releases wrote to `%APPDATA%`.
+
+REA recognizes only the MSIX package. A non-MSIX Claude Desktop installed
+beside it, which would read the `%APPDATA%` file, is not detected.
+
+The package identity, both file locations, the redirected view, and these
+setup and doctor results were observed on Windows 11 with the MSIX build
+2.31226.1.0, using read-only `doctor` and `setup --dry-run` runs both inside
+and outside the app. On that host, setup run from an ordinary terminal with
+the app quit wrote the package-private copy; after the app restarted, the
+entry was still present, doctor reported it aligned, and Claude Desktop's MCP
+log showed REA starting and answering `tools/list`. Uninstall against the real
+app is unverified.

 ## Claude Code

@@ -64,6 +129,18 @@ and Claude Code reports that autocompact is thrashing. To avoid this:
 The sizes above come from REA's own `tools/list`. A live Claude Code session
 against DeepSeek's API is unverified.

+## Kimi Code
+
+Setup registers `rea` in `~/.kimi-code/mcp.json`, or
+`$KIMI_CODE_HOME/mcp.json` when set, while preserving unrelated settings and
+creating a `.rea.backup` before updating an existing file. Kimi Code infers
+stdio from the `command` entry, so setup does not add a `type` field. The
+registration includes `startupTimeoutMs = 30000` and `toolTimeoutMs = 120000`.
+Kimi Code also discovers personal skills in `~/.agents/skills` and project-local
+`.agents/skills`, so no separate skill root is required; setup still installs
+and verifies the matching skill files through the normal shared-skill flow.
+Start a new Kimi Code session to pick up MCP and skill changes.
+
 ## Pi

 For [Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/mcp.md),
@@ -251,7 +328,7 @@ in `~/.agents/skills` (`$DSH_AGENTS_HOME/skills` when configured); Harness
 discovers that directory, and its native `skill` tool can load
 `reverse-engineer-anything`.

-REA's optional [native client verification](testing.md#end-to-end-integration-and-golden-evidence)
+REA's optional [native client verification](../development/testing.md#end-to-end-integration-and-golden-evidence)
 checks headless chat, skill loading, all tool input schemas and actual analysis
 using the installed Harness and a local model fixture. This establishes the
 Harness integration, with live DeepSeek API compatibility remaining unverified.
@@ -3,13 +3,13 @@
 Run REA, connect your selected agents, and check the tools needed for your task.
 Setup previews configuration changes and asks for approval before applying them.

-| Task                              | Section                                                                   |
-| --------------------------------- | ------------------------------------------------------------------------- |
-| Connect an agent                  | [Start setup](#start-setup), then [review changes](#review-setup-changes) |
-| Diagnose one task                 | [Scoped readiness checks](#check-readiness-for-your-task)                 |
-| Configure an analysis engine      | [Hopper](#hopper), [Ghidra](#ghidra), or the [IDA guide](ida-provider.md) |
-| Update or remove REA              | [Maintenance](#diagnose-update-and-remove)                                |
-| Resolve a client-specific problem | [Client configuration](client-configuration.md)                           |
+| Task                              | Section                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------- |
+| Connect an agent                  | [Start setup](#start-setup), then [review changes](#review-setup-changes)              |
+| Diagnose one task                 | [Scoped readiness checks](#check-readiness-for-your-task)                              |
+| Configure an analysis engine      | [Hopper](#hopper), [Ghidra](#ghidra), or the [IDA guide](../providers/ida-provider.md) |
+| Update or remove REA              | [Maintenance](#diagnose-update-and-remove)                                             |
+| Resolve a client-specific problem | [Client configuration](client-configuration.md)                                        |

 ## Start setup

@@ -20,7 +20,9 @@ npx rea-agents setup
 Choose the agents to configure, review the proposed paths and changes, and
 approve the plan. npm's package-download approval and REA's setup approval are
 separate. Setup asks before changing agent configuration or installing Hopper.
-Restart the agents named in the completion message.
+Restart the agents named in the completion message. Quit Claude Desktop fully
+before approving, because a running app can overwrite the registration; on
+Windows, see [where Claude Desktop reads its configuration](client-configuration.md#claude-desktop).

 For the latest published release, use `npx rea-agents@latest setup`.
 [Package-runner and global-installation options](#package-runners-and-global-installation)
@@ -277,6 +279,7 @@ hosted connector; see [its configuration](client-configuration.md#other-client-s
 | GitHub Copilot CLI | `copilot_cli`    |
 | Command Code       | `commandcode`    |
 | Qwen Code          | `qwen_code`      |
+| Kimi Code          | `kimi`           |
 | VS Code            | `vscode`         |
 | Grok Build         | `grok_build`     |
 | OMP                | `omp`            |
@@ -288,8 +291,8 @@ hosted connector; see [its configuration](client-configuration.md#other-client-s
 | ZCode              | `zcode`          |
 | DeepSeek Harness   | `dsh`            |

-`dsh` is main-only until a release after 6.4.0. The registry check above does
-not cover it.
+`dsh` and `kimi` require a release containing them. The registry check above does
+not cover them.

 See [client configuration and troubleshooting](client-configuration.md) for
 configuration paths, profiles, trust policies, and schema-limit workarounds.
@@ -308,9 +311,12 @@ Hopper is separate commercial software with its own license. Its free demo has
 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+,
-Nobara 44+, 64-bit Arch Linux, CachyOS, or Omarchy. Ghidra and IDA have their own provider-specific
-host requirements; Windows Ghidra uses the [experimental P0 boundary](windows-ghidra-p0.md).
+The automated Hopper installer supports macOS 12+, Ubuntu 24.04+, Fedora 41+,
+Nobara 44+, 64-bit Arch Linux, CachyOS, or Omarchy. REA itself runs on any
+Linux distribution with a recognized apt, dnf, or pacman package family, where
+an existing Hopper launcher is selected through `HOPPER_LAUNCHER_PATH`. Ghidra
+and IDA have their own provider-specific host requirements; Windows Ghidra uses
+the [experimental P0 boundary](../providers/windows-ghidra-p0.md).

 On macOS, approved setup downloads the official DMG, checks its published size
 and digest, validates the application bundle, and atomically installs it to
@@ -443,7 +449,7 @@ output-stream closure; `output_closed: false` keeps that uncertainty explicit.
 Later requests retain the known exit instead of reducing it to socket loss.
 An external GUI's helper exit does not establish that the GUI itself exited.
 For cursor navigation, string decoding, symbol-name limits, and regex matching,
-see [Hopper analysis behavior](native-investigation.md#hopper-analysis-behavior).
+see [Hopper analysis behavior](../guides/native/native-investigation.md#hopper-analysis-behavior).

 Closing or switching a target closes its bound Hopper document, shuts down REA's
 bridge and removes its temporary socket directory. The macOS Hopper application
@@ -514,12 +520,12 @@ session metadata edits leave executable bytes unchanged and are discarded on clo
 require Hopper; Windows P0 remains read-only.

 Windows P0 admits native x86 and x86-64 PE applications and DLLs, plus explicitly
-selected [raw NMOS 6502 images](raw-binary.md#nmos-6502) with a caller-supplied
+selected [raw NMOS 6502 images](../providers/raw-binary.md#nmos-6502) with a caller-supplied
 entry at file offset 0, on fixed local NTFS volumes. Other raw CPU families remain
 unsupported on Windows.
 The npm package bundles native Job Object ownership, protected private runtime
 DACLs, and handle-based path admission; no separate addon installation is needed.
-See the [Windows Ghidra P0 guide](windows-ghidra-p0.md) for verified scope and
+See the [Windows Ghidra P0 guide](../providers/windows-ghidra-p0.md) for verified scope and
 limitations.

 Extract Ghidra and install the JDK outside REA, then export absolute paths:
@@ -545,7 +551,7 @@ REA skill after approval. Direct registrations use Node to launch REA's entry
 script; package-runner registrations use the pinned `npx` or `bunx` command. Hopper
 installation remains unavailable on Windows. Setup never installs Ghidra,
 Java, or Python. It preserves valid detected Ghidra/JDK settings in agent
-registrations. See [Windows Ghidra P0](windows-ghidra-p0.md) for provider diagnostics.
+registrations. See [Windows Ghidra P0](../providers/windows-ghidra-p0.md) for provider diagnostics.

 Doctor validates the platform, architecture, Ghidra 12.1.x application version,
 `support/analyzeHeadless` or `support/analyzeHeadless.bat`, the installation's
@@ -586,7 +592,7 @@ passes the deadline to each provider client; a startup failure is returned by th
 without exposing partial analysis. This deadline is separate from MCP transport
 initialization and the client's deadline for that individual tool call. A client
 can time out earlier even when Ghidra would complete within its startup deadline.
-See [Ghidra first-query deadlines and recovery](mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
+See [Ghidra first-query deadlines and recovery](../reference/mcp-contracts.md#ghidra-first-query-deadlines-and-recovery)
 for client options and the close/reopen recovery flow.

 One session contains exactly one imported Program; use `provider_id: "ghidra"`, `--provider ghidra`, or
@@ -747,7 +753,7 @@ contains the launch arguments and `/proc/<jvm-pid>/status` reports
 session and retain the resource flags needed for the measurement rather than
 copying full command lines or environments into reports. Heap and affinity
 settings affect cost and latency; they are not part of REA's semantic analysis
-profile identity. See [real-provider testing](testing.md) for bounded
+profile identity. See [real-provider testing](../development/testing.md) for bounded
 verification workflows.

 ### Ghidra diagnostics and verification
@@ -181,4 +181,4 @@ Record: verified against adb 34.0.5 on Linux against an Android 14
 (API 34) x86_64 emulator — all operations above, a 224-package inventory,
 287 services, 92 features, a real two-APK split set pulled with byte-exact
 digests, a verified push/pull roundtrip, a 1.3 MB screen capture, and the
-complete package lifecycle; see `docs/testing.md` for the lane summary.
+complete package lifecycle; see `docs/development/testing.md` for the lane summary.
@@ -6,7 +6,7 @@ kept as an unmodified, commit-pinned Git submodule; see
 application workflow and return artifact-bound Evidence inline.

 This family is present on repository main and in npm 4.1.0. Check the
-[released package boundary](installation.md#released-package-and-main) and the
+[released package boundary](../../getting-started/installation.md#released-package-and-main) and the
 connected server's tool list before selecting it.

 ## Optional package delivery
@@ -86,6 +86,7 @@ rea inspect-android-method /path/Example.apk example.MainActivity onCreate
 rea inspect-android-method /path/Example.apk example.MainActivity select --overload-index 1
 rea trace-android-references /path/Example.apk example.MainActivity
 rea trace-android-references /path/Example.apk example.MainActivity --method-name onCreate
+rea trace-android-references /path/Example.apk example.MainActivity --method-name select --overload-index 1
 ```

 Equivalent MCP methods are `inspect_android_package`, `search_android_classes`,
@@ -106,9 +107,10 @@ Every request includes `path`. Class/method operations use `class_name`,
 ```

 Use `inspect_android_class` to choose an overload. REA rejects an ambiguous
-method request rather than silently selecting the first match. The engine's
-method reference operation cannot select overloads, so REA reports that boundary
-as unsupported when multiple same-name methods exist.
+method request rather than silently selecting the first match. Method reference
+queries accept the same `overload_index`; the bridge resolves the selected
+method node and the result reports its index and displayed signature. These
+indices are tied to the current artifact and engine, not stable across builds.

 The engine's smali fallback also joins same-name overloads; REA rejects that
 fallback for an overloaded method instead of attributing all bodies to one
@@ -137,14 +139,28 @@ the same source byte limit and explicit truncation reporting.
  full reported display types, fields and inner class names. Synthetic members
  that code generation hides can appear in the inventory; it stays consistent
  after method decompilation within the retained session.
-  Exact DEX descriptors are unknown. Overload indices are tied to this artifact
-  and engine, not stable identities across different builds.
+  Exact DEX prototypes are reported from frozen JADX method metadata as
+  `dex_descriptor`, for example `(I)V`. Display names can be JADX aliases;
+  the descriptor alone is not a complete raw DEX method ID. Overload indices
+  are tied to this artifact and engine, not stable identities across builds.
 - Method inspection reports Java or smali, fallback markers and complete/partial
  returned text. Decompiled source is a derived representation. A complete text
  result does not establish complete semantics or a byte-identical reconstruction.
 - Reference results are incoming static relationships between provider nodes.
-  Source lines and DEX instruction offsets remain unknown. They are not observed
-  runtime calls.
+  `reference_unit=using_node` means `total` counts containing JADX nodes, not
+  individual invoke instructions; two calls from one method can appear as one
+  entry. `coverage=complete` covers this node inventory only. For a method
+  reference whose using node has raw code, `direct_invokes` lists matching DEX
+  invoke instructions with their DEX entry, raw source method ID, code-unit
+  offset, method index and opcode. An empty array means no direct invoke was
+  matched in that node; `null` means raw code was unavailable or the using node
+  was not a method. This list does not establish complete call-site coverage
+  outside JADX's using-node inventory or through reflection and dynamic loading.
+  A virtual or interface invoke also does not establish its runtime implementation.
+  Source lines and the containing node's own `dex_offset` remain unknown.
+  Method-reference results also carry the selected `dex_descriptor`;
+  class-reference results report `null`.
+  These relationships are not observed runtime calls.
 - Original requests, APK SHA-256, actual engine JAR SHA-256 and raw producer
  responses remain in Evidence. Source revision is populated only for bytes
  matching the audited release JAR.
@@ -210,9 +226,11 @@ REA never writes to the original APK or launches target code.

 On Windows, stdin writes preserve stream backpressure and run outside the Node
 event loop. Cancellation terminates the retained job, including descendants,
-before workspace cleanup. An abrupt CLI/server process termination closes the
-job and stops Java, but cannot run JavaScript workspace cleanup; temporary
-workspace files can remain after that forced exit.
+before workspace cleanup. On Windows, a detached REA helper owns the private
+workspace's native directory handle. An abrupt CLI/server owner termination
+closes the Java job and the helper's input pipe; the helper then removes the
+workspace by handle. The real Windows lane checks both effects. If the helper
+also dies or the host loses power before it finishes, private files can remain.

 If Java cannot start the bridge, REA reports the selected executable and retained
 startup diagnostics. Select a full JDK through `JAVA_HOME` or `PATH`, and use
@@ -275,12 +293,20 @@ The original APK and host Java configuration remain unchanged.

 The same lane runs on Windows x64 with the bundled native controls and a full
 JDK. It checks CLI/MCP results, real MCP cancellation and disconnect, and Java
-exit after abrupt CLI owner termination. Windows forced termination is checked
-separately from the POSIX CLI SIGTERM handler; it does not claim a structured
-cancellation result or workspace removal after the owner is forcibly killed.
+exit and workspace removal after abrupt CLI owner termination. Windows forced
+termination is checked separately from the POSIX CLI SIGTERM handler. A
+synthetic two-owner test confirms that one owner's exit does not remove the
+other owner's workspace. The lane does not claim a structured cancellation
+result or power-loss recovery.

 The download script verifies fixed SHA-256 values, reuses matching files and
 refuses to overwrite a different existing file. APK/JAR files live under ignored
 `_reference/` and are excluded from package contents. The lane exercises actual
 REA CLI and MCP results with the real engine, separately from synthetic protocol
 regressions. It needs no Gradle build, emulator, Android SDK or Ghidra.
+
+Direct invoke sites retain exact DEX code-unit offsets separately from each
+containing node's unknown `dex_offset`. `direct_invokes_exhaustive: false`
+means instruction rows were bounded by the local bridge frame budget; `null`
+means the producer did not establish instruction coverage. Using-node totals
+and coverage do not imply complete instruction evidence.
@@ -91,4 +91,4 @@ OpenJDK 25 against a signed aapt2-built probe APK carrying two resource
 locales — launcher version, on-disk digest agreement, apktool.yml metadata
 (1.2.3, SDK 24–34), manifest package agreement, default and `de` string
 tables projected. Parser goldens in the test suite come from the same
-decode. See `docs/testing.md` for the lane summary.
+decode. See `docs/development/testing.md` for the lane summary.
@@ -60,6 +60,10 @@ server; older servers keep the complete request after schema discovery.
  [Dart 2.14 layout](https://github.com/dart-lang/sdk/blob/2.14.0/runtime/vm/snapshot.h).
  Kind numbers vary across Dart releases; other values are preserved with
  partial coverage, without guessing their interpretation.
+  Address resolution examines every overlapping `PT_LOAD` interpretation,
+  including partial overlaps. Equivalent mappings are coalesced; conflicting
+  mappings leave affected symbols unresolved and qualify coverage. Dynamic
+  hash, symbol and string tables use the same mapping checks.
  A payload without exported snapshot symbols is refused rather
  than guessed at.
 - **The snapshot hash** from the header at the start of each exported data
@@ -133,8 +137,11 @@ server; older servers keep the complete request after schema discovery.
  `resource_constraint`.
 - **Engine notes.** Engine libraries are spooled into the owned root. ELF
  headers, note tables and note payloads share an 8 MiB metadata budget;
-  up to 64 distinct build IDs are retained. Exceeding either bound preserves
-  the candidates already examined and reports partial coverage.
+  up to 64 distinct build IDs and 1024 distinct nonempty note ranges are retained.
+  The range cap bounds bookkeeping and separate positional reads even for tiny
+  overlapping declarations. Exact duplicates share one read and empty ranges
+  consume no inventory slots. Exceeding a bound preserves the candidates examined
+  from retained ranges and reports partial coverage with `build_id: null`.
 - **Metadata and candidate capacity.** Both operations refuse duplicate
  relevant library paths. Inventory is limited to 32 ABIs and 1024 bytes per
  relevant library path, independently of compressed size. Identification
@@ -174,3 +181,9 @@ engine build-ids, no labeled Dart version (as expected for a release
 engine), and the Android clang toolchain line; a plain aapt2-built APK
 reports not-detected with complete coverage. The suite uses self-contained
 synthetic ELF images and scanner payloads; it does not read private local files.
+
+The Gallery workflow and all 147 focused Flutter tests also pass on macOS Sonoma
+14.8.9 x86-64 and Windows 11 x64 build 26300.9457 guests with Node 24.18.0,
+including the conflicting-load and note-range-limit CLI/MCP regressions. Windows
+verification runs under a non-administrator account. Verifiers use a shared
+temporary parent so each CLI/MCP process can own and release its own snapshots.
@@ -39,6 +39,18 @@ license](https://github.com/morluto/rea/blob/main/third_party/evmole/README.md)
 - Upstream also returns terminal metadata during selector recovery. Its reported
  values remain in `raw_result`; integer precision and non-text-key coverage are
  unknown in the JS binding. Full bytecode retains the original encoded metadata.
+- `bytecode.metadata` independently interprets a plausible terminal CBOR root
+  map from the selected bytes. Integers use decimal strings; byte strings use hex,
+  and scalar keys retain their types. The recorded offset/length addresses the
+  original bytecode, so summary delivery does not copy an opaque CBOR payload.
+  Nested containers have partial scalar coverage; unsupported or malformed
+  candidates report `not-decoded` with a diagnostic. Decoding is bounded to 64
+  container levels and the terminal payload's encoded size.
+- An unavailable trailer does not prove metadata absence or Solidity origin.
+  Compiler-version bytes/text are metadata declarations, not verified compiler,
+  source-file or deployed-contract identity. Historical omission parses as a null
+  unknown facet without changing the original Evidence record. Metadata/source
+  URLs are not fetched.
 - Selectors, argument strings and state mutability are **inferences**. Function
  names/signatures are not looked up. Optimized code may produce different
  mutability candidates; recovered types are not a verified source ABI.
@@ -125,3 +137,15 @@ The real verification lane traces representative raw/hex CLI workflows and check
 that only declared Node/prlimit launchers and process ownership inspection run.
 Socket traces permit local stdio socket pairs and reject attempted network requests.
 These observations verify those fixtures; they are not a general network sandbox.
+
+For the independent metadata parser, `npm run verify:solidity:metadata` uses an
+existing caller-selected solc 0.8.30 module:
+
+```sh
+REA_VERIFY_SOLC_MODULE=/absolute/path/to/solc/index.js npm run verify:solidity:metadata
+```
+
+It compiles the owned fixture with unoptimized, viaIR, content-hash-free and
+CBOR-free settings, verifies the observed trailer facts and reports local decode
+timings. No contract is executed. This lane does not establish the complete
+Linux EVM provider's CLI/MCP, resource-limit or cleanup behavior.
@@ -124,7 +124,7 @@ Select a verified native child for the existing tools:

 Then use `analyze_function`, `inspect_native_api` or the other native primitives.
 Native architecture and executable validation still apply. Generic
-[MIPS ELF](ghidra-mips.md) and [RISC-V ELF](ghidra-riscv.md) lanes are separate
+[MIPS ELF](../../providers/ghidra-mips.md) and [RISC-V ELF](../../providers/ghidra-riscv.md) lanes are separate
 documents with their own admission boundaries. This milestone does
 not add PPC decompilation, raw flash load profiles, bootloader/device
 tree semantics, vulnerability scanning, emulation or hardware runtime capture.
@@ -294,7 +294,7 @@ References are scoped to one connection; `close_binary` clears them. Export a
 bundle before closing and import it on another connection, or supply the full
 inline Evidence there. Versions before 4.1.0 accept full inline Evidence only; installing
 newer skill instructions does not change that schema. See
-[MCP Evidence inputs](mcp-contracts.md#retained-application-evidence-inputs).
+[MCP Evidence inputs](../../reference/mcp-contracts.md#retained-application-evidence-inputs).

 For two operator-provided directories or ASARs, run:

@@ -159,7 +159,7 @@ An unpacked entry whose companion bytes were not supplied remains
 `unavailable`. REA continues analyzing embedded JavaScript and records the
 missing native/resource bytes as unknown. The occurrence keeps
 `hash_status: unavailable`; no content-addressed child artifact is created for
-those missing bytes. See [MCP integrity handling](mcp-contracts.md#integrity-record-and-continue)
+those missing bytes. See [MCP integrity handling](../../reference/mcp-contracts.md#integrity-record-and-continue)
 for the tool-result contract.

 ## Large results
@@ -170,7 +170,7 @@ select exact [source paths](#select-sources-before-analysis).

 If a complete response exceeds the transport budget, use its retained Evidence
 ID for a summary, module page, or item, or export the bundle. See
-[MCP tool results](mcp-contracts.md#tool-results) for delivery limits, export, and
+[MCP tool results](../../reference/mcp-contracts.md#tool-results) for delivery limits, export, and
 matching server/client buffer settings. Follow-up results also need to fit that
 budget. [Analyzer limits](#analyzer-and-result-admission) control analysis memory,
 source deadlines, and semantic capacity separately.
@@ -184,7 +184,7 @@ or Evidence sealing. Unexamined relationships remain unknown.

 MCP returns a `partial_observation` retained reference after recording succeeds;
 open it with `inspect_analysis_view` on the same connection. If the SDK stopped
-waiting before receiving the reply, follow [MCP cancellation recovery](mcp-contracts.md#progress-and-cancellation)
+waiting before receiving the reply, follow [MCP cancellation recovery](../../reference/mcp-contracts.md#progress-and-cancellation)
 to find the record. CLI failure output contains the complete partial Evidence.
 Owned analyzer cleanup is verified before private files are released; uncertain
 cleanup retains ownership for retry and is reported separately.
@@ -136,6 +136,6 @@ output, with 8 MiB per diagnostic/report stream. Exceeding a limit is an explici
 failure with rollback. These limits apply per operation and do not claim aggregate
 host containment across concurrent callers.

-See [testing.md](testing.md#javascript-source-recovery) for the focused real
+See [testing.md](../../development/testing.md#javascript-source-recovery) for the focused real
 Wakaru CLI/MCP lane and its source-owned compiler fixtures. Other host platforms
 and Bun/Vue recovery are not claimed by this adapter.
@@ -24,7 +24,7 @@ Native-body bridge mapping and managed runtime execution are outside the
 current tool set.

 The canonical tool inventory is the
-[build-generated catalog](mcp-contracts.md#generated-catalog).
+[build-generated catalog](../../reference/mcp-contracts.md#generated-catalog).

 ## Inspect an assembly

@@ -228,13 +228,14 @@ describes exported shared-library entry points.
 REA offers a built-in read-only snapshot parser for x64 PE/RTR 9.1 metadata and
 an optional Linux headless Ghidra adapter for annotations and broader recovery.
 The adapter requires a locally built `REA_GHIDRA_NATIVEAOT_JAR`; REA does not
-install it or its toolchain. The [NativeAOT guide](ghidra-nativeaot.md) defines
+install it or its toolchain. The [NativeAOT guide](../../providers/ghidra-nativeaot.md) defines
 these routes, their layout/host restrictions, derived-memory provenance, and
 verification coverage.

 REA's experimental Windows Ghidra boundary admits native x86 and x86-64 PE
-applications and DLLs for static analysis. This does not establish Windows
-NativeAOT metadata-recovery coverage.
+applications and DLLs for static analysis. For x64 PE NativeAOT, the read-only
+parser also runs there; the [NativeAOT guide](../../providers/ghidra-nativeaot.md) lists what a
+Windows host covers.

 For NativeAOT analysis, preserve the selected native artifact's path and digest
 and report recovered type data with its returned provenance. Linking those types
@@ -242,6 +243,7 @@ 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.

+<div id="managednative-boundary-rules"></div>
 <div id="managed-native-boundaries"></div>

 ## Managed/native boundary rules
@@ -253,7 +255,7 @@ 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.
+[Ghidra NativeAOT extension](../../providers/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,
@@ -379,7 +381,7 @@ The current lane uses source-owned byte-built fixtures and malformed-input
 regressions, with optional operator-supplied applications and ILSpy verification.

 Run the deterministic lane with `npm run verify:managed`. See
-[testing](testing.md#real-toolchain-verification-lanes) for prerequisites and
+[testing](../../development/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.

@@ -104,7 +104,7 @@ reply budget applies to the decoder record; the CLI/MCP Evidence envelope adds
 copies and encoding overhead. The
 pinned MCP SDK defaults to a 10 MiB receive buffer. Large complete results need
 a caller-configured `StdioClientTransport({ maxBufferSize: ... })` and a matching
-server `REA_MCP_MAX_RESPONSE_BYTES`. See [MCP delivery budgets](mcp-contracts.md#tool-results).
+server `REA_MCP_MAX_RESPONSE_BYTES`. See [MCP delivery budgets](../../reference/mcp-contracts.md#tool-results).
 These settings affect delivery, not decoder coverage or limits. The large
 extended-index verification uses 256 MiB and an explicit five-minute request
 timeout in its separate opt-in MCP lane. REA does not silently truncate the result. Python lowers resource soft limits to at most 3 GiB virtual address space,
@@ -81,7 +81,7 @@ temporary files, starts no subprocesses and accesses no network endpoint.
 Resource guards bound the selected file to 256 MiB, aggregate embedded strings
 to 1 MiB, structural table decoding to 16 MiB and the complete normalized metadata
 report to 8 MiB. Oversized results fail without partial success. MCP also applies
-its [response transport budget](mcp-contracts.md), which counts both text and
+its [response transport budget](../../reference/mcp-contracts.md), which counts both text and
 structured content; a report within the metadata limit can still require export
 from retained Evidence. These limits are not operating-system memory or CPU
 isolation.
@@ -8,7 +8,7 @@ observation complement that analysis when they answer a specific question.

 ## Start with a function

-Choose an installed provider from [setup](installation.md#hopper). For Ghidra:
+Choose an installed provider from [setup](../../getting-started/installation.md#hopper). For Ghidra:

 ```bash
 rea inspect /absolute/path/to/program --provider ghidra --json
@@ -299,7 +299,7 @@ complete observation.
  It reports each `@rpath`, `@loader_path` and `@executable_path` candidate with
  its outcome. Paths outside the analyzed root, including shared-cache system
  libraries, stay undetermined. See
-  [Apple application analysis](apple-application-analysis.md#dylib-load-resolution).
+  [Apple application analysis](../apple/apple-application-analysis.md#dylib-load-resolution).
 - `inspect_asset_catalog` / `rea inspect-asset-catalog <app>` reads compiled
  `Assets.car` metadata through macOS `assetutil --info`. Catalog digests, raw
  rendition fields, pagination and exact UI resource-name matches are returned.
@@ -477,10 +477,10 @@ Install a Ghidra 12.1.x release and the 64-bit full JDK it declares, then config
 use them. Ghidra analysis supports Linux x64/arm64 and macOS x64/arm64; each installation requires
 the matching native decompiler. Experimental Windows x64 P0 admits native
 x86 and x86-64 PE applications and DLLs, plus explicitly selected
-[raw NMOS 6502 images](raw-binary.md#nmos-6502) with a caller-supplied load address,
+[raw NMOS 6502 images](../../providers/raw-binary.md#nmos-6502) with a caller-supplied load address,
 on fixed local NTFS volumes. Other raw CPU families remain unsupported on Windows.
 The boundary uses bundled Job Object ownership, protected runtime DACLs, and
-handle-based path admission. See [Windows Ghidra P0](windows-ghidra-p0.md) and
+handle-based path admission. See [Windows Ghidra P0](../../providers/windows-ghidra-p0.md) and
 [issue #527](https://github.com/morluto/rea/issues/527).
 On Linux and macOS, `annotate_native_function` atomically edits a function name
 and entry comments in the ephemeral database, returning refreshed analysis
@@ -549,3 +549,17 @@ Value projection preserves serialized node kinds, IDs, references and pagination
 Exact and ambiguous value counts describe emitted root/object value instances;
 a root and an object may contain the same value. Archive digests identify the
 original bytes.
+
+## Locate a byte signature
+
+Use `search_bytes` after opening a target with Ghidra to locate a known constant
+or instruction sequence. For example, `{"pattern":"48 8B ?? ?? 89","limit":100}`
+returns ordered addresses with segments, source file offsets and containing
+procedures. The CLI equivalent is
+`rea search-bytes ./program '48 8B ?? ?? 89' --provider ghidra`.
+Use `start`/`end` to constrain the inclusive address window, and continue with
+`next_cursor` until `complete` is true. Inspect `searched` for page coverage and
+skipped uninitialized blocks. A missing match does not establish absence from
+uninitialized memory or across block boundaries. See
+[Ghidra byte search](../../providers/ghidra-provider.md#masked-byte-search) for mask and coverage
+semantics. This query never executes or modifies target bytes.
@@ -1,7 +1,10 @@
 # Recorded crash evidence

 `inspect_recorded_crash` / `rea inspect-recorded-crash` inspect a caller-selected
-Linux ELF64 x86-64 little-endian core independently of an active binary target.
+Linux ELF64 little-endian core independently of an active binary target. Two
+architecture profiles are interpreted, x86-64 and AArch64; each binds registers
+to its own `NT_PRSTATUS` layout, and any other `e_machine` is refused as
+`unsupported_target` before note interpretation.

 ```sh
 export REA_PWNTOOLS_PYTHON=/absolute/existing/venv/bin/python
@@ -10,8 +13,8 @@ rea inspect-recorded-crash ./crash.core --json

 The selected Python needs unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2.
 REA does not install these dependencies. ELFFile/its original ELF structures and
-pwntools' original Linux amd64 ctypes provide parsing and ABI layout. The adapter
-adds bounds, representation preservation and lifecycle ownership.
+pwntools' original Linux amd64 and aarch64 ctypes provide parsing and ABI layout.
+The adapter adds bounds, representation preservation and lifecycle ownership.
 The initial Linux note profile accepts System V/unspecified and GNU/Linux OSABI
 with ABI version zero. Other declared ABIs return `unsupported_target` before
 note interpretation; an unspecified OSABI alone does not prove OS origin.
@@ -27,7 +30,8 @@ note interpretation; an unspecified OSABI alone does not prove OS origin.
 - Every exact Linux CORE PRSTATUS note as a separate recorded thread, with
  historical PID, signal and lossless uint64 registers bound to source bytes.
  Each supported note has exactly one interpretation; each thread contains the
-  complete 27-register ABI set, with names bound to their original ABI offsets.
+  complete ABI register set for its architecture (27 registers for amd64,
+  34 for AArch64), with names bound to their original ABI offsets.
  Physical note ranges cannot overlap or leave segment gaps. ELF and note headers
  are independently bound to the snapshot, including extended program counts.
 - Signed SIGINFO number/code/errno. Initially only SIGSEGV codes 1/2 establish the
@@ -13,6 +13,11 @@ Check `binary_session` for configured capability availability. A recognized
 header is not validation of the complete module; missing WABT is reported
 separately as an unavailable capability, not as missing native engine support.

+The recognized WASM header is checked before automatic database routing from a
+.hop filename. Renaming a module to .hop therefore keeps the static-inspection
+diagnostic. An explicit database selection or raw/COM format selection retains
+the caller's requested interpretation; ordinary .hop database routing is unchanged.
+
 Set `REA_WABT_BIN_DIRECTORY` to an absolute directory containing executable
 `wasm-validate`, `wasm-objdump` and `wasm2wat` (with `.exe` on Windows). Missing
 executables, unsupported banners and inaccessible tools produce actionable
@@ -78,4 +83,47 @@ Candidates are caller-selected files; their identity does not imply validation.
 Both CLI and MCP use the same typed port and application service. MCP publishes
 SDK-compatible schemas and records Evidence for `get_evidence_bundle` readback.
 See [WABT provenance](https://github.com/morluto/rea/blob/main/third_party/wabt/README.md) and
-[testing](testing.md#offline-wasm-artifacts) for real-tool verification.
+[testing](../../development/testing.md#offline-wasm-artifacts) for real-tool verification.
+
+## Compare core-module interfaces
+
+Inspection adds producer-owned typed `interface` facts while keeping exact WAT
+import/export forms. Function/tag signatures resolve type indices; table/memory
+limits, memory page size and global value type/mutability remain explicit.
+Unadmitted types (including GC reference signatures) retain null signatures and
+issues. Exact decoded names retain escapes, empty names, BOM and punctuation.
+This facet is absent in historical Evidence that did not examine typed interfaces.
+
+`compare_wasm_interfaces` accepts two complete `inspect_wasm_artifact` Evidence
+records, or exact retained references in the current MCP session, and required
+`scope: "imports" | "exports" | "both"`. It reads no files and needs no active
+WABT toolchain. CLI uses portable inline Evidence in one JSON document:
+
+```bash
+rea compare-wasm-interfaces comparison-input.json --json
+```
+
+```json
+{
+  "left": { "kind": "retained-evidence", "evidence_id": "ev_<left-digest>" },
+  "right": { "kind": "retained-evidence", "evidence_id": "ev_<right-digest>" },
+  "scope": "both"
+}
+```
+
+The references above are MCP-only; put complete Evidence objects in the CLI
+input. Resolve summary delivery to its retained complete parent before comparing.
+Results retain both input Evidence IDs, artifact paths/digests/lengths and every
+selected occurrence. Unique names are added, removed, changed or unchanged;
+duplicate names and unsupported signatures are unknown. Incomplete or historical
+inventories never establish absence. Imports group by module/name, exports by
+name, so a change of kind is visible. Output ordering is deterministic.
+
+Static type equality does not establish runtime compatibility, ABI compatibility
+or linking success. Comparison covers core modules; WebAssembly components and
+canonical ABI relationships belong to their separate inspection workflow.
+
+After building, run `REA_WABT_BIN_DIRECTORY=/absolute/wabt/bin node
+scripts/verify-wasm-interface-comparison.mjs` for original-module comparison
+through the compiled CLI and stdio MCP. It uses owned fixtures and WABT 1.0.42;
+no WASM module is instantiated or executed.
@@ -51,7 +51,7 @@ Caller-owned JSON/base64 strings, input parsing and validation, transport
 buffers, garbage-collector behavior, and other runtime memory are outside this
 estimate; the budget does not promise a bound on total process memory.

-Electron `file://` pages use a separate provider and target boundary; see [electron-observation.md](electron-observation.md).
+Electron `file://` pages use a separate provider and target boundary; see [electron-observation.md](../javascript/electron-observation.md).

 ## Provider authorities

@@ -65,7 +65,7 @@ vocabulary (`BrowserExclusionReason`): every denial reason in every stack maps
 onto it, even where a wire schema keeps a narrower historical bucket.
 Existing static application Evidence and passive web/Electron captures can be
 combined later through
-[JavaScript static/runtime reconciliation](javascript-runtime-reconciliation.md).
+[JavaScript static/runtime reconciliation](../javascript/javascript-runtime-reconciliation.md).

 ## Start a browser

@@ -107,6 +107,47 @@ first navigation. For a dedicated investigation profile, add
 then describe an unloaded page; REA continues to require an allowed, committed
 URL. See [the startup investigation](https://github.com/morluto/rea/issues/1384#issuecomment-6093781686).

+### Browsers without HTTP discovery
+
+Some browsers expose a loopback browser WebSocket but no `/json/version` or
+`/json/list`. Chrome 144 and later can enable remote debugging on a running
+browser from `chrome://inspect/#remote-debugging`; this mode is reported to
+serve only the browser socket. Since Chrome 136, `--remote-debugging-port` is
+ignored for the default profile, so this is the remaining way to inspect a page
+in an existing profile.
+
+For such a browser, pass the browser socket instead of the HTTP endpoint:
+
+```bash
+rea list-browser-targets ws://127.0.0.1:9222/devtools/browser/<id>
+```
+
+Chrome writes the port and the `/devtools/browser/<id>` path to the
+`DevToolsActivePort` file in its user data directory. REA does not read that
+file for you.
+
+- Only `list_browser_targets`, `inspect_web_page`, `analyze_web_bundle`,
+  `observe_web_session`, `discover_webmcp_tools`, and `capture_web_screenshot`
+  accept a browser socket. Website runtime attribution, Electron inspection,
+  and scenario attach mode still require HTTP discovery.
+- Each call opens one WebSocket and uses it for discovery
+  (`Browser.getVersion`, `Target.getTargets`) and for the selected page.
+  Discovery must finish within the same 10-second deadline as HTTP discovery.
+  Chrome may ask you to approve each connection.
+- The browser identifier controls access to the socket. Evidence records the
+  endpoint as `ws://127.0.0.1:9222/devtools/browser/[REDACTED]`.
+- `browser.revision` is the socket's `Browser.getVersion` value, such as
+  `@e533e98…`. HTTP discovery reports `WebKit-Version`, such as
+  `537.36 (@e533e98…)`.
+- `Target.getTargets` reports whether each target is attached. Chrome's
+  `/json/list` can omit it, so HTTP discovery may report `attached` as `null`.
+- An existing profile can hold many unrelated pages. Target listing returns
+  each eligible page's URL and title, so pass `--allowed-origins` to list only
+  the origins you are investigating.
+
+A browser driven only through `--remote-debugging-pipe` or a vendor's private
+automation channel has neither endpoint, and REA cannot attach to it.
+
 ## Request boundary

 CDP connections enforce the shared 64 MiB limit per WebSocket message. A larger
@@ -116,9 +157,13 @@ decoded strings or JSON objects.

 Discovery supplies a literal loopback CDP endpoint and returns all eligible
 page targets unless an exact HTTP(S) origin filter narrows the result. Follow-up
-inspection requests select one target; their default scope is its current origin. `localhost`, private-LAN
-addresses, HTTPS CDP endpoints, credentials, paths, queries, fragments, and
-implicit ports are not valid CDP endpoints. Origin filters contain only scheme,
+inspection requests select one target; their default scope is its current origin.
+The endpoint is either `http://127.0.0.1:PORT` or a
+[browser socket](#browsers-without-http-discovery),
+`ws://127.0.0.1:PORT/devtools/browser/ID`; `[::1]` may replace `127.0.0.1`.
+`localhost`, private-LAN addresses, HTTPS and `wss:` endpoints, credentials,
+queries, fragments, implicit ports, and any other path are not valid CDP
+endpoints. Origin filters contain only scheme,
 host, and port; paths, credentials, queries, fragments, and wildcards are not
 valid origins.

@@ -82,4 +82,4 @@ closes only the owned browser; cleanup failure cannot return a successful trace.
 `REA_BROWSER_NO_SANDBOX=true` passes Chromium's corresponding launch option when
 the host requires it; it does not enable an REA security boundary.

-See [testing](testing.md) for the native loading oracle and CLI/MCP real lane.
+See [testing](../../development/testing.md) for the native loading oracle and CLI/MCP real lane.
@@ -0,0 +1,183 @@
+# Verify real HTTP/3 MITM captures
+
+This optional Linux laboratory checks native mitmproxy captures through REA's
+public CLI and MCP. It changes no runtime contracts or adapters and establishes
+only the specific producer, mode and clients exercised here.
+
+## Prepare a disposable guest
+
+The exercised image is [Omarchy 4.0.4, build 440](https://nightly.omarchy.org/stable/4.0.4/440/omarchy-4.0.4.qcow2),
+SHA-256 `43412b896fe3d730e373a51a8acf99343d7c3e6dee78aa9f9bd7fca181127264`.
+Download it without installing guest packages on the host, check its digest,
+and use a **new qcow2 overlay** with that file as a read-only backing image.
+The matching [boot artifacts](https://nightly.omarchy.org/stable/4.0.4/440/unpacked/)
+include the kernel, initrd, cmdline and upstream vm-boot recipe. Use a fresh SSH
+key, loopback forwarding and guest disk; do not reuse another investigation's
+writable overlay or host trust configuration. Shut the guest down before
+switching overlays. Preserve the image and boot artifact hashes with evidence.
+
+This sealed guest already supplies cURL 8.22.0 with OpenSSL 3.6.4, ngtcp2 1.25.0,
+nghttp3 1.18.0 and nghttp2 1.70.0. **No guest rolling package upgrade is needed.**
+Run `curl --version` and verify HTTP2 and HTTP3 features before starting. A stock
+cURL from another distribution may omit HTTP/3. For a different guest, building
+cURL requires a compatible TLS library, ngtcp2 and nghttp3; follow the
+[official build instructions](https://curl.se/docs/http3.html), install to a guest
+private prefix, and record exact source revisions and build inputs. That alternative
+has not been exercised by this laboratory; it is not the pinned reproduction path.
+
+Use a fresh VM overlay over a sealed Linux image. Use user-mode networking with
+SSH forwarding bound to host loopback; keep host directories unmounted. Install
+and build dependencies inside the guest, then remove its default route before
+generating traffic. Host trust, routes and installed packages stay unchanged.
+
+Record the image digest, REA source revision and these dependency versions:
+
+- REA's `.nvmrc`, `package.json#packageManager` and locked npm dependencies.
+- Official Linux x86_64 mitmproxy **12.2.3** standalone archive. SHA-256:
+  `2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5`.
+- A private Python virtual environment using the complete pinned graph in
+  `scripts/fixtures/http3-lab-requirements.txt`. Save `pip freeze` and build/download logs.
+- OpenSSL and cURL advertising HTTP3 and HTTP2 in `curl --version`.
+
+The verified guest used Python 3.14.7, cURL 8.22.0, ngtcp2 1.25.0 and nghttp3
+1.18.0. Other dependency profiles need verification. Back up the guest's
+`/etc/hosts` before adding `127.0.0.1 lab.test`. Reserve guest TCP/UDP loopback
+ports 18443 and 19443. These changes belong only to the disposable guest.
+
+From the guest REA checkout, use its pinned Node/npm toolchain:
+
+```sh
+npm ci
+npm run build:cached
+python3 -m venv /absolute/lab/venv
+/absolute/lab/venv/bin/pip install --no-deps -r scripts/fixtures/http3-lab-requirements.txt
+/absolute/lab/venv/bin/pip check
+/absolute/lab/venv/bin/pip freeze > /absolute/lab/python-requirements.txt
+```
+
+Before removing the guest default route, download the official mitmproxy archive
+and verify it, then extract to the guest's private tools directory:
+
+```sh
+mkdir -p /absolute/lab/tools
+curl --fail --location https://downloads.mitmproxy.org/12.2.3/mitmproxy-12.2.3-linux-x86_64.tar.gz \
+  --output /absolute/lab/mitmproxy.tar.gz
+printf '%s  %s\n' 2e95286b618fa6fd33e5e62a78c2e5112571d85f42ec2bac29b97ee242bdb5c5 \
+  /absolute/lab/mitmproxy.tar.gz | sha256sum --check --strict
+tar -xzf /absolute/lab/mitmproxy.tar.gz -C /absolute/lab/tools
+/absolute/lab/tools/mitmdump --version
+```
+
+Pin the REA revision with `git rev-parse HEAD` or archive SHA-256. Build using
+the exact `.nvmrc` and npm version; do not copy a different checkout's `dist`.
+For stronger offline dependency reproduction, preserve downloaded Python
+archives, their digests and built wheels along with the image and toolchain.
+The requirement versions pin the runtime graph, not every transient build tool;
+source builds and alternate interpreters are not guaranteed byte-identical.
+
+## Run the narrow profile
+
+Select absolute executables and a new evidence directory. The producer refuses
+to reuse a directory. No certificates are installed in a system trust store;
+clients and proxy receive explicit paths to freshly generated test CAs.
+
+```sh
+REA_MITMDUMP_COMMAND=/absolute/lab/tools/mitmdump \
+REA_HTTP3_PYTHON_COMMAND=/absolute/lab/venv/bin/python \
+npm run verify:web:http3 -- /absolute/evidence/run-1
+```
+
+The producer sends three concurrent binary POSTs on one HTTP/3 connection to the
+same URL through mitmproxy reverse mode to an aioquic HTTP/3 origin. The origin
+waits for all complete requests, then dispatches responses in reverse order of
+completion at the origin. QUIC stream send/receive orders need not coincide. A cURL HTTP/3-only
+request checks a second client implementation. Mitmproxy's real save addon
+writes `normal.mitm`; no native flows are synthesized.
+
+A second proxy run disables HTTP/3. cURL `--http3` falls back to HTTP/2, reaching
+an HTTP/1.1 TLS test origin. `fallback.mitm` must retain those lower protocols,
+so a successful HTTP request cannot masquerade as an HTTP/3 success.
+
+## Acceptance and evidence
+
+Each execution creates `verifications/<run-UUID>/` with its own diagnostics.
+`verification-latest.json` belongs to the most recently registered attempt and
+changes atomically from `running` to `passed` or `failed`. Registration and
+the ownership check/replacement use the same SQLite transaction lock. An older
+attempt finishing later keeps its own reports without replacing the marker.
+The `.verification-lock.sqlite` pathname must remain in place while attempts
+may run; SQLite releases the lock on connection close or process death.
+Lock acquisition waits for the current owner without a timeout or lease
+stealing. The verifier has per-command deadlines, but no overall run deadline;
+a live stalled lock owner can therefore delay publication until it exits.
+Only a successful attempt writes its own `verification.json`, after
+all cleanup and input-integrity checks. `result.json` also records failures and
+the original error separately from cleanup errors. Older successes remain in
+identified history; a legacy root `verification.json` is archived before a rerun.
+A killed verifier may leave `running`, which must never be interpreted as success.
+
+Capture inputs live in `captures/`. To inspect them again without new traffic:
+
+```sh
+REA_MITMDUMP_COMMAND=/absolute/lab/tools/mitmdump \
+npm run verify:web:http3 -- /absolute/evidence/run-1 --inspect-existing
+```
+
+Acceptance for the current run:
+
+- Every positive native record reports HTTP/3, UDP, ALPN h3 and successful TLS
+  timestamps on both legs. Connection IDs, producer TLS labels, exact TLS setup
+  timestamps and connection errors match the UUID-matched producer observation
+  on each leg. Endpoint handshakes independently observe QUIC v1.
+- Native flow UUIDs remain distinct. Three endpoint streams share a connection
+  on each leg. Origin dispatch reverses completed receipt. Client and capture
+  ordering is observed, while association is verified independent of their order.
+- CLI and MCP agree. Request/response bytes, lengths, SHA-256, ordered duplicate
+  headers, method, scheme, authority and path match independent observations.
+  Readable header names and values, request URL fields and ALPN also match;
+  non-UTF-8 header bytes retain a null display value rather than replacement text.
+- Actual MCP advertised schemas validate, Evidence preserves source digests and
+  provider provenance, and the complete returned Evidence matches the retained MCP session records.
+- The fallback capture reports client HTTP/2 over TCP and origin HTTP/1.1, with
+  cURL independently reporting version 2. Input files remain unchanged.
+- Every cleanup action is attempted on success and failure, and final lineage
+  contains no live descendants. Recorded producer groups are inspected separately
+  after token-verified cleanup, including after their launcher has exited.
+
+Retain captures, endpoint/producer JSONL, proxy diagnostics, cURL output, manifest,
+CLI/MCP output, advertised schema and session bundle. Export public certificates
+and dependency/source provenance separately. Do not commit evidence, private
+keys, dependencies or VM disks. Shut down the guest after exporting evidence.
+
+The reverse proxy can preserve authority `lab.test:18443` while recording origin
+port 19443. Mitmproxy's serialized flow/connection UUIDs are not stream IDs.
+Endpoint stream IDs are scoped observations; this test invents no cross-leg
+mapping. Mitmproxy 12.2.3's `QUICv1` label alone does not prove negotiation: the
+fixture checks the negotiated `_quic._version` in pinned aioquic 1.2.0.
+
+Coverage is native capture, Linux reverse mode, QUIC v1 and these clients.
+Empty/absent/incomplete/redacted body semantics, cancellations, resets,
+certificate failures, malformed captures, HAR and qlog are separate increments.
+Local/WireGuard, browsers, QUIC v2, migration, 0-RTT, mTLS, replay, sustained load
+and loss tolerance remain unverified by this profile. Passing it does not
+establish general HTTP/3 support in REA.
+
+Official references: [mitmproxy protocol support](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/docs/src/content/concepts/protocols.md),
+[HTTP/3 implementation](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/mitmproxy/proxy/layers/http/_http3.py),
+[serialized HTTP state](https://github.com/mitmproxy/mitmproxy/blob/v12.2.3/mitmproxy/http.py),
+[aioquic configuration](https://github.com/aiortc/aioquic/blob/1.2.0/src/aioquic/quic/configuration.py).
+
+## Verifier regressions
+
+After building REA, run these inside the same isolated guest:
+
+```sh
+node --test scripts/lib/http3-verifier-lifecycle.test.mjs scripts/lib/http3-capture-assertions.test.mjs
+/absolute/lab/venv/bin/python scripts/fixtures/http3-lab.test.py
+```
+
+These cover different QUIC stream completion orders, stale success reports,
+multiple failed closes, separately owned process groups and partially acquired
+resources, plus producer TLS fact mismatches on both legs and altered readable
+fields with unchanged binary evidence. They test verifier
+semantics; they do not add HTTP/3 provider coverage.
@@ -41,28 +41,31 @@ For a first result from an extracted JavaScript application or ASAR:
 npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
 ```

-See [installation and setup](./installation.md) for requirements and configuration.
+See [installation and setup](getting-started/installation.md) for requirements and configuration.

-For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md).
+For runtime instrumentation, see the [Frida guide](guides/runtime/frida-instrumentation.md).

 ## Choose a guide

-| Task                                                | Guides                                                                                                                                                                                                                                                                                                                      |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Inspect native functions, references, or types      | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md)                                                                                                                                                             |
-| Select a native provider or import format           | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [JEB](jeb-analysis.md)                                                                   |
-| Analyze JavaScript or Electron artifacts            | [Static analysis](javascript-artifact-reconstruction.md), [tracing and comparisons](javascript-application-workflows.md), [application graph](javascript-application-graph.md), [source recovery](javascript-recovery.md)                                                                                                   |
-| Compare static JavaScript with runtime observations | [Runtime attribution](javascript-runtime-observation.md), [reconciliation](javascript-runtime-reconciliation.md), [Electron observation](electron-observation.md)                                                                                                                                                           |
-| Inspect assemblies, packages, or firmware           | [.NET](managed-code-analysis.md), [Android](android-analysis.md), [Apktool resources](apktool-resource-analysis.md), [ADB acquisition](adb-device-analysis.md), [Apple](apple-application-analysis.md), [Harmony](harmony-analysis.md), [firmware](firmware-analysis.md), [WASM](wasm-artifacts.md), [EVM](evm-bytecode.md) |
-| Observe or compare a browser scenario               | [CDP observation](browser-observation.md), [scenarios](browser-scenario-contract.md), [runtime evidence](web-runtime.md), [historical captures](web-network-captures.md)                                                                                                                                                    |
-| Trace captured website source                       | [Source locations](web-source-location.md), [module traces](website-module-trace.md), [script export](website-script-export.md)                                                                                                                                                                                             |
-| Capture and compare a command                       | [Process capture](process-capture.md)                                                                                                                                                                                                                                                                                       |
-| Use CLI/MCP and retain evidence                     | [CLI](cli.md), [MCP contracts](mcp-contracts.md), [agent prompts](mcp-prompts.md), [obligation ledgers](reconstruction-obligation-ledgers.md)                                                                                                                                                                               |
+The [documentation directory](README.md) lists every guide by domain and explains
+where authored references, specifications and generated records belong.

-For development, use [testing](testing.md), [client verification](client-verification.md),
-[tool design](tool-design.md), and [releasing](releasing.md).
-[Reconstruction readiness](reconstruction-readiness.md) describes a development
-conformance verifier. [The 6.2 migration](migration-6.2.md) records that release's
-compatibility changes; [the roadmap](roadmap.md) tracks future work.
+| Task                                                | Guides                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Inspect native functions, references, or types      | [Native binaries](guides/native/native-investigation.md), [Go metadata](guides/native/go-binaries.md), [offline ELF layout](guides/native/binary-diagnostics.md), [recorded crashes](guides/native/recorded-crashes.md)                                                                                                                                                                                                                                    |
+| Select a native provider or import format           | [Ghidra semantics](providers/ghidra-provider.md), [Windows](providers/windows-ghidra-p0.md), [DOS](providers/ghidra-dos.md), [raw bytes](providers/raw-binary.md), [MIPS](providers/ghidra-mips.md), [PSP](providers/ghidra-psp.md), [NativeAOT](providers/ghidra-nativeaot.md), [IDA](providers/ida-provider.md), [JEB](providers/jeb-analysis.md)                                                                                                        |
+| Analyze JavaScript or Electron artifacts            | [Static analysis](guides/javascript/javascript-artifact-reconstruction.md), [tracing and comparisons](guides/javascript/javascript-application-workflows.md), [application graph](guides/javascript/javascript-application-graph.md), [source recovery](guides/javascript/javascript-recovery.md)                                                                                                                                                          |
+| Compare static JavaScript with runtime observations | [Runtime attribution](guides/javascript/javascript-runtime-observation.md), [reconciliation](guides/javascript/javascript-runtime-reconciliation.md), [Electron observation](guides/javascript/electron-observation.md)                                                                                                                                                                                                                                    |
+| Inspect assemblies, packages, or firmware           | [.NET](guides/managed/managed-code-analysis.md), [Android](guides/android/android-analysis.md), [Apktool resources](guides/android/apktool-resource-analysis.md), [ADB acquisition](guides/android/adb-device-analysis.md), [Apple](guides/apple/apple-application-analysis.md), [Harmony](guides/harmony/harmony-analysis.md), [firmware](guides/firmware/firmware-analysis.md), [WASM](guides/wasm/wasm-artifacts.md), [EVM](guides/evm/evm-bytecode.md) |
+| Observe or compare a browser scenario               | [CDP observation](guides/web/browser-observation.md), [scenarios](guides/web/browser-scenario-contract.md), [runtime evidence](guides/web/web-runtime.md), [historical captures](guides/web/web-network-captures.md)                                                                                                                                                                                                                                       |
+| Trace captured website source                       | [Source locations](guides/web/web-source-location.md), [module traces](guides/web/website-module-trace.md), [script export](guides/web/website-script-export.md)                                                                                                                                                                                                                                                                                           |
+| Capture and compare a command                       | [Process capture](guides/runtime/process-capture.md)                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Use CLI/MCP and retain evidence                     | [CLI](getting-started/cli.md), [MCP contracts](reference/mcp-contracts.md), [agent prompts](getting-started/mcp-prompts.md), [obligation ledgers](reference/reconstruction-obligation-ledgers.md)                                                                                                                                                                                                                                                          |
+
+For development, use [testing](development/testing.md), [client verification](development/client-verification.md),
+[tool design](development/tool-design.md), and [releasing](development/releasing.md).
+[Reconstruction readiness](development/reconstruction-readiness.md) describes a development
+conformance verifier. [The 6.2 migration](migrations/migration-6.2.md) records that release's
+compatibility changes; [the roadmap](development/roadmap.md) tracks future work.

 ![REA inspecting a native binary in Hopper](./assets/rea-hopper-analysis.png)
@@ -38,7 +38,7 @@ if (reply.isError === true) {

 Lifecycle and other non-Evidence tools still use their own advertised output
 contracts. Do not assume every successful tool returns Evidence. Consult
-[`tools/list` and the result guide](mcp-contracts.md#tool-results).
+[`tools/list` and the result guide](../reference/mcp-contracts.md#tool-results).

 A transport `resource_constraint` error can include a retained
 `details.reported_limits.evidence_reference`. Use `inspect_analysis_view` or
@@ -79,7 +79,7 @@ rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/pat
 In MCP, open the target without the incompatible `snapshot_path`, run the
 required queries, then save to a new path through `close_binary.snapshot_path`.
 Do not fabricate missing provider profiles or query bindings. See
-[snapshot usage](cli.md#save-and-reuse-analysis-snapshots).
+[snapshot usage](../getting-started/cli.md#save-and-reuse-analysis-snapshots).

 Artifact inventory nodes identify content bytes. Path-specific role and
 permissions now belong to each occurrence:
@@ -22,6 +22,28 @@ lane. MIPS16 shared images have the separate bounded profile below; other shared
 or compressed images remain unsupported. Their family may be identified, but provider selection returns the
 specific unsupported constraint rather than guessing a compatible profile.

+A second admission covers recordless legacy firmware images
+([#1620](https://github.com/morluto/rea/issues/1620)): ELF32 `ET_EXEC` headers
+declaring `EF_MIPS_ARCH_32` or `EF_MIPS_ARCH_32R2` with an unspecified ABI
+field, `EF_MIPS_ABI2` clear, and an _inspected_ absence of any ABI flags
+record (a target whose record was merely not observed stays refused). For
+these images o32 is an analysis assumption derived from the ELF32/ET_EXEC
+structure, recorded as `mips_abi_basis` in the profile and stated as a
+limitation in Evidence, never a declared fact; floating-point ABI semantics
+stay unverified. Ghidra's own header auto-selection picks a 64-bit language
+for exactly these files, so the lane pins `-processor MIPS:<LE|BE>:32:default`
+through a `provider-pinned-v1` profile selection and checks the
+bridge-reported `language_id` after import. A caller-selected
+`REA_GHIDRA_LANGUAGE_ID`/`REA_GHIDRA_COMPILER_SPEC_ID` still wins over the
+pin; combining the pinned profile with an environment override is a typed
+refusal. A header that declares an ABI field but carries no record is still
+refused. Two further boundaries apply: an inspection that could not examine
+every ABI declaration source (for example a carved ELF whose section table
+extends past the captured bytes without a program-header record) does not
+establish the recordless admission, and an `EF_MIPS_ARCH_32` header that
+_declares_ an ABI is refused rather than relabeled, because the declared-ABI
+lane is verified for `EF_MIPS_ARCH_32R2` headers only.
+
 Explicit `EF_MIPS_FP64` and `EF_MIPS_NAN2008` declarations are refused. Their
 absence is insufficient: Clang can emit identical `e_flags` for FP32, FP64 and
 soft-float targets. Target resolution also reads the 24-byte ABI flags record
@@ -40,12 +62,14 @@ absent or supply a default ABI.
 The field layout follows
 [`Elf_MIPS_ABIFlags_v0`](https://github.com/bminor/glibc/blob/master/elf/elf.h).

-Provider admission requires record version 0, MIPS32r2, 32-bit GPRs, no CPR2,
-no ISA extension, ASE or unknown general flags, and one of two floating-point
-declarations: 32-bit CPR1 with a double-precision or FPXX ABI, or no CPR1 with
-the soft-float ABI. Other combinations, including single-float, FP64 and
-unspecified ABIs, are refused. Missing records remain unknown rather than
-defaulting to a compatible ABI, and this lane refuses them. Unknown record
+Provider admission on the declared-ABI lane above requires record version 0,
+MIPS32r2, 32-bit GPRs, no CPR2, no ISA extension, ASE or unknown general
+flags, and one of two floating-point declarations: 32-bit CPR1 with a
+double-precision or FPXX ABI, or no CPR1 with the soft-float ABI. Other
+combinations, including single-float, FP64 and unspecified ABIs, are refused.
+Missing records remain unknown rather than defaulting to a compatible ABI, and
+the declared-ABI lane refuses them; the recordless legacy admission above is
+the only path that admits a recordless image. Unknown record
 values are retained for diagnosis but do not gain provider support. These checks
 bind the declared interpretation; the fixtures do not establish full
 floating-point behavioral conformance.
@@ -8,7 +8,7 @@ labels, functions, or memory bytes. The hydration semantics are adapted from
 `effeb734fc570c32650f88b159608979dc7b423e` (MIT), cross-checked against
 .NET's `MethodTable.h` at runtime commit
 `a3b2d40328be0be3f8dd43f0e5cc925b8827b044` (MIT). The required notice ships in
-[`licenses/nativeaot-parser-MIT.txt`](../licenses/nativeaot-parser-MIT.txt).
+[`licenses/nativeaot-parser-MIT.txt`](https://github.com/morluto/rea/blob/main/licenses/nativeaot-parser-MIT.txt).

 The optional headless Ghidra adapter remains available for database annotations
 and broader recovery. It uses the same pinned upstream commit as an opt-in
@@ -17,10 +17,14 @@ submodule and is a separate, more capable workflow.
 The parser currently handles x64 PE32+ and RTR 9.1, including bounded
 DEHYDRATED_DATA processing, MethodTable relationships, virtual slots, and
 frozen strings. Other RTR versions and PE architectures are reported as
-unsupported or partial. The matching .NET 8.0.22 fixture is source-built and
-the parser's Windows-host Ghidra workflow has not yet had a real Windows-host
-run. This does not establish Windows Ghidra import or decompiler behavior.
-Windows Ghidra P0 has no database mutation authority. A PE/CLI or ReadyToRun
+unsupported or partial. The matching .NET 8.0.22 fixture is source-built.
+
+On a Windows host, Windows Ghidra P0 runs the parser without a JAR. Metadata,
+MethodTable relationships, virtual slots and frozen strings come from the
+parser report, and `analyze_function` decompiles slot targets. Tools that read
+the Ghidra database do not see rehydrated bytes (see below), because only the
+optional adapter writes them into the database and Windows Ghidra P0 has no
+database mutation authority. A PE/CLI or ReadyToRun
 assembly should use `inspect_managed_artifact`; it is not NativeAOT.

 ## Build and configure
@@ -57,7 +61,9 @@ returns `observations.metadata_recovery` inline from the captured source snapsho
 including the RTR header, MethodTable addresses, frozen strings, derived overlay
 identity, and examined/recovered counts. Its enclosing `unsupported` load-image
 status means independent PE load-image verification was not performed; it does
-not mean the metadata parser failed or the executable failed to load.
+not mean the metadata parser failed or the executable failed to load. Without
+the optional adapter, each recovered type's `type` is `null`, because no Ghidra
+DataType exists; select it by `address`.

 Pass a returned MethodTable address to `inspect_native_data_type`. A direct PE
 query also derives the snapshot metadata from the authenticated Ghidra session
@@ -67,8 +73,12 @@ The database result remains `unavailable` when Ghidra has no DataType at that
 address; its `metadata_recovery.source` is `read-only-derived-overlay` and
 carries related type, interface, slot, and target observations. Generated
 address identities do not claim original managed names. The parser does not
-merge frozen literals into Ghidra's database string inventory. Follow slot
-targets with `analyze_function` and ordinary cross-references.
+merge frozen literals into Ghidra's database string inventory: read them from
+`metadata_recovery.frozen_strings`, not `search_strings`. Slot targets come
+from the parser report; on Windows P0 without the adapter, a `read_bytes` of
+a slot in the rehydrated region returns no bytes. The Linux adapter route
+verifies a complete slot read and its target. Follow slot targets with `analyze_function` and ordinary
+cross-references.

 The built-in CLI path uses a MethodTable address returned by the parser or
 another observation:
@@ -122,10 +132,18 @@ does not imply that ordinary native disassembly/decompilation is impossible.

 ## Verification

-See [the dedicated lane](testing.md#optional-nativeaot-ghidra-analysis).
+See [the dedicated lane](../development/testing.md#optional-nativeaot-ghidra-analysis).
 Fixtures are source-built benign .NET programs with inheritance, an interface,
 virtual dispatch, representative arithmetic and frozen strings. Independent
 compiler/linker symbols and raw directory bytes provide the oracle. Stripped
 fixtures exercise heuristic detection. Tests do not execute the resulting
 NativeAOT binaries. Fixture generation and adapter compilation are optional and
 never prerequisites of ordinary native analysis or setup.
+
+The real MCP lane runs only on a Linux x64 host with the adapter. The
+Windows-host behavior above was checked manually over MCP on Windows 11 x64
+(non-elevated, Ghidra 12.1.4, JDK 21, no JAR) with the source-built win-x64
+symbols fixture. The format, RTR version and frozen strings matched the fixture
+oracle; the derived MethodTable, its base type, its interface and a virtual
+slot reaching the overridden method matched the linker map; and pseudocode was
+readable. No CI lane repeats this check.
--- a/Show More
+++ b/Show More