doctor

Category: diagnostics
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

SHAMPOO-wide health diagnostics in nine grouped sections with typed checks. Call it to distinguish ok, warn, fail, and unknown before investigating or repairing.

Arguments

Optional: detail, sections.

detail: summary | full. Note: summary omits per-check detail text; full includes it.
sections: CSV section filter; empty runs all. Note: CSV filter using exact section names (config, database, auth, jobs, pump, wake, ledger, readiness, invariants); empty runs all.

Result

Object with sections array; each section has a name and checks with id, status (ok, warn, fail, unknown), severity, summary, and detail (full mode only).

Boundaries

Read-only across the selected profile; secret material is never disclosed (presence and mode only). UNKNOWN means unobservable, never unhealthy.

Lifecycle / side effects

Pure diagnostic read; records nothing and changes nothing.

Errors

Wrong-typed arguments rejected by validation. Unknown section names are silently skipped. Backend failures surface as transport errors.

Example

{
  "detail": "summary"
}

Result shape:

{
  "sections": [
    {
      "checks": [
        {
          "id": "readiness_db_ping",
          "severity": "info",
          "status": "ok",
          "summary": "database reachable (3 ms)"
        }
      ],
      "section": "readiness"
    }
  ]
}