agent-skillboard 0.3.0 → 0.3.2

package/src/agent-integration-home.mjs

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { access, chown, lstat, readFile } from "node:fs/promises";
+import { access, chown, lstat, readFile, readdir } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 
@@ -53,6 +53,19 @@ export async function applyOwnership(path, ownership) {
   }
 }
 
+export async function applyOwnershipTree(path, ownership) {
+  if (ownership === null) return;
+  const stats = await pathStats(path);
+  if (stats === null || stats.isSymbolicLink()) return;
+  await applyOwnership(path, ownership);
+  if (!stats.isDirectory()) return;
+  const entries = await readdir(path, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    await applyOwnershipTree(resolve(path, entry.name), ownership);
+  }
+}
+
 function canApplyProcessOwnership(uid, gid) {
   if (typeof process.getuid !== "function") {
     return false;

package/src/agent-inventory-platforms.mjs

@@ -1,19 +1,22 @@
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { agentSkillRootCandidates } from "./agent-skill-roots.mjs";
+import { activeAgentSkillRootCandidates } from "./agent-skill-roots.mjs";
 
-export async function defaultScanRoots(home, env) {
+export async function defaultScanRoots(home, env, options = {}) {
   const codexHome = env.CODEX_HOME ?? join(home, ".codex");
   const agentRoots = await Promise.all([
-    agentSkillRootCandidates("codex", home, env),
-    agentSkillRootCandidates("claude", home, env),
-    agentSkillRootCandidates("opencode", home, env),
-    agentSkillRootCandidates("hermes", home, env)
+    activeAgentSkillRootCandidates("codex", home, env, options),
+    activeAgentSkillRootCandidates("claude", home, env, options),
+    activeAgentSkillRootCandidates("opencode", home, env, options),
+    activeAgentSkillRootCandidates("hermes", home, env, options)
   ]);
   return [
-    join(codexHome, "skills", ".system"),
-    join(codexHome, "plugins", "cache"),
-    join(home, ".agents", "shared-skills"),
-    ...agentRoots.flat().map((root) => root.skillRoot)
+    { path: join(codexHome, "skills", ".system") },
+    { path: join(codexHome, "plugins", "cache") },
+    { path: join(home, ".agents", "shared-skills") },
+    ...agentRoots.flatMap((roots, index) => roots.map((root) => ({
+      path: root.skillRoot,
+      agent: ["codex", "claude", "opencode", "hermes"][index]
+    })))
   ];
 }
 

package/src/agent-inventory.mjs

@@ -110,16 +110,16 @@ export async function discoverAgentSkillInventory(options = {}) {
   const env = options.env ?? process.env;
   const home = options.home ?? env.HOME ?? env.USERPROFILE ?? homedir();
   const detectors = options.detectors ?? agentInventoryDetectors;
-  const roots = uniquePaths([
-    ...(await defaultScanRoots(home, env)),
-    ...readCsv(env.SKILLBOARD_INIT_SCAN_ROOTS),
-    ...(options.roots ?? [])
+  const roots = uniqueRootEntries([
+    ...(await defaultScanRoots(home, env, { registeredRoots: options.registeredRoots })),
+    ...readCsv(env.SKILLBOARD_INIT_SCAN_ROOTS).map((path) => ({ path })),
+    ...(options.roots ?? []).map((path) => ({ path }))
   ], home);
   const groups = [];
   const warnings = [];
 
   for (const root of roots) {
-    const discovered = await discoverRoot(root, home, detectors);
+    const discovered = await discoverRoot(root.path, home, detectors, root.agent);
     groups.push(...discovered.groups);
     warnings.push(...discovered.warnings);
   }
@@ -293,13 +293,13 @@ function ensureLocalWorkflow(workflowsMap, target, skills, document) {
   return true;
 }
 
-async function discoverRoot(root, home, detectors) {
+async function discoverRoot(root, home, detectors, agent) {
   const path = resolvePath(root, home);
   if (!(await exists(path))) {
     return { groups: [], warnings: [] };
   }
   const warnings = [];
-  const detector = detectors.find((candidate) => {
+  const matched = detectors.find((candidate) => {
     try {
       return candidate.matches(path);
     } catch (error) {
@@ -307,6 +307,7 @@ async function discoverRoot(root, home, detectors) {
       return false;
     }
   });
+  const detector = agent === undefined ? matched : forcedAgentDetector(agent, matched, detectors);
   if (detector === undefined) {
     return { groups: [], warnings };
   }
@@ -319,6 +320,12 @@ async function discoverRoot(root, home, detectors) {
   }
 }
 
+function forcedAgentDetector(agent, matched, detectors) {
+  if (matched?.id === "hermes-profile-skills" && agent === "hermes") return matched;
+  const id = `${agent}-user-skills`;
+  return detectors.find((candidate) => candidate.id === id) ?? matched;
+}
+
 async function discoverSkillDirectory(root, unit, options) {
   const files = await findSkillFiles(root, root, options);
   return files.length === 0 ? [] : [{ unit, root, files }];
@@ -898,21 +905,20 @@ function uniqueStrings(values) {
   return [...new Set(values.filter((value) => value.trim().length > 0))];
 }
 
-function uniquePaths(values, home) {
-  const seen = new Set();
-  const result = [];
+function uniqueRootEntries(values, home) {
+  const byPath = new Map();
   for (const value of values) {
-    const trimmed = value.trim();
+    const trimmed = value.path.trim();
     if (trimmed.length === 0) {
       continue;
     }
     const key = resolve(trimmed.startsWith("~/") ? join(home, trimmed.slice(2)) : trimmed);
-    if (!seen.has(key)) {
-      seen.add(key);
-      result.push(trimmed);
+    const existing = byPath.get(key);
+    if (existing === undefined || existing.agent === undefined && value.agent !== undefined) {
+      byPath.set(key, { path: trimmed, ...(value.agent === undefined ? {} : { agent: value.agent }) });
     }
   }
-  return result;
+  return [...byPath.values()];
 }
 
 function errorMessage(error) {

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)
   };
 }