skillrepo 3.1.5 → 4.0.0

package/src/commands/init.mjs

@@ -1,5 +1,6 @@
 /**
- * `skillrepo init` (#673) — PR3b rewrite, v3.1.0 session-sync (#884).
+ * `skillrepo init` (#673) — PR3b rewrite, v3.1.0 session-sync (#884),
+ * Phase 3 detection picker (#1236).
  *
  * First-run command. Replaces the v2.0.0 init that consumed the
  * deprecated `/api/v1/setup` endpoint and wrote hook-delivery
@@ -8,12 +9,30 @@
  *   1. Collect credentials (--key | env var | interactive prompt)
  *   2. Validate the key via POST /api/v1/auth/validate
  *   3. Write ~/.claude/skillrepo/config.json via config.mjs
- *   4. Detect installed IDEs (.claude/, .cursor/, .vscode/, ~/.codeium/windsurf/)
+ *   4. Multi-signal agent detection + two-row picker (#1236)
  *   5. Run MCP auto-merge for detected IDEs (user-confirmed unless --yes)
  *   6. Install Claude Code SessionStart hook (v3.1.0 #884)
  *   7. Run the first library sync via sync.mjs
  *   8. Print summary
  *
+ * Step 4 details (#1236):
+ *
+ *   - When `--agent` is passed (including `--agent none`), the picker
+ *     is skipped entirely and the explicit list is used.
+ *   - Otherwise, multi-signal detection runs against the registry.
+ *     Each row of the picker (Claude Code / Other agents) is
+ *     pre-checked when its target's signal fires. Fresh clone with no
+ *     detection at all → both rows pre-checked anyway (the product's
+ *     job is to set things up; defaulting to "do nothing" is the bug
+ *     we are fixing). When detection fires for one target only, the
+ *     other row is left unchecked so the picker nudges the user toward
+ *     what was found.
+ *   - `--yes` skips the render and uses the pre-checked rows. With
+ *     no signals, that means BOTH targets — running `init --yes` on
+ *     a fresh clone and writing nothing is broken automation.
+ *   - The "None" row produces vendors = `[]`, the same sentinel
+ *     `--agent none` returns. Mutually exclusive with the other rows.
+ *
  * Key differences from v2.0.0:
  *
  *   - Uses /api/v1/auth/validate (not /api/v1/setup)
@@ -21,8 +40,10 @@
  *   - MCP merge is interactive with per-vendor prompts
  *   - NO rules-delivery files (.claude/rules/, .claude/skillrepo*.md) —
  *     those died with the hooks in #835
- *   - NO silent vendor fallback — if nothing is detected, refuse with
- *     a clear --ide hint
+ *   - The Phase-3 picker REPLACED the old "no agent targets detected
+ *     → refuse" branch. Fresh clones now configure both default
+ *     targets; the user can still opt out via the "None" row or
+ *     `--agent none`.
  *   - Idempotent: re-running with a valid existing config re-runs
  *     detection + MCP merge prompts + sync, but does NOT re-prompt
  *     for a key. A stale (401) key triggers automatic re-prompt.
@@ -33,37 +54,67 @@
  * Flags:
  *   --key/-k <key>   Access key (overrides config + env)
  *   --url/-u <url>   SkillRepo server URL (overrides config + env)
- *   --yes/-y         Non-interactive: skip all prompts (MCP merge + IDE confirm)
+ *   --yes/-y         Non-interactive: skip all prompts (MCP merge + picker)
  *   --force          Re-prompt for a new key even if config exists and is valid
  *   --global         Run first sync in global mode (~/.claude/skills/)
- *   --ide <list>     Override detected IDEs (comma-separated)
+ *   --agent <list>   Override detected agent targets (comma-separated)
  *   --json           JSON summary output
  */
 
+import { existsSync, readdirSync } from "node:fs";
+
 import { validateAccessKey } from "../lib/http.mjs";
-import { detectIdes, formatDetectedIdes } from "../lib/detect-ides.mjs";
+import { detectAgents } from "../lib/detect-agents.mjs";
+import { AGENT_REGISTRY, AGENTS_COHORT_KEYS } from "../lib/agent-registry.mjs";
 import { readConfig, writeConfig } from "../lib/config.mjs";
 import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
 import {
   detectTransientRunner,
   globalInstallCommandFor,
 } from "../lib/transient-runners.mjs";
