skillvault 0.9.3 → 0.11.1

package/dist/cli.js

@@ -17,15 +17,19 @@
  *   5. Claude reads the output and follows the instructions
  *   6. Decrypted content is never written to disk
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, cpSync } from 'node:fs';
+import { dirname, join, resolve as pathResolve } from 'node:path';
 import { createDecipheriv, createHmac, createPublicKey, diffieHellman, hkdfSync, generateKeyPairSync, } from 'node:crypto';
-const VERSION = '0.9.3';
+import { resolveScope, resolveRoots, } from './scope.js';
+import { loadCredentials, saveCredentials, loadProjectConfig, saveProjectConfig, } from './credentials.js';
+import { registerProject, unregisterProject, getCurrentProject, listProjects, } from './projects-registry.js';
+import { confirmInstall } from './prompts.js';
+const VERSION = '0.11.1';
 const HOME = process.env.HOME || process.env.USERPROFILE || '~';
 const API_URL = process.env.SKILLVAULT_API_URL || 'https://api.getskillvault.com';
 const CONFIG_DIR = join(HOME, '.skillvault');
-const CONFIG_PATH = join(CONFIG_DIR, 'agent-config.json');
-const VAULT_DIR = join(CONFIG_DIR, 'vaults');
+/** Legacy config path. Kept for backward-compat read-only fallback in loadConfig(). */
+const LEGACY_CONFIG_PATH = join(CONFIG_DIR, 'agent-config.json');
 const AGENTS_SKILLS_DIR = join(HOME, '.agents', 'skills'); // agent-agnostic source of truth
 const AGENTS_LOCK_PATH = join(HOME, '.agents', '.skill-lock.json');
 /** Detect which AI agent platforms are installed and return their skill directories */
@@ -44,8 +48,43 @@ function detectAgentPlatforms() {
     }
     return platforms;
 }
-// Legacy: SKILLS_DIR points to Claude for backward compat in other functions
-const SKILLS_DIR = join(HOME, '.claude', 'skills');
+// ── Active install roots ──
+//
+// SkillVault supports project-scoped and global installs. The active roots
+// are resolved once at startup based on flags + CWD + the projects registry.
+// Functions that read or write per-install state (vaults, hooks, stubs)
+// pull from currentRoots so they can be redirected by the entry point.
+let currentRoots = resolveRoots('global');
+/**
+ * Resolve the active install roots from explicit flags, the projects
+ * registry, and existing-install detection.
+ *
+ * Precedence:
+ *   1. --global / --project flag
+ *   2. CWD matches a registered project → project scope
+ *   3. ~/.skillvault/credentials.json or agent-config.json exists → global
+ *   4. resolveScope() default (project unless CWD is HOME or /)
+ */
+function resolveActiveRoots(opts = {}) {
+    if (opts.global)
+        return resolveRoots('global');
+    if (opts.project)
+        return resolveRoots('project', process.cwd());
+    const registered = getCurrentProject(process.cwd());
+    if (registered)
+        return resolveRoots('project', registered.path);
+    if (existsSync(join(CONFIG_DIR, 'credentials.json')) || existsSync(LEGACY_CONFIG_PATH)) {
+        return resolveRoots('global');
+    }
+    const detected = resolveScope({ cwd: process.cwd() });
+    return resolveRoots(detected, process.cwd());
+}
+function setActiveRoots(roots) {
+    currentRoots = roots;
+}
+function getActiveRoots() {
+    return currentRoots;
+}
 // ── CLI Argument Parsing ──
 const args = process.argv.slice(2);
 const inviteIdx = args.indexOf('--invite');
@@ -73,6 +112,43 @@ const eventType = eventTypeIdx >= 0 ? args[eventTypeIdx + 1] : null;
 const sessionCleanupFlag = args.includes('--session-cleanup');
 const scanOutputFlag = args.includes('--scan-output');
 const checkSessionFlag = args.includes('--check-session');
