[PR #745] [MERGED] docs: clarify onboarding and align provider guidance #2209

New issue

Closed

opened 2026-10-16 21:15:41 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:15:41 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: docs/cleanup-onboarding-and-provider-guidance

📝 Commits (1)

376cae8 docs: clarify onboarding and align provider guidance

📊 Changes

32 files changed (+668 additions, -149 deletions)

View changed files

📝 README.md (+32 -9)
📝 README_ar.md (+34 -11)
📝 README_ja.md (+34 -11)
📝 README_ko.md (+34 -11)
📝 README_zh.md (+34 -11)
📝 docs/adr/0001-provider-selection-and-analysis-profiles.md (+7 -4)
📝 docs/adr/README.md (+5 -5)
📝 docs/android-analysis.md (+4 -0)
📝 docs/browser-observation.md (+4 -4)
📝 docs/browser-scenario-contract.md (+28 -0)
📝 docs/installation.md (+56 -3)
📝 docs/javascript-application-workflows.md (+28 -3)
📝 docs/javascript-runtime-observation.md (+18 -0)
📝 docs/managed-code-analysis.md (+33 -11)
📝 docs/process-capture.md (+4 -1)
📝 docs/product-catalog.json (+1 -1)
📝 docs/provider-evaluation.md (+18 -12)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 docs/windows-ghidra-p0.md (+6 -2)
📝 scripts/lib/docs-facts.d.mts (+4 -0)

...and 12 more files

📄 Description

Summary

Make the first REA investigation usable after either guided setup or a skill-only installation, and correct documentation that mixed repository capabilities with the published package. Fixes #737.

Problem and expected behavior

A skill-only install could direct an agent to unavailable MCP tools before explaining registration and reconnection. Other guides supplied an unsupported session parameter, an installed link outside the skill bundle, and a process capture saved as JSON without selecting JSON output. Working connections should proceed immediately; missing connections should receive scoped setup guidance or a usable CLI result.

Change and scope

Move conditional connection guidance before target routing; distinguish registration repair, missing providers, and a disconnected session. Keep approval scoped to actual configuration writes or an optional Hopper installation. Add the skills.sh route and a static JavaScript first-result command across the READMEs. Explain the dated npm/main release boundary, inline versus retained Evidence, current Ghidra/Windows coverage, Android and firmware prerequisites, and executable runtime recipes.

Install the Android reference alongside the existing skill references, bump the skill to version 25, and guard installed links and documented producer/consumer examples. Unified capability discovery remains follow-up #740; this change does not implement diagnostic error projection or publish a release. Technical corrections in translated READMEs are written in English.

Contract and boundary impact

Semantic owner and earliest changed stage: onboarding instructions and packaged skill installation.
CLI and MCP/tool-catalog contract: no schema or tool-inventory changes; preserve main's 125 tools and six prompts. Document binary_session with {} and its availability results.
Provider, bridge, target-format, or platform compatibility: no provider execution changes; distinguish verified, experimental, unsupported, and unreleased coverage.
Evidence, artifact, provenance, or reconstruction contract: unchanged; clarify CLI full-Evidence records, MCP envelopes, and connection-scoped retained IDs.
Process execution, authorization, cleanup, or containment impact: unchanged. No new analysis approval fields or prerequisite installations.
Generated metadata (docs/product-catalog.json), package, or installation impact: source-generated skill version/digest updates; setup installs one additional Markdown reference.

Evidence and regression coverage

Tests added or updated: installed skill link containment/readback/idempotence; minimal browser scenario against its named contract; execute the documented process capture and consume it through the comparison CLI.
Base reproduction or other evidence: the original DOS reference escaped the installed bundle; the original process recipe emitted TOON into capture.json. The new regressions exercise those consumer failures. Documentation was compared with contracts, provider adapters, and the published 4.0.1 artifact.
User-visible CLI/MCP output: rea analyze-javascript-application /absolute/path/to/app --json returns inline Evidence without native engines or MCP registration. rea capture-process ./scenario.json --json > capture.json produces consumable JSON. An already working MCP investigation requires no doctor/setup call.
Remaining proof gaps: no new real Hopper/Ghidra/JADX/browser verification. The disconnected-session task controls active MCP availability; it does not automate a GUI restart. Branch tarballs do not establish release publication.
Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run check — passed typecheck, lint, formatting, Knip, and metadata checks; existing lint warnings remain.
npm run docs:check — passed generated metadata and documentation facts.
npx --no-install vitest run --maxWorkers=1 --no-file-parallelism tests/boundary/cli/productCatalog.test.ts tests/boundary/cli/processCli.test.ts tests/boundary/filesystem/setupSkill.test.ts tests/acceptance/applications/applicationWorkflowCli.test.ts — 25 tests passed serially. An initial concurrent run exceeded one existing deadline; rerun passed without changing it.
npm run verify:package — passed isolated install, setup planning/backups/idempotence, installed references, CLI/MCP startup/lifecycle, and Evidence workflows.
npm pack --dry-run --json — inspected package contents and bounded size; Android reference included. The final branch tarball is approximately 1.58 MB (757 files).
Actual skills CLI project installation from the branch source — installed matching instructions and all five references, with no broken bundled links and no MCP registration.
npm run verify:inspector — passed real Node Inspector CLI/MCP checks for eight owned fixtures.
Documented JavaScript analyze/save/trace recipe — executed successfully against an isolated installed package.
CI run — all 19 jobs passed, including four test shards, coverage, Linux/macOS package installation, Windows native-control/package verification, and Node Inspector on Linux/Windows.
Actual ephemeral Codex CLI tasks — working MCP; skill-only with MCP absent; aligned registration with disconnected session; actual CLI setup followed by a new MCP-connected session. The setup-generated transport was consumed without rewriting its fields; the second setup apply reported zero changes. Synthetic shipped JavaScript was analyzed without execution.

Compatibility, safety, and release

Breaking changes or migration steps: none; reconnect after an approved registration update, as before.
Real Hopper/Ghidra, browser, or OS coverage: no new real Hopper/Ghidra/JADX/browser-engine verification. Local real Node Inspector and Linux package workflows passed; CI additionally passed Windows Node Inspector/native controls/packages and macOS installation. The local Windows host/D-drive was untouched.
Package or release metadata impact: skill version 25 and its bundled guide; no npm release. The inspected npm 4.0.1 has 116 tools and differs from current main.
Security, privacy, process, or containment review: two-CPU affinity, low scheduling priority, bounded Node heaps, and serial heavy verification. Temporary installations/configurations only; public examples use synthetic paths and contain no credentials or raw host logs.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, 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/745 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `docs/cleanup-onboarding-and-provider-guidance` --- ### 📝 Commits (1) - [`376cae8`](https://github.com/morluto/rea/commit/376cae86ddc68f663f9a73d28d48e6964e5d6d8a) docs: clarify onboarding and align provider guidance ### 📊 Changes **32 files changed** (+668 additions, -149 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+32 -9) 📝 `README_ar.md` (+34 -11) 📝 `README_ja.md` (+34 -11) 📝 `README_ko.md` (+34 -11) 📝 `README_zh.md` (+34 -11) 📝 `docs/adr/0001-provider-selection-and-analysis-profiles.md` (+7 -4) 📝 `docs/adr/README.md` (+5 -5) 📝 `docs/android-analysis.md` (+4 -0) 📝 `docs/browser-observation.md` (+4 -4) 📝 `docs/browser-scenario-contract.md` (+28 -0) 📝 `docs/installation.md` (+56 -3) 📝 `docs/javascript-application-workflows.md` (+28 -3) 📝 `docs/javascript-runtime-observation.md` (+18 -0) 📝 `docs/managed-code-analysis.md` (+33 -11) 📝 `docs/process-capture.md` (+4 -1) 📝 `docs/product-catalog.json` (+1 -1) 📝 `docs/provider-evaluation.md` (+18 -12) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `docs/windows-ghidra-p0.md` (+6 -2) 📝 `scripts/lib/docs-facts.d.mts` (+4 -0) _...and 12 more files_ </details> ### 📄 Description ## Summary Make the first REA investigation usable after either guided setup or a skill-only installation, and correct documentation that mixed repository capabilities with the published package. Fixes #737. ## Problem and expected behavior A skill-only install could direct an agent to unavailable MCP tools before explaining registration and reconnection. Other guides supplied an unsupported session parameter, an installed link outside the skill bundle, and a process capture saved as JSON without selecting JSON output. Working connections should proceed immediately; missing connections should receive scoped setup guidance or a usable CLI result. ## Change and scope Move conditional connection guidance before target routing; distinguish registration repair, missing providers, and a disconnected session. Keep approval scoped to actual configuration writes or an optional Hopper installation. Add the skills.sh route and a static JavaScript first-result command across the READMEs. Explain the dated npm/main release boundary, inline versus retained Evidence, current Ghidra/Windows coverage, Android and firmware prerequisites, and executable runtime recipes. Install the Android reference alongside the existing skill references, bump the skill to version 25, and guard installed links and documented producer/consumer examples. Unified capability discovery remains follow-up #740; this change does not implement diagnostic error projection or publish a release. Technical corrections in translated READMEs are written in English. ## Contract and boundary impact - Semantic owner and earliest changed stage: onboarding instructions and packaged skill installation. - CLI and MCP/tool-catalog contract: no schema or tool-inventory changes; preserve main's 125 tools and six prompts. Document `binary_session` with `{}` and its availability results. - Provider, bridge, target-format, or platform compatibility: no provider execution changes; distinguish verified, experimental, unsupported, and unreleased coverage. - Evidence, artifact, provenance, or reconstruction contract: unchanged; clarify CLI full-Evidence records, MCP envelopes, and connection-scoped retained IDs. - Process execution, authorization, cleanup, or containment impact: unchanged. No new analysis approval fields or prerequisite installations. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: source-generated skill version/digest updates; setup installs one additional Markdown reference. ## Evidence and regression coverage - Tests added or updated: installed skill link containment/readback/idempotence; minimal browser scenario against its named contract; execute the documented process capture and consume it through the comparison CLI. - Base reproduction or other evidence: the original DOS reference escaped the installed bundle; the original process recipe emitted TOON into `capture.json`. The new regressions exercise those consumer failures. Documentation was compared with contracts, provider adapters, and the published 4.0.1 artifact. - User-visible CLI/MCP output: `rea analyze-javascript-application /absolute/path/to/app --json` returns inline Evidence without native engines or MCP registration. `rea capture-process ./scenario.json --json > capture.json` produces consumable JSON. An already working MCP investigation requires no doctor/setup call. - Remaining proof gaps: no new real Hopper/Ghidra/JADX/browser verification. The disconnected-session task controls active MCP availability; it does not automate a GUI restart. Branch tarballs do not establish release publication. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check` — passed typecheck, lint, formatting, Knip, and metadata checks; existing lint warnings remain. - `npm run docs:check` — passed generated metadata and documentation facts. - `npx --no-install vitest run --maxWorkers=1 --no-file-parallelism tests/boundary/cli/productCatalog.test.ts tests/boundary/cli/processCli.test.ts tests/boundary/filesystem/setupSkill.test.ts tests/acceptance/applications/applicationWorkflowCli.test.ts` — 25 tests passed serially. An initial concurrent run exceeded one existing deadline; rerun passed without changing it. - `npm run verify:package` — passed isolated install, setup planning/backups/idempotence, installed references, CLI/MCP startup/lifecycle, and Evidence workflows. - `npm pack --dry-run --json` — inspected package contents and bounded size; Android reference included. The final branch tarball is approximately 1.58 MB (757 files). - Actual skills CLI project installation from the branch source — installed matching instructions and all five references, with no broken bundled links and no MCP registration. - `npm run verify:inspector` — passed real Node Inspector CLI/MCP checks for eight owned fixtures. - Documented JavaScript analyze/save/trace recipe — executed successfully against an isolated installed package. - [CI run](https://github.com/morluto/rea/actions/runs/37482210704) — all 19 jobs passed, including four test shards, coverage, Linux/macOS package installation, Windows native-control/package verification, and Node Inspector on Linux/Windows. - Actual ephemeral Codex CLI tasks — working MCP; skill-only with MCP absent; aligned registration with disconnected session; actual CLI setup followed by a new MCP-connected session. The setup-generated transport was consumed without rewriting its fields; the second setup apply reported zero changes. Synthetic shipped JavaScript was analyzed without execution. ## Compatibility, safety, and release - Breaking changes or migration steps: none; reconnect after an approved registration update, as before. - Real Hopper/Ghidra, browser, or OS coverage: no new real Hopper/Ghidra/JADX/browser-engine verification. Local real Node Inspector and Linux package workflows passed; CI additionally passed Windows Node Inspector/native controls/packages and macOS installation. The local Windows host/D-drive was untouched. - Package or release metadata impact: skill version 25 and its bundled guide; no npm release. The inspected npm 4.0.1 has 116 tools and differs from current main. - Security, privacy, process, or containment review: two-CPU affinity, low scheduling priority, bounded Node heaps, and serial heavy verification. Temporary installations/configurations only; public examples use synthetic paths and contain no credentials or raw host logs. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, 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-16 21:15:41 +00:00