-import { mergeMcpForVendors, printManualMcpInstructions } from "../lib/mcp-merge.mjs";
+import { mergeMcpForVendors } from "../lib/mcp-merge.mjs";
 import { runSync } from "../lib/sync.mjs";
+import {
+  placementTargetsFor,
+  describePlacementTarget,
+} from "../lib/file-write.mjs";
 import { mergeEnvLocal } from "../lib/mergers/env-local.mjs";
 import { mergeGitignore } from "../lib/mergers/gitignore.mjs";
 import { installSessionSyncHook } from "./init-session-sync.mjs";
 import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
-  promptSecret,
-  confirm,
-} from "../lib/prompt.mjs";
+  claudeSkillsProjectRoot,
+  agentsSkillsProjectRoot,
+} from "../lib/paths.mjs";
+import { promptWithBrowserOpen } from "../lib/prompt.mjs";
+import { promptMultiSelect } from "../lib/prompt-multiselect.mjs";
 import {
   CliError,
   authError,
   validationError,
   EXIT_AUTH,
 } from "../lib/errors.mjs";
+import { cliAuthUrl } from "../lib/constants.mjs";
+
+/**
+ * Format the user-visible "configured X, Y" line for the init step-4
+ * success message. Resolves the vendor list to its placement targets,
+ * deduplicates via placementTargetsFor, and labels each with a
+ * readable path. Falls back to vendor display names if path resolution
+ * throws (e.g., a vendor was passed without a corresponding target —
+ * shouldn't happen post-validation, but the fallback prevents a
+ * step-4 success line from blowing up the rest of init).
+ */
+function describeVendors(vendors, global) {
+  try {
+    const targets = placementTargetsFor({ vendors, global: !!global });
+    return targets.map(describePlacementTarget).join(", ");
+  } catch {
+    return vendors
+      .map((v) => AGENT_REGISTRY.find((e) => e.key === v)?.displayName ?? v)
+      .join(", ");
+  }
+}
 
 // Local print helpers that use the INJECTED stdout/stderr streams.
 // The prompt.mjs `print*` helpers write to process.stdout directly,
@@ -153,6 +204,16 @@ export async function runInit(argv, io = {}, deps = {}) {
 
   const { flags, yes, force, noSessionSync } = parseInitFlags(argv);
 
+  // Capture detection state EARLY — before step 3 writes
+  // `~/.claude/skillrepo/config.json`, which would itself create
+  // `~/.claude/` and self-fire the Claude Code home-trace signal.
+  // Detection has to reflect what's on disk before init touches
+  // anything. The result feeds the step 4 picker; it's only used
+  // when the user did NOT pass `--agent` (otherwise the picker is
+  // skipped). Capturing unconditionally is cheap (a handful of
+  // `existsSync` probes) and keeps the code simple.
+  const earlyDetections = detectAgents();
+
   // `--json` is for non-interactive consumers (CI scripts, programmatic
   // callers). Without `--yes`, init would hang at step 5 (MCP merge
   // per-vendor confirm prompt) waiting for stdin that no one is going
@@ -204,7 +265,10 @@ export async function runInit(argv, io = {}, deps = {}) {
         hint: "Pass --key sk_live_... or set SKILLREPO_ACCESS_KEY.",
       });
     }
-    apiKey = await promptSecret("Enter your access key (sk_live_...)");
+    apiKey = await promptWithBrowserOpen(
+      cliAuthUrl(serverUrl),
+      "Enter your access key (sk_live_...)",
+    );
   }
 
   // Trim whitespace from the key before validating. Pasting an API
