@canonical/pragma-cli 0.35.0 → 0.36.0

package/src/capabilities/doctor/doctor.render.ts

@@ -10,58 +10,26 @@
  * Glyphs are plain constants tinted at render time; nothing is baked at load.
  */
 
-import chalk from "chalk";
 import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import {
+  CHECK_GLYPHS,
+  checkRemedyWord,
+  FIX_ARROW,
+  SCOPE_LABELS,
+  SUB_BULLET,
+  SUB_INDENT,
+} from "../../kernel/render/vocabulary.js";
 import type { Formatters } from "../../kernel/spec/index.js";
-import { BAND_LABELS } from "../shared/index.js";
 import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
 
-/**
- * Uncolored status glyphs — tinted at render time (never baked at module load).
- * `available` gets its own glyph, distinct from ✗: an opt-in integration that
- * is not set up is not a fault, and rendering it as one would train users to
- * ignore the failure count. The glyph pairs with the word in the tally, so the
- * distinction survives with color stripped.
- */
-const STATUS_GLYPHS: Record<CheckStatus, string> = {
-  pass: "✓",
-  fail: "✗",
-  available: "◇",
-  skip: "○",
-};
-
-const SUB_BULLET = "·";
-const FIX_ARROW = "↳";
-const INDENT = "     "; // aligns sub-lines under the check name
-
-/** The TTY styler plus `red` — the one tint {@link RenderStyle} does not carry. */
-interface DoctorStyle extends RenderStyle {
-  red(text: string): string;
-}
-
-/**
- * Build the doctor styler for this process's stdout: the shared TTY seam, plus a
- * `red` gated on the SAME decision, so a fail tint appears only on a color TTY.
- *
- * @returns A colorizing styler on a color-capable TTY, else the identity styler.
- * @note Impure — {@link defaultStyle} reads `process.stdout.isTTY` + chalk level.
- */
-function doctorStyle(): DoctorStyle {
-  const style = defaultStyle();
-  return {
-    ...style,
-    red: style.enabled ? (text) => chalk.red(text) : (text) => text,
-  };
-}
-
 /**
  * Tint a status glyph by meaning — green pass, red fail, cyan available
  * (actionable-but-optional, the same tint as the `fix:` arrow it points at),
  * yellow skip.
  */
