agent-skillboard 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 ## Unreleased
 
+## 0.3.2 — 2026-07-14
+
+### Changed
+
+- Made global npm updates and `skillboard setup` automatically upgrade a valid
+  version 1 user policy when every migration choice is already understood.
+- Kept the explicit `migrate v2` preview, apply, and rollback commands for
+  project policies, audits, and recovery.
+
+### Fixed
+
+- Removed the hidden manual migration step left after a 0.3.1 update while
+  preserving explicit terminal denials as disabled and review-only quarantine
+  states as enabled, agent-local skills.
+- Kept automatic migration non-mutating for unknown future ambiguity kinds or
+  policy skills that are not currently observed, and restored exact version 1
+  bytes after any transactional failure.
+- Restored invoking-user ownership for migration backups, manifests, and
+  generated inventory during sudo-driven global updates.
+
+## 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.2 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,46 @@ 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.
+
+When an update finds a valid version 1 user policy, setup automatically migrates
+it only when all reported choices are understood. It creates an adjacent exact
+backup, keeps explicit terminal denials disabled, and maps review-only
+quarantine states to enabled and agent-local. Unknown future ambiguity leaves
+the policy unchanged and prints the explicit preview command instead. The same
+review path is used when a v1 policy skill is not currently observed, avoiding
+an unhealthy generated inventory or silently forgetting a denial.
+
+`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 +165,16 @@ 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.
+Starting in 0.3.2, setup and global package updates automatically migrate a
+valid version 1 user policy when the report contains only understood choices.
+The transaction creates an adjacent exact backup. Explicit terminal denials
+remain disabled; review-only quarantine becomes enabled and agent-local. An
+unknown future ambiguity leaves the policy unchanged and prints the preview
+command. A policy skill that is not currently observed also stays on v1 for an
+explicit decision, because forgetting a disabled entry could enable it if it
+later reappears. The explicit commands remain available for project policies,
+audits, and rollback. Other v1 mutations still 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,18 @@ 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.
+
+When setup encounters version 1 user policy, it may converge that policy to v2
+only if every migration ambiguity is a known review-only quarantine mapping.
+It must preserve terminal denials, create an exact recoverable backup, and leave
+unknown future ambiguity unchanged for an explicit decision.
+
 ## 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,64 @@ 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.
+
+From 0.3.2, setup and global postinstall automatically migrate a valid version
+1 user policy when every reported migration choice is understood. Migration
+creates an adjacent exact backup, preserves explicit terminal denials as
+disabled, and makes review-only quarantine states enabled and agent-local. An
+unknown future ambiguity leaves the policy unchanged and prints the explicit
+preview command; no migration files are changed. A v1 policy skill that is not
+currently observed uses the same review path so setup neither invents inventory
+nor silently forgets its policy.
+
+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.
 
@@ -61,7 +113,12 @@ skillboard migrate v2 --config <path> --yes --json
 skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-Version 1 is read-only during v0.3.x. v0.4.0 removes the v1 reader.
+Version 1 is read-only during v0.3.x. v0.4.0 removes the v1 reader. Setup and
+global postinstall automatically migrate an understood version 1 user policy
+through the same backup and validation transaction. Unknown future ambiguity
+or a policy skill that is not currently observed leaves it unchanged and prints
+the preview command. Explicit preview, apply, and rollback remain available for
+project policies, audits, and recovery.
 
 ## Uninstall
 

package/docs/policy-model.md

@@ -71,3 +71,10 @@ skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
 v0.4.0 removes the v1 reader.
+
+Setup and global postinstall automatically upgrade a valid version 1 user
+policy when its migration report contains only understood choices. The
+transaction keeps an exact adjacent backup. An unknown future ambiguity leaves
+the policy unchanged and requires the explicit preview/apply flow. Policy skills
+that are not currently observed also require review rather than being silently
+forgotten.

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,14 @@ 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 global npm postinstall automatically migrate a valid version 1 user
+policy when all reported choices are understood. They create an adjacent exact
+backup, preserve terminal denials as disabled, and map review-only quarantine
+to enabled and agent-local. An unknown future ambiguity leaves the policy
+unchanged, changes no migration files, and prints the preview form. The same
+review path names policy skills that are not currently observed. Explicit
+commands remain available for project policies, audit, and recovery.
+
 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:
@@ -98,4 +111,8 @@ skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
 Version 1 remains readable but immutable for the v0.3.x one-release read-only
-window. v0.4.0 removes the v1 reader. No ordinary command migrates implicitly.
+window. Setup and global package updates automatically migrate an understood
+version 1 user policy with an exact adjacent backup. Unknown future ambiguity
+or a policy skill that is not currently observed leaves it unchanged and prints
+the preview command. Project policies and other ordinary commands still require
+explicit migration. v0.4.0 removes the v1 reader.

package/docs/value-proof.md

@@ -15,7 +15,8 @@ node --test test/v2-agent-sharing.test.mjs test/v2-onboarding-behavior.test.mjs
 - Optional preference changes ranking without changing availability.
 - Source and provenance audits do not change guard results.
 - Commands produce the same result from different working directories.
-- Version 1 is read-only until explicit migration.
+- Version 1 project policy remains read-only until explicit migration; setup
+  automatically migrates an understood user policy with an exact backup.
 
 ## Reproduce the user surface
 

package/docs/versioning.md

@@ -22,6 +22,14 @@ 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.
 
+Starting in 0.3.2, setup and global package updates automatically migrate a
+valid version 1 user policy when all migration choices are understood. They use
+the same exact-backup, atomic-write, validation, and recovery transaction as
+the explicit command. Unknown future ambiguity leaves the policy unchanged and
+prints the preview command. A policy skill that is not currently observed also
+requires review, preserving future denial semantics. Doctor and project-local
+commands remain non-mutating.
+
 ## Versioned v2 contract
 
 Policy availability requires `enabled: true` and generated installation presence
@@ -34,12 +42,22 @@ 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, safe v1 auto-migration,
+   exact backup 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.2",
   "description": "Keep agent skills broadly available while routing overlaps consistently.",
   "keywords": [
     "ai-agent",

package/src/agent-integration-cli.mjs

@@ -1,18 +1,32 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { createInterface } from "node:readline";
+import { commandPrefix, shellQuote } from "./agent-integration-command.mjs";
 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";
+import { upgradeLegacyUserPolicy } from "./setup-policy-migration.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,19 +46,74 @@ 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);
+  let inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  const policyUpgrade = await upgradeLegacyUserPolicy({
+    home,
+    configPath,
+    inventoryPath,
+    observedSkillIds: inventory.observedSkillIds,
+    failpoint: runtime.migrationFailpoint
+  });
+  if (policyUpgrade.status === "upgraded") {
+    inventoryPath = policyUpgrade.inventoryPath;
+    await applyOwnership(configPath, ownership);
+    await applyOwnership(inventoryPath, ownership);
+    for (const artifact of policyUpgrade.artifacts) await applyOwnership(artifact, ownership);
+    inventory = await refreshAgentInventory({ root: home, home, env, registeredRoots });
+  }
+  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 (policyUpgrade.status === "upgraded") {
+    stdout.write("User policy upgraded automatically to version 2.\n");
+    stdout.write(`Backup: ${policyUpgrade.backupPath}\n`);
+  } else if (policyUpgrade.status === "decision-required") {
+    stdout.write("Policy version 1 needs review before migration; no migration files were changed.\n");
+    if (policyUpgrade.unobservedSkillIds.length > 0) {
+      stdout.write(`Policy skills not currently observed: ${formatList(policyUpgrade.unobservedSkillIds)}\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("- User-level policy and inventory were refreshed; no project was initialized.\n");
+  stdout.write("- Run skillboard doctor --summary to check policy and executable paths.\n");
+  if (policyUpgrade.status === "decision-required") {
+    stdout.write("- User-level policy was preserved and installed skills were rescanned; no project was initialized.\n");
+  } else {
+    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");
   return 0;
@@ -136,7 +205,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,47 +216,35 @@ 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;
 }
 
