agent-skillboard 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 ## Unreleased
 
+## 0.3.3 — 2026-07-15
+
+### Added
+
+- Added deterministic Unicode intent tokenization with whole-run and character
+  bigram matching for legacy v1 compatibility routing.
+
+### Changed
+
+- Removed v2 request tokenization, metadata scoring, ranked hints, and
+  deterministic recommendations. Route and brief now return raw eligible skill
+  descriptions and saved preferences for the active model to interpret.
+- Made route, can-use, and guard errors explain whether the detected policy
+  expects v2 `--agent` or v1 `--workflow`, including the v1 migration preview.
+
+### Fixed
+
+- Preserved legacy v1 explicit skill-id selection when an ASCII id is
+  immediately followed by a Hangul or CJK particle, without allowing Latin
+  prefix matches.
+
+## 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

package/README.md

@@ -6,10 +6,11 @@ SkillBoard gives AI agents one small user-level policy for installed skills:
 2. Keep an enabled skill agent-local or shared across agents.
 
 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.
+skill. The model makes semantic skill choices from the request, eligible skill
+descriptions, and raw saved preferences. SkillBoard does not tokenize, score,
+match, or recommend from v2 request text.
 
-Status: public alpha. Package 0.3.1 writes policy schema v2.
+Status: public alpha. Package 0.3.3 writes policy schema v2.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/NyXXiR/skillboard/main/skillboard.png" alt="SkillBoard architecture diagram" width="100%">
@@ -56,6 +57,14 @@ prefix, activate the Node environment that owns each stale copy, and run
 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
@@ -120,8 +129,9 @@ destructive actions, and secrets.
 From any working directory, an agent can:
 
 1. Read `skillboard brief --intent <request> --agent <agent> --json`.
-2. Select an enabled skill installed for that agent, using preference only to
-   rank matches.
+2. Select the best eligible skill from the full request, descriptions, local
+   instructions, and raw saved preferences, or use no skill. The model itself
+   interprets explicit user direction and preference semantics.
 3. Run `skillboard guard use <skill-id> --agent <agent> --json` before use.
 4. Work without another approval when the guard allows use.
 5. Ask after completion only if remembering a preference would help.
@@ -143,8 +153,8 @@ current action, runs `skillboard apply-action <action-id> --agent <agent> --yes
 rereads the returned post-apply brief.
 
 This is the distinction from a pure distribution tool: skills stay local by
-default, users promote only selected skills to shared use, and routing preference
-can be remembered without changing installation or availability.
+default, users promote only selected skills to shared use, and a model-facing
+preference can be remembered without changing installation or availability.
 
 ## Migrate version 1
 
@@ -157,9 +167,16 @@ skillboard migrate v2 --config <path> --yes --json
 skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-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.
+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/docs/ai-skill-routing-goal.md

@@ -7,16 +7,23 @@ cross-agent sharing, and overlap routing. It asks only two policy questions:
 2. Should SkillBoard share this skill with other supported agents?
 
 Installed, valid skills default to enabled and agent-local. A user may disable
-a skill or opt that individual skill into sharing. An optional preference ranks
-enabled candidates that are actually installed for the current agent;
-preference never changes availability or copies files.
+a skill or opt that individual skill into sharing. An optional preference is
+returned as raw context beside eligible skills; it never changes availability
+or copies files.
+
+The active model owns all v2 semantic skill selection. SkillBoard returns the
+request unchanged with enabled skills installed for the current agent, their
+descriptions, and raw saved preferences. It does not tokenize, normalize,
+score, match, or recommend from v2 request text. The model interprets Korean,
+explicit user direction, and preferences directly, and may choose no skill.
 
 ## Product loop
 
 Preserve `observe → route → work → explain briefly → ask after → remember`.
 Ordinary work must not stop for source review or pre-task configuration. Read
-the current brief when skills overlap, run the guard before use, and ask
-once only before a persistent policy change.
+the current brief when skills overlap, make the semantic choice in the active
+model, run the guard before use, and ask once only before a persistent policy
+change.
 
 ## Boundaries
 
@@ -45,13 +52,18 @@ inventory, and materializes missing copies only for skills already marked
 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
 project the same v2 meaning. Normal commands use one home control plane from any
 working directory; project initialization is not part of the v2 flow. Never
-reintroduce source reputation, workflow scope, or legacy state fields as hidden
-authorization checks.
+reintroduce source reputation, workflow scope, v2 tokenizers or metadata scores,
+or legacy state fields as hidden authorization or semantic-selection checks.
 
 Version 1 is migration input only. It has a one-release read-only window in the
 v0.3 release and is removed in v0.4.0.

package/docs/install.md

@@ -35,6 +35,15 @@ keep. Activate the Node environment that owns each stale prefix, confirm it with
 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:
 
@@ -104,10 +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.
-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.
+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

@@ -24,7 +24,7 @@ compatible copies for other supported agents.
 
 ## Optional routing preference
 
-Preference ranks enabled skills installed for the current agent. It never
+Preference is raw context shown to the model for an eligible skill. It never
 changes availability and never shares files.
 
 ```yaml