-function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
-  const glyph = STATUS_GLYPHS[status];
+function paintGlyph(status: CheckStatus, style: RenderStyle): string {
+  const glyph = CHECK_GLYPHS[status];
   if (status === "pass") return style.green(glyph);
   if (status === "fail") return style.red(glyph);
   if (status === "available") return style.cyan(glyph);
@@ -70,13 +38,13 @@ function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
 
 /**
  * Render one check as terminal lines: a headline row (icon, aligned name,
- * detail), an optional indented breakdown of sub-items, and — for failures — an
- * inline remedial instruction.
+ * detail), an optional indented breakdown of sub-items, and — whenever the
+ * check carries one — an inline instruction.
  */
 function formatCheckPlain(
   check: CheckResult,
   nameWidth: number,
-  style: DoctorStyle,
+  style: RenderStyle,
 ): string[] {
   const name = check.name.padEnd(nameWidth);
   const label = check.status === "fail" ? style.red(name) : style.bold(name);
@@ -96,19 +64,23 @@ function formatCheckPlain(
       const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
       const detail = item.detail ? `  ${style.dim(item.detail)}` : "";
       lines.push(
-        `${INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
+        `${SUB_INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
       );
     }
   }
 
-  // Both actionable tiers keep their inline instruction: a fail's remedy is
-  // the repair, an available's remedy is the setup command that enables it.
-  if (
-    (check.status === "fail" || check.status === "available") &&
-    check.remedy
-  ) {
+  // Every row that HAS an instruction prints it. A fail's remedy is the
+  // repair, an available's is the setup command that enables it — and a skip's,
+  // when it authored one, is the only thing standing between the reader and a
+  // dead end. Skips were dropped here, so `skills` reported "no skills
+  // installed" with the next step (`sources update`) computed, carried through
+  // the check, published in `--format json`, and then thrown away one line
+  // before it reached the person reading. A skip never DERIVES a remedy
+  // (`scopedChecks` only passes through an authored one), so this prints
+  // nothing that was not deliberately written for this machine.
+  if (check.remedy) {
     lines.push(
-      `${INDENT}${style.cyan(FIX_ARROW)} ${style.cyan("fix:")} ${check.remedy}`,
+      `${SUB_INDENT}${style.cyan(FIX_ARROW)} ${style.cyan(`${checkRemedyWord(check.status)}:`)} ${check.remedy}`,
     );
   }
 
@@ -120,7 +92,7 @@ function formatCheckPlain(
  * `available` is counted apart from `failed` so a healthy install with
  * integrations left to opt into never reports failures it does not have.
  */
-function formatSummary(data: DoctorData, style: DoctorStyle): string {
+function formatSummary(data: DoctorData, style: RenderStyle): string {
   const parts = [style.green(`${data.passed} passed`)];
   parts.push(
     data.failed > 0
@@ -141,28 +113,28 @@ function formatSummary(data: DoctorData, style: DoctorStyle): string {
 }
 
 /**
- * Partition checks into ordered bands: environment (no band), then the global
- * and project bands. Declaration order is preserved within each band, so the
- * report stays deterministic.
+ * Partition checks into ordered sections: environment (no scope), then the
+ * global and local-project scopes. Declaration order is preserved within each,
+ * so the report stays deterministic.
  */
-function partitionByBand(checks: readonly CheckResult[]): {
+function partitionByScope(checks: readonly CheckResult[]): {
   environment: CheckResult[];
-  machine: CheckResult[];
+  global: CheckResult[];
   project: CheckResult[];
 } {
   return {
-    environment: checks.filter((c) => c.band === undefined),
-    machine: checks.filter((c) => c.band === "global"),
-    project: checks.filter((c) => c.band === "project"),
+    environment: checks.filter((c) => c.scope === undefined),
+    global: checks.filter((c) => c.scope === "global"),
+    project: checks.filter((c) => c.scope === "project"),
   };
 }
 
 export const doctorFormatters: Formatters<DoctorData> = {
   plain(data) {
-    const style = doctorStyle();
+    const style = defaultStyle();
     const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
     const lines: string[] = [style.bold(`${BIN_NAME} doctor`), ""];
-    const { environment, machine, project } = partitionByBand(data.checks);
+    const { environment, global, project } = partitionByScope(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;
       if (heading) lines.push(style.bold(heading));
@@ -170,11 +142,11 @@ export const doctorFormatters: Formatters<DoctorData> = {
         lines.push(...formatCheckPlain(check, nameWidth, style));
       lines.push("");
     };
-    // Environment checks lead (no header); the global then project bands are the
-    // two banded sections before the tally.
+    // Environment checks lead (no header); Global then Local project are the
+    // two scoped sections before the tally.
     section("", environment);
-    section(BAND_LABELS.global, machine);
-    section(BAND_LABELS.project, project);
+    section(SCOPE_LABELS.global, global);
+    section(SCOPE_LABELS.project, project);
     lines.push(formatSummary(data, style));
     return lines.join("\n");
   },
@@ -182,34 +154,38 @@ export const doctorFormatters: Formatters<DoctorData> = {
   llm(data) {
     const renderCheck = (check: CheckResult): string[] => {
       const out = [
-        `- ${STATUS_GLYPHS[check.status]} **${check.name}**: ${check.detail}`,
+        `- ${CHECK_GLYPHS[check.status]} **${check.name}**: ${check.detail}`,
       ];
       for (const item of check.items ?? []) {
-        const itemIcon = item.status ? `${STATUS_GLYPHS[item.status]} ` : "";
+        const itemIcon = item.status ? `${CHECK_GLYPHS[item.status]} ` : "";
         const detail = item.detail ? `: ${item.detail}` : "";
         out.push(`  - ${itemIcon}${item.label}${detail}`);
       }
-      // Same rule as the plain path: fail and available both carry their
-      // inline instruction (the repair, or the setup command).
-      if (
-        (check.status === "fail" || check.status === "available") &&
-        check.remedy
-      ) {
-        out.push(`  - _fix:_ \`${check.remedy}\``);
+      // Same rule as the plain path: every row that carries an instruction
+      // prints it, under the label its status earns. Only a `fix:` is code-set
+      // — a derived remedy is a bare command, while a skip's authored `next:`
+      // is a sentence that may quote a command of its own, and wrapping that in
+      // backticks nests one code span inside another.
+      if (check.remedy) {
+        out.push(
+          check.status === "skip"
+            ? `  - _${checkRemedyWord(check.status)}:_ ${check.remedy}`
+            : `  - _${checkRemedyWord(check.status)}:_ \`${check.remedy}\``,
+        );
       }
       return out;
     };
 
     const lines: string[] = ["## Doctor", ""];
-    const { environment, machine, project } = partitionByBand(data.checks);
+    const { environment, global, project } = partitionByScope(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;
       if (heading) lines.push(`### ${heading}`, "");
       for (const check of checks) lines.push(...renderCheck(check));
     };
     section("", environment);
-    section(BAND_LABELS.global, machine);
-    section(BAND_LABELS.project, project);
+    section(SCOPE_LABELS.global, global);
+    section(SCOPE_LABELS.project, project);
     lines.push(
       "",
       `_${data.passed} passed, ${data.failed} failed, ${data.available} available, ${data.skipped} skipped_`,

package/src/capabilities/doctor/doctor.test.ts

@@ -1,5 +1,5 @@
 /**
- * `pragma doctor` — the environment checks plus the banded target rows.
+ * `pragma doctor` — the environment checks plus the scoped target rows.
  *
  * Runs against isolated HOME/cwd/XDG so the harness/config/completion checks are
  * deterministic (no harnesses, no config, no rc files). Covers the shape, a
@@ -34,7 +34,7 @@ import {
 } from "../../testing/fixtures/graph/canonical.js";
 import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
-import { bandedChecks } from "./checks/targetHealth.js";
+import { scopedChecks } from "./checks/targetHealth.js";
 import { doctorModule } from "./index.js";
 import { runChecks } from "./runChecks.js";
 import type { DoctorData } from "./types.js";
@@ -118,12 +118,13 @@ const byName = (data: DoctorData, name: string) =>
   data.checks.find((c) => c.name === name);
 
 describe("doctor — shape & spread", () => {
-  it("returns the environment checks plus one row per banded target", async () => {
+  it("returns the environment checks plus one row per scoped target", async () => {
     const data = await runChecks(bootRuntime(FLAGS, tmp("pragma-proj-")));
-    // Four unbanded environment checks, then the target table in both bands:
-    // all five targets are global, mcp and skills are also project.
-    expect(data.checks).toHaveLength(11);
-    expect(data.passed + data.failed + data.available + data.skipped).toBe(11);
+    // Four unscoped environment checks, then the target table in both scopes
+    // (all five targets are global, mcp and skills are also project) = 11,
+    // plus the two `harnesses` inventory rows, one per scope = 13.
+    expect(data.checks).toHaveLength(13);
+    expect(data.passed + data.failed + data.available + data.skipped).toBe(13);
     for (const check of data.checks) {
       expect(["pass", "fail", "available", "skip"]).toContain(check.status);
     }
@@ -133,14 +134,28 @@ describe("doctor — shape & spread", () => {
     // snapshot answers reads and the check passes, naming what it is reading.
     const pkgRefs = byName(data, "pack refs");
     expect(pkgRefs?.status).toBe("pass");
-    expect(pkgRefs?.detail).toContain("embedded snapshot @ ");
+    expect(pkgRefs?.detail).toContain("shipped with the CLI");
     expect(pkgRefs?.remedy).toBeUndefined();
+    // Provenance is one ITEM PER PACK, not a comma-joined string in the
+    // headline: four packs and two forty-character SHAs on one line was
+    // unreadable, and every other multi-part check here already uses items.
+    // The headline counts them; the items say which revision each one is.
+    expect(pkgRefs?.detail).toContain("packs");
+    expect((pkgRefs?.items?.length ?? 0) > 1).toBe(true);
+    for (const item of pkgRefs?.items ?? []) {
+      expect(item.label).not.toContain(",");
+      // A git hash is cut to seven — the length every other tool in this
+      // workflow prints, and short enough that four rows stay scannable.
+      expect(item.detail ?? "").not.toMatch(/[0-9a-f]{40}/);
+    }
 
-    // The banded rows carry the TARGET IDS verbatim — `mcp`, not "MCP
+    // The scoped rows carry the TARGET IDS verbatim — `mcp`, not "MCP
     // configured" — because the row name IS the fix command's argument. The
-    // environment checks stay unbanded.
-    const banded = data.checks.filter((c) => c.band !== undefined);
-    expect(banded.map((c) => `${c.band}:${c.name}`)).toEqual([
+    // environment checks stay unscoped. `harnesses` is the ONE scoped row that
+    // is not a target: an inventory of the machine, not something to set up, so
+    // it sits last in each scope and derives no `fix:`.
+    const scoped = data.checks.filter((c) => c.scope !== undefined);
+    expect(scoped.map((c) => `${c.scope}:${c.name}`)).toEqual([
       "global:config",
       "global:completions",
       "global:lsp",
@@ -148,18 +163,27 @@ describe("doctor — shape & spread", () => {
       "global:skills",
       "project:mcp",
       "project:skills",
+      "global:harnesses",
+      "project:harnesses",
     ]);
     // Every row that wants action names the exact command that repairs it,
-    // band included — the bijection, derived rather than authored.
-    for (const check of banded) {
+    // scope included — the bijection, derived rather than authored.
+    for (const check of scoped) {
       if (check.status === "fail" || check.status === "available") {
         expect(check.remedy).toBeDefined();
       }
     }
+    // The inventory never inflates the failure or the action count: it is only
+    // ever `pass` (this scope holds harnesses) or `skip` (it holds none), and it
+    // proposes nothing — the `mcp`/`skills` rows own every harness action.
+    for (const check of scoped.filter((c) => c.name === "harnesses")) {
+      expect(["pass", "skip"]).toContain(check.status);
+      expect(check.remedy).toBeUndefined();
+    }
     // No harnesses in an empty HOME/cwd, so both mcp rows skip; the project
-    // band is opt-in, so its absence is never a fault.
+    // scope is opt-in, so its absence is never a fault.
     expect(
-      banded.find((c) => c.band === "project" && c.name === "mcp")?.status,
+      scoped.find((c) => c.scope === "project" && c.name === "mcp")?.status,
     ).toBe("skip");
     // No global config in the isolated XDG — an opt-in that is not set up yet.
     expect(byName(data, "config")?.status).toBe("available");
@@ -190,8 +214,12 @@ describe("doctor — the pack-refs check", () => {
     const data = await runChecks(fixture.runtime);
     const pkgRefs = byName(data, "pack refs");
     expect(pkgRefs?.status).toBe("pass");
-    // The fixture pack's own provenance label, not the embedded snapshot's.
-    expect(pkgRefs?.detail).toContain("fixture");
+    // The fixture pack's own provenance label, not the embedded snapshot's —
+    // now carried as an item rather than inline, and passed through WHOLE
+    // because it parses as no scheme. An unreadable provenance is still
+    // provenance; dropping it would be the one failure this check exists to
+    // prevent.
+    expect(pkgRefs?.items?.map((item) => item.label)).toContain("fixture");
     expect(pkgRefs?.detail).not.toContain("embedded snapshot");
     await fixture.dispose();
   });
@@ -200,7 +228,7 @@ describe("doctor — the pack-refs check", () => {
 describe("doctor — the store check", () => {
   it("a store that fails to boot is an attributable fail, not a crash", async () => {
     const data = await runChecks(throwingStoreRuntime(tmp("pragma-proj-")));
-    expect(data.checks).toHaveLength(11);
+    expect(data.checks).toHaveLength(13);
     const store = byName(data, "store");
     expect(store?.status).toBe("fail");
     expect(store?.remedy).toBeTruthy();
@@ -242,23 +270,23 @@ describe("doctor — dispatch & MCP", () => {
     const envelope = await mcp.callTool("doctor");
     await mcp.cleanup();
     expect(envelope.ok).toBe(true);
-    expect((envelope.data as DoctorData).checks).toHaveLength(11);
+    expect((envelope.data as DoctorData).checks).toHaveLength(13);
   });
 });
 
-describe("doctor — the banded rows can see the GLOBAL band", () => {
-  it("reports a configured global-band entry as configured, not missing", async () => {
+describe("doctor — the scoped rows can see the GLOBAL scope", () => {
+  it("reports a configured global-scope entry as configured, not missing", async () => {
     // The regression this closes: detection recorded only each harness's
-    // DEFAULT band, so a server registered by `setup mcp --global` was invisible
+    // DEFAULT scope, so a server registered by `setup mcp --global` was invisible
     // and doctor reported it not-configured forever. The rows now come from the
-    // same target table `setup` writes through, enumerated in BOTH bands, so the
+    // same target table `setup` writes through, enumerated in BOTH scopes, so the
     // two surfaces cannot disagree about what they looked at.
     const cwd = tmp("pragma-doctor-proj-");
     mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // ⇒ Windsurf detected
     const home = process.env.HOME ?? "";
     const wsDir = join(home, ".codeium", "windsurf");
     mkdirSync(wsDir, { recursive: true });
-    // Exactly what a global-band `setup mcp` writes: no `cwd`, so the entry is
+    // Exactly what a global-scope `setup mcp` writes: no `cwd`, so the entry is
     // not pinned to whatever directory the registration ran from.
     writeFileSync(
       join(wsDir, "mcp_config.json"),
@@ -272,18 +300,175 @@ describe("doctor — the banded rows can see the GLOBAL band", () => {
     writeFileSync(join(binDir, "pragma"), "#!/bin/sh\nexit 0\n");
     chmodSync(join(binDir, "pragma"), 0o755);
 
-    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
-    const global = rows.find((r) => r.name === "mcp" && r.band === "global");
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const global = rows.find((r) => r.name === "mcp" && r.scope === "global");
     expect(global?.status).toBe("pass");
     expect(
       global?.items?.some((i) => i.label.includes("mcp_config.json")),
     ).toBe(true);
-    // ...and the project band stays an opt-in skip, never a fault.
-    const project = rows.find((r) => r.name === "mcp" && r.band === "project");
+    // ...and the project scope stays an opt-in skip, never a fault.
+    const project = rows.find((r) => r.name === "mcp" && r.scope === "project");
     expect(project?.status).toBe("skip");
   });
 });
 
+describe("doctor — the harness inventory", () => {
+  const VERBOSE: GlobalFlags = { ...FLAGS, verbose: true };
+  const inventory = (rows: Awaited<ReturnType<typeof scopedChecks>>) => ({
+    global: rows.find((r) => r.name === "harnesses" && r.scope === "global"),
+    project: rows.find((r) => r.name === "harnesses" && r.scope === "project"),
+  });
+
+  it("lists ONLY detected harnesses by default, by name and with their location", async () => {
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".vscode"), { recursive: true }); // ⇒ VS Code detected
+
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const { global, project } = inventory(rows);
+
+    // The project scope holds the hit — by NAME, with the file it resolves to.
+    expect(project?.status).toBe("pass");
+    expect(project?.detail).toBe("1 detected · 0 registered");
+    expect(project?.items?.map((i) => i.label)).toEqual(["VS Code"]);
+    expect(project?.items?.[0]?.status).toBe("available");
+    expect(project?.items?.[0]?.detail).toContain("detected, not registered");
+    expect(project?.items?.[0]?.detail).toContain(".vscode/mcp.json");
+
+    // Nothing detected in the global scope, and that is a skip — not a fault.
+    expect(global?.status).toBe("skip");
+    expect(global?.detail).toBe("no harnesses detected");
+    expect(global?.items).toBeUndefined();
+  });
+
+  it("--verbose lists every registry harness, undetected ones as a NON-failing skip", async () => {
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".vscode"), { recursive: true });
+
+    const rows = await scopedChecks(bootRuntime(VERBOSE, cwd), "pragma");
+    const { global, project } = inventory(rows);
+
+    // Every harness the registry knows, in both scopes.
+    expect(project?.items).toHaveLength(13);
+    expect(global?.items).toHaveLength(13);
+    expect(project?.detail).toBe("1 detected · 0 registered · 13 known");
+
+    // `types.ts` forbids inflating the failure count: a machine that simply
+    // does not have Cursor is not a broken machine.
+    for (const check of [global, project]) {
+      expect(["pass", "skip"]).toContain(check?.status);
+      for (const item of check?.items ?? []) {
+        expect(item.status).not.toBe("fail");
+        expect(["pass", "available", "skip"]).toContain(item.status);
+      }
+    }
+
+    const cursor = project?.items?.find((i) => i.label === "Cursor");
+    expect(cursor?.status).toBe("skip");
+    expect(cursor?.detail).toBe("not detected");
+  });
+
+  it("says where a harness DOES keep its config, rather than omitting it", async () => {
+    // `vscode` is `scope: "project"`, so it can NEVER carry a global entry. A
+    // verbose global listing that silently dropped it would read as a bug in
+    // the listing; the row says why instead. The mirror case is Windsurf, which
+    // is `scope: "global"` and keeps nothing per project.
+    //
+    // The sentence states the FACT, not the partition: `no Global band` named
+    // an internal word for the answer instead of giving it.
+    const rows = await scopedChecks(
+      bootRuntime(VERBOSE, tmp("pragma-doctor-proj-")),
+      "pragma",
+    );
+    const { global, project } = inventory(rows);
+
+    const vscodeGlobal = global?.items?.find((i) => i.label === "VS Code");
+    expect(vscodeGlobal?.detail).toBe(
+      "keeps no global config — it is per-project only",
+    );
+    expect(vscodeGlobal?.status).toBe("skip");
+
+    const windsurfProject = project?.items?.find((i) => i.label === "Windsurf");
+    expect(windsurfProject?.detail).toBe(
+      "keeps no per-project config — it is global only",
+    );
+    expect(windsurfProject?.status).toBe("skip");
+  });
+
+  it("reports a harness whose pragma entry is current as registered", async () => {
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".vscode"), { recursive: true });
+    // Byte-for-byte what a project-scope `setup mcp` writes for VS Code: its
+    // `servers` key, and the `cwd` a project registration pins.
+    writeFileSync(
+      join(cwd, ".vscode", "mcp.json"),
+      JSON.stringify({
+        servers: { pragma: { command: "pragma", args: ["mcp", "serve"], cwd } },
+      }),
+    );
+
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const { project } = inventory(rows);
+    expect(project?.detail).toBe("1 detected · 1 registered");
+    const vscode = project?.items?.find((i) => i.label === "VS Code");
+    expect(vscode?.status).toBe("pass");
+    expect(vscode?.detail).toContain("registered");
+    expect(vscode?.detail).not.toContain("not registered");
+  });
+
+  it("reports two harnesses sharing ONE file by their own keys, not by the file", async () => {
+    // The co-detection case. `.vscode/mcp.json` is written under TWO keys —
+    // VS Code's `servers` and Cline's `mcpServers` — and registering pragma
+    // for VS Code alone leaves the FILE half-configured, which `detectMcp`
+    // aggregates to `drifted` (correctly: a write is still owed). That
+    // aggregate is not either harness's standing, and reporting it per harness
+    // said both had a stale entry when one was current and the other had none.
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".vscode"), { recursive: true });
+    // Cline is detected ONLY by its installed extension, in the same directory
+    // that also proves VS Code is installed — so the two co-detect.
+    mkdirSync(
+      join(
+        process.env.HOME as string,
+        ".vscode",
+        "extensions",
+        "saoudrizwan.claude-dev-3.20.0",
+      ),
+      { recursive: true },
+    );
+    writeFileSync(
+      join(
+        process.env.HOME as string,
+        ".vscode",
+        "extensions",
+        "saoudrizwan.claude-dev-3.20.0",
+        "package.json",
+      ),
+      "{}",
+    );
+    // Only VS Code's key is registered; Cline's `mcpServers` is absent.
+    writeFileSync(
+      join(cwd, ".vscode", "mcp.json"),
+      JSON.stringify({
+        servers: { pragma: { command: "pragma", args: ["mcp", "serve"], cwd } },
+      }),
+    );
+
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const { project } = inventory(rows);
+    expect(project?.detail).toBe("2 detected · 1 registered");
+
+    const vscode = project?.items?.find((i) => i.label === "VS Code");
+    expect(vscode?.status).toBe("pass");
+    expect(vscode?.detail).toContain("registered — ");
+    expect(vscode?.detail).not.toContain("differs");
+
+    const cline = project?.items?.find((i) => i.label === "Cline");
+    expect(cline?.status).toBe("available");
+    expect(cline?.detail).toContain("detected, not registered");
+    expect(cline?.detail).not.toContain("differs");
+  });
+});
+
 describe("doctor — a blocked skill link path is never reported as current", () => {
   it("distinguishes a hand-placed real directory from a link that is correct", async () => {
     // Detection marks both `skipped` — there is nothing to do to either — so
@@ -299,8 +484,8 @@ describe("doctor — a blocked skill link path is never reported as current", ()
     // A hand-placed directory sitting exactly where the link would go.
     mkdirSync(join(cwd, ".agents", "skills", "my-skill"), { recursive: true });
 
-    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
-    const row = rows.find((r) => r.name === "skills" && r.band === "project");
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const row = rows.find((r) => r.name === "skills" && r.scope === "project");
     expect(row?.status).not.toBe("pass");
     expect(row?.detail).toContain("real directory");
     // And the remedy is the one that settles it — rerunning setup skips it.
@@ -308,6 +493,33 @@ describe("doctor — a blocked skill link path is never reported as current", ()
   });
 });
 
+describe("doctor — an EMPTY skills root is not diagnosed as an ABSENT one", () => {
+  it("reports an existing but empty project skills root as holding none", async () => {
+    // doctor publishes a DIAGNOSIS, so a wrong one is worse than a vague one:
+    // the shared skip line told the user `.pragma/skills` "is absent" while
+    // they were looking at the directory. Both surfaces read the same
+    // `rootExists` the detection already carries.
+    const cwd = tmp("pragma-doctor-proj-");
+    mkdirSync(join(cwd, ".pragma", "skills"), { recursive: true });
+
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const row = rows.find((r) => r.name === "skills" && r.scope === "project");
+    expect(row?.status).toBe("skip"); // still nothing to reconcile...
+    expect(row?.detail).toContain("is empty"); // ...for the true reason
+    expect(row?.detail).not.toContain("does not exist");
+  });
+
+  it("still reports a missing project skills root as absent", async () => {
+    const rows = await scopedChecks(
+      bootRuntime(FLAGS, tmp("pragma-doctor-proj-")),
+      "pragma",
+    );
+    const row = rows.find((r) => r.name === "skills" && r.scope === "project");
+    expect(row?.status).toBe("skip");
+    expect(row?.detail).toContain("does not exist");
+  });
+});
+
 describe("doctor — an unconfigured opt-in integration is available, not a fault", () => {
   it("a detected harness with no MCP entry reports available with the setup command", async () => {
     // Windsurf is detected (project signal) but nothing is configured. A fresh
@@ -317,11 +529,11 @@ describe("doctor — an unconfigured opt-in integration is available, not a faul
     const cwd = tmp("pragma-doctor-proj-");
     mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // ⇒ Windsurf detected
 
-    const rows = await bandedChecks(bootRuntime(FLAGS, cwd), "pragma");
-    const check = rows.find((r) => r.name === "mcp" && r.band === "global");
+    const rows = await scopedChecks(bootRuntime(FLAGS, cwd), "pragma");
+    const check = rows.find((r) => r.name === "mcp" && r.scope === "global");
     expect(check?.status).toBe("available");
-    expect(check?.detail).toContain("not configured");
-    // The fix is the target's own invocation, derived from the row's id + band.
+    expect(check?.detail).toContain("not registered");
+    // The fix is the target's own invocation, derived from the row's id + scope.
     expect(check?.remedy).toBe("pragma setup mcp");
   });
 });

package/src/capabilities/doctor/doctor.verb.ts

@@ -20,8 +20,13 @@ import type { DoctorData } from "./types.js";
 
 const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   path: ["doctor"],
-  summary: "Check environment health and every setup target, in both bands.",
-  doc: "Reports the environment checks and then one row per setup target in each band, as pass, fail, available (an opt-in integration not yet set up), or skip, with inline remedies. Every banded row is named after the setup target that repairs it. Storeless by default; the store check boots lazily and never fails the run.",
+  summary:
+    "Check your environment and every setup target, globally and in this project.",
+  // Two house rules constrain this string and both are PROTECTED: it may not
+  // name the distribution (`identity.test.ts`) and it may not spell a CLI flag
+  // (`toolDescriptions.test.ts`), so the inventory's widening is described as
+  // "the verbose global flag" rather than by its spelling.
+  doc: "Reports the environment checks first, then one row per setup target — once for your home directory, once for this project. Each row is pass, fail, available (an optional integration you have not set up yet), or skip (nothing to do here, and the row says why), with the next step printed inline. Every row is named after the setup target that repairs it, except `harnesses`: a listing, per scope, of the AI harnesses found on this machine and whether this CLI's MCP server is registered in each — the ones actually found, or every harness it knows about under the verbose global flag. Needs no store; the store check boots lazily and never fails the run.",
   params: [],
   output: { formatters: doctorFormatters },
   examples: [