@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -0,0 +1,170 @@
+/**
+ * Render goldens for `pragma doctor` — the band-grouped report AND the plain-path
+ * color gate (F1).
+ *
+ * The banded Global/Project grouping (`partitionByBand` → sections) is pinned for
+ * both the plain and llm formatters, locking the unified Global/Project
+ * vocabulary (the report no longer says MACHINE/PROJECT). Separately, the plain
+ * formatter tints ONLY on a color-capable TTY: `supports-color` reports a
+ * non-zero `chalk.level` off a TTY under `GITHUB_ACTIONS` / `FORCE_COLOR`, so the
+ * `isTTY` gate (via the shared style seam) keeps ANSI out of
+ * `doctor --format plain | tee`. `beforeEach` forces color OFF so the banded
+ * goldens stay deterministic; the color tests opt a level back in explicitly.
+ */
+
+import chalk from "chalk";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { doctorFormatters } from "./doctor.render.js";
+import type { DoctorData } from "./types.js";
+
+/** A fixture spanning all three groups: environment (no band), global, project. */
+const BANDED_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v20 detected" },
+    {
+      name: "Shell completions",
+      status: "pass",
+      detail: "zsh up to date and resolving",
+      band: "global",
+    },
+    {
+      name: "MCP configured",
+      status: "fail",
+      detail: "detected Windsurf but pragma not configured",
+      remedy: "pragma setup mcp",
+      band: "global",
+    },
+    {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+      band: "project",
+    },
+  ],
+  passed: 2,
+  failed: 1,
+  skipped: 1,
+};
+
+/** A fixture spanning pass/fail/skip, sub-items, and a remedy — every color path. */
+const COLOR_DATA: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v24" },
+    {
+      name: "pack refs",
+      status: "fail",
+      detail: "packs are configured but the store has not been built",
+      items: [
+        { label: "core", status: "fail", detail: "not built" },
+        { label: "ui", status: "fail", detail: "not built" },
+      ],
+      remedy: "pragma sources update",
+    },
+    { name: "Skills symlinked", status: "skip", detail: "no harness" },
+  ],
+  passed: 1,
+  failed: 1,
+  skipped: 1,
+};
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+let prevLevel: number;
+beforeAll(() => {
+  prevLevel = chalk.level;
+});
+beforeEach(() => {
+  chalk.level = 0; // color-free ⇒ deterministic text (color tests opt back in)
+});
+afterAll(() => {
+  chalk.level = prevLevel;
+});
+
+describe("doctor render — banded plain report", () => {
+  it("groups checks under Global then Project headers (unified labels)", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    const lines = out.split("\n");
+    // The two banded section headers use the unified Global/Project vocabulary.
+    expect(lines).toContain("Global");
+    expect(lines).toContain("Project");
+    // The superseded MACHINE/PROJECT labels are gone.
+    expect(out).not.toContain("MACHINE");
+    expect(out).not.toMatch(/^PROJECT$/m);
+  });
+
+  it("orders environment → Global → Project, banding each check correctly", () => {
+    const out = doctorFormatters.plain(BANDED_DATA);
+    // Environment check leads with no header; the two global-band checks sit
+    // under Global; the project-band check sits under Project.
+    const at = (needle: string): number => out.indexOf(needle);
+    expect(at("Node version")).toBeGreaterThanOrEqual(0);
+    expect(at("Node version")).toBeLessThan(at("Global"));
+    expect(at("Global")).toBeLessThan(at("Shell completions"));
+    expect(at("MCP configured")).toBeLessThan(at("Project"));
+    expect(at("Project")).toBeLessThan(at("Skills symlinked"));
+    // A failing banded check keeps its inline remedy under its band.
+    expect(out).toContain("fix: pragma setup mcp");
+    // The tally closes the report.
+    expect(out).toContain("2 passed");
+  });
+});
+
+describe("doctor render — banded llm report", () => {
+  it("groups checks under ### Global then ### Project headers", () => {
+    const out = doctorFormatters.llm(BANDED_DATA);
+    expect(out).toContain("### Global");
+    expect(out).toContain("### Project");
+    expect(out).not.toContain("### Machine");
+    const at = (needle: string): number => out.indexOf(needle);
+    // Environment leads (no section header), then the two banded sections.
+    expect(at("Node version")).toBeLessThan(at("### Global"));
+    expect(at("### Global")).toBeLessThan(at("Shell completions"));
+    expect(at("Shell completions")).toBeLessThan(at("### Project"));
+    expect(at("### Project")).toBeLessThan(at("Skills symlinked"));
+    expect(out).toContain("_2 passed, 1 failed, 1 skipped_");
+  });
+});
+
+describe("doctor render — json", () => {
+  it("is the exact DoctorData round-trip", () => {
+    expect(JSON.parse(doctorFormatters.json(BANDED_DATA))).toEqual(BANDED_DATA);
+  });
+});
+
+describe("doctor render — piped output is ANSI-free (F1)", () => {
+  it("plain emits ZERO ANSI off a TTY even when chalk reports color (CI/FORCE_COLOR)", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = doctorFormatters.plain(COLOR_DATA);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      // The structural, color-free content still renders (glyphs, names, remedy).
+      expect(out).toContain("pragma doctor");
+      expect(out).toContain("✓  Node version");
+      expect(out).toContain("✗  pack refs");
+      expect(out).toContain("○  Skills symlinked");
+      expect(out).toContain("↳ fix: pragma sources update");
+      expect(out).toContain("  1 passed · 1 failed · 1 skipped");
+    });
+  });
+});
+
+describe("doctor render — color ON (attended TTY)", () => {
+  it("plain tints the output on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the literal ESC byte is the point
+      expect(doctorFormatters.plain(COLOR_DATA)).toMatch(/\x1b\[/);
+    });
+  });
+});

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

