agent-skillboard 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## Unreleased
 
+## 0.3.1 — 2026-07-14
+
+### Added
+
+- Added read-only installation health to `doctor` and `status`, including the
+  running package, PATH-selected executable, shadowing, and duplicate npm
+  installs without executing candidate programs.
+- Added `skillboard setup --agent <agent> --skill-root <path>` for registering a
+  nonstandard user skill root and reusing it across later setup, package update,
+  share, unshare, and user-uninstall runs.
+
+### Changed
+
+- Made setup and global package updates preserve version 1 policy bytes and
+  print only the explicit v2 migration preview command.
+- Made `setup` the idempotent install/update/reconcile entrypoint for agents and
+  Hermes profiles added after SkillBoard installation.
+- Made setup backfill only already-selected `shared: true` skills into newly
+  active compatible roots while preserving agent-local defaults and unmanaged
+  collisions.
+- Kept registered roots in generated operational state rather than expanding
+  the v2 policy beyond `enabled`, `shared`, and optional preference.
+
+### Fixed
+
+- Added actionable single-prefix recovery guidance so system npm and Node
+  version-manager installations cannot silently drift without a doctor warning.
+- Prevented a stale default-root copy from producing false guard availability
+  after a custom root is registered.
+- Preserved conventional roots that still contain agent-owned skills alongside
+  registered roots, and included historical managed guidance in clean user
+  removal.
+- Restored invoking-user ownership recursively for shared skill copies created
+  or repaired by setup during sudo-driven global installs and updates.
+
+### Security
+
+- Restricted registered roots to non-symlinked directories inside the invoking
+  user's home and rejected assigning one root to different agents.
+- Treated malformed or symlinked share markers as unmanaged evidence so setup
+  and removal preserve user-owned or externally linked content.
+
 ## 0.3.0 — 2026-07-13
 
 ### Changed

package/README.md

@@ -9,7 +9,7 @@ Valid installed skills default to enabled and agent-local. Sharing is opt-in per
 skill. Optional preference ranks enabled skills installed for the current agent
 and never changes availability or copies files.
 
-Status: public alpha. Package 0.3.0 writes policy schema v2.
+Status: public alpha. Package 0.3.1 writes policy schema v2.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
@@ -28,6 +28,7 @@ Install globally:
 
 ```bash
 npm install -g agent-skillboard
+skillboard doctor --summary
 ```
 
 The package postinstall sets up detected agent guidance and creates the
@@ -39,6 +40,38 @@ normal install. If lifecycle scripts were skipped or another agent was added:
 skillboard setup --agent codex,claude,opencode,hermes --yes
 ```
 
+Use the same Node/npm environment for later updates:
+
+```bash
+npm config get prefix
+npm install -g agent-skillboard@latest
+skillboard doctor --summary
+```
+
+Doctor compares the running package with the `skillboard` executable selected
+by `PATH` and reports duplicate global installs without executing those
+candidates. If multiple SkillBoard installations are reported, choose one npm
+prefix, activate the Node environment that owns each stale copy, and run
+`npm uninstall -g agent-skillboard` there. SkillBoard does not automatically
+uninstall another prefix. Restart or refresh agents after an update because
+some agents cache user skills.
+
+`setup` is safe to rerun. It refreshes managed guidance and inventory, discovers
+late standard agent homes and Hermes profiles, and fills already-selected
+`shared: true` skills into newly active roots. It does not make every skill
+global and never overwrites an unmanaged skill.
+
+For an agent that uses a nonstandard skill directory, register that root once:
+
+```bash
+skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes
+```
+
+The root must be inside the invoking user's home. SkillBoard records it as
+operational discovery state in `~/.skillboard/agent-roots.json`, then reuses it
+on later setup and global package updates. This does not add another policy
+scope; per-skill `shared` remains the only cross-agent sharing decision.
+
 `sudo npm install -g agent-skillboard` is supported when system npm requires
 it. Setup resolves `SUDO_USER` and restores managed home files to that user.
 Setup and ordinary use write no project policy and require no project init.
@@ -124,7 +157,9 @@ skillboard migrate v2 --config <path> --yes --json
 skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-All v1 mutations refuse and point to migration. v0.4.0 removes the v1 reader.
+Setup and package updates keep v1 bytes unchanged and print the preview command.
+SkillBoard does not automatically migrate version 1. All v1 mutations refuse
+and point to migration. v0.4.0 removes the v1 reader.
 
 ## Cleanup
 

package/bin/postinstall.mjs

@@ -19,7 +19,7 @@ if (!shouldAutoSetup(process.env)) {
     "Run skillboard setup later after adding another supported agent:",
     "  skillboard setup",
     "",
-    "Setup only writes user agent skill files. It does not create skillboard.config.yaml or .skillboard/.",
+    "Setup writes user-agent guidance, reconciles shared skills, and refreshes the user-level policy and inventory.",
     "skillboard init is deprecated project-local policy bootstrap and is not needed for normal use.",
     ""
   ].join("\n")}`);
