@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/setup/setup.test.ts

@@ -185,7 +185,11 @@ describe("setup mcp — recap gate", () => {
     mkdirSync(join(cwd, ".cursor"), { recursive: true });
     const configPath = join(cwd, ".cursor", "mcp.json");
 
-    const { generator } = await buildSetupPlan(bootRuntime(FLAGS, cwd), "mcp");
+    const { generator } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "mcp",
+      "both",
+    );
     // A handler that declines EVERYTHING (incl. execute's "Proceed?" gate) must
     // fail the run cleanly — the GENERATOR_CANCELLED code the boundary renders
     // as a plain "Cancelled." — and write nothing.
@@ -197,6 +201,207 @@ describe("setup mcp — recap gate", () => {
   });
 });
 
+describe("setup mcp — scope & dedup", () => {
+  // Isolate PATH so a `claude`/`codex` on the host PATH can't inject harnesses
+  // via a `process` signal — detection is driven only by the dirs each test makes.
+  let prevPath: string | undefined;
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    process.env.PATH = tmp("pragma-scope-path-");
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  it("writes both VS Code and Cline keys into one .vscode/mcp.json (7a dedup)", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".vscode"), { recursive: true }); // VS Code (dir signal)
+    // Cline is detected by its extension (NOT the .vscode dir), so install a fake
+    // one under the isolated HOME — both harnesses then resolve to the SAME
+    // .vscode/mcp.json, which is what the two-level dedup write must handle. The
+    // extension is matched by its `package.json` manifest, so write one.
+    const clineExt = join(
+      process.env.HOME ?? "",
+      ".vscode",
+      "extensions",
+      "saoudrizwan.claude-dev-1.0.0",
+    );
+    mkdirSync(clineExt, { recursive: true });
+    writeFileSync(join(clineExt, "package.json"), "{}");
+    const outcome = await executeVerb(
+      verbOf("mcp"),
+      {},
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const config = JSON.parse(
+      readFileSync(join(cwd, ".vscode", "mcp.json"), "utf-8"),
+    );
+    // VS Code writes under `servers`, Cline under `mcpServers` — the two-level
+    // dedup makes two writes to one file, each preserving the other's key.
+    expect(config.servers?.pragma?.command).toBe("pragma");
+    expect(config.mcpServers?.pragma?.command).toBe("pragma");
+  });
+
+  it("--local writes the project config and skips a global-only harness", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const home = process.env.HOME ?? "";
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project scope
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // global scope
+    await executeVerb(
+      verbOf("mcp"),
+      { local: true },
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(true);
+    expect(
+      existsSync(join(home, ".codeium", "windsurf", "mcp_config.json")),
+    ).toBe(false);
+  });
+
+  it("--global writes a global harness's home config, skipping project harnesses", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const home = process.env.HOME ?? "";
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // global scope
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project scope
+    await executeVerb(
+      verbOf("mcp"),
+      { global: true },
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    const windsurfHome = JSON.parse(
+      readFileSync(
+        join(home, ".codeium", "windsurf", "mcp_config.json"),
+        "utf-8",
+      ),
+    );
+    expect(windsurfHome.mcpServers?.pragma?.command).toBe("pragma");
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(false);
+  });
+
+  // The `--scope <enum>` values (project/global/both) resolve independently of
+  // the `--global`/`--local` boolean sugars above — a distinct resolveScope arm.
+  it("--scope project (the enum) writes the project config, skipping a global harness", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const home = process.env.HOME ?? "";
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project scope
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // global scope
+    await executeVerb(
+      verbOf("mcp"),
+      { scope: "project" },
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(true);
+    expect(
+      existsSync(join(home, ".codeium", "windsurf", "mcp_config.json")),
+    ).toBe(false);
+  });
+
+  it("--scope global (the enum) writes the home config, skipping a project harness", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const home = process.env.HOME ?? "";
+    mkdirSync(join(cwd, ".windsurf"), { recursive: true }); // global scope
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project scope
+    await executeVerb(
+      verbOf("mcp"),
+      { scope: "global" },
+      YES,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(
+      existsSync(join(home, ".codeium", "windsurf", "mcp_config.json")),
+    ).toBe(true);
+    expect(existsSync(join(cwd, ".cursor", "mcp.json"))).toBe(false);
+  });
+});
+
+describe("setup mcp — customize opt-in gate (Item 6)", () => {
+  it("gates the per-file multiselect behind an explicit customize=true", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // ⇒ one MCP target group
+    const { generator } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "mcp",
+      "both",
+    );
+    const customize = generator.prompts.find((p) => p.name === "customize");
+    const targets = generator.prompts.find((p) => p.name === "mcpTargets");
+    // The gate is an opt-in confirm that defaults to NOT customizing.
+    expect(customize?.type).toBe("confirm");
+    expect(customize?.default).toBe(false);
+    // The per-file multiselect only surfaces after an explicit yes — so the
+    // "all" default configures every deduped file without an extra question.
+    expect(targets?.when?.({})).toBe(false);
+    expect(targets?.when?.({ customize: false })).toBe(false);
+    expect(targets?.when?.({ customize: true })).toBe(true);
+  });
+});
+
+describe("setup (run-all wizard) — scope threading", () => {
+  // Isolate PATH so an ambient `claude`/`codex` can't inject a harness via a
+  // `process` signal — detection is driven only by the dirs each test makes.
+  let prevPath: string | undefined;
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    process.env.PATH = tmp("pragma-runall-path-");
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  /** Seed a discoverable skill so the project-band skills step is offerable. */
+  const seedSkill = (cwd: string): void => {
+    const dir = join(cwd, ".pragma", "skills", "s");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      "---\nname: s\ndescription: A skill.\n---\n",
+    );
+  };
+
+  it("--local omits the global-band completions + lsp steps, keeping project steps", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true }); // project-band MCP target
+    seedSkill(cwd); // project-band skills step
+    const outcome = await executeVerb(
+      setupSelfVerb,
+      { local: true },
+      DRY,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const plan = outcome.stdout ?? "";
+    // The global-band steps are gone under --local (the bug: they used to run).
+    expect(plan).not.toContain(completionScriptPath("zsh"));
+    expect(plan).not.toContain("terrazzo-lsp-extension");
+    // The project-band steps remain: MCP into .cursor, skills into .agents/skills.
+    expect(plan).toContain("mcp.json");
+    expect(plan).toContain(".agents/skills");
+  });
+
+  it("--global omits the project-band skills step, keeping global steps", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    seedSkill(cwd); // WOULD be offered under the default `both`
+    const outcome = await executeVerb(
+      setupSelfVerb,
+      { global: true },
+      DRY,
+      bootRuntime(FLAGS, cwd),
+    );
+    expect(outcome.exitCode).toBe(0);
+    const plan = outcome.stdout ?? "";
+    // The global-band steps are present under --global.
+    expect(plan).toContain(completionScriptPath("zsh"));
+    expect(plan).toContain("terrazzo-lsp-extension");
+    // The project-band skills step is gone (the bug: it used to run under --global).
+    expect(plan).not.toContain(".agents/skills");
+  });
+});
+
 describe("setup skills", () => {
   it("empty skills raise EMPTY_RESULTS on the direct sub-verb", async () => {
     const cwd = tmp("pragma-setup-proj-");
@@ -261,6 +466,152 @@ describe("setup lsp — missing-binary guard (bunx absent)", () => {
   });
 });
 
+describe("setup — idempotent detection of already-present config", () => {
+  // Isolate PATH so an ambient harness can't inject via a `process` signal.
+  let prevPath: string | undefined;
+  beforeEach(() => {
+    prevPath = process.env.PATH;
+    process.env.PATH = tmp("pragma-idem-path-");
+  });
+  afterEach(() => {
+    process.env.PATH = prevPath;
+  });
+
+  it("mcp: a second run detects the already-configured file (byte-identical rewrite)", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const configPath = join(cwd, ".cursor", "mcp.json");
+
+    // First run writes the pragma entry.
+    await executeVerb(verbOf("mcp"), {}, YES, bootRuntime(FLAGS, cwd));
+    const firstBody = readFileSync(configPath, "utf-8");
+
+    // Detection now classifies the group `configured`.
+    const { toResult } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "mcp",
+      "both",
+    );
+    const result = toResult({});
+    expect(result.kind).toBe("mcp");
+    if (result.kind === "mcp") {
+      expect(result.targets.at(0)?.state).toBe("configured");
+    }
+
+    // The wizard default-DESELECTS a configured target (so a plain re-run offers
+    // it unchecked) — proven on the generated multiselect's default.
+    const { generator } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "mcp",
+      "both",
+    );
+    const multiselect = generator.prompts.find((p) => p.name === "mcpTargets");
+    expect(multiselect?.default).toEqual([]); // the only file is configured
+    expect(
+      (multiselect?.choices ?? []).some((c) =>
+        typeof c === "object" && "label" in c
+          ? c.label.includes("already configured")
+          : false,
+      ),
+    ).toBe(true);
+
+    // A real second run is idempotent: the file stays byte-identical (the
+    // read-modify-write re-merges the SAME pragma entry).
+    await executeVerb(verbOf("mcp"), {}, YES, bootRuntime(FLAGS, cwd));
+    expect(readFileSync(configPath, "utf-8")).toBe(firstBody);
+  });
+
+  it("mcp: a drifted pragma entry (wrong cwd) reads as `drifted` and is updated", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    mkdirSync(join(cwd, ".cursor"), { recursive: true });
+    const configPath = join(cwd, ".cursor", "mcp.json");
+    // Seed a stale pragma entry pointing at a different cwd.
+    writeFileSync(
+      configPath,
+      `${JSON.stringify(
+        {
+          mcpServers: {
+            pragma: { command: "pragma", args: ["mcp"], cwd: "/old" },
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+
+    const { toResult, generator } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "mcp",
+      "both",
+    );
+    const result = toResult({});
+    if (result.kind === "mcp") {
+      expect(result.targets.at(0)?.state).toBe("drifted");
+    }
+    // A drifted target stays SELECTED by default (it needs the update).
+    const multiselect = generator.prompts.find((p) => p.name === "mcpTargets");
+    expect(multiselect?.default).toEqual([configPath]);
+
+    await executeVerb(verbOf("mcp"), {}, YES, bootRuntime(FLAGS, cwd));
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(config.mcpServers.pragma.cwd).toBe(cwd); // updated to the real cwd
+  });
+
+  it("completions: a second run detects the up-to-date script (state=installed)", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const path = completionScriptPath("zsh");
+    // First install.
+    await executeVerb(completionsVerb, {}, YES, bootRuntime(FLAGS, cwd));
+    const firstBody = readFileSync(path, "utf-8");
+
+    // Detection now classifies the installed script `installed`.
+    const { toResult } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "completions",
+      "both",
+    );
+    const result = toResult({});
+    if (result.kind === "completions") {
+      expect(result.state).toBe("installed");
+    }
+
+    // A real second run is idempotent — the byte-identical script survives.
+    await executeVerb(completionsVerb, {}, YES, bootRuntime(FLAGS, cwd));
+    expect(readFileSync(path, "utf-8")).toBe(firstBody);
+  });
+
+  it("completions: a stale script (different body) reads as `stale`", async () => {
+    const cwd = tmp("pragma-setup-proj-");
+    const path = completionScriptPath("zsh");
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, "# stale hand-edited completion\n");
+    const { toResult } = await buildSetupPlan(
+      bootRuntime(FLAGS, cwd),
+      "completions",
+      "both",
+    );
+    const result = toResult({});
+    if (result.kind === "completions") {
+      expect(result.state).toBe("stale");
+    }
+  });
+
+  it("lsp: reports `unknown` when the `code` CLI is absent from PATH", async () => {
+    // PATH is the isolated empty dir (beforeEach), so `code` is unresolvable:
+    // detection cannot enumerate and reports `unknown` (installer still runs).
+    const { toResult } = await buildSetupPlan(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "both",
+    );
+    const result = toResult({});
+    expect(result.kind).toBe("lsp");
+    if (result.kind === "lsp") {
+      expect(result.state).toBe("unknown");
+    }
+  });
+});
+
 describe("setup (run-all wizard)", () => {
   it("--dry-run previews every DETECTED step (completions + lsp + mcp), writing nothing", async () => {
     const cwd = tmp("pragma-setup-proj-");

package/src/capabilities/setup/setup.verb.ts

@@ -21,11 +21,55 @@
 
 import type { GeneratorResult } from "@canonical/summon-core";
 import { $, gen, type Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type {
+  CapabilityModule,
+  ParamSpec,
+  VerbSpec,
+} from "../../kernel/spec/types.js";
 import { setupFormatters } from "./setup.render.js";
-import type { SetupMode, SetupResult } from "./types.js";
+import type { ScopeSelection, SetupMode, SetupResult } from "./types.js";
+
+/**
+ * The `--scope` flag + its `--global`/`--local` boolean sugars, shared by the
+ * band-aware verbs (`setup`/`mcp`/`skills`). `completions`/`lsp` never carry
+ * them — they are single-band installers.
+ */
+const SCOPE_PARAMS: readonly ParamSpec[] = [
+  {
+    kind: "enum",
+    name: "scope",
+    doc: "Which config band(s) to configure: project, global, or both.",
+    values: ["project", "global", "both"],
+    default: "both",
+  },
+  {
+    kind: "boolean",
+    name: "global",
+    doc: "Shorthand for --scope global (configure the user/home band).",
+  },
+  {
+    kind: "boolean",
+    name: "local",
+    doc: "Shorthand for --scope project (configure the per-project band).",
+  },
+];
+
+/**
+ * Resolve the `--scope`/`--global`/`--local` params into a single selection.
+ * The boolean sugars win over `--scope`; `--global` wins over `--local`.
+ *
+ * @param params - The coerced param bag.
+ * @returns The resolved scope selection (defaults to `both`).
+ */
+function resolveScope(params: Record<string, unknown>): ScopeSelection {
+  if (params.global === true) return "global";
+  if (params.local === true) return "project";
+  const scope = params.scope;
+  return scope === "global" || scope === "project" ? scope : "both";
+}
 
 /** The exposed-to-MCP capability the run-all self-verb declares. */
 const SELF_CAPABILITY = {
@@ -76,6 +120,7 @@ const SUB_CAPABILITY = {
 async function runSetup(
   mode: SetupMode,
   rt: PragmaRuntime,
+  scope: ScopeSelection,
 ): Promise<Task<SetupResult>> {
   // Lazy dynamic imports (R1 lazy-React discipline): summon-core's barrel is
   // React-free, and the non-TTY branch picks autoPrompt/mcpPrompt (never mounts
@@ -85,7 +130,7 @@ async function runSetup(
     import("./operations/setupGenerator.js"),
   ]);
 
-  const { generator, toResult } = await ops.buildSetupPlan(rt, mode);
+  const { generator, toResult } = await ops.buildSetupPlan(rt, mode, scope);
 
   const { isTTY, transport, yes, signal, abort } = rt.interaction ?? {
     isTTY: false,
@@ -149,7 +194,8 @@ function setupVerb(
     output: { formatters: setupFormatters },
     capability,
     ...extras,
-    run: (_params, rt) => runSetup(mode, rt) as unknown as Task<SetupResult>,
+    run: (params, rt) =>
+      runSetup(mode, rt, resolveScope(params)) as unknown as Task<SetupResult>,
   };
 }
 
@@ -159,20 +205,32 @@ const setupAllVerb = setupVerb(
   "all",
   SELF_CAPABILITY,
   {
-    doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply.",
+    params: SCOPE_PARAMS,
+    doc: "Runs the shell-completions, LSP, MCP, and skills installers as a single wizard: pick the steps, review the recap, then apply. The scope option targets the project band, the user/home band, or both.",
     examples: [
-      { cmd: "pragma setup" },
-      { cmd: "pragma setup --dry-run", note: "preview every step's effects" },
-      { cmd: "pragma setup mcp", note: "just the MCP server registration" },
+      { cmd: `${BIN_NAME} setup` },
+      {
+        cmd: `${BIN_NAME} setup --dry-run`,
+        note: "preview every step's effects",
+      },
+      {
+        cmd: `${BIN_NAME} setup --global`,
+        note: "configure only the user/home band",
+      },
+      {
+        cmd: `${BIN_NAME} setup mcp`,
+        note: "just the MCP server registration",
+      },
     ],
   },
 );
 
 const mcpVerb = setupVerb(
   ["setup", "mcp"],
-  "Register the pragma MCP server in detected AI harnesses.",
+  `Register the ${BIN_NAME} MCP server in detected AI harnesses.`,
   "mcp",
   SUB_CAPABILITY,
+  { params: SCOPE_PARAMS },
 );
 
 const completionsVerb = setupVerb(
@@ -187,6 +245,7 @@ const skillsVerb = setupVerb(
   "Symlink discovered skills into each AI harness.",
   "skills",
   SUB_CAPABILITY,
+  { params: SCOPE_PARAMS },
 );
 
 const lspVerb = setupVerb(

package/src/capabilities/setup/shell.ts

@@ -9,6 +9,7 @@
 
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
 /** The shells `setup completions` can install for. */
 export type ShellId = "zsh" | "bash" | "fish";
@@ -34,6 +35,31 @@ export function detectShell(): ShellId | null {
 /**
  * The standard install path for a shell's completion script.
  *
+ * The BASENAME is {@link BIN_NAME}, never a literal, because `emitScripts`
+ * derives the script's own `#compdef` / `complete -F` / `complete -c` from that
+ * same name, and for two of the three shells the basename decides whether the
+ * file is ever loaded. Measured against real shells with the distribution
+ * renamed to `widget9`:
+ *
+ * - **fish** autoloads `completions/<cmd>.fish` BY NAME. A correct `widget9`
+ *   script in a file called `pragma.fish` is never loaded — TAB silently falls
+ *   back to filenames. Verified: renaming that one file is the entire
+ *   difference between candidates and no candidates.
+ * - **bash-completion** looks up `completions/<cmd>` by the command name the
+ *   same way. Verified against bash-completion 2.11's `__load_completion`:
+ *   with the file named `widget9`, `complete -p widget9` reports
+ *   `complete -F _widget9 widget9`; with the identical file named `pragma`,
+ *   `_widget9` is never defined and bash falls back to `_minimal`.
+ * - **zsh** does NOT work that way: `compinit` binds by the `#compdef` tag
+ *   inside the file, so `~/.zfunc/_pragma` holding `#compdef widget9` does
+ *   complete `widget9` (verified — `_comps[widget9]` resolves to `_pragma`).
+ *   The basename still matters, for a different reason: it names the function
+ *   zsh autoloads, and two distributions both writing `_pragma` would silently
+ *   overwrite each other's completions.
+ *
+ * Either way `setup completions` and `doctor` report success, so nothing else
+ * would tell the user.
+ *
  * @param shell - The target shell.
  * @returns The absolute path the completion script is written to.
  * @note Impure — reads the home directory.
@@ -42,7 +68,7 @@ export function completionScriptPath(shell: ShellId): string {
   const home = homedir();
   switch (shell) {
     case "zsh":
-      return join(home, ".zfunc", "_pragma");
+      return join(home, ".zfunc", `_${BIN_NAME}`);
     case "bash":
       return join(
         home,
@@ -50,10 +76,10 @@ export function completionScriptPath(shell: ShellId): string {
         "share",
         "bash-completion",
         "completions",
-        "pragma",
+        BIN_NAME,
       );
     case "fish":
-      return join(home, ".config", "fish", "completions", "pragma.fish");
+      return join(home, ".config", "fish", "completions", `${BIN_NAME}.fish`);
   }
 }
 

package/src/capabilities/setup/types.ts

@@ -11,6 +11,58 @@ import type { ShellId } from "./shell.js";
  */
 export type SetupMode = "all" | "completions" | "lsp" | "mcp" | "skills";
 
+/**
+ * One of the two config bands: the per-user/home `global` band or the per-repo
+ * `project` band. Mirrors `@canonical/harnesses`' `ScopeBand` structurally, but
+ * is redeclared here so this statically-reachable type module never pulls the
+ * harnesses runtime into the fast-path module graph (the lazy-dispatch invariant).
+ */
+export type ScopeBand = "project" | "global";
+
+/**
+ * The resolved `--scope` selection: which config band(s) a run touches. `both`
+ * (the default) runs each detected harness's default band; `global`/`project`
+ * run only that band. Structurally mirrors the harnesses `ScopeSelection`.
+ */
+export type ScopeSelection = "project" | "global" | "both";
+
+/**
+ * The prior state of an MCP target file, read up front by `detectMcp`:
+ * `absent` (no pragma entry yet), `configured` (a matching pragma entry already
+ * present in every write — a re-run skips it), or `drifted` (a pragma entry
+ * exists but differs, so a write updates it). Mirrors the skills step's
+ * created/skipped/replaced idempotency at the file grain.
+ */
+export type McpTargetState = "absent" | "configured" | "drifted";
+
+/**
+ * One configured MCP target in a result: the file that was written, which band
+ * it belongs to, the harness name(s) that share it, and its prior
+ * {@link McpTargetState} (so the recap can report new vs updated vs unchanged).
+ */
+export interface ConfiguredTarget {
+  readonly name: string;
+  readonly band: ScopeBand;
+  readonly path: string;
+  readonly state: McpTargetState;
+}
+
+/**
+ * The prior on-disk state of the shell-completion script, read up front by
+ * `detectCompletions`: `absent` (no script), `installed` (a byte-identical
+ * script is already present — a re-run skips it), or `stale` (a different
+ * script is present, so a write updates it).
+ */
+export type CompletionsState = "absent" | "installed" | "stale";
+
+/**
+ * The detected state of the Terrazzo LSP VS Code extension, probed up front by
+ * `detectLsp`: `installed` (already present — a re-run skips it), `absent` (not
+ * present, so the installer runs), or `unknown` (the `code` CLI is not on PATH,
+ * so we cannot enumerate and the installer runs regardless).
+ */
+export type LspState = "installed" | "absent" | "unknown";
+
 /** One symlink create/skip/replace action performed during skill setup. */
 export interface SymlinkAction {
   readonly skillName: string;
@@ -35,8 +87,13 @@ export type SetupResult =
       readonly shell: ShellId | null;
       readonly path: string | null;
       readonly installed: boolean;
+      readonly state: CompletionsState;
+    }
+  | { readonly kind: "lsp"; readonly state: LspState }
+  | {
+      readonly kind: "mcp";
+      readonly configured: readonly string[];
+      readonly targets: readonly ConfiguredTarget[];
     }
-  | { readonly kind: "lsp" }
-  | { readonly kind: "mcp"; readonly configured: readonly string[] }
   | { readonly kind: "skills"; readonly result: SetupSkillsResult }
   | { readonly kind: "all"; readonly steps: readonly string[] };

package/src/capabilities/shared/bands.ts

@@ -0,0 +1,16 @@
+/**
+ * User-facing labels for the two config bands, shared by the setup recap
+ * ({@link ../setup/setup.render}) and the doctor report
+ * ({@link ../doctor/doctor.render}) so ONE consistent vocabulary appears across
+ * both. The pair matches the CLI grammar users already meet elsewhere: the
+ * `--global`/`--local` flags, the `--scope project|global|both` enum, config
+ * show's `[global]`/`[project]` origin markers, and the `setup` manifest's
+ * `[global]`/`[project]` lines. (Earlier these two surfaces said MACHINE/PROJECT
+ * — a third term for the same bands; this is the single source that unifies it.)
+ */
+
+/** The user-facing display label for each of the two config bands. */
+export const BAND_LABELS: Record<"project" | "global", string> = {
+  global: "Global",
+  project: "Project",
+};