@canonical/pragma-cli 0.35.0 → 0.36.0

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

@@ -9,18 +9,18 @@
  * only the self-verb is an MCP tool. `destructive: false` keeps MCP from
  * advertising the tool as destructive.
  *
- * THE BAND DEFAULT IS GLOBAL. `--scope` used to default to `both`, and `both`
- * runs each harness's own default band — which is `project` for most of the
+ * THE SCOPE DEFAULT IS GLOBAL. `--scope` used to default to `both`, and `both`
+ * runs each harness's own default scope — which is `project` for most of the
  * registry — so a bare `setup` scattered `.mcp.json`, `.gemini/settings.json`
  * and `opencode.json` into whatever directory you happened to be standing in.
- * The user band is what a machine-level installer configures; the project band
+ * The user scope is what a machine-level installer configures; the project scope
  * is a deliberate, checked-in, team-shared choice, and is now chosen with
  * `--local` rather than assumed.
  *
- * Every sub-verb registers the scope flags UNIFORMLY. That is what lets the band
+ * Every sub-verb registers the scope flags UNIFORMLY. That is what lets the scope
  * answer come from the table instead of per-verb flag wiring — previously
  * `setup completions --local` died as an unknown option, while `setup mcp
- * --local` worked, for no reason a user could see. Asking a target for a band it
+ * --local` worked, for no reason a user could see. Asking a target for a scope it
  * cannot honour is a usage error (exit 2) with the corrected command; asking the
  * RUN-ALL for such a band merely filters, and the out-of-band target still shows
  * as a named row.
@@ -43,20 +43,25 @@ import type {
 } from "../../kernel/spec/index.js";
 import { resolveSetupMode, setupModeInput } from "./mode.js";
 import {
+  isActionable,
   planExitFailed,
   planTally,
   type SetupPlan,
   TARGET_IDS,
 } from "./plan.js";
-import { renderProgressLine, renderRecap } from "./plan.render.js";
+import {
+  renderDetectionSummary,
+  renderProgressLine,
+  renderRecap,
+} from "./plan.render.js";
 import { renderDryRun, setupFormatters } from "./setup.render.js";
-import type { ScopeBand, ScopeSelection, SetupMode } from "./types.js";
+import type { Scope, ScopeSelection, SetupMode } from "./types.js";
 
 /**
  * The `--scope` flag + its `--global`/`--local` boolean sugars. Registered by
- * EVERY setup verb, including the single-band ones: a flag that exists on some
- * sub-verbs and not others is a grammar the user has to memorise, and the band
- * a single-band target can honour is a question the target table answers.
+ * EVERY setup verb, including the single-scope ones: a flag that exists on some
+ * sub-verbs and not others is a grammar the user has to memorise, and the scope
+ * a single-scope target can honour is a question the target table answers.
  *
  * `--global` is a synonym of the default; it stays for scripts and for symmetry
  * with `--local`.
@@ -65,19 +70,19 @@ const SCOPE_PARAMS: readonly ParamSpec[] = [
   {
     kind: "enum",
     name: "scope",
-    doc: "Which config band(s) to configure: global (the default), project, or both.",
+    doc: "Where to configure: global (your home directory, the default), project (this repository), or both.",
     values: ["project", "global", "both"],
     default: "global",
   },
   {
     kind: "boolean",
     name: "global",
-    doc: "Shorthand for --scope global (configure the user/home band).",
+    doc: "Shorthand for --scope global — configure your home directory.",
   },
   {
     kind: "boolean",
     name: "local",
-    doc: "Shorthand for --scope project (configure the per-project band).",
+    doc: "Shorthand for --scope project — configure this project only.",
   },
 ];
 
@@ -96,34 +101,35 @@ function resolveScope(params: Record<string, unknown>): ScopeSelection {
 }
 
 /**
- * Reject a sub-verb asked for a band its target cannot hold.
+ * Reject a sub-verb asked for a scope its target cannot hold.
  *
  * This is a usage error, not a skip: the user typed a contradiction, and
- * correcting it is exactly what exit 2 means. The message names the band the
+ * correcting it is exactly what exit 2 means. The message names the scope the
  * target DOES have and prints the command that works, so the correction is one
  * paste rather than one manual page.
  *
  * @param mode - The sub-verb's target, or `all`.
  * @param scope - The resolved selection.
- * @throws PragmaError INVALID_INPUT when the target has no such band.
+ * @throws PragmaError INVALID_INPUT when the target has no such scope.
  */
-async function assertBandIsPossible(
+async function assertScopeIsPossible(
   mode: SetupMode,
   scope: ScopeSelection,
 ): Promise<void> {
   if (mode === "all" || scope === "both") return;
   const { findTarget } = await import("./targets.js");
   const target = findTarget(mode);
-  if (target === undefined || target.bands.includes(scope as ScopeBand)) return;
-  const only = target.bands[0] as ScopeBand;
-  const level = only === "global" ? "user-level" : "project-level";
+  if (target === undefined || target.scopes.includes(scope as Scope)) return;
+  const only = target.scopes[0] as Scope;
+  const level = only === "global" ? "global only" : "per-project only";
+  const asked = scope === "global" ? "globally" : "per project";
   const corrected =
     only === "global"
       ? `${BIN_NAME} setup ${mode}`
       : `${BIN_NAME} setup ${mode} --local`;
   throw new PragmaError({
     code: "INVALID_INPUT",
-    message: `${mode} is ${level} — it has no ${scope} band.`,
+    message: `${mode} is ${level} — it cannot be configured ${asked}.`,
     recovery: { message: `Run: ${corrected}` },
   });
 }
@@ -169,7 +175,7 @@ const SUB_CAPABILITY = {
  *
  * @param mode - Which entry point (`all` or one target).
  * @param rt - The per-invocation runtime (mutated: `rt.exec` and `rt.planData`).
- * @param scope - The resolved band selection.
+ * @param scope - The resolved scope selection.
  * @returns The `Task<SetupPlan>` the dispatcher/MCP handler interprets.
  * @note Impure — runs every target's real detection before returning a Task.
  */
@@ -178,7 +184,7 @@ async function runSetup(
   rt: PragmaRuntime,
   scope: ScopeSelection,
 ): Promise<Task<SetupPlan>> {
-  await assertBandIsPossible(mode, scope);
+  await assertScopeIsPossible(mode, scope);
 
   // Lazy dynamic imports (lazy-React discipline): summon-core's barrel is
   // React-free, and the non-TTY branch picks autoPrompt/mcpPrompt (never mounts
@@ -203,6 +209,28 @@ async function runSetup(
   // to know which of the two it is.
   const previewing = interactionMode === "batch-dry-run";
 
+  // A CONVERGED machine has no question to ask. Every row is `none` or `skip`,
+  // so nothing composes an effect — and the wizard's confirm gate then mounted
+  // Ink to render summon-core's "No operations planned." above a "Proceed?"
+  // over an empty tally. For a sub-verb, whose prompt list is empty, that
+  // contentless gate was the FIRST AND ONLY thing the user ever saw. The
+  // explanation existed the whole time (each row's `none` detail, one child row
+  // per file/editor marked `unchanged`) and was dropped at the render seam.
+  //
+  // So: report the plan instead of asking a question with no content. There is
+  // no `preview: true` here — the run really did complete. `applied({})` marks
+  // each `none` row `{status:"noop", note:"unchanged"}`, `wasApplied` is then
+  // true, and `setupFormatters.plain` renders the recap. That also retires a
+  // second defect: a non-interactive converged run used to print the misleading
+  // "Nothing was applied. Run again with --yes to apply." over an all-`none`
+  // plan. A run whose every DETECTION threw is not converged in this sense —
+  // its rows are skips that report `failed` — so it falls through to the normal
+  // path, which is the one that raises.
+  if (!previewing && run.plan.rows.every((row) => !isActionable(row.action))) {
+    const converged = run.applied({});
+    if (!planExitFailed(converged)) return pure<SetupPlan>(converged);
+  }
+
   // Adaptation (b): a non-interactive run without `--yes` previews rather than
   // mutating. It is the same plan the dry-run prints, plus one hint line, at
   // exit 0 — the invocation completed a real read-only unit of work.
@@ -210,6 +238,23 @@ async function runSetup(
     return pure<SetupPlan>({ ...run.plan, preview: true });
   }
 
+  // Say what was DETECTED before asking anything about it. The data has been
+  // sitting in `run.plan` since before the prompt list was built — `inkPrompt`
+  // mounts no React until the first Prompt effect — so this is a rendering gap,
+  // not an ordering one, and closing it is nearly free.
+  //
+  // It MUST be emitted here, before `execute` is driven: the summary and the
+  // Ink frame both write to stderr, and only a line written first lands in
+  // scrollback ABOVE the frame. `rt.report` is the non-Ink seam — `--quiet`
+  // silences it and it is a no-op over MCP — so no React is loaded to print it.
+  // A preview says nothing here: the plan table IS its output.
+  if (!previewing) {
+    const summary = renderDetectionSummary(run.plan, {
+      verbose: rt.globalFlags.verbose,
+    });
+    if (summary !== undefined) rt.report?.(summary);
+  }
+
   const { transport, yes, signal, abort } = rt.interaction ?? {
     isTTY: false,
     transport: "cli" as const,
@@ -226,6 +271,19 @@ async function runSetup(
       signal,
       onCancel: abort,
     });
+    // Live progress in the PLAN's units, not the interpreter's: the wizard's
+    // default execution view is the per-effect transcript — right for `create`,
+    // whose unit of work IS the file, and wrong here, where one unit is one
+    // configured target and the transcript renders eighteen symlink rows for
+    // the row the plan called `skills  link  9 skills → 2 folders`. Each row
+    // event carries the SAME sentence `renderProgressLine` prints, so the
+    // watcher and the recap reader see one dialect. `--verbose` withholds the
+    // listener, which falls the wizard back to the full effect transcript —
+    // the same detected-only-unless-verbose rule the detection summary and
+    // doctor already follow.
+    if (rt.globalFlags.verbose !== true) {
+      run.setRowListener((event) => session.reportStep(event));
+    }
     rt.exec = {
       promptHandler: session.promptHandler,
       onEffectStart: session.onEffectStart,
@@ -345,24 +403,24 @@ function setupVerb(
 
 const setupAllVerb = setupVerb(
   ["setup"],
-  "Configure the global config, completions, the LSP, MCP, and skills.",
+  "Set up your config file, TAB completion, the editor extension, MCP, and skills.",
   "all",
   SELF_CAPABILITY,
   {
-    doc: "Plans every target in the selected band, then applies the ones you keep. The user/home band is the default; the scope option chooses the per-project band, or both. A run with no attended terminal prints the plan and applies nothing unless the run is confirmed.",
+    doc: "Shows what each target needs, then applies the ones you keep. Everything is configured in your home directory by default; the scope option moves the run to this project alone, or covers both. Without an attended terminal the plan is printed and nothing is written unless the run is explicitly confirmed.",
     examples: [
       { cmd: `${BIN_NAME} setup` },
       {
         cmd: `${BIN_NAME} setup --dry-run`,
-        note: "print the plan, write nothing",
+        note: "show the plan, write nothing",
       },
       {
         cmd: `${BIN_NAME} setup --local`,
-        note: "configure the project band instead",
+        note: "configure this project instead of your home directory",
       },
       {
         cmd: `${BIN_NAME} setup mcp`,
-        note: "just the MCP server registration",
+        note: "only register the MCP server",
       },
     ],
   },
@@ -370,35 +428,35 @@ const setupAllVerb = setupVerb(
 
 const configVerb = setupVerb(
   ["setup", "config"],
-  "Create the global config file with its defaults.",
+  "Create your global config file, filled in with the defaults.",
   "config",
   SUB_CAPABILITY,
 );
 
 const mcpVerb = setupVerb(
   ["setup", "mcp"],
-  `Register the ${BIN_NAME} MCP server in detected AI harnesses.`,
+  `Register the ${BIN_NAME} MCP server with the AI harnesses on this machine.`,
   "mcp",
   SUB_CAPABILITY,
 );
 
 const completionsVerb = setupVerb(
   ["setup", "completions"],
-  "Install the shell-completion script for your shell.",
+  "Install TAB completion for the shell you are running.",
   "completions",
   SUB_CAPABILITY,
 );
 
 const skillsVerb = setupVerb(
   ["setup", "skills"],
-  "Symlink discovered skills into each AI harness.",
+  "Link the skills you have installed into every AI harness that reads them.",
   "skills",
   SUB_CAPABILITY,
 );
 
 const lspVerb = setupVerb(
   ["setup", "lsp"],
-  "Ensure the Terrazzo LSP VS Code extension is installed.",
+  "Install the Terrazzo design-token extension into your VS Code-family editors.",
   "lsp",
   SUB_CAPABILITY,
 );

package/src/capabilities/setup/targets.ts

@@ -1,14 +1,14 @@
 /**
  * THE target table — the one list `setup` and `doctor` both read.
  *
- * Five rows, each with a band column. This table drives the `setup <target>`
+ * Five rows, each with a scope column. This table drives the `setup <target>`
  * sub-verbs, the wizard's choices, the `--dry-run` plan, the progress lines, the
  * recap, the doctor rows, and each doctor row's `fix:` line. Adding a sixth
  * target is one row here — not a new sub-verb, a new check, a new recap branch
  * and a new fix string that four separate files have to agree about.
  *
  * A row owns: its identity (`id` is BOTH the sub-verb argument and the doctor
- * row name, so `mcp` and `setup mcp` visibly share a token), which bands it can
+ * row name, so `mcp` and `setup mcp` visibly share a token), which scopes it can
  * be installed into, how to DETECT its current state, how to PLAN a run from
  * that detection, and how to COMPOSE the forward and removal effects. Detection
  * runs once per invocation and feeds every reader, so setup and doctor cannot
@@ -47,7 +47,7 @@ import {
   type LspDetection,
   lspEditorNames,
   lspSkipReason,
-  lspUninstallRemedy,
+  ownedLspEditors,
 } from "./operations/setupLsp.js";
 import {
   composeMcp,
@@ -65,6 +65,8 @@ import {
   ownedSkillLinks,
   type SkillsDetection,
   skillsSkipReason,
+  skillsSkipRemedy,
+  staleSkillLinks,
 } from "./operations/setupSkills.js";
 import {
   type PlanAction,
@@ -73,7 +75,7 @@ import {
   shortenPath,
   type TargetId,
 } from "./plan.js";
-import type { ScopeBand } from "./types.js";
+import type { Scope } from "./types.js";
 
 /** What a target contributes to one plan row, before selection is applied. */
 export interface TargetDraft {
@@ -98,13 +100,13 @@ export interface TargetDefinition<D> {
   readonly id: TargetId;
   /** Human title, used where a sentence needs one; the id is the row name. */
   readonly title: string;
-  readonly bands: readonly ScopeBand[];
-  /** Real reads, up front, once per (target, band) per invocation. */
-  detect(rt: PragmaRuntime, band: ScopeBand): Promise<D>;
+  readonly scopes: readonly Scope[];
+  /** Real reads, up front, once per (target, scope) per invocation. */
+  detect(rt: PragmaRuntime, scope: Scope): Promise<D>;
   /** What a forward run would do. */
-  plan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  plan(detection: D, scope: Scope, roots: Roots): TargetDraft;
   /** What a removal would do — composed from what detection says we own. */
-  removalPlan(detection: D, band: ScopeBand, roots: Roots): TargetDraft;
+  removalPlan(detection: D, scope: Scope, roots: Roots): TargetDraft;
   /**
    * The forward effects. `chosen` is the row's per-child selection (MCP file
    * paths); a row without children ignores it.
@@ -128,21 +130,21 @@ const defineTarget = <D>(target: TargetDefinition<D>): AnyTarget =>
 const configTarget = defineTarget<ConfigDetection>({
   id: "config",
   title: "Global configuration",
-  bands: ["global"],
+  scopes: ["global"],
   detect: () => detectConfigFile(),
-  plan: (d, _band, roots) => {
+  plan: (d, _scope, roots) => {
     const path = shortenPath(d.path, roots);
     if (!d.exists) return { action: "install", detail: path };
     return { action: "none", detail: `${path} — present` };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const path = shortenPath(d.path, roots);
     if (!d.exists) return { action: "none", detail: `${path} — absent` };
     if (!d.isSeed) {
       return {
         action: "skip",
         detail: path,
-        reason: "kept — it holds your settings",
+        reason: `it holds your own settings, so ${path} stays`,
       };
     }
     return { action: "remove", detail: path };
@@ -154,9 +156,9 @@ const configTarget = defineTarget<ConfigDetection>({
 const completionsTarget = defineTarget<CompletionsDetection>({
   id: "completions",
   title: "Shell completions",
-  bands: ["global"],
+  scopes: ["global"],
   detect: (rt) => detectCompletions(rt.cwd),
-  plan: (d, _band, roots) => {
+  plan: (d, _scope, roots) => {
     // Never guess a shell. Installing for the wrong one is invisible until the
     // user presses TAB and nothing happens, so an unresolved shell is a named
     // skip whose remedy is the one action that DOES settle it.
@@ -187,13 +189,18 @@ const completionsTarget = defineTarget<CompletionsDetection>({
       };
     }
     const where = `${d.shell} → ${shortenPath(d.path, roots)}`;
-    if (d.state === "installed") return { action: "none", detail: where };
+    // A no-op row says what it FOUND, not just where it looked: `no change`
+    // beside a bare path leaves the reader to guess whether the script is
+    // there and current or missing and unreachable.
+    if (d.state === "installed") {
+      return { action: "none", detail: `${where} — already up to date` };
+    }
     return {
       action: d.state === "stale" ? "update" : "install",
       detail: where,
     };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     if (d.path === null || d.state === "absent") {
       return { action: "none", detail: "no script installed" };
     }
@@ -206,7 +213,7 @@ const completionsTarget = defineTarget<CompletionsDetection>({
 const lspTarget = defineTarget<LspDetection>({
   id: "lsp",
   title: "Terrazzo LSP extension",
-  bands: ["global"],
+  scopes: ["global"],
   detect: (rt) => detectLsp(rt.cwd),
   plan: (d) => {
     if (d.state === "unknown") {
@@ -225,32 +232,71 @@ const lspTarget = defineTarget<LspDetection>({
       label: `${e.editor.cli} — ${e.editor.name}`,
       action: e.installed ? ("unchanged" as const) : ("add" as const),
     }));
+    // The detail names WHAT is being placed and WHERE — never the row's own
+    // state, which the action column already carries. `installed (VSCodium)`
+    // beside a child row reading `codium — VSCodium (unchanged)` said the
+    // editor's name twice and "nothing happens here" twice.
     if (d.state === "installed") {
       return {
         action: "none",
-        detail: `installed (${lspEditorNames(d).join(", ")})`,
+        detail: `Terrazzo extension in ${lspEditorNames(d).join(", ")}`,
         children,
       };
     }
     const pending = d.editors.filter((e) => !e.installed);
     return {
       action: "install",
-      detail: `${pending.length} ${pending.length === 1 ? "editor" : "editors"}`,
+      detail: `Terrazzo extension → ${pending
+        .map((e) => e.editor.name)
+        .join(", ")}`,
       children,
     };
   },
-  removalPlan: (d) => ({
-    action: "skip",
-    detail: "not removed",
-    reason: "an extension install cannot be reversed from here",
-    remedy:
-      lspUninstallRemedy(d) ??
-      "no editor CLI is on PATH — uninstall it from your editor",
-  }),
+  removalPlan: (d) => {
+    // No editor CLI on PATH is the SAME named skip the forward plan reports:
+    // there is nothing on this machine to run an uninstall with.
+    if (d.state === "unknown") {
+      return {
+        action: "skip",
+        detail: lspSkipReason(d),
+        reason: lspSkipReason(d),
+        remedy: LSP_SKIP_REMEDY,
+      };
+    }
+    // Removal is composed from what detection says we OWN — a copy that is
+    // present, whatever its version. The forward plan's version gate would let
+    // a dead pre-0.8.3 copy this command installed survive its own `--undo`.
+    const owned = ownedLspEditors(d);
+    if (owned.length === 0) {
+      return { action: "none", detail: "no editor carries the extension" };
+    }
+    return {
+      action: "remove",
+      detail: `Terrazzo extension from ${owned
+        .map((e) => e.editor.name)
+        .join(", ")}`,
+      children: owned.map((e) => ({
+        key: e.editor.cli,
+        label: `${e.editor.cli} — ${e.editor.name}`,
+        action: "update" as const,
+      })),
+    };
+  },
   compose: (d, chosen) => composeLsp(d, chosen),
   composeRemoval: (d) => composeLspRemoval(d),
 });
 
+/**
+ * Why the `mcp` row has nothing to write in a scope — authored once, because
+ * `setup`'s row and `doctor`'s row are the same finding and must not word it
+ * differently. Neither sentence says "scope": the two scopes are `global` and
+ * `local project`, after the `--global` / `--local` flags that select them.
+ */
+export const MCP_NO_LOCATION: Record<Scope, string> = {
+  global: "no AI harness on this machine keeps a global config",
+  project: "no AI harness in this project keeps a per-project config",
+};
+
 /** One MCP file as a plan child: its path, the harnesses sharing it, its state. */
 const mcpChild = (
   d: McpDetection,
@@ -262,7 +308,7 @@ const mcpChild = (
     key: group.path,
     label: shortenPath(group.path, roots),
     action:
-      state === "configured"
+      state === "registered"
         ? "unchanged"
         : state === "drifted"
           ? "update"
@@ -273,35 +319,34 @@ const mcpChild = (
 const mcpTarget = defineTarget<McpDetection>({
   id: "mcp",
   title: "MCP server registration",
-  bands: ["global", "project"],
-  detect: (rt, band) => detectMcp(rt, band),
-  plan: (d, band, roots) => {
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectMcp(rt, scope),
+  plan: (d, scope, roots) => {
     if (d.groups.length === 0) {
       return {
         action: "skip",
-        detail: "no harness config location in this band",
-        reason:
-          band === "project"
-            ? "no AI harness in this project writes a per-repository config"
-            : "no detected AI harness declares a user-level config location",
+        detail: MCP_NO_LOCATION[scope],
+        reason: MCP_NO_LOCATION[scope],
       };
     }
     const children = d.groups.map((group) => mcpChild(d, group, roots));
     const pending = children.filter((c) => c.action !== "unchanged");
     return {
       action: pending.length === 0 ? "none" : "update",
-      detail: `${d.groups.length} ${d.groups.length === 1 ? "file" : "files"}`,
+      detail: `${d.groups.length} ${
+        d.groups.length === 1 ? "config file" : "config files"
+      }`,
       children,
     };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const owned = ownedMcpGroups(d);
     if (owned.length === 0) {
       return { action: "none", detail: "no entry to remove" };
     }
     return {
       action: "remove",
-      detail: `${owned.length} ${owned.length === 1 ? "file" : "files"}`,
+      detail: `${owned.length} ${owned.length === 1 ? "config file" : "config files"}`,
       children: owned.map((group) => ({
         key: group.path,
         label: shortenPath(group.path, roots),
@@ -317,19 +362,42 @@ const mcpTarget = defineTarget<McpDetection>({
 const skillsTarget = defineTarget<SkillsDetection>({
   id: "skills",
   title: "Skill symlinks",
-  bands: ["global", "project"],
-  detect: (rt, band) => detectSkills(rt, band),
-  plan: (d, band, roots) => {
-    if (!d.available) {
-      const reason = skillsSkipReason(shortenPath(d.sourceRoot, roots), band);
-      return { action: "skip", detail: reason, reason };
+  scopes: ["global", "project"],
+  detect: (rt, scope) => detectSkills(rt, scope),
+  plan: (d, scope, roots) => {
+    // A forward run RECONCILES: stale links this scope owns are its work too, so
+    // an orphan-only tree is actionable rather than a row that plans `none` and
+    // is then deselected into doing nothing. `staleSkillLinks` carries the
+    // absent-root safety gate, so a machine whose source root does not exist
+    // contributes no sweep and the row falls back to the honest skip.
+    const stale = staleSkillLinks(d);
+    if (!d.available && stale.length === 0) {
+      const short = shortenPath(d.sourceRoot, roots);
+      const reason = skillsSkipReason(short, scope, d.rootExists);
+      // A skip with no remedy is a dead end — this one names the command that
+      // fills the scope's source root, exactly as the completions and lsp skips
+      // beside it name theirs.
+      return {
+        action: "skip",
+        detail: reason,
+        reason,
+        remedy: skillsSkipRemedy(short, scope),
+      };
     }
     const dirs = d.targets.map((t) => shortenPath(t.dir, roots)).join(", ");
-    const where = `${d.skillCount} ${d.skillCount === 1 ? "skill" : "skills"} → ${d.targets.length} ${d.targets.length === 1 ? "dir" : "dirs"} (${dirs})`;
+    const where = `${d.skillCount} ${d.skillCount === 1 ? "skill" : "skills"} → ${d.targets.length} ${d.targets.length === 1 ? "folder" : "folders"} (${dirs})`;
+    const detail =
+      stale.length === 0
+        ? where
+        : `${where}, ${stale.length} stale ${stale.length === 1 ? "link" : "links"} to remove`;
     const pending = d.actions.filter((a) => a.action !== "skipped");
-    return { action: pending.length === 0 ? "none" : "link", detail: where };
+    if (pending.length > 0) return { action: "link", detail };
+    // Nothing to link, but something to retire: `update` is the table's word
+    // for "this row has work that is not a fresh install".
+    if (stale.length > 0) return { action: "update", detail };
+    return { action: "none", detail };
   },
-  removalPlan: (d, _band, roots) => {
+  removalPlan: (d, _scope, roots) => {
     const owned = ownedSkillLinks(d);
     if (owned.length === 0) {
       return { action: "none", detail: "no link to remove" };
@@ -362,6 +430,6 @@ export const TARGETS: readonly AnyTarget[] = [
 export const findTarget = (id: string): AnyTarget | undefined =>
   TARGETS.find((target) => target.id === id);
 
-/** Whether a target can be installed into a band. */
-export const supportsBand = (target: AnyTarget, band: ScopeBand): boolean =>
-  target.bands.includes(band);
+/** Whether a target can be installed into a scope. */
+export const supportsScope = (target: AnyTarget, scope: Scope): boolean =>
+  target.scopes.includes(scope);

package/src/capabilities/setup/types.ts

@@ -15,31 +15,23 @@ export type SetupMode =
   | "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.
- * `global` is the DEFAULT — the user/home band a machine-level installer
- * configures; `project` is the opt-in per-repository band; `both` is the
- * explicit "run each band in one invocation". Structurally mirrors the
- * harnesses `ScopeSelection`.
- */
-export type ScopeSelection = "project" | "global" | "both";
+// The scope types are part of the rendering vocabulary — the one module that
+// owns both the states and the words for them. Re-exported here so setup's
+// type surface stays complete; the definitions (and the structural pin against
+// `@canonical/harnesses`) live with the vocabulary.
+export type {
+  Scope,
+  ScopeSelection,
+} from "../../kernel/render/vocabulary.js";
 
 /**
  * The prior state of an MCP target file, read up front by `detectMcp`:
- * `absent` (no pragma entry yet), `configured` (a matching pragma entry already
+ * `absent` (no pragma entry yet), `registered` (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";
+export type McpTargetState = "absent" | "registered" | "drifted";
 
 /**
  * The prior on-disk state of the shell-completion script, read up front by