@@ -38,8 +38,10 @@ changes availability and never shares files.
       priority: 100
 ```
 
-An explicit user selection wins when the guard allows it. A high priority cannot
-enable a disabled skill or make a skill appear on an agent where it is absent.
+The model interprets explicit user selection and saved preference semantics from
+the full request. SkillBoard does not match the `intents` strings or use
+`priority` as a score in v2. A high priority cannot enable a disabled skill or
+make a skill appear on an agent where it is absent.
 
 ## Generated inventory
 
@@ -71,3 +73,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/positioning.md

@@ -8,8 +8,10 @@ Its durable policy answers two questions:
 1. Is this skill enabled?
 2. Should this one skill remain agent-local or be shared across agents?
 
-Optional preference ranks enabled skills installed for the current agent and
-never changes availability.
+The active model chooses the best enabled skill installed for the current
+agent, or no skill, from raw descriptions and optional saved preferences.
+SkillBoard does not tokenize, score, or match v2 request text. Preference never
+changes availability.
 
 ## Difference from distribution tools
 

package/docs/reference.md

@@ -16,9 +16,9 @@ Source tree: replace `skillboard ` with `node bin/skillboard.mjs `.
 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]
-skillboard can-use <skill-id> --agent codex|claude|opencode|hermes [--json]
-skillboard guard use <skill-id> --agent codex|claude|opencode|hermes [--json]
+skillboard route <intent> --agent <name> (v2 policy) | --workflow <name> (v1 policy) [--json]
+skillboard can-use <skill-id> --agent <name> (v2 policy) | --workflow <name> (v1 policy) [--json]
+skillboard guard use <skill-id> --agent <name> (v2 policy) | --workflow <name> (v1 policy) [--json]
 skillboard skill enable <skill-id> [--dry-run] [--json]
 skillboard skill disable <skill-id> [--dry-run] [--json]
 skillboard skill share <skill-id> [--dry-run] [--json]
@@ -50,12 +50,18 @@ non-symlinked path inside the invoking user's home, and persists the mapping in
 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.
+in `installed_on`. For v2 routing, SkillBoard returns the request plus raw
+eligible skill descriptions and saved preferences. It does not tokenize, score,
+match, or recommend from request text. The active model interprets explicit
+direction and preferences, chooses a skill or no skill, then runs guard.
+Preference never changes availability.
 
 Version 2 route, can-use, and guard require `--agent`; generated agent guidance
 passes it automatically. This prevents one agent from selecting another
 agent's local-only skill without adding a user prompt to the normal flow.
+Version 1 compatibility policy uses `--workflow` instead. Passing the selector
+for the other policy version exits with guidance for the detected version and,
+for v1, the exact `migrate v2` preview command.
 
 ## Config schema v2
 
@@ -79,8 +85,8 @@ skills:
 - `enabled` and `shared` are required Booleans.
 - `shared: false` means agent-local; `shared: true` enables managed cross-agent
   copies while preserving the original.
-- `preference` is optional and ranks enabled skills installed for the current
-  agent only.
+- `preference` is optional raw context for model selection when the skill is
+  enabled and installed for the current agent. SkillBoard does not score it.
 - Unknown policy keys are rejected.
 - Skill ids use letters, numbers, `.`, `_`, `:`, and `-`; path-like ids are rejected.
 - A valid newly discovered skill defaults to enabled and agent-local.
@@ -153,8 +159,13 @@ 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.
+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

package/docs/routing.md

@@ -4,16 +4,22 @@ Routing chooses among skills already available to the current agent. Guard
 decides availability from valid generated inventory, `enabled`, and
 `installed_on`; routing cannot override that verdict.
 
-## Resolution order
+## v2 resolution order
 
 1. Remove skills missing valid inventory records.
 2. Remove disabled skills.
 3. Remove skills not installed for the selected agent.
-4. Honor an explicit user-selected skill if it remains eligible.
-5. Rank intent matches by optional preference and priority.
-6. Return one recommendation and ordered fallbacks.
-
-Preference ranks only and never changes availability.
+4. Return every remaining skill's id, name, description, path, and raw optional
+   preference beside the request.
+5. Let the active model interpret the full request, explicit user direction,
+   descriptions, instructions, and preferences and choose a skill or no skill.
+6. Guard the model-selected skill immediately before use.
+
+V2 has no intent tokenizer, metadata score, request matcher, ranked candidates,
+or deterministic recommendation. Korean and other languages are handled by the
+foundation model. Preference is raw model context and never changes
+availability. Version 1 compatibility routing retains its deterministic
+tokenizer until the v1 reader is removed in v0.4.0.
 
 ```bash
 skillboard brief --intent "write tests" --agent codex --json