@@ -43,6 +43,7 @@ try {
   });
   if (exitCode === 0) {
     process.stderr.write("Agent setup complete. Package updates rerun this setup automatically; run skillboard setup later after adding another supported agent. No project init was run.\n");
+    process.stderr.write("Run skillboard doctor --summary to check policy and executable paths after the update.\n");
   } else {
     process.stderr.write("Agent setup did not find supported agent homes. Run skillboard setup after installing or enabling a supported agent.\n");
   }

package/docs/ai-skill-routing-goal.md

@@ -38,6 +38,13 @@ remove or quarantine copies that the user or another tool installed. With
 managed copies for supported agents, while preserving every agent-owned
 original.
 
+`setup` is a repeatable user-level convergence operation. It observes agents
+and Hermes profiles added after installation, refreshes managed guidance and
+inventory, and materializes missing copies only for skills already marked
+`shared: true`. Custom agent roots are remembered outside policy as operational
+discovery state. They must not introduce project scope, source trust gates, or
+another authorization layer.
+
 ## Development rule
 
 Every route, brief, guard, dashboard, generated bridge, and policy mutation must

package/docs/install.md

@@ -5,6 +5,7 @@
 ```bash
 npm install -g agent-skillboard
 skillboard --version
+skillboard doctor --summary
 ```
 
 Postinstall detects supported agent homes, installs managed guidance, creates
@@ -12,13 +13,55 @@ Postinstall detects supported agent homes, installs managed guidance, creates
 separate setup command is required after a normal global install or update, and
 no project init is needed.
 
-Run setup later only when lifecycle scripts were skipped or another agent was
-added:
+## Safe updates and npm prefixes
+
+Run the update with the Node/npm environment whose global prefix should own the
+CLI:
+
+```bash
+npm config get prefix
+npm install -g agent-skillboard@latest
+skillboard doctor --summary
+```
+
+Node version managers and system npm can use different global prefixes. Doctor
+reports the current package, the `skillboard` executable selected by `PATH`, and
+multiple SkillBoard installations. Discovery reads executable links and package
+metadata only; it does not execute PATH candidates.
+
+When doctor reports duplicate global installs, select the prefix you intend to
+keep. Activate the Node environment that owns each stale prefix, confirm it with
+`npm config get prefix`, and run `npm uninstall -g agent-skillboard` there.
+SkillBoard does not automatically uninstall another prefix or request elevated
+permissions for cleanup.
+
+Run setup later when lifecycle scripts were skipped, another agent or Hermes
+profile was added, or a managed root needs to be repaired:
 
 ```bash
 skillboard setup --agent codex,claude,opencode,hermes --yes
 ```
 
+Setup is idempotent. Each run refreshes managed agent guidance, user policy,
+and observed inventory. If the user already chose `shared: true` for a skill,
+setup creates only the missing compatible managed copies for newly discovered
+agent roots. It preserves unmanaged files and does not share agent-local skills.
+Restart or refresh agents after setup or an npm update because an agent may
+cache its user skill inventory.
+
+Register a nonstandard agent skill directory once with exactly one agent:
+
+```bash
+skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes
+```
+
+The root must remain inside the invoking user's home and must not traverse a
+symbolic link. SkillBoard stores it in `~/.skillboard/agent-roots.json` as
+operational discovery state, not policy, and reuses it during setup and global
+package updates. Conventional roots that contain agent-owned skills remain
+active; obsolete roots containing only SkillBoard-managed artifacts do not
+create false agent presence.
+
 System npm may require `sudo npm install -g agent-skillboard`. SkillBoard uses
 `SUDO_USER` for user-level state and restores managed files to that user.
 
@@ -62,6 +105,9 @@ skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
 Version 1 is read-only during v0.3.x. v0.4.0 removes the v1 reader.
