[GH-ISSUE #2156] docs: correct documentation drift and simplify English guides #708

Open
opened 2026-10-15 18:27:34 +00:00 by bsakaguchi · 1 comment
Owner

Originally created by @N0zoM1z0 on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2156

Goal

Make the English documentation accurate and straightforward for humans and agents. Remove repeated explanations and material that does not help readers complete a task or interpret its result. Keep the inputs, provenance, uncertainty, limits, and recovery steps that affect those decisions.

Review scope and verification

Reviewed 86 tracked REA-authored English Markdown documents, excluding website/ and translated READMEs. Read 85 current prose documents in detail; the historical changelog received a full structural scan, detailed review of the latest entry, and older-entry sampling.

The reviewed main baseline is 672bdea21fd943688e081d209a993e234c45507f (package version 6.4.0). Real CLI/MCP probes used fresh source builds at c22111eca2c4bc84a084f12711f405b3e7422a40 and 672bdea. D02, D03, D04, D07, and D08 were repeated at 672bdea; the other runtime findings below are from c22111e, with their current documentation and source checked at 672bdea. These observations do not establish the contents of the npm release.

Real tools used: Ghidra 12.1.4, Hopper 6.4.2, Chrome for Testing 153.0.8010.12, the HAR decoder, and pwntools 4.15.0. Isolated Codex CLI 0.161.0 completed three actual REA MCP calls at c22111e. No full test suite or complete provider/platform matrix ran.

The 21 records comprise 9 runtime-backed findings, 2 repository defects, and 10 clarifications or candidates with limited verification. Some findings are missing explanations rather than false claims. Each link below is pinned to the reviewed main baseline. Analysis is complete; repository edits are deferred.

Accuracy: runtime-backed findings

ID / documentation Correction and observed behavior
D01 — NativeAOT skill reference Replace the claim that the extension is absent from the headless bridge. The optional Linux headless adapter exists; a real x64 symbols fixture recovered 1,528 MethodTables and passed independent type/slot and pseudocode checks. Distinguish this route from the built-in PE/RTR snapshot parser described in the NativeAOT guide. This establishes neither original C# recovery nor Windows verification.
D02 — MCP cancellation Explain new partial Evidence separately from an incomplete success result. After one JS file completed, cancellation retained a new partial record alongside earlier Evidence; its summary was readable and a subsequent analysis succeeded. The producer retains completed facts. Document same-connection recovery when the client has already stopped waiting.
D03 — HAR integration README Remove the old claim that __proto__ members are unsupported. Actual CLI/MCP results preserve own __proto__, constructor, and prototype keys; duplicate keys are rejected. Limit this statement to the verified HAR/JSON boundary; XML keyed-archive behavior differs.
D04 — Prompt completion State that document/procedure completion in a binary session reads an already-ready provider. A cold Ghidra session returned no candidates; after binary_overview, it returned 0x1000 and entry. An empty list need not mean the target has no functions. Starting/transition races were source-reviewed rather than exhaustively executed.
D05 — Browser limits Reconcile the “no internal byte quota” sentence with the same page's 64 MiB WebSocket message limit. A real DOM containing 68 MiB of text hit payload_limit with a 67,108,864-byte budget; the page remained alive. Describe waiting behavior and payload capacity separately.
D07 — Load-image verification scope Replace global MZ-only/MZ-and-COM descriptions with the admitted MZ, explicit COM, and explicit raw-binary interpretations. Real Linux raw and COM imports returned verified with unchanged source hashes. Synchronize the source-owned capability limitation with the attestation implementation; preserve the unsupported PE attestation status and Windows admission scope.
D08 — DOS coverage boundary Clarify the sentence excluding raw COM, which conflicts with the guide's explicit COM route. A real 64-byte COM import verified at entry 0x10100, with measured CS/DS/ES/SS 0x1000. Keep explicit interpretation requirements, absence of automatic COM guessing, and DOS extender restrictions clear.
D16 — Large binary diagnostics results Configure both server REA_MCP_MAX_RESPONSE_BYTES and client maxBufferSize, as the MCP reference already explains. A valid 65,281-section ELF failed with only the client buffer increased; increasing both allowed complete delivery. CLI output was 22,834,956 bytes. Explain retained summary/view/export recovery and separate delivery budgets from decoder limits.
Q01 — Native type inspection Explain total_fields and truncated. A real 20,005-field struct returned 20,000 fields, total_fields: 20005, and truncated: true. The bridge also caps enum serialization at 20,000 members; the enum case was source-reviewed only. The current guide omits completeness guidance rather than promising unlimited output.

Accuracy: repository defects

  • D09: CLI catalog link targets absent docs/product-catalog.json. The generated file is ignored docs/public/product-catalog.json. Link to the tracked generated-catalog explanation and its generation/deployment entry; preserve generated-file ownership. This is a source/GitHub link defect; deployed website asset behavior was not tested.
  • D10: Android fixture instructions name removed scripts/fetch-android-fixtures.mjs. Executing that path exits with MODULE_NOT_FOUND. Use npm run fixtures:android, which resolves to scripts/fixtures/android/fetch.mjs. No Android fixture download or JADX verification was performed.

Claims that need narrower wording or further verification

  • D06 — Hopper lifecycle: Installation says closing a session leaves the document open; the later lifecycle section says close/switch closes it. Distinguish explicit close from the server-shutdown retention option. Real Linux close/disconnect succeeded; attached macOS GUI behavior remains source-reviewed.
  • D11 — Windows operation count: Conformance README says 19 operations; the canonical inventory has 25 after excluding three mutations. The real inventory check was on Linux. Update or derive the count without presenting it as a completed Windows run.
  • D12 — Transport and budgets: Security policy makes universal Unix-socket/message-bound statements. Scope them by REA-owned versus external bridges, POSIX versus Windows transport, and bridge versus MCP delivery limits. Windows/IDA/JEB behavior and a giant Ghidra bridge reply were not executed here.
  • D13 — Active Electron reconciliation: Reconciliation guide omits the active producer accepted by the parser. A real Electron 44.7.0 capture returned cleanup_incomplete before successful producer Evidence was available. Keep this as a source-backed candidate pending real successful reconciliation; document its narrower target-only projection if confirmed.
  • D14 — Host schema forwarding: MCP reference says all hosts forward schemas on every request, while installation describes deferred discovery. Use conditional wording tied to client configuration. Passing Codex calls does not establish every host's model payload.
  • D15 — ADB restrictions: ADB guide can be read as banning all am operations, although the same guide documents specific lifecycle actions. Clarify allowed lifecycle operations versus arbitrary shell/UI automation. This is wording ambiguity; no device run was possible because adb was absent.
  • Q02: Managed host scope should distinguish current admission/support policy from hosts actually verified. Portable source registration alone does not prove Windows compatibility.
  • Q03: Ghidra notice row should distinguish checked version 12.1.4 from accepted 12.1.x. Preserve original license and attribution text.
  • Q04: Raw-binary and firmware limits need named workflow scope and links to existing DLL/MIPS/raw routes. Those Windows/MIPS lanes were not run during this audit.
  • Q05: Synchronous parsing caveat should distinguish synchronous work inside the analyzer from the parent's ability to terminate that worker. Both can be true; this is a process-scope clarification.

Refactoring priorities

  1. Installation: Put install/setup, planned changes and approval, provider configuration, doctor, update, and uninstall in a readable main flow. Put client-specific troubleshooting behind clear headings or links. Keep native analysis contracts in their canonical investigation references.
  2. Testing: Put common developer commands first, followed by a lane matrix covering command, host/tools, coverage, and skip/failure behavior. Move long dated verification narratives out of the command entry. Preserve the distinction between simulated boundaries and real-provider runs.
  3. MCP contracts: Lead with success/error replies, inline/retained Evidence, session lifecycle, availability, cancellation, and budgets. Keep precise schema details available. Place client-specific workarounds with installation/troubleshooting.
  4. Investigation guides: Give native analysis a clear general entry. Order JS guidance around target selection, analysis, views, comparison/trace, partial recovery, and runtime follow-up. Move resolver/recognizer micro-rules and allocation algorithms to references. Replace unanchored “milestone/increment/earlier” prose with current workflow scope.
  5. Examples and navigation: Provide working producer-to-consumer Evidence recipes; label placeholders as shapes. Use one complete example plus a differences table for repeated JSON records. Index guide families by task and distinguish user guides from development/conformance references.
  6. Shared rules and maintenance: Give each contract one complete explanation and link other guides/agent references to it with necessary local reminders. Consolidate repeated PR-template prompts. Preserve authority rules, the managed Turborepo block, provenance, partial/unknown states, cleanup semantics, and real limits. Keep historical release claims tied to their release; preserve original legal text.

Implementation and acceptance

  • Correct the runtime-backed findings and repository defects; synchronize affected skill references and source-owned descriptive metadata.
  • Resolve each qualified record with appropriately scoped wording or a documented verification prerequisite.
  • Assign canonical owners before reorganizing the long guides, then rewrite around reader tasks. Every main guide should expose its question, inputs, working example, result interpretation, decision-relevant limits, and recovery.
  • Remove repeated meaning and irrelevant detail while preserving information needed for correct calls and result interpretation. Do not use a uniform word-count target.
  • Check changed commands/JSON recipes, links/anchors, contract names, generated ownership, and relevant documentation checks during implementation. Record real-provider verification by artifact, host, and version; do not expand support claims from prose changes.

Related: #2141 tracks the separately approved, deferred translation-directory migration; #1017 previously tracked root English README simplification; #778 tracks reproducible demos; #2076 is the related completion implementation report; #744 tracks NativeAOT product requests. This issue tracks the English documentation audit and refactoring findings.

Originally created by @N0zoM1z0 on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2156 ## Goal Make the English documentation accurate and straightforward for humans and agents. Remove repeated explanations and material that does not help readers complete a task or interpret its result. Keep the inputs, provenance, uncertainty, limits, and recovery steps that affect those decisions. ## Review scope and verification Reviewed 86 tracked REA-authored English Markdown documents, excluding `website/` and translated READMEs. Read 85 current prose documents in detail; the historical changelog received a full structural scan, detailed review of the latest entry, and older-entry sampling. The reviewed main baseline is `672bdea21fd943688e081d209a993e234c45507f` (package version 6.4.0). Real CLI/MCP probes used fresh source builds at `c22111eca2c4bc84a084f12711f405b3e7422a40` and `672bdea`. D02, D03, D04, D07, and D08 were repeated at `672bdea`; the other runtime findings below are from `c22111e`, with their current documentation and source checked at `672bdea`. These observations do not establish the contents of the npm release. Real tools used: Ghidra 12.1.4, Hopper 6.4.2, Chrome for Testing 153.0.8010.12, the HAR decoder, and pwntools 4.15.0. Isolated Codex CLI 0.161.0 completed three actual REA MCP calls at `c22111e`. No full test suite or complete provider/platform matrix ran. The 21 records comprise **9 runtime-backed findings, 2 repository defects, and 10 clarifications or candidates with limited verification**. Some findings are missing explanations rather than false claims. Each link below is pinned to the reviewed main baseline. Analysis is complete; repository edits are deferred. ## Accuracy: runtime-backed findings | ID / documentation | Correction and observed behavior | | --- | --- | | D01 — [NativeAOT skill reference](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md#L124-L132) | Replace the claim that the extension is absent from the headless bridge. The optional Linux headless adapter exists; a real x64 symbols fixture recovered 1,528 MethodTables and passed independent type/slot and pseudocode checks. Distinguish this route from the built-in PE/RTR snapshot parser described in the [NativeAOT guide](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/ghidra-nativeaot.md#L3-L24). This establishes neither original C# recovery nor Windows verification. | | D02 — [MCP cancellation](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/mcp-contracts.md#L214-L224) | Explain new partial Evidence separately from an incomplete success result. After one JS file completed, cancellation retained a new partial record alongside earlier Evidence; its summary was readable and a subsequent analysis succeeded. The [producer](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/src/application/javascript/JavaScriptArtifactReconstruction.ts#L270-L291) retains completed facts. Document same-connection recovery when the client has already stopped waiting. | | D03 — [HAR integration README](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/third_party/web-network-captures/README.md#L33-L36) | Remove the old claim that `__proto__` members are unsupported. Actual CLI/MCP results preserve own `__proto__`, `constructor`, and `prototype` keys; duplicate keys are rejected. Limit this statement to the verified HAR/JSON boundary; XML keyed-archive behavior differs. | | D04 — [Prompt completion](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/mcp-prompts.md#L92-L118) | State that document/procedure completion in a binary session reads an already-ready provider. A cold Ghidra session returned no candidates; after `binary_overview`, it returned `0x1000` and `entry`. An empty list need not mean the target has no functions. Starting/transition races were source-reviewed rather than exhaustively executed. | | D05 — [Browser limits](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/browser-observation.md#L194-L198) | Reconcile the “no internal byte quota” sentence with the same page's [64 MiB WebSocket message limit](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/browser-observation.md#L85-L90). A real DOM containing 68 MiB of text hit `payload_limit` with a 67,108,864-byte budget; the page remained alive. Describe waiting behavior and payload capacity separately. | | D07 — [Load-image verification scope](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/windows-ghidra-p0.md#L23-L27) | Replace global MZ-only/MZ-and-COM descriptions with the admitted MZ, explicit COM, and explicit raw-binary interpretations. Real Linux raw and COM imports returned `verified` with unchanged source hashes. Synchronize the source-owned [capability limitation](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/src/ghidra/GhidraProviderCapabilities.ts#L82-L87) with the [attestation implementation](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/src/ghidra/GhidraLoadImageAttest.ts#L99-L141); preserve the unsupported PE attestation status and Windows admission scope. | | D08 — [DOS coverage boundary](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/ghidra-dos.md#L150-L156) | Clarify the sentence excluding raw COM, which conflicts with the guide's explicit COM route. A real 64-byte COM import verified at entry `0x10100`, with measured CS/DS/ES/SS `0x1000`. Keep explicit interpretation requirements, absence of automatic COM guessing, and DOS extender restrictions clear. | | D16 — [Large binary diagnostics results](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/binary-diagnostics.md#L100-L110) | Configure both server `REA_MCP_MAX_RESPONSE_BYTES` and client `maxBufferSize`, as the [MCP reference](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/mcp-contracts.md#L405-L410) already explains. A valid 65,281-section ELF failed with only the client buffer increased; increasing both allowed complete delivery. CLI output was 22,834,956 bytes. Explain retained summary/view/export recovery and separate delivery budgets from decoder limits. | | Q01 — [Native type inspection](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/native-investigation.md#L267-L273) | Explain `total_fields` and `truncated`. A real 20,005-field struct returned 20,000 fields, `total_fields: 20005`, and `truncated: true`. The [bridge](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/bridge/ghidra/ReaGhidraBridge.java#L831-L880) also caps enum serialization at 20,000 members; the enum case was source-reviewed only. The current guide omits completeness guidance rather than promising unlimited output. | ## Accuracy: repository defects - **D09:** [CLI catalog link](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/cli.md#L95-L99) targets absent `docs/product-catalog.json`. The generated file is ignored `docs/public/product-catalog.json`. Link to the tracked generated-catalog explanation and its generation/deployment entry; preserve generated-file ownership. This is a source/GitHub link defect; deployed website asset behavior was not tested. - **D10:** [Android fixture instructions](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/third_party/README.md#L35-L40) name removed `scripts/fetch-android-fixtures.mjs`. Executing that path exits with `MODULE_NOT_FOUND`. Use `npm run fixtures:android`, which resolves to `scripts/fixtures/android/fetch.mjs`. No Android fixture download or JADX verification was performed. ## Claims that need narrower wording or further verification - **D06 — Hopper lifecycle:** [Installation](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/installation.md#L535-L543) says closing a session leaves the document open; the [later lifecycle section](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/installation.md#L677-L690) says close/switch closes it. Distinguish explicit close from the [server-shutdown retention option](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/src/main/shutdown.ts#L33-L36). Real Linux close/disconnect succeeded; attached macOS GUI behavior remains source-reviewed. - **D11 — Windows operation count:** [Conformance README](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/tests/conformance/README.md#L18-L22) says 19 operations; the canonical inventory has 25 after excluding three mutations. The real inventory check was on Linux. Update or derive the count without presenting it as a completed Windows run. - **D12 — Transport and budgets:** [Security policy](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/SECURITY.md#L25-L38) makes universal Unix-socket/message-bound statements. Scope them by REA-owned versus external bridges, POSIX versus Windows transport, and bridge versus MCP delivery limits. Windows/IDA/JEB behavior and a giant Ghidra bridge reply were not executed here. - **D13 — Active Electron reconciliation:** [Reconciliation guide](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/javascript-runtime-reconciliation.md#L3-L15) omits the active producer accepted by the [parser](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/src/domain/javascript/javascriptRuntimeReconciliationCaptureParsing.ts#L150-L155). A real Electron 44.7.0 capture returned `cleanup_incomplete` before successful producer Evidence was available. Keep this as a source-backed candidate pending real successful reconciliation; document its narrower target-only projection if confirmed. - **D14 — Host schema forwarding:** [MCP reference](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/mcp-contracts.md#L27-L35) says all hosts forward schemas on every request, while installation describes deferred discovery. Use conditional wording tied to client configuration. Passing Codex calls does not establish every host's model payload. - **D15 — ADB restrictions:** [ADB guide](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/adb-device-analysis.md#L138-L140) can be read as banning all `am` operations, although the same guide documents specific lifecycle actions. Clarify allowed lifecycle operations versus arbitrary shell/UI automation. This is wording ambiguity; no device run was possible because `adb` was absent. - **Q02:** [Managed host scope](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/managed-code-analysis.md#L298-L303) should distinguish current admission/support policy from hosts actually verified. Portable source registration alone does not prove Windows compatibility. - **Q03:** [Ghidra notice row](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/THIRD_PARTY_NOTICES.md#L50) should distinguish checked version 12.1.4 from accepted 12.1.x. Preserve original license and attribution text. - **Q04:** [Raw-binary](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/raw-binary.md#L63-L64) and [firmware](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/firmware-analysis.md#L125-L128) limits need named workflow scope and links to existing DLL/MIPS/raw routes. Those Windows/MIPS lanes were not run during this audit. - **Q05:** [Synchronous parsing caveat](https://github.com/morluto/rea/blob/672bdea21fd943688e081d209a993e234c45507f/docs/javascript-artifact-reconstruction.md#L509-L512) should distinguish synchronous work inside the analyzer from the parent's ability to terminate that worker. Both can be true; this is a process-scope clarification. ## Refactoring priorities 1. **Installation:** Put install/setup, planned changes and approval, provider configuration, doctor, update, and uninstall in a readable main flow. Put client-specific troubleshooting behind clear headings or links. Keep native analysis contracts in their canonical investigation references. 2. **Testing:** Put common developer commands first, followed by a lane matrix covering command, host/tools, coverage, and skip/failure behavior. Move long dated verification narratives out of the command entry. Preserve the distinction between simulated boundaries and real-provider runs. 3. **MCP contracts:** Lead with success/error replies, inline/retained Evidence, session lifecycle, availability, cancellation, and budgets. Keep precise schema details available. Place client-specific workarounds with installation/troubleshooting. 4. **Investigation guides:** Give native analysis a clear general entry. Order JS guidance around target selection, analysis, views, comparison/trace, partial recovery, and runtime follow-up. Move resolver/recognizer micro-rules and allocation algorithms to references. Replace unanchored “milestone/increment/earlier” prose with current workflow scope. 5. **Examples and navigation:** Provide working producer-to-consumer Evidence recipes; label placeholders as shapes. Use one complete example plus a differences table for repeated JSON records. Index guide families by task and distinguish user guides from development/conformance references. 6. **Shared rules and maintenance:** Give each contract one complete explanation and link other guides/agent references to it with necessary local reminders. Consolidate repeated PR-template prompts. Preserve authority rules, the managed Turborepo block, provenance, partial/unknown states, cleanup semantics, and real limits. Keep historical release claims tied to their release; preserve original legal text. ## Implementation and acceptance - [ ] Correct the runtime-backed findings and repository defects; synchronize affected skill references and source-owned descriptive metadata. - [ ] Resolve each qualified record with appropriately scoped wording or a documented verification prerequisite. - [ ] Assign canonical owners before reorganizing the long guides, then rewrite around reader tasks. Every main guide should expose its question, inputs, working example, result interpretation, decision-relevant limits, and recovery. - [ ] Remove repeated meaning and irrelevant detail while preserving information needed for correct calls and result interpretation. Do not use a uniform word-count target. - [ ] Check changed commands/JSON recipes, links/anchors, contract names, generated ownership, and relevant documentation checks during implementation. Record real-provider verification by artifact, host, and version; do not expand support claims from prose changes. Related: #2141 tracks the separately approved, deferred translation-directory migration; #1017 previously tracked root English README simplification; #778 tracks reproducible demos; #2076 is the related completion implementation report; #744 tracks NativeAOT product requests. This issue tracks the English documentation audit and refactoring findings.
Author
Owner

@CassieFox23 commented on GitHub (Nov 3, 2026):

TL;DR: At main (c3647ade1), the docs read as settled for 16 of the 21 records, partly settled for 4, and still open for 1. 7ae3c50a9d (#2207) settled 12 of the 16, and later commits settled the other 4. I read the docs and source text only and ran nothing, so "settled" means the docs now say it, not that the tool does it.

Not settled at main

Record At main What the docs say now Commit
D06, Hopper lifecycle partly installation.md:740-741 says that on macOS, closing the owning REA session releases the guard and Hopper keeps its document open. installation.md:1015-1017 says closing or switching a target closes its bound Hopper document, the macOS Hopper app and other documents stay open, and the Linux demo app stops. Shutdown retention is named in mcp-contracts.md:1062-1063 ("retaining provider documents") and in src/main/shutdown.ts:44 and :79 (retainProviderDocuments: true), not in installation.md. Wording only, behavior not rechecked. macOS and Linux scoping: c105391db5 (#2499)
D10, Android fixture partly third_party/README.md:37 now says npm run fixtures:android (scripts/fixtures/android/fetch.mjs). package.json:250 has that script and the file is in the tree. The removed scripts/fetch-android-fixtures.mjs is no longer named. The same paragraph, README.md:40, names scripts/fixtures/android-apidemos.json; the tree has scripts/fixtures/android/apidemos.json. The record did not name this path, and it reads the same at 672bdea21. fetch line: 7ae3c50a9d (#2207)
D12, transport and budgets partly SECURITY.md:27-30 now names the Hopper and Ghidra bridges and splits POSIX Unix sockets from Windows loopback TCP. SECURITY.md:40 still says REA "bounds startup and protocol messages" with no scoping. The file has no IDA or JEB line and no split between bridge limits and MCP delivery limits. transport split: a86deecac5 (#2478)
Q04, raw-binary and firmware limits partly raw-binary.md:84-86 names the admitted scope (native PE applications and DLLs, explicitly selected raw 6502) and has no link to the DLL route there. firmware-analysis.md:199-201 links the MIPS ELF and RISC-V ELF lanes, and lines 7 and 200 still say "milestone". raw-binary: 9c14999efd (#2079); firmware: 0baad58e60 (#2151)
Q05, synchronous parsing open javascript-artifact-reconstruction.md:735-737 ("synchronous Babel and JSON parser calls cannot be preempted mid-call") and :755-756 ("The owned analyzer can be stopped while its synchronous parser or semantic extractor is active") both stand. They read the same as at 672bdea21 (:509-512 and :138-139). 7ae3c50a9d (#2207) moved them and changed no words. none

Not run

  • No tool, build, test or link check ran. Every "settled" is about what the docs say.
  • I did not recheck the behavior behind any settled record. That includes the real Electron run in D13.
  • The deployed site and /rea/product-catalog.json were not fetched.
  • Windows, macOS GUI, ADB and the npm release contents were not looked at.
  • The commit messages' own test claims were not checked against logs.

Thanks, N0zoM1z0, for the audit.

Settled records (16), with the file and line at main
Record Where the docs now say it Commit
D01 skill reference native-and-artifacts.md:551-560: the built-in PE/RTR snapshot parser and the optional headless Ghidra adapter are "separate routes"; the adapter adds annotations "on Linux" and needs a NativeAOT JAR; recovered types are "not original C# source". The old "not currently part of ... headless Ghidra bridge" sentence is gone. 7ae3c50a9d (#2207)
D02 mcp-contracts.md:1215-1221: cancellation returns cancelled; completed facts can be kept as new partial Evidence; read partial_observation on the same connection, or find the record with get_evidence_bundle summary. 7ae3c50a9d (#2207)
D03 third_party/web-network-captures/README.md:35-37: own __proto__, constructor and prototype members are kept and do not make a capture unsupported. Scoped to "the shared JSON representation". 7ae3c50a9d (#2207)
D04 mcp-prompts.md:154-158: completion reads an already-ready provider, a cold provider can return nothing, and an empty list does not show the target has no procedures. 7ae3c50a9d (#2207)
D05 browser-observation.md:264-265 and :603-619: waiting behavior and the 64 MiB message limit (payload_limit) are stated apart. The "no internal byte quota" sentence is gone. 7ae3c50a9d (#2207)
D07 windows-ghidra-p0.md:25-30: PE attestation stays unsupported; verification covers admitted DOS MZ, explicit COM, raw-binary and GameCube DOL images; Windows admission is unchanged. The capability note (GhidraProviderCapabilities.ts:89) and the attestation check (GhidraLoadImageAttest.ts:97) now read one list in GhidraVerifiedLoadImageFormats.ts. 7ae3c50a9d (#2207); list: 250dc81cd6 (#7484)
D08 ghidra-dos.md:173-176: headerless COM needs the explicit interpretation, REA does not guess it, DOS extenders without an admitted MZ entry stay outside. 7ae3c50a9d (#2207)
D09 cli.md:504 links mcp-contracts.md#generated-catalog. That section (:1933-1944) names docs/public/product-catalog.json, npm run docs:generate and "not checked-in snapshots". docs/product-catalog.json is not in the tree. Deployed site not tested. 7ae3c50a9d (#2207)
D11 tests/conformance/README.md:21 says "the admitted read-only operation inventory", with no count. 7ae3c50a9d (#2207)
D13 javascript-runtime-reconciliation.md:11-18 lists capture_electron_scenario and calls it target-only partial observations. The parser accepts it at src/domain/javascript/javascriptRuntimeReconciliationCaptureParsing.ts:155-157. Whether a real successful reconciliation has run since: not checked. a86deecac5 (#2478)
D14 mcp-contracts.md:1608 now reads "When a host forwards input schemas to the model". client-configuration.md:202-207 ties "every request" to Claude Code with tool search off. 7ae3c50a9d (#2207)
D15 adb-device-analysis.md:218-220: no arbitrary shell command, input or monkey; the lifecycle tools use am start -W and am force-stop. a86deecac5 (#2478)
D16 binary-diagnostics.md:126-130 names both client maxBufferSize and server REA_MCP_MAX_RESPONSE_BYTES and says they affect delivery, not decoder limits. Retained summary and views are at :102-120. Export-bundle recovery is in the linked mcp-contracts.md Tool results section, not repeated. 7ae3c50a9d (#2207)
Q01 native-investigation.md:265-268: at most 20,000 fields or enum members; check total_fields and truncated. 7ae3c50a9d (#2207)
Q02 managed-code-analysis.md:829-835: Windows oracle jobs "do not establish" host verification of the managed workflow; the Windows Ghidra boundary has its own scope. 08e8a568f8
Q03 THIRD_PARTY_NOTICES.md:59: "Bring your own Ghidra; see supported versions", with the 12.1.4 license copies kept. installation.md:1079 and :1088 give "12.x (>=12.1)" and "verified with Ghidra 12.1.4". 0d849b1ae8
Refactoring priorities and acceptance boxes at main

Priorities, judged by reading headings and text:

# At main What I read
1 In installation.md runs Start setup (:15), Review setup changes (:36), Check readiness (:363), then Diagnose, update, and remove (:443). Client sections moved to client-configuration.md, in 7ae3c50a9d (#2207).
2 Partly The developer commands table comes first (testing.md:14-34). Dated records moved to client-verification.md, in 7ae3c50a9d (#2207). Lane detail moved to testing-lanes.md, in 0354145a2a. I did not check the lane tables for host, coverage and skip columns.
3 In, by heading order mcp-contracts.md opens with Tool results (:14) and retained Evidence (:526). Generated catalog moved from first to last (:1933). Cancellation is at :1162.
4 Partly native-investigation.md opens with "Start with a function" (:22). The JS guide runs Public workflow, Select sources, Read the analysis, Large results, Recover partial analysis. "milestone" or "increment" is on 9 lines across the 7 guides I searched, 10 at 672bdea21.
5 Partly index.md has a "Choose a guide" task table (:48) with development guides listed apart, from 7ae3c50a9d (#2207). I did not read for producer-to-consumer recipes.
6 Not in, as far as I read .github/pull_request_template.md is 79 lines at 672bdea21 and 137 at main, and 7ae3c50a9d (#2207) did not touch it. A search of AGENTS.md, CONTRIBUTING.md and docs found no "canonical owner" text. I did not judge the one-explanation-per-contract part.

Acceptance boxes:

# At main What I read
1 Largely in Of the 11 records in the runtime-backed and defect groups, 10 read as settled and D10 as partly. The skill reference, SKILL.md, GhidraProviderCapabilities.ts and generatedPackageMetadata.ts are in the file list of 7ae3c50a9d (#2207).
2 Partly Of the 10 qualified records, 6 are settled (D11, D13, D14, D15, Q02, Q03), 3 partly (D06, D12, Q04) and 1 open (Q05).
3 Not judged I found no owner list. I did not read whether every main guide has its question, inputs, example, result reading, limits and recovery.
4 Not measurable by reading 7ae3c50a9d (#2207) shows 2,090 insertions and 1,849 deletions over 25 files.
5 Not checked The commit messages list the checks that ran: 56 focused tests, check:fast, docs:check, a VitePress build, link and example checks, real CLI/MCP probes. I read the messages, not the logs.

The other commit is ae412654d5 (#2224). It adds one anchor line to the native guide. It touches none of the 21 records.

Test setup
  • Head / base: c3647ade1e / 672bdea21f (the issue's baseline)
  • Other: nothing was built or run. Text was read from a read-only bare mirror of morluto/rea with git.
Commands

Run with git -C on the mirror, shown without that prefix. Output was read as text.

git show c3647ade1e:<path>
git grep -n '<text>' c3647ade1e -- <path>
git log --format='%h %ad %s' --date=short 672bdea21f..c3647ade1e -- <path>
git log -S'<text>' c3647ade1e -- <path>
git show 7ae3c50a9d --format= -- <paths>
git show ae412654d5 --format=
git diff 672bdea21f c3647ade1e -- docs/javascript-artifact-reconstruction.md
git ls-tree -r c3647ade1e --name-only
gh api -X GET repos/morluto/rea/issues/2156 --jq .body

🤖 Written with Claude Code (Sonnet 5.5, verified by Opus 5.5), posted with my OK 🦊

<!-- gh-comment-id:6616047238 --> @CassieFox23 commented on GitHub (Nov 3, 2026): **TL;DR:** At main (c3647ade1), the docs read as settled for 16 of the 21 records, partly settled for 4, and still open for 1. 7ae3c50a9d (#2207) settled 12 of the 16, and later commits settled the other 4. I read the docs and source text only and ran nothing, so "settled" means the docs now say it, not that the tool does it. ### Not settled at main | Record | At main | What the docs say now | Commit | | --- | --- | --- | --- | | D06, Hopper lifecycle | partly | installation.md:740-741 says that on macOS, closing the owning REA session releases the guard and Hopper keeps its document open. installation.md:1015-1017 says closing or switching a target closes its bound Hopper document, the macOS Hopper app and other documents stay open, and the Linux demo app stops. Shutdown retention is named in mcp-contracts.md:1062-1063 ("retaining provider documents") and in src/main/shutdown.ts:44 and :79 (`retainProviderDocuments: true`), not in installation.md. Wording only, behavior not rechecked. | macOS and Linux scoping: c105391db5 (#2499) | | D10, Android fixture | partly | third_party/README.md:37 now says `npm run fixtures:android` (`scripts/fixtures/android/fetch.mjs`). package.json:250 has that script and the file is in the tree. The removed `scripts/fetch-android-fixtures.mjs` is no longer named. The same paragraph, README.md:40, names `scripts/fixtures/android-apidemos.json`; the tree has `scripts/fixtures/android/apidemos.json`. The record did not name this path, and it reads the same at 672bdea21. | fetch line: 7ae3c50a9d (#2207) | | D12, transport and budgets | partly | SECURITY.md:27-30 now names the Hopper and Ghidra bridges and splits POSIX Unix sockets from Windows loopback TCP. SECURITY.md:40 still says REA "bounds startup and protocol messages" with no scoping. The file has no IDA or JEB line and no split between bridge limits and MCP delivery limits. | transport split: a86deecac5 (#2478) | | Q04, raw-binary and firmware limits | partly | raw-binary.md:84-86 names the admitted scope (native PE applications and DLLs, explicitly selected raw 6502) and has no link to the DLL route there. firmware-analysis.md:199-201 links the MIPS ELF and RISC-V ELF lanes, and lines 7 and 200 still say "milestone". | raw-binary: 9c14999efd (#2079); firmware: 0baad58e60 (#2151) | | Q05, synchronous parsing | open | javascript-artifact-reconstruction.md:735-737 ("synchronous Babel and JSON parser calls cannot be preempted mid-call") and :755-756 ("The owned analyzer can be stopped while its synchronous parser or semantic extractor is active") both stand. They read the same as at 672bdea21 (:509-512 and :138-139). 7ae3c50a9d (#2207) moved them and changed no words. | none | ### Not run - No tool, build, test or link check ran. Every "settled" is about what the docs say. - I did not recheck the behavior behind any settled record. That includes the real Electron run in D13. - The deployed site and `/rea/product-catalog.json` were not fetched. - Windows, macOS GUI, ADB and the npm release contents were not looked at. - The commit messages' own test claims were not checked against logs. Thanks, N0zoM1z0, for the audit. <details> <summary>Settled records (16), with the file and line at main</summary> | Record | Where the docs now say it | Commit | | --- | --- | --- | | D01 | skill reference native-and-artifacts.md:551-560: the built-in PE/RTR snapshot parser and the optional headless Ghidra adapter are "separate routes"; the adapter adds annotations "on Linux" and needs a NativeAOT JAR; recovered types are "not original C# source". The old "not currently part of ... headless Ghidra bridge" sentence is gone. | 7ae3c50a9d (#2207) | | D02 | mcp-contracts.md:1215-1221: cancellation returns `cancelled`; completed facts can be kept as new partial Evidence; read `partial_observation` on the same connection, or find the record with `get_evidence_bundle` summary. | 7ae3c50a9d (#2207) | | D03 | third_party/web-network-captures/README.md:35-37: own `__proto__`, `constructor` and `prototype` members are kept and do not make a capture unsupported. Scoped to "the shared JSON representation". | 7ae3c50a9d (#2207) | | D04 | mcp-prompts.md:154-158: completion reads an already-ready provider, a cold provider can return nothing, and an empty list does not show the target has no procedures. | 7ae3c50a9d (#2207) | | D05 | browser-observation.md:264-265 and :603-619: waiting behavior and the 64 MiB message limit (`payload_limit`) are stated apart. The "no internal byte quota" sentence is gone. | 7ae3c50a9d (#2207) | | D07 | windows-ghidra-p0.md:25-30: PE attestation stays unsupported; verification covers admitted DOS MZ, explicit COM, raw-binary and GameCube DOL images; Windows admission is unchanged. The capability note (GhidraProviderCapabilities.ts:89) and the attestation check (GhidraLoadImageAttest.ts:97) now read one list in GhidraVerifiedLoadImageFormats.ts. | 7ae3c50a9d (#2207); list: 250dc81cd6 (#7484) | | D08 | ghidra-dos.md:173-176: headerless COM needs the explicit interpretation, REA does not guess it, DOS extenders without an admitted MZ entry stay outside. | 7ae3c50a9d (#2207) | | D09 | cli.md:504 links mcp-contracts.md#generated-catalog. That section (:1933-1944) names `docs/public/product-catalog.json`, `npm run docs:generate` and "not checked-in snapshots". `docs/product-catalog.json` is not in the tree. Deployed site not tested. | 7ae3c50a9d (#2207) | | D11 | tests/conformance/README.md:21 says "the admitted read-only operation inventory", with no count. | 7ae3c50a9d (#2207) | | D13 | javascript-runtime-reconciliation.md:11-18 lists `capture_electron_scenario` and calls it target-only partial observations. The parser accepts it at src/domain/javascript/javascriptRuntimeReconciliationCaptureParsing.ts:155-157. Whether a real successful reconciliation has run since: not checked. | a86deecac5 (#2478) | | D14 | mcp-contracts.md:1608 now reads "When a host forwards input schemas to the model". client-configuration.md:202-207 ties "every request" to Claude Code with tool search off. | 7ae3c50a9d (#2207) | | D15 | adb-device-analysis.md:218-220: no arbitrary shell command, `input` or `monkey`; the lifecycle tools use `am start -W` and `am force-stop`. | a86deecac5 (#2478) | | D16 | binary-diagnostics.md:126-130 names both client `maxBufferSize` and server `REA_MCP_MAX_RESPONSE_BYTES` and says they affect delivery, not decoder limits. Retained summary and views are at :102-120. Export-bundle recovery is in the linked mcp-contracts.md Tool results section, not repeated. | 7ae3c50a9d (#2207) | | Q01 | native-investigation.md:265-268: at most 20,000 fields or enum members; check `total_fields` and `truncated`. | 7ae3c50a9d (#2207) | | Q02 | managed-code-analysis.md:829-835: Windows oracle jobs "do not establish" host verification of the managed workflow; the Windows Ghidra boundary has its own scope. | 08e8a568f8 | | Q03 | THIRD_PARTY_NOTICES.md:59: "Bring your own Ghidra; see supported versions", with the 12.1.4 license copies kept. installation.md:1079 and :1088 give "12.x (>=12.1)" and "verified with Ghidra 12.1.4". | 0d849b1ae8 | </details> <details> <summary>Refactoring priorities and acceptance boxes at main</summary> Priorities, judged by reading headings and text: | # | At main | What I read | | --- | --- | --- | | 1 | In | installation.md runs Start setup (:15), Review setup changes (:36), Check readiness (:363), then Diagnose, update, and remove (:443). Client sections moved to client-configuration.md, in 7ae3c50a9d (#2207). | | 2 | Partly | The developer commands table comes first (testing.md:14-34). Dated records moved to client-verification.md, in 7ae3c50a9d (#2207). Lane detail moved to testing-lanes.md, in 0354145a2a. I did not check the lane tables for host, coverage and skip columns. | | 3 | In, by heading order | mcp-contracts.md opens with Tool results (:14) and retained Evidence (:526). Generated catalog moved from first to last (:1933). Cancellation is at :1162. | | 4 | Partly | native-investigation.md opens with "Start with a function" (:22). The JS guide runs Public workflow, Select sources, Read the analysis, Large results, Recover partial analysis. "milestone" or "increment" is on 9 lines across the 7 guides I searched, 10 at 672bdea21. | | 5 | Partly | index.md has a "Choose a guide" task table (:48) with development guides listed apart, from 7ae3c50a9d (#2207). I did not read for producer-to-consumer recipes. | | 6 | Not in, as far as I read | .github/pull_request_template.md is 79 lines at 672bdea21 and 137 at main, and 7ae3c50a9d (#2207) did not touch it. A search of AGENTS.md, CONTRIBUTING.md and docs found no "canonical owner" text. I did not judge the one-explanation-per-contract part. | Acceptance boxes: | # | At main | What I read | | --- | --- | --- | | 1 | Largely in | Of the 11 records in the runtime-backed and defect groups, 10 read as settled and D10 as partly. The skill reference, SKILL.md, GhidraProviderCapabilities.ts and generatedPackageMetadata.ts are in the file list of 7ae3c50a9d (#2207). | | 2 | Partly | Of the 10 qualified records, 6 are settled (D11, D13, D14, D15, Q02, Q03), 3 partly (D06, D12, Q04) and 1 open (Q05). | | 3 | Not judged | I found no owner list. I did not read whether every main guide has its question, inputs, example, result reading, limits and recovery. | | 4 | Not measurable by reading | 7ae3c50a9d (#2207) shows 2,090 insertions and 1,849 deletions over 25 files. | | 5 | Not checked | The commit messages list the checks that ran: 56 focused tests, check:fast, docs:check, a VitePress build, link and example checks, real CLI/MCP probes. I read the messages, not the logs. | The other commit is ae412654d5 (#2224). It adds one anchor line to the native guide. It touches none of the 21 records. </details> <details> <summary>Test setup</summary> - Head / base: c3647ade1e557c4179a8b825a37e0c2193cd2526 / 672bdea21fd943688e081d209a993e234c45507f (the issue's baseline) - Other: nothing was built or run. Text was read from a read-only bare mirror of morluto/rea with git. </details> <details> <summary>Commands</summary> Run with `git -C` on the mirror, shown without that prefix. Output was read as text. ```sh git show c3647ade1e:<path> git grep -n '<text>' c3647ade1e -- <path> git log --format='%h %ad %s' --date=short 672bdea21f..c3647ade1e -- <path> git log -S'<text>' c3647ade1e -- <path> git show 7ae3c50a9d --format= -- <paths> git show ae412654d5 --format= git diff 672bdea21f c3647ade1e -- docs/javascript-artifact-reconstruction.md git ls-tree -r c3647ade1e --name-only gh api -X GET repos/morluto/rea/issues/2156 --jq .body ``` </details> 🤖 Written with Claude Code (Sonnet 5.5, verified by Opus 5.5), posted with my OK 🦊
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#708
No description provided.