docs: show task-scoped readiness and provider preference in the quick start

Explain that bare `rea doctor` audits every integration, map common tasks
to `--provider`, `--client`, and `--skill` scopes, and describe how
`scope_checks`, `informational_checks`, `healthy`, and
`environment_healthy` relate. Document the typed ambiguous-provider
error and how to choose an engine once without implying a fallback.

Fixes #726

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Iwakurakaoru0822
2026-10-06 20:57:39 -07:00
co-authored by Claude Opus 5.5
parent e7cbfe04fd
commit 5fd0db37d9
2 changed files with 35 additions and 1 deletions
+32
View File
@@ -95,6 +95,38 @@ MCP setup, Hopper, Ghidra, or executing the application. For a native app, confi
its engine first, then use `analyze` with that app's path. Run `doctor` when you
need diagnosis; it is not a prerequisite for each analysis.
### Check readiness for the task at hand
`rea doctor` without options is an audit of the whole integration. It checks
every detected agent registration, the installed skill, and every optional
analysis engine, so it can report `healthy: false` while your current task works.
Choose a readiness scope for the work you are doing:
| Task | Readiness check |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| Static JavaScript/Electron analysis | None. Run `analyze-javascript-application` directly. |
| Troubleshoot one analysis engine | `rea doctor --provider ghidra --json` (or `hopper`, `ida`) |
| Check one agent's MCP registration | `rea doctor --client codex --json` (see [client IDs](docs/installation.md#supported-agents)) |
| Check the installed skill | `rea doctor --skill --json` |
A scoped report has `scope.mode: "explicit"`. Only `scope_checks` determine
`healthy` and the exit status. Everything else is listed in
`informational_checks`; you don't need to fix it for this task. For example, a
missing engine you are not using needs no repair. `environment_healthy` still
summarizes the full audit. `--target` adds a target check, but without a scope
option the report remains audit-wide.
When more than one installed engine supports a native target, REA does not pick
one: opening the target fails with `code: "capability_unavailable"`,
`details.selection_reason: "ambiguous"`, and the providers in
`details.candidate_ids`. Choose one once: pass `--provider` on
the CLI or `provider_id` on `open_binary`, or set `REA_ANALYSIS_PROVIDER` as a
standing preference. An explicit selector overrides the environment variable.
The session keeps that choice and never falls back to another engine. An
ambiguity or unavailable-provider diagnostic asks you to choose an engine; it
does not mean you have to install every engine. See
[Choosing a deep-analysis provider](#choosing-a-deep-analysis-provider).
### Install the rea command
Install the command-line interface:
+3 -1
View File
@@ -108,7 +108,9 @@ npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --
```
It returns the complete Evidence record directly and requires no native engine.
Provider failures in doctor do not prevent unrelated target-free tools.
Provider failures in doctor do not prevent unrelated target-free tools. To check
readiness for one task instead of auditing every integration, see
[Check readiness for the task at hand](../README.md#check-readiness-for-the-task-at-hand).
## Supported agents