+Setup and postinstall preserve an existing v1 policy byte-for-byte and suggest
+the preview command only. SkillBoard does not automatically migrate version 1;
+apply and rollback remain explicit user actions.
 
 ## Uninstall
 

package/docs/reference.md

@@ -13,7 +13,7 @@ Source tree: replace `skillboard ` with `node bin/skillboard.mjs `.
 ## Core user-level commands
 
 ```text
-skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]]
+skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]] [--skill-root <path>]
 skillboard inventory refresh [--config <path>] [--dry-run] [--json]
 skillboard brief [--agent codex|claude|opencode|hermes] [--intent <request>] [--include-actions] [--json]
 skillboard route <intent> --agent codex|claude|opencode|hermes [--json]
@@ -33,6 +33,22 @@ Without path overrides, commands read `~/skillboard.config.yaml` and
 `~/.skillboard/inventory.json` from any directory. Setup bootstraps both files
 atomically and never creates project state.
 
+Doctor also reports installation health: the running package version and
+entrypoint, the `skillboard` executable selected by `PATH`, discovered package
+installations, shadowing, and duplicate global installs. These observations are
+informational and do not change policy health. Candidate executables are never
+run during discovery. Use `skillboard doctor --summary` after updates; use
+`npm config get prefix` in each Node environment to identify the owner of a
+stale global copy. SkillBoard does not automatically uninstall another prefix.
+
+Setup is the convergent install/update command. It refreshes managed guidance,
+policy, and inventory; discovers late standard roots and Hermes profiles; and
+creates missing compatible copies for policy entries already marked
+`shared: true`. `--skill-root` requires exactly one `--agent`, accepts only a
+non-symlinked path inside the invoking user's home, and persists the mapping in
+`~/.skillboard/agent-roots.json`. That registry is operational discovery state,
+not authorization or policy. One root cannot be registered to two agents.
+
 Guard requires a valid inventory record, `enabled: true`, and the selected agent
 in `installed_on`. Optional preference ranks candidates but never changes
 availability.
@@ -137,6 +153,9 @@ Preview changes no bytes. Apply creates an adjacent byte-for-byte backup and
 writes v2 policy plus generated inventory atomically. Rollback restores the
 selected backup. v0.4.0 removes the v1 reader.
 
+Setup and npm postinstall preserve an existing v1 policy and print only the
+preview form. SkillBoard does not automatically migrate version 1.
+
 Legacy fields are interpreted only by migration and never become hidden v2
 authorization. Primary examples are `examples/v2-multi-source.config.yaml` and
 `examples/v2-policy-error.config.yaml`; unprefixed v1 examples remain migration

package/docs/user-flow.md

@@ -18,6 +18,19 @@ agents. No project init is needed. If setup was skipped:
 skillboard setup --yes --agent codex
 ```
 
+If an agent is installed later, rerun the same command for that agent. Setup
+discovers standard homes and Hermes profiles, installs guidance, refreshes
+inventory, and backfills only skills the user already selected with
+`shared: true`. For a custom location:
+
+```bash
+skillboard setup --agent hermes --skill-root ~/.hermes/profiles/work/skills --yes
+```
+
+The registered root survives later setup and package-update runs. No project
+init, profile-specific policy layer, or new approval per already-shared skill is
+introduced. Unmanaged collisions are preserved and reported.
+
 ## 2. Observe and route
 
 From any directory, the agent reads:

package/docs/versioning.md

@@ -22,6 +22,10 @@ Preview is non-mutating, apply creates an adjacent byte-for-byte backup, and
 rollback restores the selected backup. Old action ids, hooks, and lock
 projections are invalid after migration.
 
+Package install, update, setup, and doctor never automatically migrate a v1
+policy. Setup preserves its bytes and prints the preview command so the policy
+decision stays separate from package maintenance.
+
 ## Versioned v2 contract
 
 Policy availability requires `enabled: true` and generated installation presence
@@ -34,12 +38,21 @@ schema.
 
 1. Run `npm run check`.
 2. Run `npm pack --dry-run --json` and inspect public contents.
-3. Confirm `CHANGELOG.md` includes the package version.
-4. Create a matching `vX.Y.Z` tag.
-5. `.github/workflows/publish.yml` verifies the tag exactly matches
+3. Install the tarball into an isolated prefix and run
+   `skillboard doctor --summary`; verify fresh setup, v1 preservation, and a
+   late-agent shared-skill reconciliation.
+4. Confirm `CHANGELOG.md` includes the package version.
+5. Push `main` and wait for the complete cross-platform check matrix.
+6. Create a matching `vX.Y.Z` tag on that exact green commit.
+7. `.github/workflows/publish.yml` verifies the tag exactly matches
    `package.json`, configures the registry URL in `setup-node`, then runs
    `npm publish` with provenance.
 