-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`;
-  }
-  if (isSourceTreeEntrypoint(entrypoint)) {
-    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;
+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 "skillboard";
+  return await proposedAgentRoot(home, requested[0], skillRoot, cwd);
 }
 
-function isSourceTreeEntrypoint(entrypoint) {
-  if (entrypoint === "") {
-    return false;
-  }
-  const normalized = entrypoint.replace(/\\/g, "/");
-  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
-    && !normalized.includes("/node_modules/")
-    && !normalized.includes("/_npx/")
-    && !normalized.includes("/.npm/");
+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 sourceTreeEntrypoint(entrypoint, cwd) {
-  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(absoluteEntrypoint);
+function formatSharedEntry(entry) {
+  return `${entry.agent}:${entry.skill}:${entry.path}`;
 }
 
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
-    return value;
-  }
-  return `'${value.replace(/'/g, "'\\''")}'`;
+function formatBlockedEntry(entry) {
+  return `${entry.agent ?? "unknown"}:${entry.skill}:${entry.reason}`;
 }

package/src/agent-integration-command.mjs

@@ -0,0 +1,38 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export 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, runtime.platform)} skillboard`;
+  }
+  if (isSourceTreeEntrypoint(entrypoint)) {
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd(), runtime.platform)}`;
+  }
+  return "skillboard";
+}
+
+function isSourceTreeEntrypoint(entrypoint) {
+  if (entrypoint === "") return false;
+  const normalized = entrypoint.replace(/\\/g, "/");
+  return (normalized === "bin/skillboard.mjs" || normalized.endsWith("/bin/skillboard.mjs"))
+    && !normalized.includes("/node_modules/")
+    && !normalized.includes("/_npx/")
+    && !normalized.includes("/.npm/");
+}
+
+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, platform);
+  }
+  return shellQuote(absoluteEntrypoint, platform);
+}
+
+export 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, "'\\''")}'`;
+}