skillrepo 3.2.0 → 4.0.0

package/src/commands/remove.mjs

@@ -32,13 +32,17 @@
  *   - 403 scope → scopeError (via http.mjs) with write-key hint
  *   - 401 → authError
  *
- * Flags: --global / --ide / --json / --key / --url
+ * Flags: --global / --agent / --json / --key / --url
  * Positional: <@owner/name>
  */
 
 import { removeSkillFromLibrary } from "../lib/http.mjs";
 import { removeSkillDir, cleanupOrphans } from "../lib/file-write.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -75,6 +79,10 @@ export async function runRemove(argv, io = {}) {
 
   const { owner, name } = parseIdentifier(identifier);
   const vendors = effectiveVendors(flags);
+  // `remove` deletes specific files from disk — `--agent none` means
+  // "no targets to delete from", which is a no-op the user almost
+  // certainly didn't intend. Reject early.
+  requireVendorTargets(vendors, "remove");
 
   // Pre-flight: clean any .old/ orphans from a prior crashed write.
   // `remove` isn't writing new files, but it IS deleting, and the

package/src/commands/uninstall.mjs

@@ -430,7 +430,7 @@ function renderPreviewLine(descriptor, result) {
 function parseUninstallFlags(argv) {
   let dryRun = false;
   let yes = false;
-  // Reuse resolveFlags for the standard --global / --json / --ide /
+  // Reuse resolveFlags for the standard --global / --json / --agent /
   // --key / --url shape. resolveFlags ignores unknown flags when an
   // acceptPositional callback is provided that can consume them —
   // the callback pattern matches init's own parsing.

package/src/commands/update.mjs

@@ -7,7 +7,7 @@
  *
  * Flags (parsed by the shared `resolveFlags` helper):
  *   --global         Write to ~/.claude/skills/ instead of project-local
- *   --ide <list>     Comma-separated vendor list
+ *   --agent <list>   Comma-separated agent target list
  *   --json           Print summary as JSON
  *   --key <key>      Override config-file access key
  *   --url <url>      Override config-file server URL
@@ -26,7 +26,11 @@
  */
 
 import { runSync } from "../lib/sync.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  resolveFlags,
+  effectiveVendors,
+  requireVendorTargets,
+} from "../lib/cli-config.mjs";
 
 /**
  * Run `update`.
@@ -70,7 +74,7 @@ export async function runUpdate(argv, io = {}) {
   //     fires before `skillrepo init` has run — a real first-run
   //     scenario, not synthetic)
   //   - `validationError` on unknown flags
-  //   - `validationError` from parseVendorList on a malformed --ide
+  //   - `validationError` from parseAgentList on a malformed --agent
   //
   // All three happen INSIDE resolveFlags, before our try/catch block
   // could see them if we called it after. The only robust answer is
@@ -98,6 +102,13 @@ export async function runUpdate(argv, io = {}) {
         },
       });
       const vendors = effectiveVendors(flags);
+      // `--agent none` makes `update` a no-op — the user opted out of
+      // placement, so there's nowhere to write the synced library.
+      // Reject in session-hook mode too: the contract is "exit 0 on
+      // any error", but the requireVendorTargets throw is a typed
+      // validation error and the outer try/catch maps it to the
+      // documented one-line failure message.
+      requireVendorTargets(vendors, "update");
 
       const summary = await runSync({
         serverUrl: flags.serverUrl,
@@ -143,6 +154,7 @@ export async function runUpdate(argv, io = {}) {
   // when tests inject one.
   const flags = resolveFlags(argv);
   const vendors = effectiveVendors(flags);
+  requireVendorTargets(vendors, "update");
 
   const summary = await runSync({
     serverUrl: flags.serverUrl,

package/src/lib/agent-registry.mjs

@@ -0,0 +1,215 @@
+/**
+ * Single source of truth for the agent vendors the CLI supports (#1234).
+ *
+ * Every agent the CLI knows about is declared here exactly once. Path
+ * resolvers (file-write.mjs), flag parsers (cli-config.mjs), MCP merge
+ * coordinators (mcp-merge.mjs), gitignore management (mergers/gitignore.mjs),
+ * detection probes (detect-agents.mjs), and orphan sweeps all derive their
+ * vendor lists from this registry.
+ *
+ * Adding a vendor: append a frozen entry. Renaming a vendor: change `key`
+ * and put the old key in `aliases` so prior CLI invocations keep working.
+ *
+ * The two-target placement model (per the verified vendor matrix):
+ *   - Claude Code uses Anthropic's documented `.claude/skills/` path.
+ *   - Every other supported agent shares `.agents/skills/` for project
+ *     scope and (with the exception of Windsurf and Copilot) for personal
+ *     scope. Windsurf has a vendor-specific personal path under
+ *     `~/.codeium/windsurf/skills/`. Copilot has no personal scope.
+ *
+ * Detection signals (`detectionSignals`) are the primary-source-verified
+ * fingerprints `detect-agents.mjs` probes when picking which agents have
+ * footprint on this machine / in this project. Three signal types:
+ *
+ *   - `env` — an environment variable the agent sets in shells/sub-processes
+ *     it spawns. Truthy presence in `process.env` indicates an active session.
+ *     NOTE: only assert env vars the vendor's own docs document as set BY the
+ *     agent in spawned shells. Variables the agent merely *reads* (e.g.
+ *     `CODEX_HOME` for Codex's config dir) are config inputs, not detection
+ *     signals — listing them here would produce false positives.
+ *   - `home` — a HOME-relative path the agent creates on first run. Used as
+ *     a "this user has installed the agent" proxy when no env var is
+ *     documented.
+ *   - `project` — a CWD-relative dotfile / dotdir the user keeps in the
+ *     repo to drive agent behavior. Used as the "configured in this repo"
+ *     signal.
+ *
+ * Detection is registry-driven: adding a new signal is a registry edit,
+ * no detect-agents.mjs change required.
+ *
+ * @typedef {"claudeProject" | "claudeGlobal" | "agentsProject" | "agentsGlobal" | "windsurfGlobal"} PlacementTarget
+ *
+ * @typedef {Object} DetectionSignal
+ * @property {"env"|"home"|"project"} type
+ * @property {string} value           - Env var name, HOME-relative path, or
+ *           project (CWD)-relative path. Use forward slashes; resolution is
+ *           via `node:path.join` so Windows separators are produced
+ *           automatically at probe time.
+ *
+ * @typedef {Object} AgentEntry
+ * @property {string} key             - Canonical key. Stored in config files.
+ * @property {string} displayName     - User-facing name (used in prompts and summaries).
+ * @property {string[]} aliases       - Alternate names accepted on the command line.
+ * @property {PlacementTarget} projectTarget    - Where project-scope writes land.
+ * @property {PlacementTarget|null} globalTarget - Where personal-scope writes land, or null if the vendor has no personal scope.
+ * @property {boolean} hasMcp         - True if the CLI has a per-vendor MCP merger; false for file-only vendors (cohort vendors without a documented MCP config path).
+ * @property {readonly DetectionSignal[]} detectionSignals - Fingerprints that mark this agent as present.
+ */
+
+/** @type {readonly AgentEntry[]} */
+export const AGENT_REGISTRY = Object.freeze([
+  Object.freeze({
+    key: "claudeCode",
+    displayName: "Claude Code",
+    // `claude` is the canonical short token (also recognized
+    // explicitly by parseAgentList for the target-shortcut role).
+    // `claude-code` is the kebab-case form some users reach for by
+    // habit; accepting it as a silent alias matches the spec's
+    // "vendor names accepted silently as courtesy aliases" rule.
+    aliases: Object.freeze(["claude", "claude-code"]),
+    projectTarget: "claudeProject",
+    globalTarget: "claudeGlobal",
+    hasMcp: true,
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "CLAUDECODE" }),
+      Object.freeze({ type: "home", value: ".claude" }),
+      Object.freeze({ type: "project", value: ".claude" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "cursor",
+    displayName: "Cursor",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: true,
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "CURSOR_AGENT" }),
+      // CURSOR_CLI is the documented fallback when CURSOR_AGENT is
+      // not set in older Cursor builds; both fire under the same
+      // OR semantics so listing both costs nothing.
+      Object.freeze({ type: "env", value: "CURSOR_CLI" }),
+      Object.freeze({ type: "home", value: ".cursor" }),
+      Object.freeze({ type: "project", value: ".cursor" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "windsurf",
+    displayName: "Windsurf",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "windsurfGlobal",
+    hasMcp: true,
+    detectionSignals: Object.freeze([
+      // No documented active-session env var (verified absent in
+      // Windsurf docs 2026-05). HOME trace under the Codeium prefix
+      // is the strongest available signal.
+      Object.freeze({ type: "home", value: ".codeium/windsurf" }),
+      Object.freeze({ type: "project", value: ".windsurf" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "gemini",
+    displayName: "Gemini CLI",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    detectionSignals: Object.freeze([
+      Object.freeze({ type: "env", value: "GEMINI_CLI" }),
+      Object.freeze({ type: "home", value: ".gemini" }),
+      Object.freeze({ type: "project", value: ".gemini" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "codex",
+    displayName: "Codex CLI",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    detectionSignals: Object.freeze([
+      // Codex has no documented active-session env var. CODEX_HOME
+      // is a config var Codex *reads*, not one it sets — listing it
+      // would produce false positives for users who simply have the
+      // var pointed elsewhere. Detection is HOME + project only.
+      Object.freeze({ type: "home", value: ".codex" }),
+      Object.freeze({ type: "project", value: ".codex" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "cline",
+    displayName: "Cline",
+    aliases: Object.freeze([]),
+    projectTarget: "agentsProject",
+    globalTarget: "agentsGlobal",
+    hasMcp: false,
+    detectionSignals: Object.freeze([
+      // Cline v3.24+ sets CLINE_ACTIVE="true" in spawned shells.
+      // Detection treats any truthy value as the signal.
+      Object.freeze({ type: "env", value: "CLINE_ACTIVE" }),
+      Object.freeze({ type: "home", value: ".cline" }),
+      Object.freeze({ type: "project", value: ".cline" }),
+    ]),
+  }),
+  Object.freeze({
+    key: "copilot",
+    displayName: "VS Code + Copilot",
+    aliases: Object.freeze(["vscode"]),
+    projectTarget: "agentsProject",
+    globalTarget: null,
+    hasMcp: true,
+    detectionSignals: Object.freeze([
+      // Copilot has no documented active-session env var. The HOME
+      // path is the directory the Copilot CLI / VS Code Copilot
+      // extension creates on first run; the project path is the
+      // documented Agent Skills location for VS Code + Copilot.
+      Object.freeze({ type: "home", value: ".copilot" }),
+      Object.freeze({ type: "project", value: ".github/skills" }),
+    ]),
+  }),
+]);
+
+/**
+ * Canonical keys of every cohort vendor — every registry entry whose
+ * project-scope writes land in `.agents/skills/`. Derived from the
+ * registry so a future cohort addition flows through every consumer
+ * without touching their code. Used by `cli-config.mjs` to expand the
+ * `--agent agents` token, and by `init.mjs` to translate the
+ * "Other agents" picker row to a vendor list.
+ *
+ * @type {readonly string[]}
+ */
+export const AGENTS_COHORT_KEYS = Object.freeze(
+  AGENT_REGISTRY.filter((entry) => entry.projectTarget === "agentsProject").map(
+    (entry) => entry.key,
+  ),
+);
+
+/**
+ * Look up a registry entry by its canonical key. Returns `undefined`
+ * for unknown keys — callers should treat that as a programming error.
+ *
+ * @param {string} key
+ * @returns {AgentEntry | undefined}
+ */
+export function getAgentByKey(key) {
+  return AGENT_REGISTRY.find((entry) => entry.key === key);
+}
+
+/**
+ * Resolve an alias (or canonical key) to its canonical key. Returns
+ * `null` for inputs that match neither a canonical key nor any
+ * declared alias. The function is case-sensitive — alias normalization
+ * is the caller's responsibility.
+ *
+ * @param {string} alias
+ * @returns {string | null}
+ */
+export function getAgentByAlias(alias) {
+  for (const entry of AGENT_REGISTRY) {
+    if (entry.key === alias) return entry.key;
+    if (entry.aliases.includes(alias)) return entry.key;
+  }
+  return null;
+}

package/src/lib/cli-config.mjs

@@ -2,7 +2,7 @@
  * Shared credential + flag resolution for command modules.
  *
  * Every command needs to:
- *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
+ *   1. Resolve `--key`/`--url`/`--agent`/`--global`/`--json` flags
  *   2. Fall back to ~/.claude/skillrepo/config.json
  *   3. Fall back to SKILLREPO_ACCESS_KEY / SKILLREPO_URL env vars
  *   4. Hard-error with an actionable hint pointing at `init` if no
@@ -20,17 +20,28 @@
 import { existsSync, readFileSync } from "node:fs";
 
 import { globalConfigPath } from "./paths.mjs";
+import {
+  AGENT_REGISTRY,
+  AGENTS_COHORT_KEYS,
+  getAgentByAlias,
+} from "./agent-registry.mjs";
 import { authError, validationError } from "./errors.mjs";
 
-const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
-const VENDOR_ALIASES = { claude: "claudeCode" };
+const ALL_VENDOR_KEYS = AGENT_REGISTRY.map((entry) => entry.key);
+
+// Sentinel returned by parseAgentList for `--agent none`. It is the
+// empty array literally — every consumer reads `flags.vendors.length`
+// to detect "no placement writes." Frozen so a downstream mutation
+// (e.g. `.push`) cannot turn one user's `none` into another's surprise.
+const NO_VENDORS = Object.freeze([]);
 
 /**
  * @typedef {Object} ResolvedFlags
  * @property {string} serverUrl
  * @property {string} apiKey
  * @property {boolean} global
- * @property {string[]|null} vendors  - null = use the default
+ * @property {string[]|null} vendors  - null = use the default;
+ *           empty array = `--agent none` (caller skips placement)
  * @property {boolean} json
  */
 
@@ -78,8 +89,22 @@ export function resolveFlags(argv, opts = {}) {
 
     if (arg === "--global") {
       flagState.global = true;
-    } else if (arg === "--ide" && argv[i + 1] !== undefined) {
-      flagState.vendors = parseVendorList(argv[++i]);
+    } else if (arg === "--agent") {
+      if (argv[i + 1] === undefined) {
+        throw validationError(
+          "Missing value for --agent. Pass a comma-separated list (e.g., --agent claude,agents).",
+        );
+      }
+      flagState.vendors = parseAgentList(argv[++i]);
+    } else if (arg === "--ide") {
+      throw validationError(
+        "--ide was renamed to --agent in v3.0.0.",
+        {
+          hint:
+            "Replace --ide with --agent (e.g., --agent claude). " +
+            "Run the command with --help for valid options.",
+        },
+      );
     } else if (arg === "--json") {
       flagState.json = true;
     } else if ((arg === "--key" || arg === "-k") && argv[i + 1] !== undefined) {
@@ -172,62 +197,139 @@ export function resolveFlags(argv, opts = {}) {
 }
 
 /**
- * Compute the vendor list to pass to file-write / sync. Defaults to
- * `["claudeCode"]` when neither `--ide` nor `--global` is provided —
- * the v3.0.0 CLI deliberately does NOT silently fall back to
- * `[claudeCode, cursor]` like v2.0.0 did. The user opts in.
+ * Compute the vendor list to pass to file-write / sync.
+ *
+ * Resolution order:
+ *   1. Explicit `--agent` (including the `--agent none` sentinel `[]`)
+ *      always wins. Both flags propagate together, so `--global
+ *      --agent windsurf` correctly resolves to `["windsurf"]` and
+ *      placementTargetsFor maps that to `windsurfGlobal`.
+ *   2. No `--agent` defaults to `["claudeCode"]`, regardless of
+ *      `--global`. The v3.0.0 CLI deliberately does NOT silently
+ *      fall back to `[claudeCode, cursor]` like v2.0.0 did.
+ *
+ * The empty-array `--agent none` sentinel is returned verbatim —
+ * callers detect "no placement" via `vendors.length === 0`. The
+ * default-fallback branch uses an explicit null/undefined check so
+ * the empty array survives.
  */
 export function effectiveVendors(flags) {
-  if (flags.global) return undefined; // global mode ignores vendors
-  if (flags.vendors) return flags.vendors;
-  return ["claudeCode"];
+  if (flags.vendors === null || flags.vendors === undefined) {
+    return ["claudeCode"];
+  }
+  return flags.vendors;
+}
+
+/**
+ * Reject `--agent none` for commands that have no meaningful behavior
+ * without a placement target. `init` and `update` accept `--agent none`
+ * (init still writes config + gitignore; update is a no-op). Every
+ * other write/read-write command (`add`, `get`, `remove`, `uninstall`)
+ * exists to put or remove specific skill files on disk — calling them
+ * with no targets is a user error, not a degenerate-but-valid case.
+ *
+ * Pass the resolved `vendors` array (the output of `effectiveVendors`).
+ * `undefined` (the `--global` case) is allowed because `--global`
+ * implies the Claude Code personal directory; only an empty array is
+ * rejected.
+ *
+ * @param {string[] | undefined} vendors
+ * @param {string} commandName - For the error message.
+ */
+export function requireVendorTargets(vendors, commandName) {
+  if (Array.isArray(vendors) && vendors.length === 0) {
+    throw validationError(
+      `--agent none has no effect on \`skillrepo ${commandName}\` ` +
+        `because the command writes or deletes specific skill files.`,
+      {
+        hint:
+          "Use --agent claude or --agent agents (or a specific vendor) to " +
+          "target a placement, or drop --agent to use the default.",
+      },
+    );
+  }
 }
 
 // ── Internals ──────────────────────────────────────────────────────────
 
-function parseVendorList(raw) {
+/**
+ * Parse the raw `--agent <list>` argument into a deduplicated array
+ * of canonical vendor keys, OR the empty array sentinel for `none`.
+ *
+ * Token semantics (each comma-separated token):
+ *
+ *   - `none`  → empty array (no placement writes). Must be the only
+ *               token — mixing with any other token is rejected.
+ *   - `claude` → `["claudeCode"]` (the Claude Code target shortcut).
+ *   - `agents` → every cohort vendor whose project writes land in
+ *                `.agents/skills/`, derived from the registry.
+ *   - canonical key (e.g., `claudeCode`, `cursor`) → that key.
+ *   - alias declared on a registry entry (e.g., `claude-code`,
+ *     `vscode`) → its canonical key.
+ *   - anything else → validation error.
+ *
+ * `all` is NOT a valid token — use `claude,agents` for full coverage.
+ */
+function parseAgentList(raw) {
   if (typeof raw !== "string") {
-    throw validationError(`--ide expects a comma-separated list, got: ${raw}`);
+    throw validationError(`--agent expects a comma-separated list, got: ${raw}`);
   }
 
-  // First pass: collect tokens, normalize aliases, detect `all`.
   const pieces = raw.split(",").map((p) => p.trim()).filter(Boolean);
-  const normalized = pieces.map((v) => VENDOR_ALIASES[v] ?? v);
-  const hasAll = normalized.includes("all");
-  const otherVendors = normalized.filter((v) => v !== "all");
-
-  // Defense against confusing input: `--ide cursor,all` is ambiguous
-  // — the user might think it means "cursor first, then everything"
-  // or "all minus duplicates". Both interpretations are wrong because
-  // `all` is the full set. Reject the combination so the user is
-  // forced to pick one.
-  if (hasAll && otherVendors.length > 0) {
-    throw validationError(
-      `--ide cannot mix "all" with other vendors: "${raw}"`,
-      { hint: "Use --ide all OR --ide claude,cursor,... — not both." },
-    );
+  if (pieces.length === 0) {
+    throw validationError("--agent list is empty.", {
+      hint: "Pass one or more of: claude, agents, none, or a vendor name.",
+    });
   }
 
-  if (hasAll) {
-    return ["claudeCode", "cursor", "windsurf", "vscode"];
+  // `none` is mutually exclusive with every other token. Mixing
+  // `--agent claude,none` is ambiguous — does the user want Claude
+  // or no placement? Reject so they pick one.
+  if (pieces.includes("none")) {
+    if (pieces.length > 1) {
+      throw validationError(
+        `--agent cannot mix "none" with other tokens: "${raw}"`,
+        { hint: "Pass --agent none alone, or list specific targets without none." },
+      );
+    }
+    return NO_VENDORS;
   }
 
-  if (normalized.length === 0) {
-    throw validationError("--ide list is empty.");
+  const expanded = [];
+  for (const token of pieces) {
+    if (token === "claude") {
+      expanded.push("claudeCode");
+      continue;
+    }
+    if (token === "agents") {
+      for (const key of AGENTS_COHORT_KEYS) {
+        expanded.push(key);
+      }
+      continue;
+    }
+    const canonical = getAgentByAlias(token);
+    if (canonical !== null) {
+      expanded.push(canonical);
+      continue;
+    }
+    throw validationError(`Unknown --agent target: "${token}"`, {
+      hint:
+        "Use one of: claude, agents, none, or a canonical vendor key " +
+        `(${ALL_VENDOR_KEYS.join(", ")}).`,
+    });
   }
 
-  // Validate each vendor token
-  for (const resolved of normalized) {
-    if (!VALID_VENDORS.has(resolved)) {
-      // Find the original (un-aliased) form for the error message
-      const original = pieces[normalized.indexOf(resolved)];
-      throw validationError(`Unknown --ide vendor: "${original}"`, {
-        hint: "Use claudeCode (or 'claude'), cursor, windsurf, vscode, or 'all'.",
-      });
+  // Dedupe while preserving first-seen order — matters for tests and
+  // for downstream consumers that iterate the array deterministically.
+  const seen = new Set();
+  const result = [];
+  for (const key of expanded) {
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(key);
     }
   }
-
-  return normalized;
+  return result;
 }
 
 function readGlobalConfig() {

package/src/lib/detect-agents.mjs

@@ -0,0 +1,112 @@
+/**
+ * Multi-signal agent detection (#1236, Phase 3 of #876).
+ *
+ * Replaces the single-signal `detect-ides.mjs` module. Detection is
+ * registry-driven: every probe is described as a `DetectionSignal` on
+ * the corresponding `AGENT_REGISTRY` entry, and this module just
+ * iterates the registry and runs the platform-correct probe for each
+ * signal type. Adding a new signal is a registry edit, no change here.
+ *
+ * Three signal types:
+ *
+ *   - `env`     — `process.env[value]` is truthy. Indicates an active
+ *                 agent session (the agent itself sets the var in the
+ *                 shells it spawns).
+ *   - `home`    — `~/<value>` exists on disk. Indicates the agent has
+ *                 been installed for this user (most agents create the
+ *                 directory on first run).
+ *   - `project` — `<cwd>/<value>` exists on disk. Indicates the agent
+ *                 is configured for this repo (dotdir / dotfile).
+ *
+ * For each agent, `detected` is the OR of all signal probes. The first
+ * signal that fires (priority order: env > home > project) becomes the
+ * human-readable `reason`. Reasons are formatted to match the picker UX:
+ *
+ *   - env signal:     `"CLAUDECODE=1"`
+ *   - home signal:    `"~/.claude/"` or `"~/.codeium/windsurf/"`
+ *   - project signal: `".claude/"` or `".github/skills/"`
+ *   - none:           `null` (the picker translates this to
+ *                     `"(no signal — opt in if you use one)"`)
+ *
+ * Cross-platform: paths use `node:path.join(homedir(), …)` and
+ * `join(process.cwd(), …)`. On Windows, `homedir()` reads
+ * `USERPROFILE`; the test sandbox helper sets both HOME and USERPROFILE
+ * so probes are sandbox-isolated on every platform.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { AGENT_REGISTRY } from "./agent-registry.mjs";
+
+/**
+ * @typedef {Object} AgentDetection
+ * @property {string} key                 - Canonical agent key.
+ * @property {string} displayName         - Brand name (used in picker hints).
+ * @property {boolean} detected           - True if any signal fired.
+ * @property {string|null} reason         - Short human-readable label of the
+ *           first signal that fired, or `null` when nothing fired.
+ */
+
+/**
+ * Probe one detection signal against the live process state and disk.
+ *
+ * Pure helper. Returns the formatted reason string when the signal
+ * fires, or `null` when it does not.
+ *
+ * @param {import("./agent-registry.mjs").DetectionSignal} signal
+ * @returns {string | null}
+ */
+function probeSignal(signal) {
+  if (signal.type === "env") {
+    const raw = process.env[signal.value];
+    if (raw === undefined || raw === "") return null;
+    // Env vars in shell environments are always strings. Truthy
+    // values include "1", "true", "yes", etc — Cline's documented
+    // value is the literal string "true". We accept any non-empty
+    // value rather than a stricter truthy-string match because the
+    // signal's purpose is "the agent set this var on me" and any
+    // value the agent chose to set qualifies.
+    return `${signal.value}=${raw}`;
+  }
+  if (signal.type === "home") {
+    const path = join(homedir(), signal.value);
+    if (!existsSync(path)) return null;
+    return `~/${signal.value}/`;
+  }
+  if (signal.type === "project") {
+    const path = join(process.cwd(), signal.value);
+    if (!existsSync(path)) return null;
+    return `${signal.value}/`;
+  }
+  // Unknown type — defensive guard. Callers should never see this
+  // because the registry's frozen entries are typed.
+  return null;
+}
+
+/**
+ * Detect every agent in the registry against the current process and
+ * working directory. Returns one `AgentDetection` per registry entry,
+ * in registry order (Claude Code first, then the cohort).
+ *
+ * @returns {AgentDetection[]}
+ */
+export function detectAgents() {
+  return AGENT_REGISTRY.map((entry) => {
+    let reason = null;
+    for (const signal of entry.detectionSignals) {
+      const fired = probeSignal(signal);
+      if (fired !== null) {
+        reason = fired;
+        break;
+      }
+    }
+    return {
+      key: entry.key,
+      displayName: entry.displayName,
+      detected: reason !== null,
+      reason,
+    };
+  });
+}