[PR #1043] [MERGED] docs: simplify the English README and organize guides #2602

New issue

Closed

opened 2026-10-17 21:08:05 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:08:05 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1043
Author: @N0zoM1z0
Created: 10/8/2026
Status: ✅ Merged
Merged: 10/8/2026
Merged by: @N0zoM1z0

Base: main ← Head: docs/english-readme-cleanup

📝 Commits (7)

ff957c0 docs: simplify the English README
452430b docs: add README workflow and FAQ
f823796 docs: clarify README updates and collapse FAQ
a049060 docs: welcome contributions in the README
352fc59 docs: highlight website guidance before quick start
0d33a6a docs: keep README capability links aligned with main
29d1184 fix(docs): preserve README backlinks and release checks

📊 Changes

12 files changed (+497 additions, -668 deletions)

View changed files

📝 README.md (+154 -658)
📝 docs/.vitepress/config.ts (+1 -0)
➕ docs/cli.md (+184 -0)
📝 docs/installation.md (+78 -1)
📝 docs/javascript-artifact-reconstruction.md (+15 -0)
📝 docs/roadmap.md (+24 -0)
📝 docs/testing.md (+23 -0)
📝 release-please-config.json (+0 -1)
📝 scripts/lib/docs-facts.mjs (+10 -2)
📝 tests/boundary/cli/productCatalog.test.ts (+2 -0)
📝 tests/conformance/readmeConsistency.test.ts (+6 -5)
📝 tests/conformance/releaseConfiguration.test.ts (+0 -1)

📄 Description

Summary

The English README mixed onboarding with provider configuration, diagnostics and lifecycle reference material. It now leads readers through setup, one prompt, a simple investigation figure and worked examples. Reference details live in linked guides.

Fixes #1017. Translation follow-up #958 remains blocked until this English rewrite is merged.

Problem and expected behavior

Readers should find a usable setup command and understand what REA returns without reading a reference manual first. The README is reduced from 835 to 331 source lines, including seven collapsed FAQ answers.

Change and scope

Preserve the opening product copy, screenshot, community links and original Disclaimer. Add the skills.sh badge and a website callout before Quick start.
Include CLI and agent update commands, the existing investigation figure, concise prerequisites, and DX-Ball, Notion and TH04 case-study links. Welcome bug reports, feature requests and contributions.
Move CLI/Evidence details into docs/cli.md, readiness and Hopper troubleshooting into installation, ASAR integrity into artifact reconstruction, and maintenance details into roadmap/testing. Repair the installation guide's README backlink.
Keep compatibility anchors for existing translated README backlinks. Validate supported agent names in installation and link the English README to the generated catalog.
Align versioned-example conformance checks and Release Please tracking with the installation guide; the English README no longer contains a pinned MCP JSON example. Translated examples retain their existing version checks.

Contract and boundary impact

Semantic owner and earliest changed stage: documentation and documentation-fact validation.
CLI and MCP/tool-catalog contract: unchanged.
Provider, bridge, target-format or platform compatibility: unchanged; current main's guide updates and historical network-capture entry are preserved.
Evidence, artifact, provenance or reconstruction contract: unchanged.
Process execution, authorization, cleanup or containment: unchanged.
Generated metadata and package/installation behavior: unchanged; generated files are not edited. Release Please continues tracking versioned examples in installation and translated READMEs.

Evidence and regression coverage

The catalog regression checks that a newly advertised setup client is required in the installation guide, while the English README can link there. The two CI failures were reproduced locally; conformance checks now validate the MCP example and prerequisites in installation. Version pins and release markers remain checked there and in translated READMEs. All five existing translation backlinks resolve through compatibility anchors. Documentation content is source-derived; no provider behavior is changed by this PR.

Validation performed

npm run check — passed.
npm run docs:check — passed.
npm run docs:build — passed.
npm run test:focused -- tests/conformance/releaseConfiguration.test.ts tests/conformance/readmeConsistency.test.ts tests/boundary/filesystem/releaseWorkflow.test.ts tests/boundary/cli/productCatalog.test.ts — 55 tests passed.
Checked 102 repository references across the six affected reading pages.
Browser previews at 1440, 768 and 390 px — figure, navigation and FAQ click/keyboard behavior passed.
Original Disclaimer compared verbatim; public diff checked for private workspace and preview references.
CI run 37722550634 — all 23 checks passed on 29d1184500.
Fresh Codex review of that commit — no major issues; all review threads resolved.

Compatibility, safety, and release

No runtime or package migration is required. Real Hopper/Ghidra verification was not run for this documentation change. Other language READMEs remain unchanged for the translation follow-up.

Review checklist

One focused outcome; Conventional Commit title.
Related issue linked.
Documentation-fact regression covered.
Owning guides and links updated; generated catalog preserved.
CLI/MCP behavior changes: not applicable.
Final diff checked for private information, unrelated changes and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1043 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/8/2026 **Status:** ✅ Merged **Merged:** 10/8/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `docs/english-readme-cleanup` --- ### 📝 Commits (7) - [`ff957c0`](https://github.com/morluto/rea/commit/ff957c08250a563f99b7152e93f894510c77b3ed) docs: simplify the English README - [`452430b`](https://github.com/morluto/rea/commit/452430b0a0d5eb42607b962012964f81caac8c35) docs: add README workflow and FAQ - [`f823796`](https://github.com/morluto/rea/commit/f8237965799264efd372d8da3e405273194f08aa) docs: clarify README updates and collapse FAQ - [`a049060`](https://github.com/morluto/rea/commit/a049060349da1f2d6a5edde3721b1386d5adadff) docs: welcome contributions in the README - [`352fc59`](https://github.com/morluto/rea/commit/352fc59fbc561cc103bb125786404c6dea9074ba) docs: highlight website guidance before quick start - [`0d33a6a`](https://github.com/morluto/rea/commit/0d33a6a251204a3333b0360916835068e169e938) docs: keep README capability links aligned with main - [`29d1184`](https://github.com/morluto/rea/commit/29d1184500ecbc22b2643ebe1285eee37da45965) fix(docs): preserve README backlinks and release checks ### 📊 Changes **12 files changed** (+497 additions, -668 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+154 -658) 📝 `docs/.vitepress/config.ts` (+1 -0) ➕ `docs/cli.md` (+184 -0) 📝 `docs/installation.md` (+78 -1) 📝 `docs/javascript-artifact-reconstruction.md` (+15 -0) 📝 `docs/roadmap.md` (+24 -0) 📝 `docs/testing.md` (+23 -0) 📝 `release-please-config.json` (+0 -1) 📝 `scripts/lib/docs-facts.mjs` (+10 -2) 📝 `tests/boundary/cli/productCatalog.test.ts` (+2 -0) 📝 `tests/conformance/readmeConsistency.test.ts` (+6 -5) 📝 `tests/conformance/releaseConfiguration.test.ts` (+0 -1) </details> ### 📄 Description ## Summary The English README mixed onboarding with provider configuration, diagnostics and lifecycle reference material. It now leads readers through setup, one prompt, a simple investigation figure and worked examples. Reference details live in linked guides. Fixes #1017. Translation follow-up #958 remains blocked until this English rewrite is merged. ## Problem and expected behavior Readers should find a usable setup command and understand what REA returns without reading a reference manual first. The README is reduced from 835 to 331 source lines, including seven collapsed FAQ answers. ## Change and scope - Preserve the opening product copy, screenshot, community links and original Disclaimer. Add the skills.sh badge and a website callout before Quick start. - Include CLI and agent update commands, the existing investigation figure, concise prerequisites, and DX-Ball, Notion and TH04 case-study links. Welcome bug reports, feature requests and contributions. - Move CLI/Evidence details into `docs/cli.md`, readiness and Hopper troubleshooting into installation, ASAR integrity into artifact reconstruction, and maintenance details into roadmap/testing. Repair the installation guide's README backlink. - Keep compatibility anchors for existing translated README backlinks. Validate supported agent names in installation and link the English README to the generated catalog. - Align versioned-example conformance checks and Release Please tracking with the installation guide; the English README no longer contains a pinned MCP JSON example. Translated examples retain their existing version checks. ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation and documentation-fact validation. - CLI and MCP/tool-catalog contract: unchanged. - Provider, bridge, target-format or platform compatibility: unchanged; current main's guide updates and historical network-capture entry are preserved. - Evidence, artifact, provenance or reconstruction contract: unchanged. - Process execution, authorization, cleanup or containment: unchanged. - Generated metadata and package/installation behavior: unchanged; generated files are not edited. Release Please continues tracking versioned examples in installation and translated READMEs. ## Evidence and regression coverage The catalog regression checks that a newly advertised setup client is required in the installation guide, while the English README can link there. The two CI failures were reproduced locally; conformance checks now validate the MCP example and prerequisites in installation. Version pins and release markers remain checked there and in translated READMEs. All five existing translation backlinks resolve through compatibility anchors. Documentation content is source-derived; no provider behavior is changed by this PR. ## Validation performed - `npm run check` — passed. - `npm run docs:check` — passed. - `npm run docs:build` — passed. - `npm run test:focused -- tests/conformance/releaseConfiguration.test.ts tests/conformance/readmeConsistency.test.ts tests/boundary/filesystem/releaseWorkflow.test.ts tests/boundary/cli/productCatalog.test.ts` — 55 tests passed. - Checked 102 repository references across the six affected reading pages. - Browser previews at 1440, 768 and 390 px — figure, navigation and FAQ click/keyboard behavior passed. - Original Disclaimer compared verbatim; public diff checked for private workspace and preview references. - [CI run 37722550634](https://github.com/morluto/rea/actions/runs/37722550634) — all 23 checks passed on `29d1184500`. - Fresh Codex review of that commit — no major issues; all review threads resolved. ## Compatibility, safety, and release No runtime or package migration is required. Real Hopper/Ghidra verification was not run for this documentation change. Other language READMEs remain unchanged for the translation follow-up. ## Review checklist - [x] One focused outcome; Conventional Commit title. - [x] Related issue linked. - [x] Documentation-fact regression covered. - [x] Owning guides and links updated; generated catalog preserved. - [x] CLI/MCP behavior changes: not applicable. - [x] Final diff checked for private information, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:08:05 +00:00