@@ -1,35 +1,75 @@
 /**
- * Formatters for `pragma doctor` — plain (chalk), llm (Markdown), json.
+ * Formatters for `pragma doctor` — plain (chalk on a TTY), llm (Markdown), json.
  *
  * Ported from the old shell's `doctor/formatters/doctor.ts`, retargeted at the
- * kernel `Formatters` contract.
+ * kernel `Formatters` contract. The plain path is colored ONLY on a color-capable
+ * TTY: it consults the shared {@link defaultStyle} seam (stdout `isTTY` AND a
+ * non-zero chalk level), so a piped / redirected / CI run — where `supports-color`
+ * can report a level with no TTY (`GITHUB_ACTIONS`, `FORCE_COLOR`) — renders the
+ * plain form byte-for-byte instead of leaking ANSI into `doctor --format plain`.
+ * 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 type { Formatters } from "../../kernel/spec/types.js";
+import { BAND_LABELS } from "../shared/bands.js";
 import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
 
-/** Status icons for pass/fail/skip results (checks and sub-items). */
-const STATUS_ICONS: Record<CheckStatus, string> = {
-  pass: chalk.green("✓"),
-  fail: chalk.red("✗"),
-  skip: chalk.yellow("○"),
+/** Uncolored status glyphs — tinted at render time (never baked at module load). */
+const STATUS_GLYPHS: Record<CheckStatus, string> = {
+  pass: "✓",
+  fail: "✗",
+  skip: "○",
 };
 
-const SUB_BULLET = chalk.dim("·");
-const FIX_ARROW = chalk.cyan("↳");
+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, yellow skip. */
+function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
+  const glyph = STATUS_GLYPHS[status];
+  if (status === "pass") return style.green(glyph);
+  if (status === "fail") return style.red(glyph);
+  return style.yellow(glyph);
+}
+
 /**
  * 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.
  */
