[GH-ISSUE #726] [Docs] Show task-scoped readiness and provider preference in the quick start #325

New issue

Closed

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

bsakaguchi commented

2026-10-15 18:23:55 +00:00

Owner

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

Before submitting

I searched the open and closed issues and relevant pull requests for a related report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

README.md (Quick start/troubleshooting and Ghidra provider selection); docs/installation.md.

Problem

A new user following broad doctor guidance can receive unhealthy optional-provider and unrelated client/skill checks even though a JS analysis task works immediately. With both Hopper and Ghidra installed, opening a native target in auto mode also requires a preference decision.

Both capabilities already exist: rea doctor --provider hopper --json returned healthy=true with relevant checks, and ambiguity errors named provider_id/--provider/REA_ANALYSIS_PROVIDER. The requested improvement is a short task-focused onboarding path, not a replacement policy or a claim that scoped doctor is missing.

Expected content

Show an agent/user how to:

Distinguish full integration audit from readiness for the current task.
Use a provider-scoped doctor when troubleshooting that engine.
Start an engine-free JS task without repairing unrelated integrations.
Set or supply an existing provider preference once when more than one engine can handle a target.
Read typed ambiguity/capability diagnostics without treating them as a request to install every backend.

Keep current syntax and precedence accurate. A --target argument alone did not select an analysis-only view in this run; avoid implying it does. Keep the provider choice explicit, with no silent fallback or repeated permission declarations.

Supporting evidence

Baseline public-interface controls:

rea doctor --json: unhealthy due to optional engine/integration checks
rea analyze <JS_APP> --json: success without repairs
rea doctor --provider hopper --json: healthy=true, scope.mode=explicit
open_binary <ELF>, provider omitted: typed ambiguity with Hopper/Ghidra candidates
open_binary <ELF>, provider_id=ghidra: success

The directory-specific diagnostic mismatch is a separate Bug report; this documentation issue owns the onboarding explanation.

Additional context

Hands-on public CLI/MCP evaluation, findings F01 and F05. Baseline: REA 4.0.1, source revision c3bc38bf6c74d2175a4680530dcadd6cab0e7791; evaluation date 2026-10-06.

docs/mcp-contracts.md already documents deterministic provider binding. The proposed quick start should link to that policy, not invent an automatic fallback.

Related evaluation issues: #720.

Originally created by @N0zoM1z0 on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/726 ### Before submitting - [x] I searched the open and closed issues and relevant pull requests for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location [README.md](https://github.com/morluto/rea/blob/c3bc38bf6c74d2175a4680530dcadd6cab0e7791/README.md) (Quick start/troubleshooting and Ghidra provider selection); [docs/installation.md](https://github.com/morluto/rea/blob/c3bc38bf6c74d2175a4680530dcadd6cab0e7791/docs/installation.md). ### Problem A new user following broad doctor guidance can receive unhealthy optional-provider and unrelated client/skill checks even though a JS analysis task works immediately. With both Hopper and Ghidra installed, opening a native target in auto mode also requires a preference decision. Both capabilities already exist: `rea doctor --provider hopper --json` returned healthy=true with relevant checks, and ambiguity errors named provider_id/--provider/REA_ANALYSIS_PROVIDER. The requested improvement is a short task-focused onboarding path, not a replacement policy or a claim that scoped doctor is missing. ### Expected content Show an agent/user how to: 1. Distinguish full integration audit from readiness for the current task. 2. Use a provider-scoped doctor when troubleshooting that engine. 3. Start an engine-free JS task without repairing unrelated integrations. 4. Set or supply an existing provider preference once when more than one engine can handle a target. 5. Read typed ambiguity/capability diagnostics without treating them as a request to install every backend. Keep current syntax and precedence accurate. A `--target` argument alone did not select an analysis-only view in this run; avoid implying it does. Keep the provider choice explicit, with no silent fallback or repeated permission declarations. ### Supporting evidence Baseline public-interface controls: ```text rea doctor --json: unhealthy due to optional engine/integration checks rea analyze <JS_APP> --json: success without repairs rea doctor --provider hopper --json: healthy=true, scope.mode=explicit open_binary <ELF>, provider omitted: typed ambiguity with Hopper/Ghidra candidates open_binary <ELF>, provider_id=ghidra: success ``` The directory-specific diagnostic mismatch is a separate Bug report; this documentation issue owns the onboarding explanation. ### Additional context Hands-on public CLI/MCP evaluation, findings F01 and F05. Baseline: REA 4.0.1, source revision [c3bc38bf6c74d2175a4680530dcadd6cab0e7791](https://github.com/morluto/rea/commit/c3bc38bf6c74d2175a4680530dcadd6cab0e7791); evaluation date 2026-10-06. [docs/mcp-contracts.md](https://github.com/morluto/rea/blob/c3bc38bf6c74d2175a4680530dcadd6cab0e7791/docs/mcp-contracts.md) already documents deterministic provider binding. The proposed quick start should link to that policy, not invent an automatic fallback. Related evaluation issues: [#720](https://github.com/morluto/rea/issues/720).

bsakaguchi

2026-10-15 18:23:55 +00:00