Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs(doctor): document --help and the CLI's no-report failure payload

M3gA-Mind7e5ccc559006
diff --git a/docs/gitbooks/en/guides/doctor.md b/docs/gitbooks/en/guides/doctor.md
index 4458329e99..9ad05f4093 100644
--- a/docs/gitbooks/en/guides/doctor.md
+++ b/docs/gitbooks/en/guides/doctor.md
@@ -86,6 +86,12 @@ openhuman-core doctor --lint --severity-min warn --json
| `--lint` | Returns `0` when no finding meets the minimum severity, `1` when one or more do, or `2` if the report could not be produced. |
| `--lint --json` | Prints the report as JSON and keeps lint's `0`, `1`, or `2` exit behavior. |
+If no report can be produced, the command exits `2` with a short reason, for
+example `doctor could not produce a report: the doctor host could not start
+(profile selection, config or core boot)`. With `--json` it prints
+`{"ok": false, "reason": "…"}` instead. `openhuman-core doctor --help` lists
+every option.
+
`--severity-min` accepts `info`, `warn`, or `error` and defaults to `error`.
Pass and skipped findings never meet the threshold. For example, to fail CI on
warnings as well as errors:
diff --git a/docs/specs/doctor.md b/docs/specs/doctor.md
index c6e165fd66..86b02a4f21 100644
--- a/docs/specs/doctor.md
+++ b/docs/specs/doctor.md
@@ -224,6 +224,19 @@ The CLI does not add fields to the RPC report. Human output is a rendering of
the same findings and includes the severity, check id, message, and fix hint.
JSON uses the same report in every surface.
+`--help` (also `-h` or `help`) prints usage and exits `0`. When no report is
+produced the CLI exits `2` and names one fixed reason; the underlying error is
+never printed, because it can carry endpoints or credential context. Text mode
+prints `doctor could not produce a report: <reason>` to stderr; `--json` prints
+`{"ok": false, "reason": "<reason>"}`. The reason strings are stable:
+
+| Reason | Meaning |
+| -------------------------------------------------------------------------- | ------------------------------------- |
+| `the async runtime could not start` | The CLI could not create its runtime. |
+| `the doctor host could not start (profile selection, config or core boot)` | The in-process host did not start. |
+| `the doctor_report call failed` | The core rejected or failed the RPC. |
+| `the core answered without a report` | The RPC returned no report object. |
+
## Profile semantics
On desktop, a requested profile id resolves through `ProfileLayout`. Doctor