+After publish, verify the registry version from a clean install. On development
+machines with system npm plus a Node version manager, use `npm config get
+prefix` and doctor to detect multiple SkillBoard installations; release tooling
+never automatically uninstalls another prefix.
+
 Publishing uses `NPM_TOKEN` through `NODE_AUTH_TOKEN`. Prefer npm trusted
 publishing with OIDC when available. Release automation skips `npm publish`
 only when that exact version already exists on npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Keep agent skills broadly available while routing overlaps consistently.",
   "keywords": [
     "ai-agent",

package/src/agent-integration-cli.mjs

@@ -2,17 +2,29 @@ import { isAbsolute, relative, resolve } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { installAgentIntegration, uninstallAgentIntegration } from "./agent-integration-files.mjs";
-import { applyOwnership, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
+import { applyOwnership, applyOwnershipTree, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
+import {
+  agentRootRegistryPath,
+  loadRegisteredAgentRoots,
+  mergeRegisteredAgentRoots,
+  proposedAgentRoot,
+  writeRegisteredAgentRoots
+} from "./agent-root-registry.mjs";
 import { refreshAgentInventory } from "./inventory-refresh.mjs";
+import { reconcileSharedSkills } from "./shared-skill-reconcile.mjs";
 
 export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
+  assertSetupOptions(options);
   if (options.get("dir") !== undefined) {
     throw new Error("skillboard setup is agent-layer setup and does not accept --dir");
   }
   const env = runtime.env ?? process.env;
   const home = await resolveSetupHome(env, runtime);
-  const targets = await agentSetupTargets(options, runtime, home);
+  const existingRoots = await loadRegisteredAgentRoots(home);
+  const proposedRoot = await setupSkillRoot(options, home, runtime.cwd ?? process.cwd());
+  const registeredRoots = mergeRegisteredAgentRoots(existingRoots, proposedRoot);
+  const targets = await agentSetupTargets(options, runtime, home, registeredRoots);
   if (targets.length === 0) {
     stdout.write("No supported agent user skill roots were detected.\n");
     stdout.write(`Create a supported agent home or pass --agent ${supportedAgentNames().join(",")} to choose targets.\n`);
@@ -32,18 +44,49 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
   const ownership = setupOwnership(env, runtime, home);
   const result = await installAgentIntegration(targets, ownership);
   await mkdir(home, { recursive: true });
-  const inventory = await refreshAgentInventory({ root: home, home, env });
-  await applyOwnership(resolve(home, inventory.configPath), ownership);
-  if (inventory.inventoryPath !== null) await applyOwnership(resolve(home, inventory.inventoryPath), ownership);
+  let inventory = await refreshAgentInventory({
+    root: home,
+    home,
+    env,
+    registeredRoots,
+    preserveLegacyPolicy: true
+  });
+  const configPath = resolve(home, inventory.configPath);
+  const inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  const shared = inventoryPath === null
+    ? { created: [], unchanged: [], preserved: [], blocked: [] }
+    : await reconcileSharedSkills({ home, env, targets, configPath, inventoryPath });
+  if (shared.created.length > 0) {
+    inventory = await refreshAgentInventory({ root: home, home, env, registeredRoots });
+  }
+  for (const entry of [...shared.created, ...shared.unchanged]) {
+    await applyOwnershipTree(entry.path, ownership);
+  }
+  if (proposedRoot !== undefined) {
+    await writeRegisteredAgentRoots(home, registeredRoots);
+    await applyOwnership(agentRootRegistryPath(home), ownership);
+  }
+  await applyOwnership(configPath, ownership);
+  if (inventoryPath !== null) await applyOwnership(inventoryPath, ownership);
   stdout.write("SkillBoard agent integration installed.\n");
   writeList(stdout, "Created", result.created);
   writeList(stdout, "Updated", result.updated);
   writeList(stdout, "Unchanged", result.unchanged);
   writeList(stdout, "Preserved", result.preserved);
+  if (proposedRoot !== undefined) stdout.write(`Registered agent roots: ${registeredRoots.length}\n`);
+  if (shared.created.length > 0) stdout.write(`Created shared copies: ${shared.created.length}\n`);
+  if (shared.unchanged.length > 0) stdout.write(`Unchanged shared copies: ${shared.unchanged.length}\n`);
+  writeList(stdout, "Preserved shared copies", shared.preserved.map(formatSharedEntry));
+  writeList(stdout, "Blocked shared copies", shared.blocked.map(formatBlockedEntry));
   stdout.write(`User policy: ${inventory.configPath}\n`);
   stdout.write(`Observed skills: ${inventory.scan.scannedSkills}\n`);
+  if (inventory.inventoryPath === null) {
+    stdout.write("Policy version 1 remains read-only during SkillBoard v0.3.x.\n");
+    stdout.write(`Preview migration: ${commandPrefix(runtime)} migrate v2 --config ${shellQuote(configPath, runtime.platform)} --json\n`);
+  }
   stdout.write("Next:\n");
   stdout.write("- Restart or refresh agents that cache user skills.\n");
+  stdout.write("- Run skillboard doctor --summary to check policy and executable paths.\n");
   stdout.write("- User-level policy and inventory were refreshed; no project was initialized.\n");
   stdout.write('- Ask the agent in a workspace: "Review this plan and point out weak assumptions."\n');
   stdout.write("- SkillBoard will step in when skills overlap, routing is ambiguous, or you ask for a skill decision.\n");
@@ -136,7 +179,7 @@ function defaultRuntime() {
   };
 }
 
-async function agentSetupTargets(options, runtime, setupHome) {
+async function agentSetupTargets(options, runtime, setupHome, registeredRoots) {
   const env = runtime.env ?? process.env;
   const home = setupHome ?? await resolveSetupHome(env, runtime);
   const requested = readCsv(options.get("agent"));
@@ -147,20 +190,48 @@ async function agentSetupTargets(options, runtime, setupHome) {
     if (!supported.has(name)) {
       throw new Error(`Unsupported setup agent: ${name}`);
     }
-    targets.push(...await setupAgentSkillTargets(name, home, env, { includeFallback: requested.length > 0 }));
+    targets.push(...await setupAgentSkillTargets(name, home, env, {
+      includeFallback: requested.length > 0,
+      registeredRoots
+    }));
   }
   return targets;
 }
 
+async function setupSkillRoot(options, home, cwd) {
+  const skillRoot = options.get("skill-root");
+  if (skillRoot === undefined) return undefined;
+  const requested = readCsv(options.get("agent"));
+  if (requested.length !== 1) {
+    throw new Error("--skill-root requires exactly one --agent value.");
+  }
+  return await proposedAgentRoot(home, requested[0], skillRoot, cwd);
+}
+
+function assertSetupOptions(options) {
+  const allowed = new Set(["yes", "agent", "skill-root"]);
+  for (const option of options.keys()) {
+    if (!allowed.has(option)) throw new Error(`Unknown setup option: --${option}`);
+  }
+}
+
+function formatSharedEntry(entry) {
+  return `${entry.agent}:${entry.skill}:${entry.path}`;
+}
+
+function formatBlockedEntry(entry) {
+  return `${entry.agent ?? "unknown"}:${entry.skill}:${entry.reason}`;
+}
+
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
   const normalized = entrypoint.replace(/\\/g, "/");
   if (normalized.includes("/_npx/")) {
     const packageSpec = runtime.packageSpec ?? "agent-skillboard";
-    return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
+    return `npx --yes --package ${shellQuote(packageSpec, runtime.platform)} skillboard`;
   }
   if (isSourceTreeEntrypoint(entrypoint)) {
-    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd(), runtime.platform)}`;
   }
   return "skillboard";
 }
@@ -176,18 +247,21 @@ function isSourceTreeEntrypoint(entrypoint) {
     && !normalized.includes("/.npm/");
 }
 
-function sourceTreeEntrypoint(entrypoint, cwd) {
+function sourceTreeEntrypoint(entrypoint, cwd, platform) {
   const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
   const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
   if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
-    return shellQuote(relativeEntrypoint);
+    return shellQuote(relativeEntrypoint, platform);
   }
-  return shellQuote(absoluteEntrypoint);
+  return shellQuote(absoluteEntrypoint, platform);
 }
 
-function shellQuote(value) {
+function shellQuote(value, platform = process.platform) {
   if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
     return value;
   }
+  if (platform === "win32") {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
   return `'${value.replace(/'/g, "'\\''")}'`;
 }

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) {