@@ -241,7 +305,12 @@ export async function runInit(argv, io = {}, deps = {}) {
       !yes
     ) {
       p.warning("Existing config has an invalid key. Re-prompting for a new one.");
-      apiKey = (await promptSecret("Enter your access key (sk_live_...)")).trim();
+      apiKey = (
+        await promptWithBrowserOpen(
+          cliAuthUrl(serverUrl),
+          "Enter your access key (sk_live_...)",
+        )
+      ).trim();
       if (!apiKey || !apiKey.startsWith("sk_live_")) {
         throw validationError("Invalid access key format.");
       }
@@ -293,7 +362,10 @@ export async function runInit(argv, io = {}, deps = {}) {
   // three entries they should add manually. The config is already
   // saved at this point, so we don't abort init.
   try {
-    const gitignoreResult = mergeGitignore();
+    const gitignoreResult = mergeGitignore({
+      vendors: flags.vendors ?? undefined,
+      global: flags.global,
+    });
     if (gitignoreResult.action === "created") {
       p.success(`.gitignore created with ${gitignoreResult.added.length} SkillRepo entries`);
     } else if (gitignoreResult.action === "updated") {
@@ -306,61 +378,58 @@ export async function runInit(argv, io = {}, deps = {}) {
     p.warning(
       `Could not update .gitignore: ${err?.message ?? String(err)}. ` +
         `Add these entries manually: .env.local, .claude/skills/, ` +
-        `.claude/settings.local.json`,
+        `.agents/skills/, .claude/settings.local.json`,
     );
   }
   p.blank();
 
-  // ── Step 4: Detect IDEs ──────────────────────────────────────
-  p.step(4, 7, "Detecting IDEs");
+  // ── Step 4: Detection + two-row picker (#1236) ──────────────
+  p.step(4, 7, "Configuring targets");
 
-  // The v2.0.0 CLI had a silent fallback to [claudeCode, cursor]
-  // when nothing was detected. The v3.0.0 CLI removes that — the
-  // user must opt in via --ide. This catches headless CI scenarios
-  // early rather than silently installing configs the user didn't
-  // ask for.
+  // `flags.vendors === []` is the `--agent none` sentinel from
+  // parseAgentList. The user explicitly opted out of placement, so
+  // skip the picker entirely. Steps 5-7 downstream check
+  // `vendors.length === 0` to skip MCP merge, session-sync, and the
+  // first library sync.
+  //
+  // Any other non-null `flags.vendors` means the user passed an
+  // explicit `--agent` list — also skip the picker.
   let vendors;
-  if (flags.vendors) {
+  if (Array.isArray(flags.vendors) && flags.vendors.length === 0) {
     vendors = flags.vendors;
-    p.success(`Using explicit --ide list: ${vendors.join(", ")}`);
-  } else {
-    const detected = detectIdes();
-    const detectedKeys = Object.entries(detected)
-      .filter(([, v]) => v)
-      .map(([k]) => k);
-    const ideList = formatDetectedIdes(detected);
-    for (const ide of ideList) {
-      if (ide.detected) p.success(ide.name);
-    }
-    if (detectedKeys.length === 0) {
-      // Print a copy-pasteable MCP config blob so users whose IDEs
-      // aren't supported for auto-detection can still wire up MCP
-      // manually. Then refuse so headless CI scenarios fail loudly
-      // unless the user opts in with --ide. This call makes
-      // printManualMcpInstructions live code — it was exported
-      // but unused after the initial PR3b draft.
-      const mcpUrl = `${serverUrl}/api/mcp`;
-      printManualMcpInstructions(mcpUrl, { stdout });
-
-      throw validationError("No IDEs detected in this directory.", {
-        hint:
-          "The JSON above is a copy-pasteable MCP config for any IDE. " +
-          "Or run init from inside a project with .claude/, .cursor/, .vscode/, " +
-          "or with --ide <vendor> (claude, cursor, windsurf, vscode).",
-      });
+    p.success("Skipping placement (--agent none)");
+  } else if (flags.vendors) {
+    vendors = flags.vendors;
+    if (vendors.length === 0) {
+      p.success("Skipping placement (--agent none).");
+    } else {
+      p.success(`Configured: ${describeVendors(vendors, flags.global)}`);
     }
-    // Confirm the detected list unless --yes
-    if (!yes) {
-      const names = ideList
-        .filter((i) => i.detected)
-        .map((i) => i.name)
-        .join(", ");
-      const ok = await confirm(`Configure for: ${names}?`, true);
-      if (!ok) {
-        throw validationError("Cancelled. Pass --ide <vendor> to target specific IDEs.");
-      }
+  } else {
+    vendors = await runDetectionPicker({
+      yes,
+      json: flags.json,
+      stdout,
+      detections: earlyDetections,
+    });
+    if (vendors.length === 0) {
+      p.success("Skipping placement (None selected).");
+    } else {
+      p.success(`Configured: ${describeVendors(vendors, flags.global)}`);
     }
-    vendors = detectedKeys;
+  }
+
+  // Validate the (vendor, --global) combination upfront. Catches cases
+  // like `--global --agent copilot` (Copilot has no personal scope)
+  // before any side-effectful work runs. Without this check, the
+  // validation error would fire from inside runSync and be swallowed
+  // by the partial-state try/catch below — exiting 0 with a warning
+  // when the user's invocation was structurally invalid.
+  if (Array.isArray(vendors) && vendors.length > 0) {
+    placementTargetsFor({
+      vendors: effectiveVendors({ vendors, global: flags.global }),
+      global: flags.global,
+    });
   }
   p.blank();
 
@@ -405,9 +474,15 @@ export async function runInit(argv, io = {}, deps = {}) {
   // because the hook's `skillrepo update` calls expect the config
   // to already be written (step 3).
   p.step(6, 7, "Session sync");
+  // Install the Claude Code SessionStart hook only when Claude Code
+  // is actually a target. Pre-#1249 this condition also included
+  // `Boolean(flags.global)` because bare `--global` historically
+  // routed to Claude; after #1249's effectiveVendors fix, `--global
+  // --agent windsurf` legitimately targets Windsurf only, and we
+  // must NOT silently add a Claude hook for users who never picked
+  // Claude. Manual E2E sweep caught this regression.
   const claudeTargeted =
-    Boolean(flags.global) ||
-    (Array.isArray(vendors) && vendors.includes("claudeCode"));
+    Array.isArray(vendors) && vendors.includes("claudeCode");
   const sessionSync = await installSessionSyncHook({
     noSessionSync,
     claudeTargeted,
@@ -426,62 +501,87 @@ export async function runInit(argv, io = {}, deps = {}) {
   p.step(7, 7, "Pulling library");
   let syncSummary;
   let syncFailedReason = null;
-  try {
-    // In --json mode, suppress runSync's warning prints to stdout
-    // by passing a black-hole stream. (Its warnings go to stderr
-    // by default, which stays visible.)
-    const syncIo = flags.json
-      ? { stdout: BLACK_HOLE_STREAM, stderr: stderr }
-      : io;
-    syncSummary = await runSync({
-      serverUrl,
-      apiKey,
-      vendors: effectiveVendors({ vendors, global: flags.global }),
-      global: flags.global,
-      io: syncIo,
-    });
-  } catch (err) {
-    // A sync failure after the rest of init succeeded is a
-    // partial-state concern: config IS saved, MCP IS configured,
-    // and the access key IS validated — only the skill files
-    // haven't been fetched yet. The right recovery is `skillrepo
-    // update`, not a re-init. Surface the warning and exit 0 so
-    // the user sees the "run update later" message as actionable
-    // guidance rather than as a failed-command contradiction.
-    //
-    // Round-2 review caught the prior behavior (warn + unconditional
-    // rethrow) as an inconsistent contract: the warning told users
-    // to retry with `update`, but the non-zero exit code made it
-    // look like the whole init had failed.
-    p.warning(
-      `Config saved but first sync failed: ${err.message}. ` +
-        `Run \`skillrepo update\` later to retry.`,
-    );
-    syncFailedReason = err.message;
-    // Synthesize a zero-delta summary matching the SyncSummary
-    // typedef in sync.mjs (added, updated, removed, notModified,
-    // syncedAt). No `unchanged` or `failed` field — those were
-    // phantom fields the cross-review flagged; failure is signaled
-    // via `syncFailedReason` locally and via `sync.failureReason`
-    // in the --json output below.
+  // `--agent none` short-circuits the first sync: the user opted
+  // out of placement, and the credential write + gitignore + MCP
+  // bookkeeping that init also does are still complete. Calling
+  // runSync with an empty vendor list would throw inside
+  // placementTargetsFor (no vendors specified), and even if it
+  // didn't, fetching skill files we have nowhere to write is
+  // pure waste.
+  const skipFirstSync =
+    Array.isArray(vendors) && vendors.length === 0 && !flags.global;
+  if (skipFirstSync) {
+    p.success("Skipped first sync (--agent none).");
     syncSummary = {
       added: 0,
       updated: 0,
       removed: 0,
       notModified: false,
-      // On a synthesized failure summary we genuinely don't know
-      // whether the sync WOULD have been full or delta — the network
-      // call never completed. Architect review (v3.1.1) flagged that
-      // emitting `fullSync: false` here is misleading for --json
-      // consumers: it looks like a legitimate "delta sync returned
-      // zero" signal. Using `null` makes the unknown-state
-      // explicit — any typed consumer must handle it separately
-      // from true/false. The always-present `sync.failureReason`
-      // field is still the authoritative "did the sync fail"
-      // indicator; fullSync is just additional context.
+      // Same null-fullSync rationale as the failure-recovery branch:
+      // the network call never ran, so reporting `false` would be a
+      // legitimate-looking "delta returned zero" lie. `null` makes
+      // the unknown-state explicit.
       fullSync: null,
       syncedAt: new Date().toISOString(),
     };
+  } else {
+    try {
+      // In --json mode, suppress runSync's warning prints to stdout
+      // by passing a black-hole stream. (Its warnings go to stderr
+      // by default, which stays visible.)
+      const syncIo = flags.json
+        ? { stdout: BLACK_HOLE_STREAM, stderr: stderr }
+        : io;
+      syncSummary = await runSync({
+        serverUrl,
+        apiKey,
+        vendors: effectiveVendors({ vendors, global: flags.global }),
+        global: flags.global,
+        io: syncIo,
+      });
+    } catch (err) {
+      // A sync failure after the rest of init succeeded is a
+      // partial-state concern: config IS saved, MCP IS configured,
+      // and the access key IS validated — only the skill files
+      // haven't been fetched yet. The right recovery is `skillrepo
+      // update`, not a re-init. Surface the warning and exit 0 so
+      // the user sees the "run update later" message as actionable
+      // guidance rather than as a failed-command contradiction.
+      //
+      // Round-2 review caught the prior behavior (warn + unconditional
+      // rethrow) as an inconsistent contract: the warning told users
+      // to retry with `update`, but the non-zero exit code made it
+      // look like the whole init had failed.
+      p.warning(
+        `Config saved but first sync failed: ${err.message}. ` +
+          `Run \`skillrepo update\` later to retry.`,
+      );
+      syncFailedReason = err.message;
+      // Synthesize a zero-delta summary matching the SyncSummary
+      // typedef in sync.mjs (added, updated, removed, notModified,
+      // syncedAt). No `unchanged` or `failed` field — those were
+      // phantom fields the cross-review flagged; failure is signaled
+      // via `syncFailedReason` locally and via `sync.failureReason`
+      // in the --json output below.
+      syncSummary = {
+        added: 0,
+        updated: 0,
+        removed: 0,
+        notModified: false,
+        // On a synthesized failure summary we genuinely don't know
+        // whether the sync WOULD have been full or delta — the network
+        // call never completed. Architect review (v3.1.1) flagged that
+        // emitting `fullSync: false` here is misleading for --json
+        // consumers: it looks like a legitimate "delta sync returned
+        // zero" signal. Using `null` makes the unknown-state
+        // explicit — any typed consumer must handle it separately
+        // from true/false. The always-present `sync.failureReason`
+        // field is still the authoritative "did the sync fail"
+        // indicator; fullSync is just additional context.
+        fullSync: null,
+        syncedAt: new Date().toISOString(),
+      };
+    }
   }
 
   const zeroDeltas =
@@ -599,10 +699,10 @@ export async function runInit(argv, io = {}, deps = {}) {
 
 /**
  * Parse init-specific flags. Uses resolveFlags for the common ones
- * (--key/--url/--global/--ide/--json) and pulls out --yes/-y + --force.
+ * (--key/--url/--global/--agent/--json) and pulls out --yes/-y + --force.
  */
 function parseInitFlags(argv) {
-  // resolveFlags handles --key/--url/--global/--ide/--json and
+  // resolveFlags handles --key/--url/--global/--agent/--json and
   // rejects unknown flags via its acceptPositional callback. We
   // intercept --yes, --force, and --no-session-sync as "positional-
   // shaped" flags via the callback so we don't need to pre-filter
@@ -644,3 +744,237 @@ function parseInitFlags(argv) {
 
   return { flags, yes, force, noSessionSync };
 }
+
+/**
+ * Build the picker rows from a detection result.
+ *
+ * Both Claude Code and the cohort row are pre-checked when ANY signal
+ * fires for that target. On a fresh clone with no detection, both
+ * rows are still pre-checked — the product's reason for existing is
+ * to set up skills, and defaulting to "do nothing" because env vars
+ * didn't fire is the bug we are fixing.
+ *
+ * @param {ReturnType<typeof detectAgents>} detections
+ * @returns {{ items: import("../lib/prompt-multiselect.mjs").MultiSelectItem[], claudeReason: string|null, cohortReasons: string[] }}
+ */
+function buildPickerItems(detections) {
+  const claudeDetection = detections.find((d) => d.key === "claudeCode");
+  const cohortDetections = detections.filter((d) =>
+    AGENTS_COHORT_KEYS.includes(d.key),
+  );
+  const cohortDetectedNames = cohortDetections
+    .filter((d) => d.detected)
+    .map((d) => d.displayName);
+
+  const claudeDetected = Boolean(claudeDetection?.detected);
+  const cohortDetected = cohortDetectedNames.length > 0;
+
+  // Idempotent re-run hint: if the target dir already exists with
+  // content, annotate the row.
+  const claudeAlreadyConfigured = directoryHasContent(claudeSkillsProjectRoot());
+  const cohortAlreadyConfigured = directoryHasContent(agentsSkillsProjectRoot());
+
+  const claudeHint = formatHint({
+    detectionReason: claudeDetected ? claudeDetection.reason : null,
+    pathLabel: ".claude/skills/",
+    alreadyConfigured: claudeAlreadyConfigured,
+  });
+  const cohortHint = formatHint({
+    detectionReason: cohortDetected ? formatCohortBrands(cohortDetectedNames) : null,
+    pathLabel: ".agents/skills/",
+    alreadyConfigured: cohortAlreadyConfigured,
+  });
+
+  // Three-state pre-check policy:
+  //   1. Detection fires for both targets → both rows pre-checked.
+  //   2. Detection fires for one target only → only that row pre-checked
+  //      (the other stays empty so the picker nudges the user toward
+  //      what we actually found).
+  //   3. No detection anywhere (fresh clone) → both rows pre-checked
+  //      (the product's job is to set things up; defaulting to "do
+  //      nothing" is the bug we are fixing).
+  const anySignal = claudeDetected || cohortDetected;
+  const claudePreChecked = anySignal ? claudeDetected : true;
+  const cohortPreChecked = anySignal ? cohortDetected : true;
+
+  return {
+    claudeReason: claudeDetected ? claudeDetection.reason : null,
+    cohortReasons: cohortDetectedNames,
+    items: [
+      {
+        key: "claude",
+        label: "Claude Code",
+        hint: claudeHint,
+        preChecked: claudePreChecked,
+      },
+      {
+        key: "agents",
+        label: "Other agents",
+        hint: cohortHint,
+        preChecked: cohortPreChecked,
+      },
+      {
+        key: "none",
+        label: "None — I'll configure manually",
+        preChecked: false,
+      },
+    ],
+  };
+}
+
+/**
+ * Format the cohort detection reason. Up to 3 brand names listed,
+ * then "+N more" — keeps the picker hint readable when most cohort
+ * vendors fire at once.
+ *
+ * @param {string[]} names
+ */
+export function formatCohortBrands(names) {
+  if (names.length <= 3) return names.join(", ");
+  return `${names.slice(0, 3).join(", ")} +${names.length - 3} more`;
+}
+
+/**
+ * Build the per-row hint string. Combines the path label, the
+ * detection reason (or the "no signal" fallback), and the
+ * already-configured annotation when applicable.
+ *
+ * Exported for unit-test surface area (#1252 / QA round): the
+ * `(already configured — re-checking will refresh)` annotation has
+ * historically been only end-to-end-tested via the picker, which
+ * locks the wording to its rendering layer rather than to the data
+ * shape callers expect. Direct testing of this helper means a future
+ * refactor that splits picker rendering from row construction can't
+ * silently drop the annotation without breaking the targeted unit
+ * test.
+ *
+ * @param {object} args
+ * @param {string|null} args.detectionReason
+ * @param {string} args.pathLabel
+ * @param {boolean} args.alreadyConfigured
+ */
+export function formatHint({ detectionReason, pathLabel, alreadyConfigured }) {
+  const detectionPart = detectionReason
+    ? `(detected: ${detectionReason})`
+    : "(not detected — leave checked if you use one)";
+  const configuredPart = alreadyConfigured
+    ? " (already configured — re-checking will refresh)"
+    : "";
+  return `${pathLabel}  ${detectionPart}${configuredPart}`;
+}
+
+/**
+ * `true` when `dir` exists and contains at least one entry. Used to
+ * annotate the picker rows with the idempotent "already configured"
+ * hint. We don't validate skill layout here — any content under the
+ * target dir means a prior run wrote there.
+ *
+ * Exported alongside `formatHint` for direct unit-test coverage of
+ * the idempotent re-run annotation path. See `formatHint` for the
+ * rationale.
+ *
+ * @param {string} dir
+ */
+export function directoryHasContent(dir) {
+  if (!existsSync(dir)) return false;
+  try {
+    const entries = readdirSync(dir);
+    return entries.length > 0;
+  } catch {
+    // Permission denied, race, etc. — treat as "no content" so the
+    // row is annotated as fresh. Annotation is informational; a
+    // false negative just shows the row without the "already
+    // configured" hint, which is harmless.
+    return false;
+  }
+}
+
+/**
+ * Run the two-row picker and translate the user's selection into a
+ * vendors list. The output matches what `--agent` produces:
+ *
+ *   - "claude" selected → ["claudeCode"]
+ *   - "agents" selected → cohort keys
+ *   - "claude" + "agents" selected → ["claudeCode", ...cohort]
+ *   - "none" selected (alone) → []
+ *   - "none" + anything else → rejected (validation error)
+ *
+ * Under `--yes`, the picker render is skipped: the pre-checked rows
+ * become the selection. With no detection, that means both default
+ * rows pre-checked → both targets configured. Spec rationale: writing
+ * a few KB the user didn't strictly need is trivial; CI running
+ * `init --yes` on a fresh clone and writing nothing is broken
+ * automation.
+ *
+ * @param {object} args
+ * @param {boolean} args.yes
+ * @param {boolean} args.json    - True under --json: suppress the human
+ *           explanatory header so stdout stays parseable.
+ * @param {NodeJS.WritableStream} args.stdout
+ * @param {ReturnType<typeof detectAgents>} args.detections - Captured
+ *           BEFORE step 3 writes `~/.claude/skillrepo/config.json`
+ *           (which would itself create `~/.claude/` and self-fire the
+ *           Claude Code home-trace signal).
+ * @returns {Promise<string[]>}
+ */
+async function runDetectionPicker({ yes, json, stdout, detections }) {
+  const { items } = buildPickerItems(detections);
+
+  // Print the explanatory header before the picker (or before the
+  // pre-checked auto-select under --yes). Keeps the user grounded
+  // in WHAT will be written WHERE. Suppressed under --json so the
+  // final JSON blob is the only thing on stdout.
+  if (!json) {
+    stdout.write(
+      "\n  This will write skills to your project under:\n" +
+        "    .claude/skills/   (for Claude Code)\n" +
+        "    .agents/skills/   (for Cursor, Windsurf, Gemini CLI, Codex CLI, " +
+        "Cline, Copilot, and others)\n" +
+        "\n" +
+        "  Both paths are added to .gitignore — skills are a per-developer " +
+        "cache, not committed.\n\n",
+    );
+  }
+
+  let selectedKeys;
+  if (yes) {
+    // Auto-select: pre-checked rows become the selection.
+    selectedKeys = items
+      .filter((it) => it.preChecked)
+      .map((it) => it.key);
+  } else {
+    selectedKeys = await promptMultiSelect(
+      { question: "Set up which targets?", items },
+      { stdout },
+    );
+  }
+
+  return translatePickerSelection(selectedKeys);
+}
+
+/**
+ * Map the picker's selected keys to the canonical vendor list.
+ * Exported for test surface area would be ideal but the function is
+ * an internal helper to `runDetectionPicker` — translation is
+ * exercised end-to-end via `init.test.mjs`.
+ *
+ * @param {string[]} selected
+ * @returns {string[]}
+ */
+function translatePickerSelection(selected) {
+  const hasNone = selected.includes("none");
+  const hasOther = selected.some((k) => k !== "none");
+  if (hasNone && hasOther) {
+    throw validationError(
+      "Cannot mix 'None' with other targets in the picker.",
+      {
+        hint: "Pick either 'None' alone (skip placement) or one or both of the configured target rows.",
+      },
+    );
+  }
+  if (hasNone) return [];
+  const out = [];
+  if (selected.includes("claude")) out.push("claudeCode");
+  if (selected.includes("agents")) out.push(...AGENTS_COHORT_KEYS);
+  return out;
+}