@@ -26,8 +32,13 @@ These commands use `~/skillboard.config.yaml` and
 `--config` and `--skills` overrides remain available for migration, testing,
 and legacy workspaces.
 
-When guard allows use, continue without another approval. Ask after completion
-only when remembering a preference would reduce future ambiguity.
+When guard allows use, continue without another approval. If the model-selected
+choice was ambiguous, finish first and ask afterward only when remembering a
+preference would reduce future ambiguity.
+
+Version 1 compatibility routing remains workflow-driven and may return a
+deterministic capability route. It asks for clarification when no workflow
+route matches.
 
 Source and provenance findings are optional audit metadata and never determine
 availability. Runtime and action authorization are outside SkillBoard's scope.

package/docs/user-flow.md

@@ -41,8 +41,11 @@ skillboard guard use <skill-id> --agent codex --json
 ```
 
 The guard allows an enabled skill only when generated inventory records it on
-the selected agent. Preference ranks matching candidates and never changes
-availability. Allowed use does not require another confirmation.
+the selected agent. SkillBoard returns raw eligible descriptions and saved
+preferences without tokenizing, scoring, or matching the request. The model
+interprets the full request, explicit direction, and preferences and chooses a
+skill or no skill. Preference never changes availability. Allowed use does not
+require another confirmation.
 
 ## 3. Change one decision
 
@@ -65,9 +68,10 @@ returned post-apply brief. Cached action ids are not reused.
 
 ## 4. Ask after, then remember
 
-When a route was ambiguous, the agent finishes first. It may then ask whether to
-remember an intent preference. Preference affects ordering only; it does not
-share, enable, disable, install, or remove a skill.
+When a model-selected route was ambiguous, the agent finishes first. It may then
+ask whether to remember an intent preference. Preference becomes raw context
+for later model selection; it does not share, enable, disable, install, or
+remove a skill.
 
 ## 5. Audit separately
 
@@ -111,4 +115,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

@@ -12,10 +12,15 @@ node --test test/v2-agent-sharing.test.mjs test/v2-onboarding-behavior.test.mjs
 - Valid discovered skills default to enabled and agent-local.
 - Disabled skills and skills absent from the selected agent are denied.
 - Share and unshare preserve agent-owned originals.
-- Optional preference changes ranking without changing availability.
+- V2 returns raw eligible descriptions and preferences without interpreting
+  request text or producing a recommendation.
+- Korean, explicit skill direction, and saved preference semantics remain owned
+  by the active model.
+- Optional preference never changes 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/variant-lifecycle.md

@@ -3,7 +3,8 @@
 A variant is a manual content adaptation with snapshot and digest history. The
 lifecycle does not authorize availability. A registered variant is usable only
 according to its ordinary v2 `enabled` entry and generated installation
-presence; optional preference ranks it and never changes availability.
+presence; optional preference is raw model context and never changes
+availability.
 
 ## Current v2 boundary
 

package/docs/versioning.md

@@ -22,9 +22,13 @@ 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.
+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
 
@@ -39,7 +43,8 @@ schema.
 1. Run `npm run check`.
 2. Run `npm pack --dry-run --json` and inspect public contents.
 3. Install the tarball into an isolated prefix and run
-   `skillboard doctor --summary`; verify fresh setup, v1 preservation, and a
+   `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.