-function formatCheckPlain(check: CheckResult, nameWidth: number): string[] {
+function formatCheckPlain(
+  check: CheckResult,
+  nameWidth: number,
+  style: DoctorStyle,
+): string[] {
   const name = check.name.padEnd(nameWidth);
-  const label = check.status === "fail" ? chalk.red(name) : chalk.bold(name);
+  const label = check.status === "fail" ? style.red(name) : style.bold(name);
   const lines = [
-    `  ${STATUS_ICONS[check.status]}  ${label}  ${chalk.dim(check.detail)}`,
+    `  ${paintGlyph(check.status, style)}  ${label}  ${style.dim(check.detail)}`,
   ];
 
   if (check.items && check.items.length > 0) {
@@ -38,55 +78,86 @@ function formatCheckPlain(check: CheckResult, nameWidth: number): string[] {
     for (const item of check.items) {
       const icon = anyStatus
         ? item.status
-          ? `${STATUS_ICONS[item.status]} `
+          ? `${paintGlyph(item.status, style)} `
           : "  "
         : "";
       const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
-      const detail = item.detail ? `  ${chalk.dim(item.detail)}` : "";
-      lines.push(`${INDENT}${SUB_BULLET} ${icon}${itemLabel}${detail}`);
+      const detail = item.detail ? `  ${style.dim(item.detail)}` : "";
+      lines.push(
+        `${INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
+      );
     }
   }
 
   if (check.status === "fail" && check.remedy) {
-    lines.push(`${INDENT}${FIX_ARROW} ${chalk.cyan("fix:")} ${check.remedy}`);
+    lines.push(
+      `${INDENT}${style.cyan(FIX_ARROW)} ${style.cyan("fix:")} ${check.remedy}`,
+    );
   }
 
   return lines;
 }
 
 /** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
-function formatSummary(data: DoctorData): string {
-  const parts = [chalk.green(`${data.passed} passed`)];
+function formatSummary(data: DoctorData, style: DoctorStyle): string {
+  const parts = [style.green(`${data.passed} passed`)];
   parts.push(
     data.failed > 0
-      ? chalk.red(`${data.failed} failed`)
-      : chalk.dim(`${data.failed} failed`),
+      ? style.red(`${data.failed} failed`)
+      : style.dim(`${data.failed} failed`),
   );
   parts.push(
     data.skipped > 0
-      ? chalk.yellow(`${data.skipped} skipped`)
-      : chalk.dim(`${data.skipped} skipped`),
+      ? style.yellow(`${data.skipped} skipped`)
+      : style.dim(`${data.skipped} skipped`),
   );
-  return `  ${parts.join(chalk.dim(" · "))}`;
+  return `  ${parts.join(style.dim(" · "))}`;
+}
+
+/**
+ * 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.
+ */
+function partitionByBand(checks: readonly CheckResult[]): {
+  environment: CheckResult[];
+  machine: 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"),
+  };
 }
 
 export const doctorFormatters: Formatters<DoctorData> = {
   plain(data) {
+    const style = doctorStyle();
     const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
-    const lines: string[] = [chalk.bold("pragma doctor"), ""];
-    for (const check of data.checks) {
-      lines.push(...formatCheckPlain(check, nameWidth));
-    }
-    lines.push("", formatSummary(data));
+    const lines: string[] = [style.bold(`${BIN_NAME} doctor`), ""];
+    const { environment, machine, project } = partitionByBand(data.checks);
+    const section = (heading: string, checks: CheckResult[]): void => {
+      if (checks.length === 0) return;
+      if (heading) lines.push(style.bold(heading));
+      for (const check of checks)
+        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.
+    section("", environment);
+    section(BAND_LABELS.global, machine);
+    section(BAND_LABELS.project, project);
+    lines.push(formatSummary(data, style));
     return lines.join("\n");
   },
 
   llm(data) {
-    const lines: string[] = ["## Doctor", ""];
-    for (const check of data.checks) {
+    const renderCheck = (check: CheckResult): string[] => {
       const icon =
         check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
-      lines.push(`- ${icon} **${check.name}**: ${check.detail}`);
+      const out = [`- ${icon} **${check.name}**: ${check.detail}`];
       for (const item of check.items ?? []) {
         const itemIcon =
           item.status === "pass"
@@ -97,12 +168,24 @@ export const doctorFormatters: Formatters<DoctorData> = {
                 ? "○ "
                 : "";
         const detail = item.detail ? `: ${item.detail}` : "";
-        lines.push(`  - ${itemIcon}${item.label}${detail}`);
+        out.push(`  - ${itemIcon}${item.label}${detail}`);
       }
       if (check.status === "fail" && check.remedy) {
-        lines.push(`  - _fix:_ \`${check.remedy}\``);
+        out.push(`  - _fix:_ \`${check.remedy}\``);
       }
-    }
+      return out;
+    };
+
+    const lines: string[] = ["## Doctor", ""];
+    const { environment, machine, project } = partitionByBand(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);
     lines.push(
       "",
       `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,

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

@@ -8,7 +8,7 @@
  * the MCP read-only envelope.
  */
 
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -28,6 +28,7 @@ import {
 } from "../../testing/fixtures/graph/canonical.js";
 import { bootFixtureRuntime } from "../../testing/helpers/fixtureGraph.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { checkMcpConfigured } from "./checks/checkMcpConfigured.js";
 import { doctorModule } from "./index.js";
 import { runChecks } from "./runChecks.js";
 import type { DoctorData } from "./types.js";
@@ -50,17 +51,24 @@ const tmp = (prefix: string): string => {
 
 let prevHome: string | undefined;
 let prevXdg: string | undefined;
+let prevPath: string | undefined;
 beforeEach(() => {
   prevHome = process.env.HOME;
   prevXdg = process.env.XDG_CONFIG_HOME;
+  prevPath = process.env.PATH;
   // Empty HOME/XDG so `~`-based harness signals, rc files, and the global config
   // are all absent — the harness/config/completion checks become deterministic.
   process.env.HOME = tmp("pragma-doctor-home-");
   process.env.XDG_CONFIG_HOME = tmp("pragma-doctor-xdg-");
+  // Point PATH at an empty dir so no harness `process` signal fires off the
+  // ambient PATH (e.g. a `claude`/`codex` binary on the CI/dev host) — keeping
+  // "no harnesses detected" deterministic regardless of what is installed.
+  process.env.PATH = tmp("pragma-doctor-path-");
 });
 afterEach(() => {
   process.env.HOME = prevHome;
   process.env.XDG_CONFIG_HOME = prevXdg;
+  process.env.PATH = prevPath;
   for (const dir of roots) rmSync(dir, { recursive: true, force: true });
   roots.length = 0;
 });
@@ -71,10 +79,9 @@ const defaultLayers: ConfigLayers = {
     tier: "default",
     channel: "default",
     detail: "default",
-    packages: "default",
+    packs: "default",
     stories: "default",
     prefixes: "default",
-    prompts: "default",
   },
   global: { path: "", exists: false },
   project: { exists: false },
@@ -114,12 +121,12 @@ describe("doctor — shape & spread", () => {
     }
     // Deterministic under the isolated env.
     expect(byName(data, "Node version")?.status).toBe("pass");
-    // The 3 default-config packages are configured but not locked here → an
-    // attributable fail listing them, with the sources-update remedy.
-    const pkgRefs = byName(data, "package refs");
-    expect(pkgRefs?.status).toBe("fail");
-    expect(pkgRefs?.remedy).toBe("pragma sources update");
-    expect(pkgRefs?.items?.length).toBe(3);
+    // Nothing built, but the packs are the distribution's own — so the embedded
+    // 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?.remedy).toBeUndefined();
     // No harnesses in an empty HOME/cwd — attributable fail + skips.
     expect(byName(data, "MCP configured")?.status).toBe("fail");
     expect(byName(data, "Skills symlinked")?.status).toBe("skip");
@@ -129,6 +136,36 @@ describe("doctor — shape & spread", () => {
   });
 });
 
+describe("doctor — the pack-refs check", () => {
+  it("a project with its OWN packs and nothing built is an attributable fail", async () => {
+    // The install that must never read healthy: `origins.packs` is "project",
+    // so the embedded snapshot is a DIFFERENT graph and every read throws
+    // STORE_UNAVAILABLE. Doctor has to say so and name the fix, rather than
+    // pass by listing packs it is not actually reading from.
+    const cwd = tmp("pragma-unbuilt-");
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      'export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n',
+    );
+    const data = await runChecks(bootRuntime(FLAGS, cwd));
+    const pkgRefs = byName(data, "pack refs");
+    expect(pkgRefs?.status).toBe("fail");
+    expect(pkgRefs?.detail).toContain("the store has not been built");
+    expect(pkgRefs?.remedy).toBe("pragma sources update");
+  });
+
+  it("a project pointed at its own built pack passes, naming that pack", async () => {
+    const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL });
+    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");
+    expect(pkgRefs?.detail).not.toContain("embedded snapshot");
+    await fixture.dispose();
+  });
+});
+
 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-")));
@@ -177,3 +214,25 @@ describe("doctor — dispatch & MCP", () => {
     expect((envelope.data as DoctorData).checks).toHaveLength(9);
   });
 });
+
+describe("doctor — MCP checks band by detected harness scope, not check name", () => {
+  it("bands a configured GLOBAL-scope harness (Windsurf) as global", async () => {
+    // Windsurf is a global-only harness whose MCP config lives in the home band.
+    // The old static map tagged every "MCP configured" result PROJECT; the fix
+    // derives the band from the harness's real scope, so this reports `global`.
+    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 });
+    writeFileSync(
+      join(wsDir, "mcp_config.json"),
+      JSON.stringify({ mcpServers: { pragma: { command: "pragma" } } }),
+    );
+
+    const check = await checkMcpConfigured(cwd);
+    expect(check.status).toBe("pass");
+    expect(check.detail).toContain("Windsurf");
+    expect(check.band).toBe("global"); // NOT the old static "project"
+  });
+});

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

@@ -12,6 +12,7 @@
  * `doctor-exit-zero-with-failures`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import { doctorFormatters } from "./doctor.render.js";
@@ -24,8 +25,11 @@ const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   params: [],
   output: { formatters: doctorFormatters },
   examples: [
-    { cmd: "pragma doctor" },
-    { cmd: "pragma doctor --format json", note: "machine-readable checks" },
+    { cmd: `${BIN_NAME} doctor` },
+    {
+      cmd: `${BIN_NAME} doctor --format json`,
+      note: "machine-readable checks",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/doctor/runChecks.ts

@@ -8,6 +8,7 @@
  * neither the checks nor `@canonical/harnesses` land on the fast path.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { checkConfigFile } from "./checks/checkConfigFile.js";
 import { checkKeStore } from "./checks/checkKeStore.js";
@@ -18,7 +19,31 @@ import { checkPackageRefs } from "./checks/checkPackageRefs.js";
 import { checkPragmaVersion } from "./checks/checkPragmaVersion.js";
 import { checkShellCompletions } from "./checks/checkShellCompletions.js";
 import { checkSkillsSymlinked } from "./checks/checkSkillsSymlinked.js";
-import type { CheckResult, DoctorData } from "./types.js";
+import type { CheckResult, DoctorData, ScopeBand } from "./types.js";
+
+/**
+ * The band a check statically concerns, by name — for checks whose band is
+ * fixed by construction: skills always symlink into the per-repo project dir
+ * (`skillsPath` is project-rooted), and completions install into the user/home
+ * shell dir. The MCP checks are NOT here: they detect harnesses across BOTH
+ * bands, so each derives its own band from what it found (see `deriveBand`) and
+ * sets it on its own result — {@link attachBand} preserves that.
+ */
+const CHECK_BANDS: Record<string, ScopeBand> = {
+  "Skills symlinked": "project",
+  "Shell completions": "global",
+};
+
+/**
+ * Attach a band tag to a check result. A check that already set its own band
+ * (the harness-derived MCP checks) keeps it; otherwise the static
+ * {@link CHECK_BANDS} map fills one in by name, if defined.
+ */
+function attachBand(result: CheckResult): CheckResult {
+  if (result.band !== undefined) return result;
+  const band = CHECK_BANDS[result.name];
+  return band ? { ...result, band } : result;
+}
 
 /**
  * Each check paired with the display name used if it rejects. The fallback name
@@ -31,9 +56,9 @@ function buildChecks(
 ): readonly [string, Promise<CheckResult>][] {
   return [
     ["Node version", checkNodeVersion()],
-    ["pragma version", checkPragmaVersion(rt)],
-    ["pragma config", checkConfigFile(rt)],
-    ["package refs", checkPackageRefs(rt)],
+    [`${BIN_NAME} version`, checkPragmaVersion(rt)],
+    [`${BIN_NAME} config`, checkConfigFile(rt)],
+    ["pack refs", checkPackageRefs(rt)],
     ["ke store", checkKeStore(rt)],
     ["Shell completions", checkShellCompletions(rt.cwd)],
     ["MCP configured", checkMcpConfigured(rt.cwd)],
@@ -53,16 +78,15 @@ export async function runChecks(rt: PragmaRuntime): Promise<DoctorData> {
   const checks: CheckResult[] = await Promise.all(
     buildChecks(rt).map(async ([name, promise]): Promise<CheckResult> => {
       try {
-        return await promise;
+        return attachBand(await promise);
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        return {
+        return attachBand({
           name,
           status: "fail",
           detail: `Check threw an unexpected error: ${reason}`,
-          remedy:
-            "Re-run `pragma doctor`; if it persists, report this as a bug.",
-        };
+          remedy: `Re-run \`${BIN_NAME} doctor\`; if it persists, report this as a bug.`,
+        });
       }
     }),
   );

