feat: add read-only doctor integrations overview

[knqiufan]

Feature description

Keep the existing per-host doctor commands as the fail-closed path:

powercontext doctor
powercontext doctor codex
powercontext doctor claude-code
powercontext doctor dsh
powercontext doctor pi
powercontext doctor hermes

Add one opt-in, read-only overview that reports every first-class host on a single matrix:

powercontext doctor integrations
powercontext doctor integrations --json

Empty doctor stays a package + Server check. Single-host doctor <host> still fails when that CLI is missing. This command does not install plugins, start the Server, or launch a host.

The catalog is the shared first-class setup list from #1311: codex, claude-code, dsh, pi, hermes. PATH is not used to build or filter that list.

Problem and proposed solution

Why this issue exists

setup select in #1311 gives a multi-host install path. Diagnosis is still one command per host. A laptop that has Codex, and does not have Claude Code, Pi, or Hermes, has to remember five doctor <host> names to answer a simple question: which official integrations are present, and which of those are broken?

Empty doctor correctly refuses to scan hosts. That contract should stay. The gap is the missing read-only overview, not a change to the default doctor.

This is the follow-up that #1301 already called out and that #1311 left out on purpose. #1301 / #1311 cover explicit multi-host install. This issue covers the matching status command.

Gap this fills

Today the product has:

• five independent doctor <host> commands;
• five independent diagnose functions;
• a shared first-class catalog in feat(cli): add setup select for explicit multi-host plugin install #1311;
• no command that walks that catalog once and prints presence vs health.

Concatenating the five single-host commands is the wrong default: each missing CLI exits 1, so a machine with only Codex looks unhealthy.

Value

• One command answers “which first-class hosts are here, and which of those are broken?”
• Missing CLIs are visible as missing and do not fail the run.
• A present host with a broken plugin or a failed plugin list still fails the command.
• Empty doctor and doctor <host> keep their current meaning.
• The overview reuses the feat(cli): add setup select for explicit multi-host plugin install #1311 catalog, so a newly added first-class host does not need a second list.

Proposed user contract

powercontext doctor integrations
powercontext doctor integrations --json

Behavior:

1. Walk the shared first-class catalog. Do not PATH-scan to build or filter the menu. PATH checks stay inside the existing diagnose functions.
2. Lazily call the current probes: run_codex_diagnostics, run_claude_code_diagnostics, run_dsh_diagnostics, run_pi_diagnostics, run_hermes_diagnostics.
3. Classify each host from its CLI check plus its integration check (plugin, or package for Pi):
   • CLI not on PATH, integration skipped → missing. This row does not fail the command.
   • CLI present and the integration is ok → present / healthy.
   • CLI present but the CLI call failed, or the integration failed → present / failed. The command exits 1.
4. Human output is one line per host, for example:

codex: present - cli=ok plugin=ok
claude-code: missing - cli=failed plugin=skipped
dsh: present - cli=ok plugin=failed
pi: missing - cli=failed package=skipped
hermes: missing - cli=failed plugin=skipped

5. --json uses ok, status, and hosts. Each host includes presence (present | missing) plus the existing Diagnostic.as_json() payload for the CLI item and the integration item. ok is true only when no present host failed.
6. All five hosts missing → exit 0.
7. The command is read-only. It does not install, start the Server, or launch a host.

Rules that must not change:

• powercontext doctor without a subcommand still checks only the package and Server.
• doctor <host> still exits 1 when that host CLI is missing.
• setup select is unchanged.

Implementation suggestion

This should be orchestration over the current diagnose functions, not a second health checker.

1. Reuse the feat(cli): add setup select for explicit multi-host plugin install #1311 catalog in src/powercontext/cli/hosts.py. Do not keep a second host list in system.py.
2. Add a lazy diagnose_host(name) dispatcher, matching install_host, so hosts.py does not import system.py at module top.
3. Classify presence with a dedicated helper. Do not flatten the five raw diagnostic dicts into _diagnostics_ok; that helper treats a missing CLI as failed.
4. Register a thin doctor integrations command after the existing host doctor commands.
5. Tests go through the public CLI and mock the five run_*_diagnostics functions. Cover: JSON includes all five hosts; only Codex present and healthy → exit 0; present plugin failed → exit 1; present CLI whose list call failed → exit 1; all missing → exit 0; empty doctor still does not call any host probe; doctor codex still exits 1 when Codex is missing.

Acceptance criteria

• powercontext doctor --json still reports only package, server_liveness, and server_readiness.
• A machine with only a healthy Codex plugin: doctor integrations exits 0 and marks the other hosts missing.
• A machine with Codex on PATH but the PowerContext plugin missing: the command exits 1 and still prints the missing rows.
• A machine with no first-class host on PATH: the command exits 0 with five missing rows.
• doctor codex on a machine without Codex still exits 1.
• Docs show doctor integrations as the optional overview and keep doctor <host> as the fail-closed path.

Alternatives considered

1. Tell users to run five doctor <host> commands. This already works, and it is what the docs do. A shell one-liner fails on the first missing CLI, which is the opposite of an overview.
2. Fold host scanning into empty doctor. That would change a stable package + Server contract. Existing tests require empty doctor not to inspect Codex.
3. Flatten every host diagnostic into _diagnostics_ok. Missing CLIs are failed in the single-host probes, so a typical laptop would always exit 1.
4. PATH-scan to hide missing hosts. Presence should be visible. The catalog is the first-class list from feat(cli): add setup select for explicit multi-host plugin install #1311, not a guessed subset of PATH.
5. Install from doctor. doctor stays read-only. Mutation belongs to setup / setup select.
6. Stack this into feat(cli): add setup select for explicit multi-host plugin install #1311. feat(cli): add setup select for explicit multi-host plugin install #1311 already has a closed install contract. This overview should be a separate reviewable change.

Additional context

Prerequisite: #1311 (feat(cli): add setup select for explicit multi-host plugin install). That PR introduces the shared FIRST_CLASS_HOSTS catalog. This command must use that catalog. Implementing it from current master would either duplicate the list or conflict when #1311 merges.

Related: #1301 described a later doctor integrations as an optional follow-up and then deferred it. #1311 implements setup select and explicitly leaves this overview out. This issue is that follow-up, not a second install command.

Sources:

• src/powercontext/cli/system.py — empty doctor checks package + Server; doctor <host> uses _diagnostics_ok
• src/powercontext/cli/hosts.py on feat(cli): add setup select for explicit multi-host plugin install #1311 — shared first-class catalog
• src/powercontext/cli/pi.py — second diagnostic key is package, not plugin

Dedup: searched doctor integrations, composite doctor, and host-status matrix. No existing tracker for this read-only overview as of 2026-08-22.

I am willing to implement this against #1311's catalog.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.