package/package.json

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

package/src/advisor/guidance.mjs

@@ -3,7 +3,7 @@ import { command } from "./action-core.mjs";
 const GUARD_WHEN = "immediately before skill use";
 const GOAL_DOCUMENT = Object.freeze({
   path: "docs/ai-skill-routing-goal.md",
-  purpose: "Preserve SkillBoard v2 as a user-level control plane: enable or disable a skill, opt individual skills into cross-agent sharing, and use optional preference only to rank available overlaps.",
+  purpose: "Preserve SkillBoard v2 as a user-level control plane: enable or disable a skill, opt individual skills into cross-agent sharing, and expose optional preference as raw context for the active model.",
   loop: Object.freeze([
     "observe",
     "route",
@@ -140,14 +140,22 @@ function recommendedNextStep(status, brief, choices, route = null) {
   switch (status) {
     case "ready":
       if (route !== null) {
+        if (route.model_selection_required === true) {
+          return modelSelectionStep(route);
+        }
         return route.recommended_skill === null
-          ? "Ask a clarifying question; no workflow capability matched this request."
+          ? route.workflow === null
+            ? "No enabled skill is available for this request."
+            : "Ask a clarifying question; no workflow capability matched this request."
           : `Use ${route.recommended_skill} for this request after the guard check passes${postUsePolicyStep(route)}.`;
       }
       return availableSkillCount(brief) === 0
         ? "No policy change is required; valid installed skills default to enabled and agent-local."
         : "Run the guard check immediately before using any selected skill.";
     case "needs-decision":
+      if (route?.model_selection_required === true) {
+        return `${modelSelectionStep(route)} Handle pending review decisions after the task unless a policy-changing action is needed now.`;
+      }
       if (route?.recommended_skill !== null && route?.guard_allowed === true) {
         return route.post_use_policy_suggestion === null
           ? `Use ${route.recommended_skill} for this request after the guard check passes; handle pending review decisions after the task unless a policy-changing action is needed now.`
@@ -180,6 +188,10 @@ function recommendedNextStep(status, brief, choices, route = null) {
   }
 }
 
+function modelSelectionStep(route) {
+  return "Choose the best enabled, installed skill from the request's semantic context, skill descriptions, and raw saved preferences. Run its guard before use, or continue without a skill when none fits.";
+}
+
 function postUsePolicyStep(route) {
   return route.post_use_policy_suggestion === null
     ? ""
@@ -197,6 +209,8 @@ function routeGuidance(route) {
     matched_terms: route.matched_terms,
     recommendation_reason: route.recommendation_reason,
     recommended_skill: route.recommended_skill,
+    selection_mode: route.selection_mode ?? null,
+    model_selection_required: route.model_selection_required ?? false,
     fallback_skills: route.fallback_skills,
     route_candidates: (route.route_candidates ?? []).map((candidate) => ({
       skill: candidate.skill,
@@ -216,6 +230,10 @@ function routeGuidance(route) {
     guard_reasons: route.guard?.reasons ?? [],
     possible_skills: route.possible_skills.map((skill) => ({
       id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      path: skill.path,
+      preference: skill.preference,
       category: skill.category,
       allowed: skill.allowed
     }))

package/src/agent-integration-cli.mjs

@@ -1,6 +1,7 @@
-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, applyOwnershipTree, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
@@ -13,6 +14,7 @@ import {
 } 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);
@@ -52,7 +54,21 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
     preserveLegacyPolicy: true
   });
   const configPath = resolve(home, inventory.configPath);
-  const inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  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 });
@@ -80,14 +96,24 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
   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");
+  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("- 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");
+  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;
@@ -222,46 +248,3 @@ function formatSharedEntry(entry) {
 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, 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);
-}
-
-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, "'\\''")}'`;
-}