package/src/capabilities/doctor/types.ts

@@ -2,12 +2,19 @@
  * Data shapes for `pragma doctor` (ported verbatim from the old shell).
  */
 
+/**
+ * One of the two config bands a check can concern. Mirrors the harnesses
+ * `ScopeBand` structurally but is redeclared here so this statically-reachable
+ * type module never pulls the harnesses runtime into the fast-path module graph.
+ */
+export type ScopeBand = "project" | "global";
+
 /** Status of a doctor check or one of its sub-items. */
 export type CheckStatus = "pass" | "fail" | "skip";
 
 /**
  * A structured sub-item under a check — e.g. one resolved package under
- * `package refs`, or one unresolvable server under `MCP commands`. Lets the
+ * `pack refs`, or one unresolvable server under `MCP commands`. Lets the
  * formatter render an indented, aligned breakdown instead of cramming
  * everything into a single `detail` string.
  */
@@ -30,6 +37,14 @@ export interface CheckResult {
   readonly items?: readonly CheckItem[];
   /** Remedial instruction shown inline under a failing check. */
   readonly remedy?: string;
+  /**
+   * Which config band the check concerns, if any: `global` for the user/home
+   * level (shell completions), `project` for per-repo config (skills). The MCP
+   * checks derive their band from the harnesses they found. The renderer groups
+   * banded checks into Global/Project sections; environment checks (Node,
+   * versions, store) carry no band.
+   */
+  readonly band?: ScopeBand;
 }
 
 /** Aggregated results from all doctor checks. */