[GH-ISSUE #1017] docs: simplify the English README while preserving its opening #374

New issue

Closed

opened 2026-10-15 18:24:24 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:24:24 +00:00

Owner

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

Originally assigned to: @N0zoM1z0 on GitHub.

The English README has grown into a combination of a product introduction, setup guide, troubleshooting manual, capability catalog and runtime/architecture reference. Readers encounter 255 lines of Quick start material before the first copyable agent prompt.

This issue records a proposed restructuring for maintainer review. No README changes are approved or implemented yet. Preserve the opening product copy and its recognizable presentation.

Reviewed baseline: README at 5b172b1, 8 October 2026. English only; translations were not reviewed.

Findings

The file has 827 lines, approximately 6,833 words and 28 fenced code blocks. Counts include commands, links and markup.
Quick start, lines 56–310: approximately 2,264 words. It includes diagnosis, provider error fields, prerequisites, Linux troubleshooting, Ghidra/IDA profiles, uninstall, Evidence commands and snapshots. The agent prompt begins at line 315.
Current status, lines 421–517: approximately 1,071 words. Capabilities are mixed with API names, coverage limitations, release differences, capture ownership and Inspector semantics.
Setup-selection defaults are repeated at lines 66, 84, 545 and 795. Global npm installation is repeated at lines 147 and 630. The two Notes feature prompts serve the same introductory purpose.
The investigation model, Why REA, One prompt, What agents can do and Current status repeatedly explain the same analysis-to-reconstruction benefit.
Provider and privacy details recur across Requirements, provider sections, Current status, CLI, Security model and FAQ.
ASAR integrity, lines 731–739, is under Process capture, although it describes static artifact inspection. Linux troubleshooting also contains macOS installation instructions.
The showcase section links only DX-Ball's repository documentation. The website now provides direct worked DX-Ball, Notion and TH04 explanations.

Wording to simplify

Examples include:

“It does not claim to recover original source code or automatically clone an application.” (341)
“without claiming causality from correlation” (459)
The Inspector paragraph's list of five things it does not establish (500–516).
Repeated statements that reinstalling or changing permissions cannot enable an unsupported workflow.
Generic transitions such as “for richer context” and “a clear path from that request to working code.”

Describe the action, result or prerequisite directly. Preserve meaningful coverage and execution facts in their proper guides: setup approval, native-engine requirements, experimental Windows scope, target execution with user permissions, unresolved evidence, and the agent's role in writing/testing reconstruction.

Proposed structure

Existing opening, unchanged: name, tagline, popular feature-recreation language, badges, image/community and website links.
Quick start: a copyable setup command, choose/review/restart, one agent prompt and one optional direct CLI result.
Compact target/prerequisite overview with links to the relevant guides.
Short DX-Ball, Notion and TH04 showcase entries linking to the website and credited project sources.
Further guides/troubleshooting; optionally a small collapsed manual MCP block or a few concise FAQ answers.
Contribution, security-reporting, license and star-history links.

Approximately 180–240 lines / 1,000–1,500 words is a possible layout target, including the opening. This is an estimate, not a drafted replacement or a required quota.

Preserve the reference material

Reuse existing installation, provider, browser, Inspector, managed, Android, firmware, process and reconstruction guides.
Fill the readiness-documentation gap first: docs/installation.md currently links back to the README readiness heading at line 113. Move the complete scoped-doctor guidance and repair that backlink before removing the section.
A complete general CLI/Evidence reference is still needed for exit statuses, snapshots, reference-source imports and import/export commands; do not replace these with nonexistent guide links.
Move ASAR integrity into artifact/JavaScript documentation. Preserve mismatch and missing-companion semantics.
Consolidate roadmap work in docs/roadmap.md, and keep architecture and verification implementation details in contributor documentation.
Repair anchors, the tool-catalog badge and documentation backlinks; preserve release-please version markers around versioned MCP JSON.

Decisions before implementation

Choose the compact entry-page structure or a longer reference-oriented README.
Choose whether to retain one brief investigation visual.
Choose whether manual MCP JSON stays as a collapsed block or moves to installation.
Choose whether a few FAQ answers remain.
Decide the length of the lawful-use footer independently of technical simplification.
Approve the English-only rewrite and reference-content migration before making changes.

Opening copy remains protected. Website content, translations, source contracts and generated catalog files are outside this review's editing scope.

Originally created by @N0zoM1z0 on GitHub (Oct 7, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1017 Originally assigned to: @N0zoM1z0 on GitHub. The English README has grown into a combination of a product introduction, setup guide, troubleshooting manual, capability catalog and runtime/architecture reference. Readers encounter 255 lines of Quick start material before the first copyable agent prompt. This issue records a proposed restructuring for maintainer review. **No README changes are approved or implemented yet.** Preserve the opening product copy and its recognizable presentation. Reviewed baseline: [README at `5b172b1`](https://github.com/morluto/rea/blob/5b172b1042fc09a4e12d956018f15d86cf397ffe/README.md), 8 October 2026. English only; translations were not reviewed. ## Findings - The file has **827 lines, approximately 6,833 words and 28 fenced code blocks**. Counts include commands, links and markup. - **Quick start, lines 56–310:** approximately 2,264 words. It includes diagnosis, provider error fields, prerequisites, Linux troubleshooting, Ghidra/IDA profiles, uninstall, Evidence commands and snapshots. The agent prompt begins at line 315. - **Current status, lines 421–517:** approximately 1,071 words. Capabilities are mixed with API names, coverage limitations, release differences, capture ownership and Inspector semantics. - Setup-selection defaults are repeated at lines **66, 84, 545 and 795**. Global npm installation is repeated at lines **147 and 630**. The two Notes feature prompts serve the same introductory purpose. - The investigation model, Why REA, One prompt, What agents can do and Current status repeatedly explain the same analysis-to-reconstruction benefit. - Provider and privacy details recur across Requirements, provider sections, Current status, CLI, Security model and FAQ. - **ASAR integrity, lines 731–739, is under Process capture**, although it describes static artifact inspection. Linux troubleshooting also contains macOS installation instructions. - The showcase section links only DX-Ball's repository documentation. The website now provides direct worked DX-Ball, Notion and TH04 explanations. ## Wording to simplify Examples include: - “It does not claim to recover original source code or automatically clone an application.” (341) - “without claiming causality from correlation” (459) - The Inspector paragraph's list of five things it does not establish (500–516). - Repeated statements that reinstalling or changing permissions cannot enable an unsupported workflow. - Generic transitions such as “for richer context” and “a clear path from that request to working code.” Describe the action, result or prerequisite directly. Preserve meaningful coverage and execution facts in their proper guides: setup approval, native-engine requirements, experimental Windows scope, target execution with user permissions, unresolved evidence, and the agent's role in writing/testing reconstruction. ## Proposed structure 1. Existing opening, unchanged: name, tagline, popular feature-recreation language, badges, image/community and website links. 2. Quick start: a copyable setup command, choose/review/restart, one agent prompt and one optional direct CLI result. 3. Compact target/prerequisite overview with links to the relevant guides. 4. Short DX-Ball, Notion and TH04 showcase entries linking to the website and credited project sources. 5. Further guides/troubleshooting; optionally a small collapsed manual MCP block or a few concise FAQ answers. 6. Contribution, security-reporting, license and star-history links. Approximately **180–240 lines / 1,000–1,500 words** is a possible layout target, including the opening. This is an estimate, not a drafted replacement or a required quota. ## Preserve the reference material - Reuse existing installation, provider, browser, Inspector, managed, Android, firmware, process and reconstruction guides. - **Fill the readiness-documentation gap first:** `docs/installation.md` currently links back to the README readiness heading at line 113. Move the complete scoped-doctor guidance and repair that backlink before removing the section. - A complete general CLI/Evidence reference is still needed for exit statuses, snapshots, reference-source imports and import/export commands; do not replace these with nonexistent guide links. - Move ASAR integrity into artifact/JavaScript documentation. Preserve mismatch and missing-companion semantics. - Consolidate roadmap work in `docs/roadmap.md`, and keep architecture and verification implementation details in contributor documentation. - Repair anchors, the tool-catalog badge and documentation backlinks; preserve release-please version markers around versioned MCP JSON. ## Decisions before implementation - [ ] Choose the compact entry-page structure or a longer reference-oriented README. - [ ] Choose whether to retain one brief investigation visual. - [ ] Choose whether manual MCP JSON stays as a collapsed block or moves to installation. - [ ] Choose whether a few FAQ answers remain. - [ ] Decide the length of the lawful-use footer independently of technical simplification. - [ ] Approve the English-only rewrite and reference-content migration before making changes. Opening copy remains protected. Website content, translations, source contracts and generated catalog files are outside this review's editing scope.

bsakaguchi

2026-10-15 18:24:24 +00:00