agent-skillboard 0.3.0 → 0.3.1

package/src/agent-root-registry.mjs

@@ -0,0 +1,127 @@
+import { lstat, readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { atomicWrite } from "./migration/v2-files.mjs";
+
+const FORMAT_VERSION = 1;
+const SUPPORTED_AGENTS = new Set(["codex", "claude", "opencode", "hermes"]);
+
+export function agentRootRegistryPath(home) {
+  return join(resolve(home), ".skillboard", "agent-roots.json");
+}
+
+export async function loadRegisteredAgentRoots(home) {
+  const root = resolve(home);
+  const path = agentRootRegistryPath(root);
+  const stats = await lstat(path).catch(missingOnly);
+  if (stats === undefined) return [];
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error("Agent root registry must be a regular file, not a symbolic link.");
+  }
+  const value = JSON.parse(await readFile(path, "utf8"));
+  if (value?.format_version !== FORMAT_VERSION || !Array.isArray(value.roots)) {
+    throw new Error("Invalid agent root registry format.");
+  }
+  const entries = normalizeEntries(value.roots, root);
+  for (const entry of entries) await assertSafeRootPath(root, entry.path);
+  return entries;
+}
+
+export async function proposedAgentRoot(home, agent, path, cwd = process.cwd()) {
+  assertAgent(agent);
+  const root = resolve(home);
+  const target = resolve(cwd, path);
+  const rel = relative(root, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error("Registered skill root must remain inside the invoking user's home.");
+  }
+  await assertSafeRootPath(root, target);
+  return { agent, path: target };
+}
+
+export async function writeRegisteredAgentRoots(home, entries) {
+  const root = resolve(home);
+  const normalized = normalizeEntries(entries.map((entry) => ({
+    agent: entry.agent,
+    path: portablePath(root, entry.path)
+  })), root);
+  const value = {
+    format_version: FORMAT_VERSION,
+    roots: normalized.map((entry) => ({ agent: entry.agent, path: portablePath(root, entry.path) }))
+  };
+  await atomicWrite(agentRootRegistryPath(root), Buffer.from(`${JSON.stringify(value, null, 2)}\n`));
+  return normalized;
+}
+
+export function mergeRegisteredAgentRoots(entries, proposed) {
+  const byKey = new Map();
+  const agentByPath = new Map();
+  for (const entry of proposed === undefined ? entries : [...entries, proposed]) {
+    assertAgent(entry.agent);
+    const path = resolve(entry.path);
+    const registeredAgent = agentByPath.get(path);
+    if (registeredAgent !== undefined && registeredAgent !== entry.agent) {
+      throw new Error(`Custom skill root is already registered for agent ${registeredAgent}: ${path}`);
+    }
+    agentByPath.set(path, entry.agent);
+    byKey.set(`${entry.agent}\0${path}`, { agent: entry.agent, path });
+  }
+  return [...byKey.values()].sort(compareEntries);
+}
+
+function normalizeEntries(entries, home) {
+  if (!entries.every((entry) => entry !== null && typeof entry === "object")) {
+    throw new Error("Invalid agent root registry entry.");
+  }
+  return mergeRegisteredAgentRoots(entries.map((entry) => {
+    assertAgent(entry.agent);
+    if (typeof entry.path !== "string" || entry.path.trim() === "") {
+      throw new Error("Registered skill root path must be a non-empty string.");
+    }
+    const path = isAbsolute(entry.path) ? resolve(entry.path) : resolve(home, entry.path);
+    const rel = relative(home, path);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+      throw new Error("Registered skill root must remain inside the invoking user's home.");
+    }
+    return { agent: entry.agent, path };
+  }));
+}
+
+function portablePath(home, path) {
+  return relative(home, resolve(path)).split("\\").join("/");
+}
+
+function assertAgent(agent) {
+  if (!SUPPORTED_AGENTS.has(agent)) {
+    throw new Error(`Unsupported setup agent: ${String(agent)}`);
+  }
+}
+
+function compareEntries(left, right) {
+  return `${left.agent}\0${left.path}`.localeCompare(`${right.agent}\0${right.path}`);
+}
+
+async function assertSafeRootPath(home, target) {
+  const components = [];
+  let current = resolve(target);
+  while (current !== home) {
+    components.push(current);
+    const parent = resolve(current, "..");
+    if (parent === current) break;
+    current = parent;
+  }
+  for (const component of components.reverse()) {
+    const stats = await lstat(component).catch(missingOnly);
+    if (stats === undefined) continue;
+    if (stats.isSymbolicLink()) {
+      throw new Error("Registered skill root must not traverse a symbolic link.");
+    }
+    if (!stats.isDirectory()) {
+      throw new Error("Registered skill root components must be directories.");
+    }
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") return undefined;
+  throw error;
+}

package/src/agent-skill-roots.mjs

@@ -1,6 +1,7 @@
-import { access, readdir } from "node:fs/promises";
+import { access, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { loadRegisteredAgentRoots } from "./agent-root-registry.mjs";
 
 const SUPPORTED_AGENTS = Object.freeze(["codex", "claude", "opencode", "hermes"]);
 
@@ -9,11 +10,12 @@ export function supportedAgentNames() {
 }
 
 export async function detectedAgentSkillRoots(agent, home = homedir(), env = process.env, options = {}) {
-  const candidates = await agentSkillRootCandidates(agent, home, env);
+  const candidates = await activeAgentSkillRootCandidates(agent, home, env, options);
   const detected = [];
   for (const candidate of candidates) {
     if (
       candidate.explicit
+      || candidate.registered
       || await exists(candidate.skillRoot)
       || candidate.detectWhenExists !== undefined && await exists(candidate.detectWhenExists)
     ) {
@@ -27,7 +29,7 @@ export async function detectedAgentSkillRoots(agent, home = homedir(), env = pro
 }
 
 export async function setupAgentSkillTargets(agent, home = homedir(), env = process.env, options = {}) {
-  const roots = await detectedAgentSkillRoots(agent, home, env, { includeFallback: options.includeFallback === true });
+  const roots = await detectedAgentSkillRoots(agent, home, env, options);
   return roots.map((root) => ({
     agent,
     home: resolve(home),
@@ -42,38 +44,61 @@ export async function preferredAgentSkillRoot(agent, home = homedir(), env = pro
   return root.skillRoot;
 }
 
-export async function agentSkillRootCandidates(agent, home = homedir(), env = process.env) {
+export async function activeAgentSkillRootCandidates(agent, home = homedir(), env = process.env, options = {}) {
+  const candidates = await agentSkillRootCandidates(agent, home, env, options);
+  const hasRegistered = candidates.some((entry) => entry.registered);
+  const hasExplicit = candidates.some((entry) => entry.explicit);
+  if (!hasRegistered && !hasExplicit) return candidates;
+  const active = await Promise.all(candidates.map(async (entry) => ({
+    entry,
+    keep: entry.registered
+      || entry.explicit
+      || entry.profile
+      || entry.sharedCodex
+      || await hasAgentOwnedSkillContent(entry.skillRoot)
+  })));
+  return active.filter(({ keep }) => keep).map(({ entry }) => entry);
+}
+
+export async function agentSkillRootCandidates(agent, home = homedir(), env = process.env, options = {}) {
   const normalized = normalizeAgent(agent);
   const xdgConfig = env.XDG_CONFIG_HOME ?? join(home, ".config");
+  const registered = (options.registeredRoots ?? await loadRegisteredAgentRoots(home))
+    .filter((entry) => entry.agent === normalized)
+    .map((entry) => candidate(entry.path, "registered custom skill root", false, false, undefined, { registered: true }));
   if (normalized === "codex") {
     const agentsHome = join(home, ".agents");
     return uniqueCandidates([
+      ...registered,
       env.CODEX_HOME === undefined ? null : candidate(join(env.CODEX_HOME, "skills"), "CODEX_HOME/skills", true, false),
       env.AGENTS_HOME === undefined ? null : candidate(join(env.AGENTS_HOME, "skills"), "AGENTS_HOME/skills", true, false),
-      candidate(join(agentsHome, "skills"), "~/.agents/skills", false, false, agentsHome),
-      candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true)
+      candidate(join(agentsHome, "skills"), "~/.agents/skills", false, false, agentsHome, { sharedCodex: true }),
+      candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true, join(home, ".codex"))
     ]);
   }
   if (normalized === "claude") {
     return uniqueCandidates([
+      ...registered,
       env.CLAUDE_HOME === undefined ? null : candidate(join(env.CLAUDE_HOME, "skills"), "CLAUDE_HOME/skills", true, false),
-      candidate(join(home, ".claude", "skills"), "~/.claude/skills", false, true),
+      candidate(join(home, ".claude", "skills"), "~/.claude/skills", false, true, join(home, ".claude")),
       candidate(join(xdgConfig, "claude", "skills"), "XDG claude skills", false, false),
       candidate(join(home, ".config", "claude", "skills"), "~/.config/claude/skills", false, false)
     ]);
   }
   if (normalized === "opencode") {
     return uniqueCandidates([
+      ...registered,
       env.OPENCODE_HOME === undefined ? null : candidate(join(env.OPENCODE_HOME, "skills"), "OPENCODE_HOME/skills", true, false),
-      candidate(join(xdgConfig, "opencode", "skills"), "XDG opencode skills", false, xdgConfig !== join(home, ".config")),
-      candidate(join(home, ".config", "opencode", "skills"), "~/.config/opencode/skills", false, true),
+      candidate(join(xdgConfig, "opencode", "skills"), "XDG opencode skills", false, xdgConfig !== join(home, ".config"), join(xdgConfig, "opencode")),
+      candidate(join(home, ".config", "opencode", "skills"), "~/.config/opencode/skills", false, true, join(home, ".config", "opencode")),
       candidate(join(home, ".opencode", "skills"), "~/.opencode/skills", false, false)
     ]);
   }
   const hermesHome = env.HERMES_HOME ?? join(home, ".hermes");
   return uniqueCandidates([
+    ...registered,
     env.HERMES_HOME === undefined ? null : candidate(join(env.HERMES_HOME, "skills"), "HERMES_HOME/skills", true, false),
-    candidate(join(home, ".hermes", "skills"), "~/.hermes/skills", false, true),
+    candidate(join(home, ".hermes", "skills"), "~/.hermes/skills", false, true, join(home, ".hermes")),
     ...(await hermesProfileCandidates(hermesHome))
   ]);
 }
@@ -85,8 +110,8 @@ function normalizeAgent(agent) {
   return agent;
 }
 
-function candidate(skillRoot, source, explicit, fallback, detectWhenExists) {
-  return { skillRoot, source, explicit, fallback, detectWhenExists };
+function candidate(skillRoot, source, explicit, fallback, detectWhenExists, metadata = {}) {
+  return { skillRoot, source, explicit, fallback, detectWhenExists, ...metadata };
 }
 
 function fallbackCandidate(candidates) {
@@ -112,9 +137,41 @@ async function hermesProfileCandidates(hermesHome) {
   const entries = await readdir(profilesRoot, { withFileTypes: true }).catch(() => []);
   return entries
     .filter((entry) => entry.isDirectory())
-    .map((entry) => candidate(join(profilesRoot, entry.name, "skills"), `Hermes profile ${entry.name}`, false, false));
+    .map((entry) => candidate(
+      join(profilesRoot, entry.name, "skills"),
+      `Hermes profile ${entry.name}`,
+      false,
+      false,
+      join(profilesRoot, entry.name),
+      { profile: true }
+    ));
 }
 
 async function exists(path) {
   return access(path).then(() => true, () => false);
 }
+
+async function hasAgentOwnedSkillContent(skillRoot) {
+  const entries = await readdir(skillRoot, { withFileTypes: true }).catch((error) => {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return [];
+    throw error;
+  });
+  for (const entry of entries) {
+    if (entry.name === "skillboard" || entry.name === ".system") continue;
+    if (!entry.isDirectory()) return true;
+    const metadata = await readFile(join(skillRoot, entry.name, ".skillboard-share.json"), "utf8")
+      .then((text) => {
+        try {
+          return JSON.parse(text);
+        } catch {
+          return null;
+        }
+      }, (error) => {
+        if (error?.code === "ENOENT") return null;
+        throw error;
+      });
+    if (metadata?.version === 1 && metadata.managed_by === "skillboard") continue;
+    return true;
+  }
+  return false;
+}

package/src/cli.mjs

@@ -76,7 +76,7 @@ const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.u
 const APPLY_ACTION_VALUE_OPTIONS = new Set(["agent", "workflow", "intent", "dir", "config", "skills", "out", "skillboard-bin"]);
 const COMMAND_USAGE = new Map([
   ["skill", ["enable|disable <skill-id> [--dry-run] [--json]", "share|unshare <skill-id> [--dry-run] [--json]", "preference <skill-id> --intent <term>[,<term>] --priority <integer> [--dry-run] [--json]", "forget <skill-id> [--dry-run] [--json]"]],
-  ["setup", ["setup [--yes] [--agent codex[,claude,opencode,hermes]]"]],
+  ["setup", ["setup [--yes] [--agent codex[,claude,opencode,hermes]] [--skill-root <path>]"]],
   ["import-skill", ["import-skill --from <agent> --to <agent> --skill <id-or-dir> [--target-skill <id-or-dir>] [--adapted-file <path>] [--dry-run] [--yes] [--replace] [--json]"]],
   ["uninstall", ["uninstall --user (--dry-run|--yes) [--json]", "uninstall [--dir <path>] [--dry-run] [--keep-settings] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs] [--agent-layer] [--agent codex[,claude,opencode,hermes]]"]],
   [
@@ -451,7 +451,10 @@ async function doctor(options, stdout) {
     root: options.get("dir") ?? dirname(state.configPath),
     configPath: state.configPath,
     skillsRoot: options.get("skills"),
-    verifySources: options.get("verify") === "true"
+    verifySources: options.get("verify") === "true",
+    entrypointPath: process.argv[1],
+    env: process.env,
+    packageVersion: VERSION
   });
   const summary = options.get("summary") === "true";
   writeOutput(stdout, result, options, () => summary ? renderDoctorSummary(result) : renderDoctor(result));
@@ -1285,7 +1288,7 @@ const VALUE_OPTIONS = new Set([
   "command", "config", "config-file", "dir", "exposure", "from", "harness", "harness-status",
   "hook-projection-version", "install-output", "intent", "invocation", "kind", "mode", "out",
   "owner-install-unit", "path", "priority", "profile", "profile-dirs", "rollback", "rollouts-dir",
-  "scan-root", "scope", "skill", "skillboard-bin", "skills", "source", "source-root", "status",
+  "scan-root", "scope", "skill", "skill-root", "skillboard-bin", "skills", "source", "source-root", "status",
   "target-skill", "to", "transaction", "trust-level", "unit", "workflow"
 ]);
 
@@ -1684,6 +1687,7 @@ function renderDoctorSummary(result) {
   const status = result.ok ? result.reviewRequired ? "safe mode, review needed" : "passed" : "needs attention";
   const lines = [
     `SkillBoard doctor: ${status}`,
+    renderInstallation(result.installation),
     `Workspace: ${result.workspace.skills.declared} skills, ${result.workspace.workflows} workflows, ${result.workspace.harnesses} harnesses, ${result.workspace.installUnits.total} install units`,
     `Source audit: ${result.sources.ok ? "passed" : "failed"} (${result.sources.errors.length} errors, ${result.sources.warnings.length} warnings, ${result.sources.blockingWarnings.length} blocking)`,
     `Policy: ${result.policy.ok ? "passed" : "failed"} (${result.policy.errors.length} errors, ${result.policy.warnings.length} warnings)`
@@ -1717,6 +1721,7 @@ function renderDoctor(result) {
   const status = result.ok ? result.reviewRequired ? "safe mode, review needed" : "passed" : "needs attention";
   const lines = [
     `SkillBoard doctor: ${status}`,
+    renderInstallation(result.installation),
     `Root: ${result.root}`,
     `Config: ${result.config.exists ? result.config.valid ? `valid v${result.config.version}` : `invalid (${result.config.error})` : "missing"}`,
     `Bridge: ${bridges}`,
@@ -1743,6 +1748,14 @@ function renderDoctor(result) {
   return lines.join("\n");
 }
 
+function renderInstallation(installation) {
+  const currentVersion = installation.current.version ?? "unknown";
+  const selected = installation.pathSelected === null
+    ? "PATH selection not found"
+    : `PATH selects ${installation.pathSelected.version ?? "unknown"} at ${installation.pathSelected.path}`;
+  return `Installation: current ${currentVersion} at ${installation.current.entrypoint}; ${selected}; ${installation.installations.length} package installation(s) on PATH`;
+}
+
 function appendNotInitializedAttachGuidance(lines, result) {
   if (result.mode !== "not-initialized") {
     return;
@@ -1771,6 +1784,7 @@ function helpText() {
     "  The package postinstall auto-runs agent-layer guidance setup on install and update.",
     "  Under sudo, setup targets SUDO_USER's agent homes while npm still controls the binary prefix.",
     "  Run skillboard setup later after adding another supported agent or when install scripts were skipped.",
+    "  Run skillboard doctor --summary after updates to detect PATH shadowing or duplicate global installs.",
     "  Preview skillboard uninstall --user --dry-run before package removal to clean every managed artifact.",
     "",
     "Core AI/automation operations:",
@@ -1901,7 +1915,7 @@ function initHelpText() {
 
 function setupHelpText() {
   return [
-    "Usage: skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]]",
+    "Usage: skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]] [--skill-root <path>]",
     "",
     "Installs or refreshes SkillBoard at the agent layer, not into a project.",
     "A normal global package install already runs this automatically for detected supported agents.",
@@ -1913,6 +1927,8 @@ function setupHelpText() {
     "What changes after confirmation:",
     "  Writes a SkillBoard guidance skill into detected user agent skill roots.",
     "  Creates ~/skillboard.config.yaml and ~/.skillboard/inventory.json; it writes no project files.",
+    "  Reconciles already-shared skills into agents and profiles added after the original share.",
+    "  --skill-root registers one custom root for the selected --agent and reuses it on future updates.",
     "  Teaches agents to use local skills by default and share only user-selected skills.",
     "  Remove this managed guidance later with skillboard uninstall --agent-layer.",
     "",
@@ -1926,6 +1942,7 @@ function setupHelpText() {
     "  skillboard setup",
     "  skillboard setup --yes",
     "  skillboard setup --agent codex,claude,opencode,hermes --yes",
+    "  skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes",
     ""
   ].join("\n");
 }
@@ -2007,6 +2024,8 @@ function doctorHelpText() {
     "Usage: skillboard doctor [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--summary] [--json]",
     "",
     "Checks the user-level policy and generated inventory health.",
+    "Also compares the running package and PATH-selected SkillBoard executable.",
+    "Installation discovery reads links and package metadata; it does not execute PATH candidates.",
     "The status command is an alias for doctor.",
     "",
     "Options:",
@@ -2019,6 +2038,7 @@ function doctorHelpText() {
     "  --json             Print an agent-readable payload.",
     "",
     "Without path overrides, this checks ~/skillboard.config.yaml and ~/.skillboard/inventory.json from any directory.",
+    "Installation warnings are informational and do not change policy health.",
     "It is read-only.",
     ""
   ].join("\n");

package/src/doctor.mjs

@@ -4,6 +4,7 @@ import { auditSources } from "./control.mjs";
 import { hasRuntimeComponents, installUnitSourceClass, isModelSelectableInvocation } from "./domain/source-classes.mjs";
 import { BRIDGE_END, BRIDGE_START } from "./lifecycle-content.mjs";
 import { checkPolicy } from "./policy.mjs";
+import { inspectInstallation } from "./install-health.mjs";
 import { verifySources } from "./source-verification.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 import { loadWorkspace } from "./workspace.mjs";
@@ -13,6 +14,11 @@ export async function doctorProject(options = {}) {
   const configPath = resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml");
   const skillsRoot = resolveUnderRoot(root, options.skillsRoot ?? "skills");
   const bridges = await bridgeStatuses(root);
+  const installation = options.installation ?? await inspectInstallation({
+    entrypointPath: options.entrypointPath,
+    env: options.env,
+    packageVersion: options.packageVersion
+  });
   const uninstall = await uninstallProject({
     root,
     dryRun: true,
@@ -39,6 +45,7 @@ export async function doctorProject(options = {}) {
       error: configExists ? null : "skillboard.config.yaml was not found"
     },
     bridges,
+    installation,
     workspace: emptyWorkspaceSummary(),
     inventory: { required: false, ok: true, path: null, errors: [] },
     policy: { ok: false, errors: [], warnings: [] },
@@ -120,7 +127,7 @@ function finalizeDoctor(result, recommendations) {
     strictOk,
     reviewRequired,
     mode: ok ? reviewRequired ? "safe-mode" : "passed" : result.initialized ? "failed" : "not-initialized",
-    recommendations: [...new Set(recommendations)],
+    recommendations: [...new Set([...recommendations, ...result.installation.warnings])],
     reviewSummary: reviewSummaryFor(result)
   };
 }

package/src/install-health.mjs

@@ -0,0 +1,177 @@
+import { constants } from "node:fs";
+import { access, lstat, readFile, realpath } from "node:fs/promises";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
+
+const PACKAGE_NAME = "agent-skillboard";
+const POSIX_COMMANDS = ["skillboard", "agent-skillboard"];
+const WINDOWS_COMMANDS = [
+  "skillboard.cmd",
+  "skillboard.exe",
+  "skillboard",
+  "agent-skillboard.cmd",
+  "agent-skillboard.exe",
+  "agent-skillboard"
+];
+
+export async function inspectInstallation(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const pathDelimiter = options.pathDelimiter ?? delimiter;
+  const entrypoint = resolve(options.entrypointPath ?? process.argv[1] ?? "bin/skillboard.mjs");
+  const currentRealPath = await resolvedPath(entrypoint);
+  const currentPackage = await packageForEntrypoint(currentRealPath);
+  const pathCandidates = await findPathCandidates(options.env?.PATH ?? "", {
+    pathDelimiter,
+    platform,
+    currentRealPath,
+    currentPackageRoot: currentPackage?.root ?? null
+  });
+  const pathSelected = pathCandidates.find((candidate) => isPrimaryCommand(candidate.path, platform)) ?? null;
+  const installations = uniqueInstallations(pathCandidates);
+  const duplicateInstallations = installations.length > 1;
+  const shadowed = pathSelected !== null && !pathSelected.current;
+  const current = {
+    version: options.packageVersion ?? currentPackage?.version ?? null,
+    entrypoint,
+    realPath: currentRealPath,
+    packageRoot: currentPackage?.root ?? null
+  };
+  const warnings = installWarnings({ current, pathSelected, installations, duplicateInstallations, shadowed });
+  return {
+    current,
+    pathSelected,
+    pathCandidates,
+    installations,
+    duplicateInstallations,
+    shadowed,
+    warnings
+  };
+}
+
+async function findPathCandidates(pathValue, options) {
+  const commands = options.platform === "win32" ? WINDOWS_COMMANDS : POSIX_COMMANDS;
+  const directories = pathValue.split(options.pathDelimiter).filter((entry) => entry.trim() !== "");
+  const candidates = [];
+  const observedPaths = new Set();
+  for (const directory of directories) {
+    for (const command of commands) {
+      const path = resolve(directory, command);
+      if (observedPaths.has(path) || !await isExecutable(path, options.platform)) continue;
+      observedPaths.add(path);
+      candidates.push(await inspectCandidate(path, options));
+    }
+  }
+  return candidates;
+}
+
+async function inspectCandidate(path, options) {
+  const realPath = await resolvedPath(path);
+  const packageMetadata = await packageForCandidate(path, realPath);
+  const packageRoot = packageMetadata?.root ?? null;
+  return {
+    path,
+    realPath,
+    packageRoot,
+    version: packageMetadata?.version ?? null,
+    current: realPath === options.currentRealPath
+      || (packageRoot !== null && packageRoot === options.currentPackageRoot)
+  };
+}
+
+async function packageForCandidate(path, realPath) {
+  const fromTarget = await packageForEntrypoint(realPath);
+  if (fromTarget !== null) return fromTarget;
+  const commandDirectory = dirname(path);
+  for (const root of [
+    join(commandDirectory, "node_modules", PACKAGE_NAME),
+    resolve(commandDirectory, "..", PACKAGE_NAME)
+  ]) {
+    const metadata = await readPackage(root);
+    if (metadata !== null) return metadata;
+  }
+  return null;
+}
+
+async function packageForEntrypoint(path) {
+  let directory = dirname(path);
+  for (let depth = 0; depth < 6; depth += 1) {
+    const metadata = await readPackage(directory);
+    if (metadata !== null) return metadata;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return null;
+}
+
+async function readPackage(root) {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    if (parsed?.name !== PACKAGE_NAME || typeof parsed.version !== "string") return null;
+    return { root: await realpath(root), version: parsed.version };
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+async function isExecutable(path, platform) {
+  try {
+    const stats = await lstat(path);
+    if (!stats.isFile() && !stats.isSymbolicLink()) return false;
+    await access(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch (error) {
+    if (["EACCES", "ELOOP", "ENOENT", "ENOTDIR"].includes(error?.code)) return false;
+    throw error;
+  }
+}
+
+async function resolvedPath(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return resolve(path);
+    throw error;
+  }
+}
+
+function uniqueInstallations(candidates) {
+  const installations = [];
+  const observed = new Set();
+  for (const candidate of candidates) {
+    if (candidate.packageRoot === null || observed.has(candidate.packageRoot)) continue;
+    observed.add(candidate.packageRoot);
+    installations.push(candidate);
+  }
+  return installations;
+}
+
+function isPrimaryCommand(path, platform) {
+  const command = basename(path).toLowerCase();
+  return platform === "win32"
+    ? ["skillboard", "skillboard.cmd", "skillboard.exe"].includes(command)
+    : command === "skillboard";
+}
+
+function installWarnings(result) {
+  const warnings = [];
+  if (result.shadowed) {
+    warnings.push(
+      `PATH selects SkillBoard ${displayVersion(result.pathSelected.version)} at ${result.pathSelected.path} instead of this ${displayVersion(result.current.version)} invocation at ${result.current.entrypoint}.`
+    );
+  }
+  if (result.duplicateInstallations) {
+    warnings.push(
+      `Multiple SkillBoard installations were found on PATH: ${result.installations.map(displayInstallation).join(", ")}. Keep one npm prefix active and uninstall stale copies with the npm installation that owns them.`
+    );
+  }
+  return warnings;
+}
+
+function displayVersion(version) {
+  return version === null ? "with unknown version" : `version ${version}`;
+}
+
+function displayInstallation(candidate) {
+  return `${candidate.version ?? "unknown"} at ${candidate.path}`;
+}

package/src/inventory-refresh.mjs

@@ -29,7 +29,8 @@ async function refreshLocked(options) {
   const inventory = options.inventory ?? await discoverAgentSkillInventory({
     roots: options.roots,
     home: options.home,
-    env: options.env
+    env: options.env,
+    registeredRoots: options.registeredRoots
   });
   const configVersion = YAML.parse(current)?.version;
   const generatedInventory = configVersion === 2
@@ -43,9 +44,12 @@ async function refreshLocked(options) {
   const previousInventoryText = inventoryText === null
     ? null
     : await readFile(inventoryPath, "utf8").catch((error) => error?.code === "ENOENT" ? "" : Promise.reject(error));
-  const merged = configVersion === 2
+  const projected = configVersion === 2
     ? mergeV2InventoryPolicy(current, inventory)
     : mergeAgentSkillInventory(current, inventory);
+  const merged = configVersion === 1 && options.preserveLegacyPolicy === true
+    ? { ...projected, text: current }
+    : projected;
   const plan = textChangePlan(current, merged.text);
   const dryRun = options.dryRun === true;