+const globalFlag = args.includes('--global');
+const projectFlag = args.includes('--project');
+const dryRunFlag = args.includes('--dry-run');
+const allPublishersFlag = args.includes('--all');
+/** --all is shared between `add-publisher --all` and `uninstall --all`; alias for clarity. */
+const allFlag = allPublishersFlag;
+/** Collect all `--publisher <id>` occurrences from argv. */
+function collectPublisherFlags() {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--publisher' && i + 1 < args.length) {
+            out.push(args[i + 1]);
+            i++;
+        }
+    }
+    return out;
+}
+const publisherFlagIds = collectPublisherFlags();
+/**
+ * Subcommand parsing. SkillVault CLI mixes legacy --invite/--load/--sync flags
+ * with positional subcommands like `npx skillvault publishers`. The first
+ * non-flag arg is treated as the subcommand name; remaining positional args
+ * become its arguments.
+ */
+const positional = args.filter((a, i) => {
+    if (a.startsWith('--') || a.startsWith('-'))
+        return false;
+    // Skip values that are arguments to known --flag <value> pairs.
+    const prev = args[i - 1];
+    if (prev === '--invite' || prev === '--load' || prev === '--file' ||
+        prev === '--list-files' || prev === '--report' || prev === '--skill' ||
+        prev === '--detail' || prev === '--event-type' || prev === '--publisher')
+        return false;
+    return true;
+});
+const subcommand = positional[0] || null;
+const subcommandArgs = positional.slice(1);
 if (versionFlag) {
     console.log(`skillvault ${VERSION}`);
     process.exit(0);
@@ -83,6 +159,9 @@ if (helpFlag) {
 
   Usage:
     npx skillvault --invite CODE       Setup: redeem invite, sync, install skills
+      --global                         Force install into ~/.claude, ~/.skillvault
+      --project                        Force install into ./.claude, ./.skillvault
+      --dry-run                        Print planned writes without applying
     npx skillvault --load SKILL        Decrypt and output a skill (used by Claude)
     npx skillvault --status            Show publishers, skills, and statuses
     npx skillvault --refresh           Re-authenticate tokens + sync skills
@@ -96,9 +175,16 @@ if (helpFlag) {
     npx skillvault --help              Show this help
     npx skillvault --version           Show version
 
-  Skills are encrypted at rest in ~/.skillvault/vaults/. When Claude Code
-  triggers a skill, it runs \`npx skillvault --load <name>\` to decrypt on
-  demand. The decrypted content goes to stdout — never written to disk.
+  Install scopes:
+    - "project" install (default in any normal CWD): files live under
+      ./.claude/ and ./.skillvault/. Removed by deleting the project folder.
+    - "global"  install (default at HOME or /, or with --global): files live
+      under ~/.claude/ and ~/.skillvault/. Affects every Claude Code session.
+    - Customer credentials always live at ~/.skillvault/credentials.json.
+
+  Skills are encrypted at rest in <install>/.skillvault/vaults/. When Claude
+  Code triggers a skill, it runs \`npx skillvault --load <name>\` to decrypt
+  on demand. The decrypted content goes to stdout — never written to disk.
   License is validated on every load.
 
   Environment:
@@ -106,39 +192,93 @@ if (helpFlag) {
   `);
     process.exit(0);
 }
-function loadConfig() {
-    try {
-        if (existsSync(CONFIG_PATH)) {
-            const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
-            if (raw.token && !raw.publishers) {
-                const migrated = {
-                    customer_token: raw.token,
-                    customer_email: raw.email || null,
-                    publishers: [{
-                            id: raw.publisher_id,
-                            name: raw.publisher_id,
-                            token: raw.token,
-                            added_at: raw.setup_at || new Date().toISOString(),
-                        }],
-                    api_url: raw.api_url || API_URL,
-                    setup_at: raw.setup_at || new Date().toISOString(),
-                };
-                saveConfig(migrated);
-                return migrated;
-            }
-            return raw;
-        }
-    }
-    catch { }
-    return null;
+/**
+ * Read both credentials.json and the active install's project.json and
+ * project them into the legacy AgentConfig view.
+ *
+ * loadCredentials() handles the one-time migration from the legacy
+ * ~/.skillvault/agent-config.json (v0.9.x format), so by the time we get
+ * here we either have new-format credentials or null.
+ */
+function loadConfig(roots = getActiveRoots()) {
+    const credentials = loadCredentials();
+    if (!credentials)
+        return null;
+    const projectConfig = loadProjectConfig(roots);
+    // In project mode, filter publishers down to the active list. In global
+    // mode (or when no project.json exists), include every publisher.
+    const visiblePublishers = projectConfig
+        ? credentials.publishers.filter(p => projectConfig.active_publishers.includes(p.id))
+        : credentials.publishers;
+    return {
+        customer_token: credentials.customer_token,
+        customer_email: credentials.customer_email,
+        publishers: visiblePublishers,
+        api_url: credentials.api_url || API_URL,
+        setup_at: credentials.created_at,
+        __credentials: credentials,
+        __projectConfig: projectConfig,
+    };
 }
-function saveConfig(config) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+/**
+ * Persist an AgentConfig back to disk in the new split format. The
+ * underlying credentials and project-config snapshots are reconstructed
+ * from the AgentConfig object so callers don't need to manage them.
+ *
+ * If the AgentConfig has __credentials/__projectConfig metadata attached,
+ * those are used as the base; otherwise we synthesize fresh ones.
+ */
+function saveConfig(config, roots = getActiveRoots()) {
+    const baseCredentials = config.__credentials ?? {
+        customer_token: config.customer_token,
+        customer_email: config.customer_email,
+        publishers: [],
+        api_url: config.api_url || API_URL,
+        created_at: config.setup_at || new Date().toISOString(),
+    };
+    // Merge: ensure every publisher in `config.publishers` exists in credentials,
+    // and update tokens/customer fields from the in-memory state.
+    const merged = new Map();
+    for (const p of baseCredentials.publishers)
+        merged.set(p.id, p);
+    for (const p of config.publishers)
+        merged.set(p.id, p);
+    const newCredentials = {
+        ...baseCredentials,
+        customer_token: config.customer_token,
+        customer_email: config.customer_email,
+        publishers: [...merged.values()],
+        api_url: config.api_url || baseCredentials.api_url || API_URL,
+        created_at: baseCredentials.created_at || config.setup_at || new Date().toISOString(),
+    };
+    saveCredentials(newCredentials);
+    // Project config: write only the active publishers (the visible set).
+    const baseProject = config.__projectConfig ?? {
+        active_publishers: config.publishers.map(p => p.id),
+        installed_at: config.setup_at || new Date().toISOString(),
+        scope: roots.scope,
+        install_path: roots.scope === 'project' ? process.cwd() : HOME,
+    };
+    const newProject = {
+        ...baseProject,
+        active_publishers: config.publishers.map(p => p.id),
+        scope: roots.scope,
+        install_path: baseProject.install_path,
+    };
+    saveProjectConfig(roots, newProject);
 }
 // ── Setup: Redeem Invite + Sync + Install ──
-async function setup(code) {
+/**
+ * Redeem an invite code and install skills into the resolved install roots.
+ *
+ * Credentials always go to ~/.skillvault/credentials.json (global). Project
+ * config (active publishers, install metadata) goes to <roots.configDir>/project.json.
+ * Vaults and skill stubs go to roots.vaultDir and roots.claudeDir respectively.
+ */
+async function setup(code, roots) {
     console.error('🔐 SkillVault Setup');
+    console.error(`   Scope:      ${roots.scope === 'project' ? 'project (this directory)' : 'global (~/.claude, ~/.skillvault)'}`);
+    console.error(`   Location:   ${roots.scope === 'project' ? process.cwd() : HOME}`);
     console.error(`   Redeeming invite code: ${code}`);
     const response = await fetch(`${API_URL}/auth/companion/token`, {
         method: 'POST',
@@ -171,53 +311,116 @@ async function setup(code) {
     if (data.capabilities.length > 0) {
         console.error(`   📦 Skills: ${data.capabilities.join(', ')}`);
     }
-    const existingConfig = loadConfig();
+    // Update credentials.json — always global, full publisher list across all
+    // projects. The new publisher is added or its token is refreshed in place.
+    const existingCredentials = loadCredentials() ?? {
+        customer_token: data.customer_token || data.token,
+        customer_email: data.email,
+        publishers: [],
+        api_url: API_URL,
+        created_at: new Date().toISOString(),
+    };
     const publisherEntry = {
         id: data.publisher_id,
         name: data.publisher_name || data.publisher_id,
         token: data.token,
         added_at: new Date().toISOString(),
     };
-    if (existingConfig) {
-        const existingIdx = existingConfig.publishers.findIndex(p => p.id === data.publisher_id);
-        if (existingIdx >= 0) {
-            existingConfig.publishers[existingIdx] = publisherEntry;
-            console.error(`   🔄 Updated publisher: ${publisherEntry.name}`);
-        }
-        else {
-            existingConfig.publishers.push(publisherEntry);
-            console.error(`   ➕ Added publisher: ${publisherEntry.name}`);
+    const wasNewPublisher = !existingCredentials.publishers.some(p => p.id === data.publisher_id);
+    const updatedPublishers = existingCredentials.publishers.filter(p => p.id !== data.publisher_id);
+    updatedPublishers.push(publisherEntry);
+    if (wasNewPublisher) {
+        console.error(`   ➕ Added publisher: ${publisherEntry.name}`);
+    }
+    else {
+        console.error(`   🔄 Updated publisher: ${publisherEntry.name}`);
+    }
+    const newCredentials = {
+        customer_token: data.customer_token || existingCredentials.customer_token || data.token,
+        customer_email: data.email || existingCredentials.customer_email,
+        publishers: updatedPublishers,
+        api_url: existingCredentials.api_url || API_URL,
+        created_at: existingCredentials.created_at,
+    };
+    saveCredentials(newCredentials);
+    // Compute the new active list for THIS install. The default is:
+    //   existing project active list (if any) + the publisher just invited
+    // overridden by --publisher flags or --all if provided.
+    const existingProject = loadProjectConfig(roots);
+    const previousActive = existingProject?.active_publishers ?? [];
+    let newActive;
+    if (allPublishersFlag) {
+        newActive = updatedPublishers.map(p => p.id);
+    }
+    else if (publisherFlagIds.length > 0) {
+        // Validate that every requested publisher is known.
+        const unknown = publisherFlagIds.filter(id => !updatedPublishers.some(p => p.id === id));
+        if (unknown.length > 0) {
+            console.error(`   ⚠️  Unknown publisher${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}`);
         }
-        if (data.customer_token)
-            existingConfig.customer_token = data.customer_token;
-        if (data.email)
-            existingConfig.customer_email = data.email;
-        saveConfig(existingConfig);
+        newActive = publisherFlagIds.filter(id => updatedPublishers.some(p => p.id === id));
+        if (!newActive.includes(data.publisher_id))
+            newActive.push(data.publisher_id);
+    }
+    else if (existingProject) {
+        // Keep existing active list and add the new publisher.
+        newActive = [...previousActive];
+        if (!newActive.includes(data.publisher_id))
+            newActive.push(data.publisher_id);
     }
     else {
-        saveConfig({
-            customer_token: data.customer_token || data.token,
-            customer_email: data.email,
-            publishers: [publisherEntry],
-            api_url: API_URL,
-            setup_at: new Date().toISOString(),
-        });
+        // Fresh install — only the publisher just invited is active.
+        newActive = [data.publisher_id];
     }
-    mkdirSync(join(VAULT_DIR, data.publisher_id), { recursive: true });
+    if (existingProject && previousActive.length > 0) {
+        const newlyActivated = newActive.filter(id => !previousActive.includes(id));
+        if (newlyActivated.length > 0) {
+            console.error(`   ✅ Activated in this install: ${newlyActivated.join(', ')}`);
+        }
+        // Hint about other publishers the customer has access to but isn't using here.
+        const inactive = updatedPublishers.filter(p => !newActive.includes(p.id));
+        if (inactive.length > 0) {
+            console.error(`   ℹ️  Inactive in this install: ${inactive.map(p => p.name).join(', ')}`);
+            console.error(`      Run \`npx skillvault add-publisher <id>\` to enable them here.`);
+        }
+    }
+    // Persist project.json with the new active list.
+    const newProject = {
+        active_publishers: newActive,
+        installed_at: existingProject?.installed_at || new Date().toISOString(),
+        scope: roots.scope,
+        install_path: existingProject?.install_path || (roots.scope === 'project' ? process.cwd() : HOME),
+        last_synced_at: new Date().toISOString(),
+    };
+    saveProjectConfig(roots, newProject);
+    mkdirSync(join(roots.vaultDir, data.publisher_id), { recursive: true });
     // Clean up legacy MCP config if present
     cleanupMCPConfig();
     // Install session hook for auto-sync
-    configureSessionHook();
+    configureSessionHook(roots);
     // Sync vaults and install stubs
     console.error('');
     console.error('   Syncing skills...');
-    await syncSkills();
-    const installResult = await installSkillStubs();
+    await syncSkills(roots);
+    const installResult = await installSkillStubs(roots);
+    // Register the install in ~/.skillvault/projects.json (project mode only)
+    if (roots.scope === 'project') {
+        const proj = loadProjectConfig(roots);
+        registerProject({
+            path: pathResolve(process.cwd()),
+            installed_at: proj?.installed_at || new Date().toISOString(),
+            last_synced_at: new Date().toISOString(),
+            active_publishers: proj?.active_publishers || [data.publisher_id],
+        });
+    }
     console.error('');
     if (installResult.installed > 0) {
-        console.error(`   ✅ ${installResult.installed} skill${installResult.installed !== 1 ? 's' : ''} installed to ~/.claude/skills/`);
+        const stubLocation = roots.scope === 'project'
+            ? `${roots.claudeDir}/skills/`
+            : '~/.claude/skills/';
+        console.error(`   ✅ ${installResult.installed} skill${installResult.installed !== 1 ? 's' : ''} installed to ${stubLocation}`);
     }
-    console.error('   ✅ Setup complete! Restart Claude Code to use your skills.');
+    console.error(`   ✅ Setup complete! Restart Claude Code to use your skills.`);
     console.error('   Skills will auto-sync at the start of each Claude Code session.');
     console.error('');
 }
@@ -257,8 +460,8 @@ function hasSkillvaultCommand(entry) {
     }
     return false;
 }
-function configureSessionHook() {
-    const settingsPath = join(HOME, '.claude', 'settings.json');
+function configureSessionHook(roots) {
+    const settingsPath = roots.settingsPath;
     try {
         let settings = {};
         if (existsSync(settingsPath)) {
@@ -313,9 +516,9 @@ function configureSessionHook() {
                     delete settings.hooks[key];
             }
         }
-        mkdirSync(join(HOME, '.claude'), { recursive: true });
+        mkdirSync(dirname(settingsPath), { recursive: true });
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
-        console.error('   ✅ Hooks updated');
+        console.error(`   ✅ Hooks updated (${settingsPath})`);
         if (removedLegacy)
             console.error('   🧹 Removed legacy monitoring hooks (now session-scoped)');
     }
@@ -324,7 +527,7 @@ function configureSessionHook() {
     }
 }
 /**
- * Inject session-scoped monitoring hooks into ~/.claude/settings.json.
+ * Inject session-scoped monitoring hooks into the active install's settings.json.
  * Called after successful --load to enable extraction detection for this session.
  *
  * Creates:
@@ -332,11 +535,13 @@ function configureSessionHook() {
  *   - PostToolUse: n-gram fingerprint matching on tool output
  *   - Stop: n-gram fingerprint matching on Claude's response
  *
- * Also creates ~/.skillvault/active-session.json with session metadata.
+ * Also creates <roots.configDir>/active-session.json with session metadata
+ * including the scope and install_path so the session-keepalive and
+ * session-cleanup hooks can locate the right install when they fire.
  */
-function injectMonitoringHooks(skillName) {
-    const settingsPath = join(HOME, '.claude', 'settings.json');
-    const activeSessionPath = join(CONFIG_DIR, 'active-session.json');
+function injectMonitoringHooks(skillName, roots = getActiveRoots()) {
+    const settingsPath = roots.settingsPath;
+    const activeSessionPath = join(roots.configDir, 'active-session.json');
     try {
         let settings = {};
         if (existsSync(settingsPath)) {
@@ -351,8 +556,11 @@ function injectMonitoringHooks(skillName) {
             skill: skillName,
             loaded_at: now.toISOString(),
             expires_at: expiresAt.toISOString(),
+            scope: roots.scope,
+            install_path: roots.scope === 'project' ? process.cwd() : HOME,
+            settings_path: settingsPath,
         };
-        mkdirSync(CONFIG_DIR, { recursive: true });
+        mkdirSync(roots.configDir, { recursive: true });
         writeFileSync(activeSessionPath, JSON.stringify(session, null, 2), { mode: 0o600 });
         // ── Remove old-format monitoring hooks (command on entry, no hooks array) ──
         for (const key of ['UserPromptSubmit', 'PostToolUse', 'Stop']) {
@@ -400,7 +608,8 @@ function injectMonitoringHooks(skillName) {
     }
 }
 async function showStatus() {
-    const config = loadConfig();
+    const roots = getActiveRoots();
+    const config = loadConfig(roots);
     if (!config) {
         console.log('🔐 SkillVault\n');
         console.log('   Not set up yet. Run:');
@@ -410,8 +619,9 @@ async function showStatus() {
     console.log('🔐 SkillVault Status\n');
     if (config.customer_email)
         console.log(`   Account: ${config.customer_email}`);
-    console.log(`   Config:  ${CONFIG_PATH}`);
-    console.log(`   Skills:  ${SKILLS_DIR}`);
+    console.log(`   Scope:   ${roots.scope}`);
+    console.log(`   Config:  ${roots.configDir}`);
+    console.log(`   Skills:  ${join(roots.claudeDir, 'skills')}`);
     console.log(`   Server:  ${config.api_url}`);
     console.log('');
     let skills = [];
@@ -451,7 +661,7 @@ async function showStatus() {
     for (const pub of config.publishers) {
         const pubSkills = skills.filter(s => s.publisher_id === pub.id);
         let localVaultCount = 0;
-        const pubVaultDir = join(VAULT_DIR, pub.id);
+        const pubVaultDir = join(roots.vaultDir, pub.id);
         if (existsSync(pubVaultDir)) {
             try {
                 localVaultCount = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault')).length;
@@ -483,8 +693,8 @@ async function showStatus() {
     console.log('');
 }
 // ── Refresh ──
-async function refreshTokens() {
-    const config = loadConfig();
+async function refreshTokens(roots = getActiveRoots()) {
+    const config = loadConfig(roots);
     if (!config) {
         console.error('🔐 SkillVault\n   Not set up. Run: npx skillvault --invite YOUR_CODE\n');
         process.exit(1);
@@ -519,22 +729,22 @@ async function refreshTokens() {
         }
     }
     if (anyRefreshed) {
-        saveConfig(config);
+        saveConfig(config, roots);
         console.error('\n   Tokens updated.\n');
     }
     else {
         console.error('\n   No tokens refreshed.\n');
     }
 }
-async function syncSkills() {
-    const config = loadConfig();
+async function syncSkills(roots = getActiveRoots()) {
+    const config = loadConfig(roots);
     if (!config || config.publishers.length === 0) {
         return { synced: 0, errors: ['No config or publishers found'] };
     }
     let totalSynced = 0;
     const errors = [];
     for (const pub of config.publishers) {
-        const pubVaultDir = join(VAULT_DIR, pub.id);
+        const pubVaultDir = join(roots.vaultDir, pub.id);
         mkdirSync(pubVaultDir, { recursive: true });
         let skills = [];
         try {
@@ -554,6 +764,7 @@ async function syncSkills() {
             continue;
         }
         const remoteSkillNames = new Set(skills.map(s => s.skill_name));
+        const localStubsDir = join(roots.claudeDir, 'skills');
         // Revocation: remove stubs for skills no longer in remote list
         try {
             if (existsSync(pubVaultDir)) {
@@ -562,23 +773,32 @@ async function syncSkills() {
                     const localSkillName = vaultFile.replace(/\.vault$/, '');
                     if (!remoteSkillNames.has(localSkillName)) {
                         console.error(`[sync] Grant revoked: "${localSkillName}" from ${pub.name}`);
-                        // Remove from agent-agnostic dir
-                        const agentDir = join(AGENTS_SKILLS_DIR, localSkillName);
+                        // Remove from this install's claude skill dir
+                        const stubDir = join(localStubsDir, localSkillName);
                         try {
-                            if (existsSync(agentDir))
-                                rmSync(agentDir, { recursive: true, force: true });
+                            if (existsSync(stubDir))
+                                rmSync(stubDir, { recursive: true, force: true });
                         }
                         catch { }
-                        // Remove from all detected agent platforms
-                        for (const platform of detectAgentPlatforms()) {
-                            const platformDir = join(platform.dir, localSkillName);
+                        // For global installs, also clean the agent-agnostic source-of-truth
+                        // and any detected secondary agent platforms.
+                        if (roots.scope === 'global') {
+                            const agentDir = join(AGENTS_SKILLS_DIR, localSkillName);
                             try {
-                                if (existsSync(platformDir))
-                                    rmSync(platformDir, { recursive: true, force: true });
+                                if (existsSync(agentDir))
+                                    rmSync(agentDir, { recursive: true, force: true });
                             }
                             catch { }
+                            for (const platform of detectAgentPlatforms()) {
+                                const platformDir = join(platform.dir, localSkillName);
+                                try {
+                                    if (existsSync(platformDir))
+                                        rmSync(platformDir, { recursive: true, force: true });
+                                }
+                                catch { }
+                            }
                         }
-                        console.error(`[sync] Removed "${localSkillName}" from all agent platforms`);
+                        console.error(`[sync] Removed "${localSkillName}"`);
                     }
                 }
             }
@@ -640,38 +860,50 @@ async function syncSkills() {
     }
     return { synced: totalSynced, errors };
 }
-async function installSkillStubs() {
-    const config = loadConfig();
+async function installSkillStubs(roots = getActiveRoots()) {
+    const config = loadConfig(roots);
     if (!config || config.publishers.length === 0) {
         return { installed: 0, skipped: 0, errors: ['No config or publishers found'] };
     }
     let installed = 0;
     let skipped = 0;
     const errors = [];
-    mkdirSync(AGENTS_SKILLS_DIR, { recursive: true });
-    const detectedPlatforms = detectAgentPlatforms();
-    for (const platform of detectedPlatforms) {
-        mkdirSync(platform.dir, { recursive: true });
+    // Per-install Claude Code skills directory.
+    const installSkillsDir = join(roots.claudeDir, 'skills');
+    mkdirSync(installSkillsDir, { recursive: true });
+    // The agent-agnostic ~/.agents/skills/ + secondary platforms only get
+    // populated for global installs. In project mode they would leak content
+    // out of the project boundary, which is the whole point of the refactor.
+    const isGlobal = roots.scope === 'global';
+    const detectedPlatforms = isGlobal ? detectAgentPlatforms() : [];
+    if (isGlobal) {
+        mkdirSync(AGENTS_SKILLS_DIR, { recursive: true });
+        for (const platform of detectedPlatforms) {
+            mkdirSync(platform.dir, { recursive: true });
+        }
     }
-    // Load existing lock file
+    // Lock file location depends on scope: global → ~/.agents/.skill-lock.json,
+    // project → <roots.configDir>/skill-lock.json (per-install).
+    const lockPath = isGlobal
+        ? AGENTS_LOCK_PATH
+        : join(roots.configDir, 'skill-lock.json');
     let lockData = { version: 3, skills: {} };
     try {
-        if (existsSync(AGENTS_LOCK_PATH)) {
-            lockData = JSON.parse(readFileSync(AGENTS_LOCK_PATH, 'utf8'));
+        if (existsSync(lockPath)) {
+            lockData = JSON.parse(readFileSync(lockPath, 'utf8'));
         }
     }
     catch { }
     for (const pub of config.publishers) {
-        const pubVaultDir = join(VAULT_DIR, pub.id);
+        const pubVaultDir = join(roots.vaultDir, pub.id);
         if (!existsSync(pubVaultDir))
             continue;
         const vaultFiles = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault'));
         for (const vaultFile of vaultFiles) {
             const skillName = vaultFile.replace(/\.vault$/, '');
             const vaultPath = join(pubVaultDir, vaultFile);
-            const agentSkillDir = join(AGENTS_SKILLS_DIR, skillName);
-            const skillDir = agentSkillDir;
-            const manifestPath = join(skillDir, 'manifest.json');
+            const installStubDir = join(installSkillsDir, skillName);
+            const manifestPath = join(installStubDir, 'manifest.json');
             const hashPath = vaultPath + '.hash';
             if (existsSync(manifestPath) && existsSync(hashPath)) {
                 try {
@@ -775,26 +1007,35 @@ ${multiFileSection}`;
                 installed_at: new Date().toISOString(),
                 encrypted: true,
             }, null, 2);
-            // Write to ~/.agents/skills/ (agent-agnostic source of truth)
-            mkdirSync(agentSkillDir, { recursive: true });
-            writeFileSync(join(agentSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
-            writeFileSync(join(agentSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
-            // Write file manifest cache for --list-files
+            // Write the stub into this install's claude skills directory.
+            mkdirSync(installStubDir, { recursive: true });
+            writeFileSync(join(installStubDir, 'SKILL.md'), stub, { mode: 0o600 });
+            writeFileSync(join(installStubDir, 'manifest.json'), manifestData, { mode: 0o600 });
             if (vaultFileList.length > 0) {
-                writeFileSync(join(agentSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+                writeFileSync(join(installStubDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
             }
-            // Copy to each detected agent platform's skill directory
-            for (const platform of detectedPlatforms) {
-                const platformSkillDir = join(platform.dir, skillName);
-                try {
-                    mkdirSync(platformSkillDir, { recursive: true });
-                    writeFileSync(join(platformSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
-                    writeFileSync(join(platformSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
-                    if (vaultFileList.length > 0) {
-                        writeFileSync(join(platformSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+            // Global mode only: also write to the agent-agnostic source-of-truth
+            // and any other detected agent platforms (Cursor, Windsurf, Codex).
+            if (isGlobal) {
+                const agentSkillDir = join(AGENTS_SKILLS_DIR, skillName);
+                mkdirSync(agentSkillDir, { recursive: true });
+                writeFileSync(join(agentSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
+                writeFileSync(join(agentSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
+                if (vaultFileList.length > 0) {
+                    writeFileSync(join(agentSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+                }
+                for (const platform of detectedPlatforms) {
+                    const platformSkillDir = join(platform.dir, skillName);
+                    try {
+                        mkdirSync(platformSkillDir, { recursive: true });
+                        writeFileSync(join(platformSkillDir, 'SKILL.md'), stub, { mode: 0o600 });
+                        writeFileSync(join(platformSkillDir, 'manifest.json'), manifestData, { mode: 0o600 });
+                        if (vaultFileList.length > 0) {
+                            writeFileSync(join(platformSkillDir, 'files.json'), JSON.stringify(vaultFileList, null, 2), { mode: 0o600 });
+                        }
                     }
+                    catch { }
                 }
-                catch { }
             }
             // Update lock file
             lockData.skills[skillName] = {
@@ -810,18 +1051,605 @@ ${multiFileSection}`;
                 encrypted: true,
             };
             installed++;
-            const platformNames = detectedPlatforms.map(p => p.name).join(', ') || 'none detected';
-            console.error(`[install] "${skillName}" → ~/.agents/skills/ + ${platformNames}`);
+            if (isGlobal) {
+                const platformNames = detectedPlatforms.map(p => p.name).join(', ') || 'none detected';
+                console.error(`[install] "${skillName}" → ~/.agents/skills/ + ${platformNames}`);
+            }
+            else {
+                console.error(`[install] "${skillName}" → ${installStubDir}`);
+            }
         }
     }
     // Persist lock file
     try {
-        mkdirSync(join(HOME, '.agents'), { recursive: true });
-        writeFileSync(AGENTS_LOCK_PATH, JSON.stringify(lockData, null, 2), { mode: 0o600 });
+        mkdirSync(dirname(lockPath), { recursive: true });
+        writeFileSync(lockPath, JSON.stringify(lockData, null, 2), { mode: 0o600 });
     }
     catch { }
     return { installed, skipped, errors };
 }
+function removePublisherStubs(publisherId, roots) {
+    const removed = [];
+    const skillsDir = join(roots.claudeDir, 'skills');
+    if (!existsSync(skillsDir))
+        return removed;
+    for (const entry of readdirSync(skillsDir)) {
+        const stubDir = join(skillsDir, entry);
+        const manifestPath = join(stubDir, 'manifest.json');
+        if (!existsSync(manifestPath))
+            continue;
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            if (manifest.publisher_id === publisherId) {
+                rmSync(stubDir, { recursive: true, force: true });
+                removed.push({ skillName: manifest.skill_name || entry, publisherId });
+            }
+        }
+        catch { }
+    }
+    return removed;
+}
+// ── Publisher management commands ──
+//
+// `publishers`            list active publishers in current install
+// `add-publisher <id>`    enable a publisher in current install + sync its skills
+// `remove-publisher <id>` disable + remove its stubs (vault data preserved)
+async function handlePublishersCommand() {
+    const roots = getActiveRoots();
+    const credentials = loadCredentials();
+    if (!credentials || credentials.publishers.length === 0) {
+        console.log('🔐 SkillVault — no publishers configured.');
+        console.log('   Run: npx skillvault --invite YOUR_CODE');
+        return;
+    }
+    const project = loadProjectConfig(roots);
+    const active = new Set(project?.active_publishers ?? credentials.publishers.map(p => p.id));
+    console.log(`🔐 Publishers (${roots.scope} install at ${roots.scope === 'project' ? process.cwd() : HOME})\n`);
+    console.log(`   ${'Active'.padEnd(8)} ${'ID'.padEnd(20)} Name`);
+    console.log('   ' + '-'.repeat(60));
+    for (const pub of credentials.publishers) {
+        const tag = active.has(pub.id) ? '   ✓   ' : '       ';
+        console.log(`   ${tag} ${pub.id.padEnd(20)} ${pub.name}`);
+    }
+    console.log('');
+    console.log(`   ${active.size} of ${credentials.publishers.length} publishers active.\n`);
+}
+async function handleAddPublisherCommand(publisherId) {
+    if (!publisherId) {
+        console.error('Usage: npx skillvault add-publisher <publisher_id>');
+        process.exit(1);
+    }
+    const roots = getActiveRoots();
+    const credentials = loadCredentials();
+    if (!credentials) {
+        console.error('🔐 SkillVault not configured. Run: npx skillvault --invite YOUR_CODE');
+        process.exit(1);
+    }
+    const pub = credentials.publishers.find(p => p.id === publisherId);
+    if (!pub) {
+        console.error(`Error: publisher "${publisherId}" not in your credentials.`);
+        console.error('Available publishers:');
+        for (const p of credentials.publishers)
+            console.error(`  - ${p.id} (${p.name})`);
+        console.error('');
+        console.error('To gain access to a new publisher, redeem an invite:');
+        console.error('  npx skillvault --invite NEW_INVITE_CODE');
+        process.exit(1);
+    }
+    const project = loadProjectConfig(roots) ?? {
+        active_publishers: [],
+        installed_at: new Date().toISOString(),
+        scope: roots.scope,
+        install_path: roots.scope === 'project' ? process.cwd() : HOME,
+    };
+    if (project.active_publishers.includes(publisherId)) {
+        console.log(`🔐 ${pub.name} is already active in this install.`);
+        return;
+    }
+    project.active_publishers = [...project.active_publishers, publisherId];
+    project.last_synced_at = new Date().toISOString();
+    saveProjectConfig(roots, project);
+    console.log(`🔐 Activated ${pub.name} in this install.`);
+    console.log('   Syncing skills...');
+    await syncSkills(roots);
+    const result = await installSkillStubs(roots);
+    console.log(`   ✅ ${result.installed} skill${result.installed !== 1 ? 's' : ''} installed.\n`);
+    if (roots.scope === 'project') {
+        registerProject({
+            path: pathResolve(process.cwd()),
+            installed_at: project.installed_at,
+            last_synced_at: project.last_synced_at,
+            active_publishers: project.active_publishers,
+        });
+    }
+}
+async function handleRemovePublisherCommand(publisherId) {
+    if (!publisherId) {
+        console.error('Usage: npx skillvault remove-publisher <publisher_id>');
+        process.exit(1);
+    }
+    const roots = getActiveRoots();
+    const project = loadProjectConfig(roots);
+    if (!project) {
+        console.error('🔐 No SkillVault install detected at this location.');
+        process.exit(1);
+    }
+    if (!project.active_publishers.includes(publisherId)) {
+        console.log(`🔐 Publisher "${publisherId}" is not active in this install.`);
+        return;
+    }
+    // Remove from active list
+    project.active_publishers = project.active_publishers.filter(id => id !== publisherId);
+    saveProjectConfig(roots, project);
+    // Remove stubs whose manifest.publisher_id matches. Vault data is preserved
+    // in case the publisher is added back later.
+    const removed = removePublisherStubs(publisherId, roots);
+    const credentials = loadCredentials();
+    const pubName = credentials?.publishers.find(p => p.id === publisherId)?.name || publisherId;
+    console.log(`🔐 Deactivated ${pubName} in this install.`);
+    if (removed.length > 0) {
+        console.log(`   Removed ${removed.length} skill stub${removed.length !== 1 ? 's' : ''}:`);
+        for (const r of removed)
+            console.log(`     - ${r.skillName}`);
+    }
+    else {
+        console.log('   (no skill stubs to remove)');
+    }
+    console.log('');
+    if (roots.scope === 'project') {
+        registerProject({
+            path: pathResolve(process.cwd()),
+            installed_at: project.installed_at,
+            last_synced_at: project.last_synced_at || new Date().toISOString(),
+            active_publishers: project.active_publishers,
+        });
+    }
+}
+/**
+ * Strip skillvault hook entries from a settings.json file. Preserves every
+ * other key (plugins, effortLevel, user-defined hooks, …) so the customer's
+ * existing Claude Code configuration survives an uninstall.
+ *
+ * Returns the number of skillvault hook entries removed.
+ */
+function scrubSkillvaultHooks(settingsPath) {
+    if (!existsSync(settingsPath))
+        return 0;
+    let removed = 0;
+    try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        if (!settings.hooks)
+            return 0;
+        const eventKeys = [
+            'SessionStart', 'SessionEnd', 'UserPromptSubmit',
+            'PostToolUse', 'Stop', 'PostToolCall', 'PreToolCall',
+        ];
+        for (const key of eventKeys) {
+            if (!Array.isArray(settings.hooks[key]))
+                continue;
+            const before = settings.hooks[key].length;
+            settings.hooks[key] = settings.hooks[key].filter((h) => !hasSkillvaultCommand(h));
+            removed += before - settings.hooks[key].length;
+            if (settings.hooks[key].length === 0)
+                delete settings.hooks[key];
+        }
+        // If hooks is now empty, drop the key entirely.
+        if (Object.keys(settings.hooks).length === 0)
+            delete settings.hooks;
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+    }
+    catch { }
+    return removed;
+}
+/**
+ * Walk a single skills directory and remove every stub whose manifest.json
+ * has an `encrypted: true` flag or a `publisher_id` (the markers we set during
+ * install). Returns the list of removed skill names. Pre-existing skills from
+ * other tools (no manifest, or non-skillvault manifest) are left untouched.
+ */
+function removeStubsFromDir(skillsDir) {
+    if (!existsSync(skillsDir))
+        return [];
+    const removed = [];
+    for (const entry of readdirSync(skillsDir)) {
+        const stubDir = join(skillsDir, entry);
+        const manifestPath = join(stubDir, 'manifest.json');
+        if (!existsSync(manifestPath))
+            continue;
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            if (manifest.encrypted === true || manifest.publisher_id) {
+                rmSync(stubDir, { recursive: true, force: true });
+                removed.push(manifest.skill_name || entry);
+            }
+        }
+        catch { }
+    }
+    return removed;
+}
+/**
+ * Walk every directory where install would have written a stub and remove
+ * the SkillVault-managed ones. For project mode this is just
+ * <roots.claudeDir>/skills/. For global mode it also covers ~/.agents/skills/
+ * and the agent-agnostic platform mirrors (Cursor, Windsurf, Codex). Vault
+ * data in <roots.vaultDir> is left in place so a future --invite or
+ * migrate-to-project can reuse it.
+ */
+function removeAllSkillvaultStubs(roots) {
+    const all = [];
+    // Always: <roots.claudeDir>/skills/ (the install's primary stub location)
+    all.push(...removeStubsFromDir(join(roots.claudeDir, 'skills')));
+    // Global only: ~/.agents/skills/ + every detected platform mirror.
+    // installSkillStubs writes to all of these in global mode, so the global
+    // uninstall has to clean all of them up too.
+    if (roots.scope === 'global') {
+        all.push(...removeStubsFromDir(AGENTS_SKILLS_DIR));
+        for (const platform of detectAgentPlatforms()) {
+            all.push(...removeStubsFromDir(platform.dir));
+        }
+    }
+    // Dedupe — the same skill_name can appear in multiple mirrors.
+    return [...new Set(all)];
+}
+/**
+ * Remove SkillVault entries from a shared skill-lock.json file, preserving
+ * any entries that belong to other tools (e.g. skill-creator's
+ * sourceType=github wallet skills coexist with our sourceType=skillvault
+ * entries in ~/.agents/.skill-lock.json). If the file ends up with zero
+ * entries, the whole file is deleted.
+ */
+function pruneSkillvaultLockEntries(lockPath) {
+    if (!existsSync(lockPath))
+        return 0;
+    try {
+        const data = JSON.parse(readFileSync(lockPath, 'utf8'));
+        if (!data.skills || typeof data.skills !== 'object')
+            return 0;
+        let removed = 0;
+        for (const [name, entry] of Object.entries(data.skills)) {
+            if (entry && typeof entry === 'object' && (entry.sourceType === 'skillvault' || entry.encrypted === true)) {
+                delete data.skills[name];
+                removed++;
+            }
+        }
+        if (removed === 0)
+            return 0;
+        if (Object.keys(data.skills).length === 0) {
+            try {
+                rmSync(lockPath);
+            }
+            catch { }
+        }
+        else {
+            writeFileSync(lockPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Uninstall a single SkillVault install at the given roots.
+ *
+ * Removes:
+ *   - <roots.configDir>/ (vaults, project.json, skill-lock.json, fingerprints,
+ *     active-session.json, …) — but NOT credentials.json or projects.json,
+ *     which always live at the global ~/.skillvault/.
+ *   - skillvault hook entries from <roots.settingsPath>
+ *   - skill stubs from <roots.claudeDir>/skills/ that were installed by us
+ *   - the registry entry (project mode)
+ *
+ * Other settings.json keys, ~/.skillvault/credentials.json, and the projects
+ * registry are left intact.
+ */
+function uninstallInstall(roots) {
+    const summary = {
+        scope: roots.scope,
+        installPath: roots.scope === 'project' ? roots.configDir.replace(/\/\.skillvault$/, '') : HOME,
+        removedFiles: [],
+        removedHooks: 0,
+        removedStubs: [],
+    };
+    // Per-install configDir contents (vaults, project.json, …). For global
+    // mode, this is ~/.skillvault/ — we must NOT delete credentials.json or
+    // projects.json, so walk the entries instead of rm -rf.
+    if (existsSync(roots.configDir)) {
+        if (roots.scope === 'project') {
+            // Project install — safe to nuke the whole .skillvault directory.
+            try {
+                rmSync(roots.configDir, { recursive: true, force: true });
+                summary.removedFiles.push(roots.configDir);
+            }
+            catch { }
+        }
+        else {
+            // Global install — preserve customer identity + publisher CLI state.
+            // credentials.json + projects.json are the customer-side files we
+            // documented as always-preserved. config.json + grants-cache.json are
+            // owned by the publisher CLI (skillvault-publisher) — the customer-
+            // side uninstall has no business deleting publisher login state.
+            const PRESERVE = new Set([
+                'credentials.json',
+                'projects.json',
+                'config.json', // publisher CLI session
+                'grants-cache.json', // publisher CLI grant cache
+            ]);
+            for (const entry of readdirSync(roots.configDir)) {
+                if (PRESERVE.has(entry))
+                    continue;
+                const path = join(roots.configDir, entry);
+                try {
+                    rmSync(path, { recursive: true, force: true });
+                    summary.removedFiles.push(path);
+                }
+                catch { }
+            }
+        }
+    }
+    // Skill stubs in every location install would have written them: always
+    // <roots.claudeDir>/skills/, and (global mode) ~/.agents/skills/ + each
+    // detected platform mirror.
+    summary.removedStubs = removeAllSkillvaultStubs(roots);
+    // Prune SkillVault entries from the shared lock file. In global mode this
+    // is ~/.agents/.skill-lock.json which can also hold non-skillvault entries
+    // (e.g. from skill-creator), so we preserve other entries.
+    if (roots.scope === 'global') {
+        pruneSkillvaultLockEntries(AGENTS_LOCK_PATH);
+    }
+    // Hooks in settings.json
+    summary.removedHooks = scrubSkillvaultHooks(roots.settingsPath);
+    // Registry: drop the entry if this was a project install. Use the install
+    // path encoded in roots (not the literal CWD) so callers can uninstall a
+    // different project's install too.
+    if (roots.scope === 'project') {
+        const installPath = roots.configDir.replace(/\/\.skillvault$/, '');
+        try {
+            unregisterProject(installPath);
+        }
+        catch { }
+    }
+    return summary;
+}
+async function handleUninstallCommand() {
+    if (allFlag)
+        return handleUninstallAllCommand();
+    const roots = getActiveRoots();
+    // If we're not in any registered install, refuse rather than scribbling.
+    if (roots.scope === 'project' && !existsSync(roots.configDir)) {
+        console.error(`🔐 No SkillVault project install at ${process.cwd()}.`);
+        console.error('   (To uninstall global, run: npx skillvault uninstall --global)');
+        process.exit(1);
+    }
+    const summary = uninstallInstall(roots);
+    printUninstallSummary(summary);
+}
+async function handleUninstallAllCommand() {
+    console.log('🔐 SkillVault uninstall --all\n');
+    const summaries = [];
+    // Walk every registered project install
+    for (const entry of listProjects()) {
+        const roots = resolveRoots('project', entry.path);
+        console.log(`   Uninstalling project: ${entry.path}`);
+        summaries.push(uninstallInstall(roots));
+    }
+    // Also uninstall global, if there's anything to clean up.
+    const globalRoots = resolveRoots('global');
+    if (existsSync(globalRoots.configDir) || scrubSkillvaultHooks(globalRoots.settingsPath) > 0) {
+        console.log('   Uninstalling global install: ~/.claude, ~/.skillvault');
+        summaries.push(uninstallInstall(globalRoots));
+    }
+    // Finally remove the global credentials and the projects registry.
+    // The customer is fully resetting; their identity comes back from a
+    // fresh --invite next time.
+    const credPath = join(HOME, '.skillvault', 'credentials.json');
+    const regPath = join(HOME, '.skillvault', 'projects.json');
+    for (const p of [credPath, regPath]) {
+        try {
+            if (existsSync(p)) {
+                rmSync(p);
+                console.log(`   Removed ${p}`);
+            }
+        }
+        catch { }
+    }
+    // Drop the now-empty ~/.skillvault dir if it's actually empty.
+    try {
+        const dir = join(HOME, '.skillvault');
+        if (existsSync(dir) && readdirSync(dir).length === 0)
+            rmSync(dir, { recursive: true, force: true });
+    }
+    catch { }
+    console.log('');
+    console.log(`Uninstalled ${summaries.length} install${summaries.length !== 1 ? 's' : ''}.`);
+}
+function printUninstallSummary(s) {
+    console.log(`🔐 Uninstalled SkillVault (${s.scope}) at ${s.installPath}`);
+    if (s.removedHooks > 0)
+        console.log(`   ✅ Removed ${s.removedHooks} hook entr${s.removedHooks !== 1 ? 'ies' : 'y'} from settings.json`);
+    if (s.removedStubs.length > 0) {
+        console.log(`   ✅ Removed ${s.removedStubs.length} skill stub${s.removedStubs.length !== 1 ? 's' : ''}:`);
+        for (const name of s.removedStubs)
+            console.log(`     - ${name}`);
+    }
+    if (s.removedFiles.length > 0)
+        console.log(`   ✅ Removed ${s.removedFiles.length} file${s.removedFiles.length !== 1 ? 's' : ''}/dir${s.removedFiles.length !== 1 ? 's' : ''}`);
+    if (s.scope === 'global') {
+        console.log('   ℹ️  ~/.skillvault/credentials.json and projects.json were preserved.');
+        console.log('   ℹ️  Run `uninstall --all` to wipe those too.');
+    }
+    console.log('');
+}
+/**
+ * `npx skillvault status` — extended version of --status with hook health
+ * and an explicit scope/location header.
+ */
+async function handleStatusSubcommand() {
+    const roots = getActiveRoots();
+    const credentials = loadCredentials();
+    if (!credentials) {
+        console.log('🔐 SkillVault — not configured.');
+        console.log('');
+        console.log('   To get started, run:');
+        console.log('   npx skillvault --invite YOUR_INVITE_CODE');
+        return;
+    }
+    const project = loadProjectConfig(roots);
+    const registryEntry = roots.scope === 'project' ? getCurrentProject() : null;
+    console.log('🔐 SkillVault Status\n');
+    console.log(`   Account:       ${credentials.customer_email || '(unknown)'}`);
+    console.log(`   Scope:         ${roots.scope}`);
+    console.log(`   Install path:  ${roots.scope === 'project' ? process.cwd() : HOME}`);
+    console.log(`   Config dir:    ${roots.configDir}`);
+    console.log(`   Settings:      ${roots.settingsPath}`);
+    console.log(`   Server:        ${credentials.api_url}`);
+    if (registryEntry?.last_synced_at) {
+        console.log(`   Last sync:     ${registryEntry.last_synced_at}`);
+    }
+    else if (project?.last_synced_at) {
+        console.log(`   Last sync:     ${project.last_synced_at}`);
+    }
+    console.log('');
+    // Hook health
+    let hookHealth = 'no settings.json';
+    if (existsSync(roots.settingsPath)) {
+        try {
+            const settings = JSON.parse(readFileSync(roots.settingsPath, 'utf8'));
+            const hooks = settings.hooks || {};
+            const skillvaultEvents = Object.entries(hooks)
+                .filter(([_, entries]) => Array.isArray(entries) && entries.some(hasSkillvaultCommand))
+                .map(([k]) => k);
+            hookHealth = skillvaultEvents.length > 0
+                ? `${skillvaultEvents.join(', ')}`
+                : 'no skillvault hooks installed';
+        }
+        catch {
+            hookHealth = 'invalid (could not parse)';
+        }
+    }
+    console.log(`   Hook health:   ${hookHealth}`);
+    console.log('');
+    // Active publishers
+    const activeIds = project?.active_publishers ?? credentials.publishers.map(p => p.id);
+    console.log(`   Active publishers (${activeIds.length} of ${credentials.publishers.length}):`);
+    for (const pub of credentials.publishers) {
+        const tag = activeIds.includes(pub.id) ? '✓' : ' ';
+        console.log(`     ${tag} ${pub.id.padEnd(20)} ${pub.name}`);
+    }
+    console.log('');
+}
+/**
+ * Move a global install into the current project. Confirmation is required
+ * before any destructive moves. Vault data, project.json, hooks, and skill
+ * stubs are migrated; credentials and the registry are not touched (they're
+ * already global).
+ */
+async function handleMigrateToProjectCommand() {
+    const globalRoots = resolveRoots('global');
+    const projectRoots = resolveRoots('project', process.cwd());
+    if (!existsSync(globalRoots.configDir) && !existsSync(globalRoots.settingsPath)) {
+        console.error('🔐 No global install detected. Nothing to migrate.');
+        return;
+    }
+    if (existsSync(projectRoots.configDir) && existsSync(join(projectRoots.configDir, 'project.json'))) {
+        console.error(`🔐 Project install already exists at ${process.cwd()}.`);
+        console.error('   Refusing to overwrite. Run `npx skillvault uninstall` first if you want to start fresh.');
+        process.exit(1);
+    }
+    console.log('🔐 SkillVault migrate-to-project');
+    console.log('');
+    console.log(`   Source: ${globalRoots.configDir}`);
+    console.log(`           ${globalRoots.settingsPath}`);
+    console.log(`   Target: ${projectRoots.configDir}`);
+    console.log(`           ${projectRoots.settingsPath}`);
+    console.log('');
+    if (!process.stdin.isTTY) {
+        console.log('   (non-TTY: auto-confirming)');
+    }
+    else {
+        process.stderr.write('Continue? [y/N]: ');
+        const key = await new Promise((resolve) => {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding('utf8');
+            process.stdin.once('data', (k) => {
+                process.stdin.setRawMode(false);
+                process.stdin.pause();
+                resolve(k);
+            });
+        });
+        console.error('');
+        if (key !== 'y' && key !== 'Y') {
+            console.log('Cancelled.');
+            return;
+        }
+    }
+    // Move <globalConfigDir>/{vaults,active-session.json,fingerprints} → projectConfigDir
+    mkdirSync(projectRoots.configDir, { recursive: true });
+    const moveItems = ['vaults', 'active-session.json', 'fingerprints', 'skill-lock.json'];
+    for (const item of moveItems) {
+        const src = join(globalRoots.configDir, item);
+        const dst = join(projectRoots.configDir, item);
+        if (!existsSync(src))
+            continue;
+        try {
+            // Cross-device-safe: try rename, fall back to copy + remove.
+            cpSync(src, dst, { recursive: true });
+            rmSync(src, { recursive: true, force: true });
+            console.log(`   Moved: ${src} → ${dst}`);
+        }
+        catch (err) {
+            console.error(`   ⚠️  Could not move ${item}: ${err instanceof Error ? err.message : 'unknown'}`);
+        }
+    }
+    // Move skill stubs from ~/.claude/skills/ to ./.claude/skills/
+    const globalStubs = join(globalRoots.claudeDir, 'skills');
+    const projectStubs = join(projectRoots.claudeDir, 'skills');
+    mkdirSync(projectStubs, { recursive: true });
+    if (existsSync(globalStubs)) {
+        for (const entry of readdirSync(globalStubs)) {
+            const src = join(globalStubs, entry);
+            const manifestPath = join(src, 'manifest.json');
+            if (!existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                if (manifest.encrypted === true || manifest.publisher_id) {
+                    const dst = join(projectStubs, entry);
+                    cpSync(src, dst, { recursive: true });
+                    rmSync(src, { recursive: true, force: true });
+                    console.log(`   Moved stub: ${entry}`);
+                }
+            }
+            catch { }
+        }
+    }
+    // Build project.json reflecting the migrated install. The active list is
+    // every publisher in credentials (since global mode had them all active).
+    const credentials = loadCredentials();
+    const newProject = {
+        active_publishers: credentials?.publishers.map(p => p.id) ?? [],
+        installed_at: new Date().toISOString(),
+        scope: 'project',
+        install_path: pathResolve(process.cwd()),
+        last_synced_at: new Date().toISOString(),
+    };
+    saveProjectConfig(projectRoots, newProject);
+    // Reinstall hooks into the project settings.json (with current version).
+    configureSessionHook(projectRoots);
+    // Strip the old global hooks now that the project has them.
+    scrubSkillvaultHooks(globalRoots.settingsPath);
+    // Register the new project install.
+    registerProject({
+        path: pathResolve(process.cwd()),
+        installed_at: newProject.installed_at,
+        last_synced_at: newProject.last_synced_at,
+        active_publishers: newProject.active_publishers,
+    });
+    console.log('');
+    console.log('   ✅ Migration complete. Restart Claude Code to pick up the new hooks.');
+    console.log('');
+}
 // ── Vault Decryption (in-memory only, output to stdout) ──
 const VAULT_MAGIC = Buffer.from([0x00, 0x53, 0x56, 0x54]);
 /** Detect binary content by checking for null bytes or high ratio of non-printable chars */
@@ -875,16 +1703,30 @@ function decryptVault(data, cek) {
     });
     return { metadata, files };
 }
-function resolveSkillPublisher(skillName, config) {
+function resolveSkillPublisher(skillName, config, roots = getActiveRoots()) {
     for (const pub of config.publishers) {
-        const vaultPath = join(VAULT_DIR, pub.id, `${skillName}.vault`);
+        const vaultPath = join(roots.vaultDir, pub.id, `${skillName}.vault`);
         if (existsSync(vaultPath))
             return { publisher: pub, vaultPath };
     }
-    const legacyPath = join(VAULT_DIR, `${skillName}.vault`);
+    // Legacy fallback: vaults that landed at <vaultDir>/<skill>.vault before the
+    // per-publisher subdirectory layout existed.
+    const legacyPath = join(roots.vaultDir, `${skillName}.vault`);
     if (existsSync(legacyPath) && config.publishers.length > 0) {
         return { publisher: config.publishers[0], vaultPath: legacyPath };
     }
+    // Cross-scope fallback: a customer running --load from CWD that's not the
+    // install directory should still be able to find a vault from any known
+    // install. Try the global roots if we're currently looking at a project,
+    // and try every registered project if currently global.
+    if (roots.scope === 'project') {
+        const globalRoots = resolveRoots('global');
+        for (const pub of config.publishers) {
+            const vaultPath = join(globalRoots.vaultDir, pub.id, `${skillName}.vault`);
+            if (existsSync(vaultPath))
+                return { publisher: pub, vaultPath };
+        }
+    }
     return null;
 }
 async function fetchCEK(skillName, publisherToken, apiUrl) {
@@ -1156,7 +1998,7 @@ function validateSkillName(name) {
  * Quick sync for a single skill — checks for vault update before decrypting.
  * Returns true if the vault was updated. Status goes to stderr.
  */
-async function syncSingleSkill(skillName, pub, config) {
+async function syncSingleSkill(skillName, pub, config, roots = getActiveRoots()) {
     try {
         const capabilityName = `skill/${skillName.toLowerCase()}`;
         const res = await fetch(`${config.api_url}/skills/check-update?capability=${encodeURIComponent(capabilityName)}&current_version=0.0.0`, { signal: AbortSignal.timeout(5000) });
@@ -1164,7 +2006,7 @@ async function syncSingleSkill(skillName, pub, config) {
             return false;
         const data = await res.json();
         // Check if local vault hash matches
-        const vaultPath = join(VAULT_DIR, pub.id, `${skillName}.vault`);
+        const vaultPath = join(roots.vaultDir, pub.id, `${skillName}.vault`);
         const hashPath = vaultPath + '.hash';
         if (existsSync(hashPath) && data.vault_hash) {
             const localHash = readFileSync(hashPath, 'utf8').trim();
@@ -1177,7 +2019,7 @@ async function syncSingleSkill(skillName, pub, config) {
             return false;
         const dlData = await dlRes.json();
         const vaultBuffer = Buffer.from(dlData.vault_data, 'base64');
-        mkdirSync(join(VAULT_DIR, pub.id), { recursive: true });
+        mkdirSync(join(roots.vaultDir, pub.id), { recursive: true });
         writeFileSync(vaultPath, vaultBuffer, { mode: 0o600 });
         if (dlData.vault_hash)
             writeFileSync(hashPath, dlData.vault_hash, { mode: 0o600 });
@@ -1201,10 +2043,10 @@ async function syncSingleSkill(skillName, pub, config) {
  * Discovers new skills the customer has been granted since last sync.
  * Runs async — doesn't block the load operation.
  */
-async function backgroundSyncAll(config) {
+async function backgroundSyncAll(_config, roots = getActiveRoots()) {
     try {
-        await syncSkills();
-        await installSkillStubs();
+        await syncSkills(roots);
+        await installSkillStubs(roots);
     }
     catch { } // non-fatal
 }
@@ -1216,14 +2058,15 @@ async function listSkillFiles(skillName) {
         console.error('Error: Invalid skill name.');
         process.exit(1);
     }
-    const config = loadConfig();
+    const roots = getActiveRoots();
+    const config = loadConfig(roots);
     if (!config) {
         console.error('Error: SkillVault is not configured. Run: npx skillvault --invite YOUR_CODE');
         process.exit(1);
     }
-    // Try local manifest cache first
-    const agentSkillDir = join(AGENTS_SKILLS_DIR, skillName);
-    const filesJsonPath = join(agentSkillDir, 'files.json');
+    // Try local manifest cache first — look in this install's claude skills dir
+    const installStubDir = join(roots.claudeDir, 'skills', skillName);
+    const filesJsonPath = join(installStubDir, 'files.json');
     try {
         if (existsSync(filesJsonPath)) {
             const filesData = JSON.parse(readFileSync(filesJsonPath, 'utf8'));
@@ -1274,30 +2117,32 @@ async function loadSkill(skillName) {
         console.error('Example: npx skillvault --load my-skill-name');
         process.exit(1);
     }
-    const config = loadConfig();
+    const roots = getActiveRoots();
+    const config = loadConfig(roots);
     if (!config) {
         console.error('Error: SkillVault is not configured on this machine.');
         console.error('');
         console.error('To set up, you need an invite code from a skill publisher.');
         console.error('Run: npx skillvault --invite YOUR_INVITE_CODE');
         console.error('');
-        console.error('If you already set up SkillVault, the config file may be missing:');
-        console.error(`  Expected: ${CONFIG_PATH}`);
+        console.error('If you already set up SkillVault, the config files may be missing:');
+        console.error(`  Expected: ${join(roots.configDir, 'project.json')}`);
+        console.error(`            ~/.skillvault/credentials.json`);
         process.exit(1);
     }
     // Pre-load sync: ensure we have the latest vault for this skill
-    let resolved = resolveSkillPublisher(skillName, config);
+    let resolved = resolveSkillPublisher(skillName, config, roots);
     if (resolved) {
-        await syncSingleSkill(skillName, resolved.publisher, config);
+        await syncSingleSkill(skillName, resolved.publisher, config, roots);
         // Re-resolve in case the vault was just downloaded
-        resolved = resolveSkillPublisher(skillName, config);
+        resolved = resolveSkillPublisher(skillName, config, roots);
     }
     else {
         // Skill not found locally — try a full sync first (may be a newly granted skill)
         console.error(`[sync] Skill "${skillName}" not found locally, syncing...`);
-        await syncSkills();
-        await installSkillStubs();
-        resolved = resolveSkillPublisher(skillName, config);
+        await syncSkills(roots);
+        await installSkillStubs(roots);
+        resolved = resolveSkillPublisher(skillName, config, roots);
     }
     if (!resolved) {
         console.error(`Error: Skill "${skillName}" not found after syncing with server.`);
@@ -1308,10 +2153,10 @@ async function loadSkill(skillName) {
         console.error('  3. Your token expired — refresh with: npx skillvault --refresh');
         console.error('');
         console.error('Available skills on this machine:');
-        const localConfig = loadConfig();
+        const localConfig = loadConfig(roots);
         if (localConfig) {
             for (const pub of localConfig.publishers) {
-                const pubVaultDir = join(VAULT_DIR, pub.id);
+                const pubVaultDir = join(roots.vaultDir, pub.id);
                 try {
                     if (existsSync(pubVaultDir)) {
                         const vaults = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault'));
@@ -1327,7 +2172,7 @@ async function loadSkill(skillName) {
         process.exit(1);
     }
     // Kick off background sync for all other skills (non-blocking)
-    backgroundSyncAll(config).catch(() => { });
+    backgroundSyncAll(config, roots).catch(() => { });
     // Fetch CEK — validates license on every load
     let cek;
     let licenseeId;
@@ -1451,7 +2296,7 @@ async function loadSkill(skillName) {
             }
         }
         // After successful decryption and output, inject session-scoped monitoring hooks
-        injectMonitoringHooks(skillName);
+        injectMonitoringHooks(skillName, roots);
     }
     catch (err) {
         cek.fill(0);
@@ -1496,32 +2341,85 @@ async function reportSecurityEvent(eventType, skill, detail) {
     }
 }
 // ── Session-scoped hook handlers ──
-const ACTIVE_SESSION_PATH = join(CONFIG_DIR, 'active-session.json');
-const FINGERPRINT_DIR = join(CONFIG_DIR, 'fingerprints');
 const SESSION_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 /**
- * Load active session. Returns null if missing or expired.
+ * Search for an active session at the active roots, then at every registered
+ * project, then at the global location. Returns the first match (or null).
+ *
+ * Project-scope sessions guard themselves: if the install_path doesn't match
+ * Claude Code's CWD, the session is treated as not-applicable for this hook
+ * invocation (returned as null) so the hook exits silently.
  */
-function loadActiveSession() {
+function findActiveSessionForCwd(cwd = process.cwd()) {
+    const candidates = [];
+    // Active roots (resolved from current CWD)
+    const active = getActiveRoots();
+    candidates.push(active);
+    // All registered projects
     try {
-        if (!existsSync(ACTIVE_SESSION_PATH))
-            return null;
-        const session = JSON.parse(readFileSync(ACTIVE_SESSION_PATH, 'utf8'));
-        if (!session.skill || !session.expires_at)
-            return null;
-        if (new Date(session.expires_at).getTime() < Date.now()) {
-            try {
-                rmSync(ACTIVE_SESSION_PATH);
+        const reg = listProjectsRegistry();
+        for (const p of reg) {
+            candidates.push(resolveRoots('project', p.path));
+        }
+    }
+    catch { }
+    // Global location as a final fallback
+    candidates.push(resolveRoots('global'));
+    const seen = new Set();
+    for (const roots of candidates) {
+        const path = join(roots.configDir, 'active-session.json');
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        if (!existsSync(path))
+            continue;
+        try {
+            const session = JSON.parse(readFileSync(path, 'utf8'));
+            if (!session.skill || !session.expires_at)
+                continue;
+            if (new Date(session.expires_at).getTime() < Date.now()) {
+                try {
+                    rmSync(path);
+                }
+                catch { }
+                continue;
             }
-            catch { }
-            return null;
+            // Project-scope guard: only honor sessions that belong to this CWD's
+            // install. A session in /tmp/proj-a should not fire when Claude Code
+            // happens to be running in /tmp/proj-b.
+            if (session.scope === 'project' && session.install_path) {
+                if (pathResolve(session.install_path) !== pathResolve(cwd))
+                    continue;
+            }
+            return { data: session, path, roots };
+        }
+        catch {
+            // Malformed session file — skip
         }
-        return session;
+    }
+    return null;
+}
+/** Re-export of projects-registry.listProjects so the helper above can read it. */
+function listProjectsRegistry() {
+    // Lazy import-style read so this module compiles even when projects-registry
+    // is not yet built. Falls back to an empty array on any error.
+    try {
+        return listProjects();
     }
     catch {
-        return null;
+        return [];
     }
 }
+/**
+ * Load active session in a backwards-compatible way.
+ *
+ * Returns the session data if a valid session exists for the current CWD.
+ * Returns null if no valid session is found, the session has expired, or
+ * the session belongs to a different project install.
+ */
+function loadActiveSession() {
+    return findActiveSessionForCwd()?.data ?? null;
+}
 /**
  * Extraction-intent keyword patterns for prompt-submit detection.
  */
@@ -1582,17 +2480,19 @@ function extractKeywords(text, max = 30) {
     return [...freq.entries()].sort((a, b) => b[1] - a[1]).slice(0, max).map(([w]) => w);
 }
 /**
- * Load fingerprint files from cache.
+ * Load fingerprint files from cache. Looks under the active install's
+ * configDir/fingerprints/ directory.
  */
-function loadFingerprintCache() {
+function loadFingerprintCache(roots = getActiveRoots()) {
+    const fingerprintDir = join(roots.configDir, 'fingerprints');
     try {
-        if (!existsSync(FINGERPRINT_DIR))
+        if (!existsSync(fingerprintDir))
             return [];
-        const files = readdirSync(FINGERPRINT_DIR).filter(f => f.endsWith('.json'));
+        const files = readdirSync(fingerprintDir).filter(f => f.endsWith('.json'));
         const fps = [];
         for (const file of files) {
             try {
-                const data = JSON.parse(readFileSync(join(FINGERPRINT_DIR, file), 'utf8'));
+                const data = JSON.parse(readFileSync(join(fingerprintDir, file), 'utf8'));
                 // Handle both encrypted and unencrypted formats
                 if (data.capability && data.ngrams) {
                     fps.push(data);
@@ -1729,11 +2629,23 @@ async function handleSessionKeepalive(evtType) {
 }
 /**
  * Session cleanup handler.
- * Removes monitoring hooks from settings.json, deletes session + fingerprint cache.
+ *
+ * Locates the active session for Claude Code's CWD via findActiveSessionForCwd,
+ * then removes monitoring hooks from THAT install's settings.json (not always
+ * ~/.claude/settings.json — that was the bug in v0.9.x). Also deletes the
+ * session marker and fingerprint cache for that install.
+ *
+ * If no session is found (e.g. session expired between load and cleanup, or
+ * the user moved between projects), falls back to global ~/.claude so we
+ * still scrub any leftover hooks from old global installs.
  */
 function handleSessionCleanup() {
     try {
-        const settingsPath = join(HOME, '.claude', 'settings.json');
+        const located = findActiveSessionForCwd();
+        const settingsPath = located?.data.settings_path
+            || located?.roots.settingsPath
+            || join(HOME, '.claude', 'settings.json');
+        const cleanupRoots = located?.roots ?? resolveRoots('global');
         if (existsSync(settingsPath)) {
             const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
             if (settings.hooks) {
@@ -1765,19 +2677,22 @@ function handleSessionCleanup() {
                 }
             }
         }
-        // Delete active session
-        try {
-            if (existsSync(ACTIVE_SESSION_PATH))
-                rmSync(ACTIVE_SESSION_PATH);
+        // Delete the active session marker we located (if any).
+        if (located?.path) {
+            try {
+                if (existsSync(located.path))
+                    rmSync(located.path);
+            }
+            catch { }
         }
-        catch { }
-        // Delete fingerprint cache
+        // Delete fingerprint cache for this install.
+        const fingerprintDir = join(cleanupRoots.configDir, 'fingerprints');
         try {
-            if (existsSync(FINGERPRINT_DIR)) {
-                const files = readdirSync(FINGERPRINT_DIR);
+            if (existsSync(fingerprintDir)) {
+                const files = readdirSync(fingerprintDir);
                 for (const file of files) {
                     try {
-                        rmSync(join(FINGERPRINT_DIR, file));
+                        rmSync(join(fingerprintDir, file));
                     }
                     catch { }
                 }
@@ -1791,6 +2706,30 @@ function handleSessionCleanup() {
 }
 // ── Main ──
 async function main() {
+    // Resolve active install roots from flags + CWD before dispatching commands.
+    // Commands that don't pass roots explicitly will fall through to currentRoots.
+    setActiveRoots(resolveActiveRoots({ global: globalFlag, project: projectFlag }));
+    // Positional subcommands for management operations.
+    switch (subcommand) {
+        case 'publishers':
+            await handlePublishersCommand();
+            process.exit(0);
+        case 'add-publisher':
+            await handleAddPublisherCommand(subcommandArgs[0]);
+            process.exit(0);
+        case 'remove-publisher':
+            await handleRemovePublisherCommand(subcommandArgs[0]);
+            process.exit(0);
+        case 'uninstall':
+            await handleUninstallCommand();
+            process.exit(0);
+        case 'status':
+            await handleStatusSubcommand();
+            process.exit(0);
+        case 'migrate-to-project':
+            await handleMigrateToProjectCommand();
+            process.exit(0);
+    }
     // --session-keepalive: unified session-scoped hook handler
     if (sessionKeepaliveFlag) {
         await handleSessionKeepalive(eventType);
@@ -1827,7 +2766,32 @@ async function main() {
         process.exit(0);
     }
     if (inviteCode) {
-        await setup(inviteCode);
+        // For --invite, scope is decided by explicit flags first, then CWD heuristics.
+        // We do NOT use the existing-install detection here — `--invite` is the
+        // moment the customer is choosing where to install.
+        let inviteRoots = resolveRoots(resolveScope({ global: globalFlag, project: projectFlag, cwd: process.cwd() }), process.cwd());
+        if (dryRunFlag) {
+            setActiveRoots(inviteRoots);
+            printDryRunPlan(inviteRoots);
+            process.exit(0);
+        }
+        // Interactive confirmation. In a TTY, the customer sees the planned
+        // writes and can press Y/n/g. In a non-TTY (CI, audit harness, scripts)
+        // confirmInstall short-circuits to 'yes'. If --global or --project was
+        // explicitly passed we trust the customer and skip the prompt.
+        if (!globalFlag && !projectFlag) {
+            const choice = await confirmInstall(inviteRoots.scope, inviteRoots);
+            if (choice === 'no') {
+                console.error('Cancelled. No files written.');
+                process.exit(0);
+            }
+            if (choice === 'global' && inviteRoots.scope === 'project') {
+                inviteRoots = resolveRoots('global');
+                console.error('Switched to global install.');
+            }
+        }
+        setActiveRoots(inviteRoots);
+        await setup(inviteCode, inviteRoots);
         if (!statusFlag && !refreshFlag)
             process.exit(0);
     }
@@ -1836,26 +2800,38 @@ async function main() {
         process.exit(0);
     }
     if (refreshFlag) {
-        await refreshTokens();
+        const roots = getActiveRoots();
+        await refreshTokens(roots);
         console.error('   Syncing skills...\n');
-        await syncSkills();
-        const result = await installSkillStubs();
+        await syncSkills(roots);
+        const result = await installSkillStubs(roots);
         if (result.installed > 0)
             console.error(`   ✅ ${result.installed} skill${result.installed !== 1 ? 's' : ''} updated`);
         console.error('');
         process.exit(0);
     }
     if (syncFlag) {
-        const config = loadConfig();
+        const roots = getActiveRoots();
+        const config = loadConfig(roots);
         if (!config) {
             console.error('🔐 Not set up. Run: npx skillvault --invite YOUR_CODE\n');
             process.exit(1);
         }
-        console.error('🔐 SkillVault Sync\n');
+        console.error(`🔐 SkillVault Sync (${roots.scope})\n`);
         // Re-install hooks with current version (auto-upgrades pinned commands)
-        configureSessionHook();
-        await syncSkills();
-        const result = await installSkillStubs();
+        configureSessionHook(roots);
+        await syncSkills(roots);
+        const result = await installSkillStubs(roots);
+        // Update the registry's last_synced_at if this is a project install.
+        if (roots.scope === 'project') {
+            const proj = loadProjectConfig(roots);
+            registerProject({
+                path: pathResolve(process.cwd()),
+                installed_at: proj?.installed_at || new Date().toISOString(),
+                last_synced_at: new Date().toISOString(),
+                active_publishers: proj?.active_publishers || config.publishers.map(p => p.id),
+            });
+        }
         console.error(`\n   ✅ ${result.installed} installed, ${result.skipped} up to date\n`);
         process.exit(0);
     }
@@ -1877,6 +2853,27 @@ async function main() {
         console.log('   Learn more: https://app.getskillvault.com\n');
     }
 }
+/**
+ * Print the planned writes for an invite without performing them. Used by
+ * --dry-run for scripts and the audit suite to verify scope detection.
+ */
+function printDryRunPlan(roots) {
+    console.error('🔐 SkillVault Setup (DRY RUN — no files will be written)');
+    console.error('');
+    console.error(`Scope:      ${roots.scope}`);
+    console.error(`Location:   ${roots.scope === 'project' ? process.cwd() : HOME}`);
+    console.error('');
+    console.error('Would write:');
+    console.error(`  ${roots.settingsPath}              (Claude Code hooks)`);
+    console.error(`  ${join(roots.claudeDir, 'skills')}/<skill>/        (skill stubs)`);
+    console.error(`  ${join(roots.configDir, 'project.json')}           (project config)`);
+    console.error(`  ${roots.vaultDir}/<publisher_id>/            (encrypted vaults)`);
+    console.error('');
+    console.error('Plus user-level (always global):');
+    console.error(`  ~/.skillvault/credentials.json                     (customer identity)`);
+    console.error(`  ~/.skillvault/projects.json                        (project install registry)`);
+    console.error('');
+}
 main().catch((err) => {
     console.error('Fatal:', err);
     process.exit(1);