skillvault 0.3.0 → 0.4.0

package/dist/cli.d.ts

@@ -6,13 +6,16 @@
  *   npx skillvault --invite CODE          # Setup / add publisher
  *   npx skillvault --status               # Show publishers & skills
  *   npx skillvault --refresh              # Re-authenticate tokens + sync
- *   npx skillvault --sync                 # Sync & install skills
- *   npx skillvault                        # Same as --sync
+ *   npx skillvault --sync                 # Sync vaults + install stubs
+ *   npx skillvault                        # Start MCP server (after setup)
  *
- * What it does:
- *   1. Redeems invite code (if provided) — additive across publishers
- *   2. Downloads encrypted skill vaults from the server
- *   3. Decrypts and installs skills as native Claude Code skills (~/.claude/skills/)
- *   4. Claude Code discovers and uses them directly — no MCP intermediary
+ * How it works:
+ *   1. Redeems invite code → gets publisher token
+ *   2. Downloads encrypted skill vaults to ~/.skillvault/vaults/
+ *   3. Installs stub SKILL.md files in ~/.claude/skills/ (Claude discovers these)
+ *   4. Starts MCP server exposing skillvault_load tool
+ *   5. When Claude triggers a skill, it calls skillvault_load → decrypts on demand
+ *   6. Decrypted content lives only in conversation context — never on disk
+ *   7. License is validated on every load — revoked license = dead skill
  */
 export {};

package/dist/cli.js

@@ -6,21 +6,26 @@
  *   npx skillvault --invite CODE          # Setup / add publisher
  *   npx skillvault --status               # Show publishers & skills
  *   npx skillvault --refresh              # Re-authenticate tokens + sync
- *   npx skillvault --sync                 # Sync & install skills
- *   npx skillvault                        # Same as --sync
+ *   npx skillvault --sync                 # Sync vaults + install stubs
+ *   npx skillvault                        # Start MCP server (after setup)
  *
- * What it does:
- *   1. Redeems invite code (if provided) — additive across publishers
- *   2. Downloads encrypted skill vaults from the server
- *   3. Decrypts and installs skills as native Claude Code skills (~/.claude/skills/)
- *   4. Claude Code discovers and uses them directly — no MCP intermediary
+ * How it works:
+ *   1. Redeems invite code → gets publisher token
+ *   2. Downloads encrypted skill vaults to ~/.skillvault/vaults/
+ *   3. Installs stub SKILL.md files in ~/.claude/skills/ (Claude discovers these)
+ *   4. Starts MCP server exposing skillvault_load tool
+ *   5. When Claude triggers a skill, it calls skillvault_load → decrypts on demand
+ *   6. Decrypted content lives only in conversation context — never on disk
+ *   7. License is validated on every load — revoked license = dead skill
  */
+import { createServer } from 'node:http';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { createDecipheriv, createPublicKey, diffieHellman, hkdfSync, generateKeyPairSync, } from 'node:crypto';
-const VERSION = '0.3.0';
+const VERSION = '0.4.0';
 const HOME = process.env.HOME || process.env.USERPROFILE || '~';
 const API_URL = process.env.SKILLVAULT_API_URL || 'https://api.getskillvault.com';
+const MCP_PORT = parseInt(process.env.SKILLVAULT_MCP_PORT || '9877', 10);
 const CONFIG_DIR = join(HOME, '.skillvault');
 const CONFIG_PATH = join(CONFIG_DIR, 'agent-config.json');
 const VAULT_DIR = join(CONFIG_DIR, 'vaults');
@@ -46,13 +51,18 @@ if (helpFlag) {
     npx skillvault --invite CODE    Setup or add a new publisher
     npx skillvault --status         Show all publishers, skills, and statuses
     npx skillvault --refresh        Re-authenticate expired tokens + sync skills
-    npx skillvault --sync           Sync and install skills from all publishers
-    npx skillvault                  Same as --sync
+    npx skillvault --sync           Sync vaults and install skill stubs
+    npx skillvault                  Start MCP server (default, after setup)
     npx skillvault --help           Show this help
     npx skillvault --version        Show version
 
+  Skills are encrypted at rest. When Claude Code triggers a skill, the
+  MCP server decrypts it on demand and returns the content to Claude's
+  session. The decrypted content is never written to disk.
+
   Environment:
     SKILLVAULT_API_URL     Server URL (default: https://api.getskillvault.com)
+    SKILLVAULT_MCP_PORT    MCP server port (default: 9877)
   `);
     process.exit(0);
 }
@@ -60,7 +70,6 @@ function loadConfig() {
     try {
         if (existsSync(CONFIG_PATH)) {
             const raw = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
-            // Migrate legacy single-publisher config
             if (raw.token && !raw.publishers) {
                 const migrated = {
                     customer_token: raw.token,
@@ -87,11 +96,10 @@ function saveConfig(config) {
     mkdirSync(CONFIG_DIR, { recursive: true });
     writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
 }
-// ── Setup: Redeem Invite + Sync Skills ──
+// ── Setup: Redeem Invite + Configure MCP + Sync ──
 async function setup(code) {
     console.log('🔐 SkillVault Setup');
     console.log(`   Redeeming invite code: ${code}`);
-    // Redeem invite code for a token
     const response = await fetch(`${API_URL}/auth/companion/token`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -117,7 +125,6 @@ async function setup(code) {
         added_at: new Date().toISOString(),
     };
     if (existingConfig) {
-        // Additive: merge new publisher into existing config
         const existingIdx = existingConfig.publishers.findIndex(p => p.id === data.publisher_id);
         if (existingIdx >= 0) {
             existingConfig.publishers[existingIdx] = publisherEntry;
@@ -127,56 +134,60 @@ async function setup(code) {
             existingConfig.publishers.push(publisherEntry);
             console.log(`   ➕ Added publisher: ${publisherEntry.name}. You now have skills from ${existingConfig.publishers.length} publishers.`);
         }
-        if (data.customer_token) {
+        if (data.customer_token)
             existingConfig.customer_token = data.customer_token;
-        }
-        if (data.email) {
+        if (data.email)
             existingConfig.customer_email = data.email;
-        }
         saveConfig(existingConfig);
     }
     else {
-        const config = {
+        saveConfig({
             customer_token: data.customer_token || data.token,
             customer_email: data.email,
             publishers: [publisherEntry],
             api_url: API_URL,
             setup_at: new Date().toISOString(),
-        };
-        saveConfig(config);
+        });
     }
-    // Create publisher-scoped vault cache directory
     mkdirSync(join(VAULT_DIR, data.publisher_id), { recursive: true });
-    // Clean up legacy MCP config if present
-    cleanupMCPConfig();
-    // Sync and install skills immediately
+    // Configure MCP server in Claude Code
+    configureMCP();
+    // Sync vaults and install stubs
     console.log('');
     console.log('   Syncing skills...');
-    const syncResult = await syncSkills();
-    const installResult = await installDecryptedSkills();
+    await syncSkills();
+    const installResult = await installSkillStubs();
     console.log('');
     if (installResult.installed > 0) {
-        console.log(`   ✅ ${installResult.installed} skill${installResult.installed !== 1 ? 's' : ''} installed to ~/.claude/skills/`);
+        console.log(`   ✅ ${installResult.installed} skill${installResult.installed !== 1 ? 's' : ''} ready`);
     }
-    console.log('   Setup complete! Restart Claude Code to use your new skills.');
+    console.log('   Setup complete! Start the agent with: npx skillvault');
+    console.log('   Then restart Claude Code to discover your skills.');
     console.log('');
 }
 /**
- * Remove legacy skillvault MCP server entry from ~/.claude/.mcp.json
+ * Configure Claude Code to connect to the SkillVault MCP server.
  */
-function cleanupMCPConfig() {
+function configureMCP() {
     const mcpConfigPath = join(HOME, '.claude', '.mcp.json');
     try {
+        let mcpConfig = {};
         if (existsSync(mcpConfigPath)) {
-            const mcpConfig = JSON.parse(readFileSync(mcpConfigPath, 'utf8'));
-            if (mcpConfig.mcpServers?.skillvault) {
-                delete mcpConfig.mcpServers.skillvault;
-                writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2), { mode: 0o600 });
-                console.log('   🧹 Removed legacy MCP server config');
-            }
+            mcpConfig = JSON.parse(readFileSync(mcpConfigPath, 'utf8'));
         }
+        if (!mcpConfig.mcpServers)
+            mcpConfig.mcpServers = {};
+        mcpConfig.mcpServers.skillvault = {
+            type: 'url',
+            url: `http://127.0.0.1:${MCP_PORT}/mcp`,
+        };
+        mkdirSync(join(HOME, '.claude'), { recursive: true });
+        writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2), { mode: 0o600 });
+        console.log(`   ✅ Claude Code MCP configured`);
+    }
+    catch {
+        console.error(`   ⚠️  Failed to configure MCP — manually add to ~/.claude/.mcp.json`);
     }
-    catch { }
 }
 async function showStatus() {
     const config = loadConfig();
@@ -187,14 +198,12 @@ async function showStatus() {
         process.exit(1);
     }
     console.log('🔐 SkillVault Status\n');
-    if (config.customer_email) {
+    if (config.customer_email)
         console.log(`   Account: ${config.customer_email}`);
-    }
     console.log(`   Config:  ${CONFIG_PATH}`);
-    console.log(`   Skills:  ${SKILLS_DIR}`);
+    console.log(`   Skills:  ${SKILLS_DIR} (stubs — encrypted at rest)`);
     console.log(`   Server:  ${config.api_url}`);
     console.log('');
-    // Try fetching live data from the server
     let skills = [];
     let online = false;
     try {
@@ -214,10 +223,7 @@ async function showStatus() {
             }
         }
     }
-    catch {
-        // Offline — fall back to local data
-    }
-    // Build publisher table
+    catch { }
     console.log('   Publishers:');
     console.log('   ' + '-'.repeat(60));
     console.log(`   ${'Name'.padEnd(25)} ${'Skills'.padEnd(10)} ${'Status'.padEnd(15)}`);
@@ -225,8 +231,6 @@ async function showStatus() {
     let totalSkills = 0;
     for (const pub of config.publishers) {
         const pubSkills = skills.filter(s => s.publisher_id === pub.id);
-        const skillCount = pubSkills.length;
-        // Check for local vaults as fallback
         let localVaultCount = 0;
         const pubVaultDir = join(VAULT_DIR, pub.id);
         if (existsSync(pubVaultDir)) {
@@ -235,13 +239,12 @@ async function showStatus() {
             }
             catch { }
         }
-        const displayCount = online ? skillCount : localVaultCount;
+        const displayCount = online ? pubSkills.length : localVaultCount;
         totalSkills += displayCount;
         const status = online ? 'connected' : 'offline (cached)';
         console.log(`   ${pub.name.padEnd(25)} ${String(displayCount).padEnd(10)} ${status.padEnd(15)}`);
     }
     console.log('   ' + '-'.repeat(60));
-    // Show skill details if online
     if (online && skills.length > 0) {
         console.log('\n   Skills:');
         console.log('   ' + '-'.repeat(70));
@@ -276,18 +279,14 @@ async function refreshTokens() {
         try {
             const res = await fetch(`${config.api_url}/auth/companion/refresh`, {
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${pub.token}`,
-                },
+                headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${pub.token}` },
                 signal: AbortSignal.timeout(10000),
             });
             if (res.ok) {
                 const data = await res.json();
                 pub.token = data.token;
-                if (data.customer_token) {
+                if (data.customer_token)
                     config.customer_token = data.customer_token;
-                }
                 console.log('✅ refreshed');
                 anyRefreshed = true;
             }
@@ -320,7 +319,6 @@ async function syncSkills() {
     for (const pub of config.publishers) {
         const pubVaultDir = join(VAULT_DIR, pub.id);
         mkdirSync(pubVaultDir, { recursive: true });
-        // Fetch skill list for this publisher
         let skills = [];
         try {
             const res = await fetch(`${config.api_url}/skills?publisher_id=${encodeURIComponent(pub.id)}`, {
@@ -328,12 +326,7 @@ async function syncSkills() {
                 signal: AbortSignal.timeout(10000),
             });
             if (!res.ok) {
-                if (res.status === 401) {
-                    errors.push(`${pub.name}: auth expired (${res.status})`);
-                }
-                else {
-                    errors.push(`${pub.name}: failed to fetch skills (${res.status})`);
-                }
+                errors.push(`${pub.name}: ${res.status === 401 ? 'auth expired' : `failed (${res.status})`}`);
                 continue;
             }
             const data = await res.json();
@@ -343,9 +336,8 @@ async function syncSkills() {
             errors.push(`${pub.name}: ${err instanceof Error ? err.message : 'fetch failed'}`);
             continue;
         }
-        // Build set of remote skill names for revocation check
         const remoteSkillNames = new Set(skills.map(s => s.skill_name));
-        // Check for revoked grants — remove decrypted skills
+        // Revocation: remove stubs for skills no longer in the remote list
         try {
             if (existsSync(pubVaultDir)) {
                 const localVaults = readdirSync(pubVaultDir).filter(f => f.endsWith('.vault'));
@@ -353,16 +345,11 @@ async function syncSkills() {
                     const localSkillName = vaultFile.replace(/\.vault$/, '');
                     if (!remoteSkillNames.has(localSkillName)) {
                         console.log(`[sync] Grant revoked: "${localSkillName}" from ${pub.name}`);
-                        // Remove decrypted skill from Claude Code skills directory
                         const skillDir = join(SKILLS_DIR, localSkillName);
                         try {
-                            if (existsSync(skillDir)) {
-                                // Verify it's a SkillVault-managed skill before deleting
-                                const manifestPath = join(skillDir, 'manifest.json');
-                                if (existsSync(manifestPath)) {
-                                    rmSync(skillDir, { recursive: true, force: true });
-                                    console.log(`[sync] Removed: ~/.claude/skills/${localSkillName}/`);
-                                }
+                            if (existsSync(skillDir) && existsSync(join(skillDir, 'manifest.json'))) {
+                                rmSync(skillDir, { recursive: true, force: true });
+                                console.log(`[sync] Removed stub: ~/.claude/skills/${localSkillName}/`);
                             }
                         }
                         catch { }
@@ -371,12 +358,11 @@ async function syncSkills() {
             }
         }
         catch { }
-        // Download missing or updated vaults
+        // Download missing or updated vaults + write skill metadata for stubs
         let pubSynced = 0;
         for (const skill of skills) {
             const vaultPath = join(pubVaultDir, `${skill.skill_name}.vault`);
             const vaultExists = existsSync(vaultPath);
-            // Check if we need to download: missing vault, or new version available
             let needsDownload = !vaultExists;
             if (vaultExists && skill.vault_hash) {
                 const hashPath = vaultPath + '.hash';
@@ -393,15 +379,11 @@ async function syncSkills() {
             }
             if (!needsDownload)
                 continue;
-            // Download vault
             const capabilityName = skill.capability_name || skill.skill_name;
             try {
                 let dlRes = await fetch(`${config.api_url}/skills/download?capability=${encodeURIComponent(capabilityName)}`, { signal: AbortSignal.timeout(15000) });
                 if (!dlRes.ok) {
-                    dlRes = await fetch(`${config.api_url}/skills/download?capability=${encodeURIComponent(capabilityName)}`, {
-                        headers: { 'Authorization': `Bearer ${pub.token}` },
-                        signal: AbortSignal.timeout(15000),
-                    });
+                    dlRes = await fetch(`${config.api_url}/skills/download?capability=${encodeURIComponent(capabilityName)}`, { headers: { 'Authorization': `Bearer ${pub.token}` }, signal: AbortSignal.timeout(15000) });
                 }
                 if (!dlRes.ok) {
                     errors.push(`${pub.name}/${skill.skill_name}: download failed (${dlRes.status})`);
@@ -410,29 +392,112 @@ async function syncSkills() {
                 const dlData = await dlRes.json();
                 const vaultBuffer = Buffer.from(dlData.vault_data, 'base64');
                 writeFileSync(vaultPath, vaultBuffer, { mode: 0o600 });
-                if (dlData.vault_hash) {
+                if (dlData.vault_hash)
                     writeFileSync(vaultPath + '.hash', dlData.vault_hash, { mode: 0o600 });
-                }
+                // Store skill metadata for stub generation
+                writeFileSync(vaultPath + '.meta', JSON.stringify({
+                    skill_name: skill.skill_name,
+                    description: skill.description || '',
+                    capability_name: skill.capability_name,
+                    version: dlData.version || skill.version || '0.0.0',
+                    publisher_name: pub.name,
+                    publisher_id: pub.id,
+                }), { mode: 0o600 });
                 pubSynced++;
-                const action = vaultExists ? 'Updated' : 'Downloaded';
-                console.log(`[sync] ${action}: "${skill.skill_name}" from ${pub.name}`);
+                console.log(`[sync] ${vaultExists ? 'Updated' : 'Downloaded'}: "${skill.skill_name}" from ${pub.name}`);
             }
             catch (err) {
                 errors.push(`${pub.name}/${skill.skill_name}: ${err instanceof Error ? err.message : 'download error'}`);
             }
         }
-        if (pubSynced > 0) {
+        if (pubSynced > 0)
             console.log(`[sync] Synced ${pubSynced} vault${pubSynced !== 1 ? 's' : ''} from ${pub.name}`);
-        }
         totalSynced += pubSynced;
     }
     return { synced: totalSynced, errors };
 }
-// ── Vault Decryption ──
-const VAULT_MAGIC = Buffer.from([0x00, 0x53, 0x56, 0x54]);
 /**
- * Decrypt a vault and return all files with their full content (frontmatter preserved).
+ * Install lightweight stub SKILL.md files in ~/.claude/skills/ for each vault.
+ * These stubs tell Claude to call the skillvault_load MCP tool to decrypt on demand.
+ * No decrypted content is written to disk.
  */
+async function installSkillStubs() {
+    const config = loadConfig();
+    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(SKILLS_DIR, { recursive: true });
+    for (const pub of config.publishers) {
+        const pubVaultDir = join(VAULT_DIR, 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 skillDir = join(SKILLS_DIR, skillName);
+            const manifestPath = join(skillDir, 'manifest.json');
+            const hashPath = vaultPath + '.hash';
+            // Check if stub is already up to date
+            if (existsSync(manifestPath) && existsSync(hashPath)) {
+                try {
+                    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                    const currentHash = readFileSync(hashPath, 'utf8').trim();
+                    if (manifest.vault_hash === currentHash) {
+                        skipped++;
+                        continue;
+                    }
+                }
+                catch { }
+            }
+            // Read skill metadata (written during sync)
+            let meta = { skill_name: skillName, description: '', publisher_name: pub.name };
+            const metaPath = vaultPath + '.meta';
+            try {
+                if (existsSync(metaPath))
+                    meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+            }
+            catch { }
+            // Write stub SKILL.md
+            mkdirSync(skillDir, { recursive: true });
+            const stub = `---
+name: ${skillName}
+description: "${(meta.description || '').replace(/"/g, '\\"')}"
+---
+
+# ${skillName}
+
+This is an encrypted SkillVault skill from **${meta.publisher_name || pub.name}**.
+
+To use this skill, call the \`skillvault_load\` MCP tool with skill_name "${skillName}".
+The tool will decrypt and return the full skill instructions for you to follow.
+
+Example: Use the skillvault_load tool with skill_name "${skillName}" to load the instructions, then follow them to complete the user's request.
+`;
+            writeFileSync(join(skillDir, 'SKILL.md'), stub, { mode: 0o600 });
+            // Write manifest
+            const vaultHash = existsSync(hashPath) ? readFileSync(hashPath, 'utf8').trim() : '';
+            writeFileSync(manifestPath, JSON.stringify({
+                publisher: meta.publisher_name || pub.name,
+                publisher_id: pub.id,
+                skill_name: skillName,
+                capability_name: meta.capability_name || `skill/${skillName}`,
+                version: meta.version || '0.0.0',
+                vault_hash: vaultHash,
+                installed_at: new Date().toISOString(),
+                encrypted: true,
+            }, null, 2), { mode: 0o600 });
+            installed++;
+            console.log(`[install] Stub installed: "${skillName}" → ~/.claude/skills/${skillName}/`);
+        }
+    }
+    return { installed, skipped, errors };
+}
+// ── Vault Decryption (in-memory only) ──
+const VAULT_MAGIC = Buffer.from([0x00, 0x53, 0x56, 0x54]);
 function decryptVault(data, cek) {
     let offset = 0;
     const magic = data.subarray(offset, (offset += 4));
@@ -465,15 +530,11 @@ function decryptVault(data, cek) {
     }));
     return { metadata, files };
 }
-/**
- * Resolve which publisher owns a skill by searching vault directories.
- */
 function resolveSkillPublisher(skillName, config) {
     for (const pub of config.publishers) {
         const vaultPath = join(VAULT_DIR, pub.id, `${skillName}.vault`);
-        if (existsSync(vaultPath)) {
+        if (existsSync(vaultPath))
             return { publisher: pub, vaultPath };
-        }
     }
     const legacyPath = join(VAULT_DIR, `${skillName}.vault`);
     if (existsSync(legacyPath) && config.publishers.length > 0) {
@@ -484,13 +545,9 @@ function resolveSkillPublisher(skillName, config) {
 async function fetchCEK(skillName, publisherToken) {
     const kp = generateKeyPairSync('x25519');
     const pub = kp.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
-    const headers = {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${publisherToken}`,
-    };
     const res = await fetch(`${API_URL}/v1/skills/${skillName}/cek`, {
         method: 'POST',
-        headers,
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${publisherToken}` },
         body: JSON.stringify({ companion_public_key: pub }),
     });
     if (!res.ok)
@@ -515,103 +572,182 @@ function watermark(content, id) {
     const mark = BigInt('0x' + hex).toString(4).split('').map(d => zw[d]).join('');
     return content.split('\n').map((l, i) => (i > 0 && i % 5 === 0 ? l + mark : l)).join('\n');
 }
-/**
- * Decrypt all vaults and write them as native Claude Code skills to ~/.claude/skills/.
- */
-async function installDecryptedSkills() {
+// ── On-Demand Skill Loading (MCP tool handler) ──
+function validateSkillName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name) && name.length > 0 && name.length <= 128;
+}
+async function loadSkill(skillName) {
+    if (!validateSkillName(skillName)) {
+        return { success: false, content: '', error: 'Invalid skill name. Only letters, numbers, hyphens, and underscores allowed.' };
+    }
     const config = loadConfig();
-    if (!config || config.publishers.length === 0) {
-        return { installed: 0, skipped: 0, errors: ['No config or publishers found'] };
+    if (!config) {
+        return { success: false, content: '', error: 'Not configured. Run: npx skillvault --invite CODE' };
+    }
+    const resolved = resolveSkillPublisher(skillName, config);
+    if (!resolved) {
+        return { success: false, content: '', error: `Vault not found for "${skillName}". Run: npx skillvault --sync` };
     }
     const licenseeId = config.customer_email || 'unknown';
-    let installed = 0;
-    let skipped = 0;
-    const errors = [];
-    mkdirSync(SKILLS_DIR, { recursive: true });
-    for (const pub of config.publishers) {
-        const pubVaultDir = join(VAULT_DIR, 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 skillDir = join(SKILLS_DIR, skillName);
-            const manifestPath = join(skillDir, 'manifest.json');
-            // Check if decryption is needed by comparing vault hash
-            const hashPath = vaultPath + '.hash';
-            if (existsSync(manifestPath) && existsSync(hashPath)) {
-                try {
-                    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-                    const currentHash = readFileSync(hashPath, 'utf8').trim();
-                    if (manifest.vault_hash === currentHash) {
-                        skipped++;
-                        continue; // Already up to date
-                    }
-                }
-                catch { }
-            }
-            // Fetch CEK (validates license)
-            let cek;
-            try {
-                cek = await fetchCEK(skillName, pub.token);
-            }
-            catch (err) {
-                errors.push(`${pub.name}/${skillName}: license check failed — ${err instanceof Error ? err.message : 'unknown'}`);
-                continue;
+    // Fetch CEK — validates license on every load
+    let cek;
+    try {
+        cek = await fetchCEK(skillName, resolved.publisher.token);
+    }
+    catch (err) {
+        return { success: false, content: '', error: `License check failed: ${err instanceof Error ? err.message : 'unknown'}. Your license may have been revoked.` };
+    }
+    // Decrypt in memory — content never touches disk
+    try {
+        const vaultData = readFileSync(resolved.vaultPath);
+        const vault = decryptVault(vaultData, cek);
+        cek.fill(0);
+        // Combine all files into a single response, with SKILL.md first
+        const skillMd = vault.files.find(f => f.path === 'SKILL.md');
+        const otherFiles = vault.files.filter(f => f.path !== 'SKILL.md');
+        let content = '';
+        if (skillMd) {
+            content = watermark(skillMd.content, licenseeId);
+        }
+        for (const file of otherFiles) {
+            content += `\n\n---\n# File: ${file.path}\n\n${watermark(file.content, licenseeId)}`;
+        }
+        return { success: true, content };
+    }
+    catch (err) {
+        cek.fill(0);
+        return { success: false, content: '', error: `Decryption failed: ${err instanceof Error ? err.message : 'unknown'}` };
+    }
+}
+function rpcOk(id, result) { return JSON.stringify({ jsonrpc: '2.0', id, result }); }
+function rpcErr(id, code, msg) { return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message: msg } }); }
+async function handleRPC(req) {
+    switch (req.method) {
+        case 'initialize':
+            return rpcOk(req.id, { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'skillvault', version: VERSION } });
+        case 'tools/list':
+            return rpcOk(req.id, {
+                tools: [{
+                        name: 'skillvault_load',
+                        description: 'Load and decrypt a SkillVault skill. Returns the full skill instructions for you to follow. The skill is decrypted on demand — license is validated each time. Call this when a stub SKILL.md tells you to load a skill.',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                skill_name: { type: 'string', description: 'Name of the skill to load (from the stub SKILL.md)' },
+                            },
+                            required: ['skill_name'],
+                        },
+                    }],
+            });
+        case 'tools/call': {
+            const name = req.params?.name;
+            const { skill_name } = req.params?.arguments || {};
+            if (name !== 'skillvault_load')
+                return rpcErr(req.id, -32601, `Unknown tool: ${name}`);
+            if (!skill_name)
+                return rpcErr(req.id, -32602, 'skill_name required');
+            console.log(`[MCP] Loading: ${skill_name}`);
+            const result = await loadSkill(skill_name);
+            return rpcOk(req.id, {
+                content: [{ type: 'text', text: result.success ? result.content : `Error: ${result.error}` }],
+                isError: !result.success,
+            });
+        }
+        case 'notifications/initialized': return '';
+        default: return rpcErr(req.id || 0, -32601, `Unknown method: ${req.method}`);
+    }
+}
+function startServer() {
+    const server = createServer(async (req, res) => {
+        if (req.method === 'OPTIONS') {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        if (req.method !== 'POST' || req.url !== '/mcp') {
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: 'POST /mcp' }));
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        const MAX_BODY = 1024 * 1024;
+        req.on('data', (c) => { size += c.length; if (size > MAX_BODY) {
+            req.destroy();
+            return;
+        } chunks.push(c); });
+        req.on('end', async () => {
+            if (size > MAX_BODY) {
+                res.writeHead(413);
+                res.end('Request too large');
+                return;
             }
-            // Decrypt vault
-            let vault;
             try {
-                const vaultData = readFileSync(vaultPath);
-                vault = decryptVault(vaultData, cek);
-            }
-            catch (err) {
-                errors.push(`${pub.name}/${skillName}: decryption failed — ${err instanceof Error ? err.message : 'unknown'}`);
-                continue;
-            }
-            finally {
-                cek.fill(0);
+                const rpc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                const result = await handleRPC(rpc);
+                if (result) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(result);
+                }
+                else {
+                    res.writeHead(204);
+                    res.end();
+                }
             }
-            // Write decrypted files to skills directory
-            mkdirSync(skillDir, { recursive: true });
-            for (const file of vault.files) {
-                const filePath = join(skillDir, file.path);
-                // Create subdirectories if needed (e.g., references/api_reference.md)
-                mkdirSync(join(filePath, '..'), { recursive: true });
-                // Apply watermark to text files
-                const content = file.path.endsWith('.md') || file.path.endsWith('.txt')
-                    ? watermark(file.content, licenseeId)
-                    : file.content;
-                writeFileSync(filePath, content, { mode: 0o600 });
+            catch {
+                res.writeHead(400);
+                res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
             }
-            // Write manifest for tracking
-            const vaultHash = existsSync(hashPath) ? readFileSync(hashPath, 'utf8').trim() : '';
-            const manifest = {
-                publisher: pub.name,
-                publisher_id: pub.id,
-                skill_name: skillName,
-                capability_name: `skill/${skillName}`,
-                version: vault.metadata.version || '0.0.0',
-                vault_hash: vaultHash,
-                installed_at: new Date().toISOString(),
-                watermark_applied: true,
-                licensee_id: licenseeId,
-            };
-            writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), { mode: 0o600 });
-            installed++;
-            console.log(`[install] Installed: "${skillName}" → ~/.claude/skills/${skillName}/`);
+        });
+    });
+    server.listen(MCP_PORT, '127.0.0.1', () => {
+        console.log(`🔐 SkillVault MCP server running on 127.0.0.1:${MCP_PORT}`);
+        const config = loadConfig();
+        if (config)
+            console.log(`   Publishers: ${config.publishers.map(p => p.name).join(', ')}`);
+        console.log(`   Skills are encrypted at rest — decrypted on demand per session.`);
+        console.log(`   Press Ctrl+C to stop.\n`);
+        // Background sync
+        syncSkills().then(({ synced, errors }) => {
+            if (synced > 0)
+                console.log(`[sync] Startup: ${synced} vault${synced !== 1 ? 's' : ''} synced`);
+            if (errors.length > 0)
+                console.log(`[sync] Errors: ${errors.join('; ')}`);
+            return installSkillStubs();
+        }).then(({ installed }) => {
+            if (installed > 0)
+                console.log(`[install] ${installed} stub${installed !== 1 ? 's' : ''} updated`);
+        }).catch((err) => {
+            console.error('[sync] Startup sync failed:', err instanceof Error ? err.message : err);
+        });
+        // Periodic sync every 5 minutes
+        setInterval(() => {
+            syncSkills().then(({ synced, errors }) => {
+                if (synced > 0)
+                    console.log(`[sync] ${synced} vault${synced !== 1 ? 's' : ''} synced`);
+                if (errors.length > 0)
+                    console.log(`[sync] Errors: ${errors.join('; ')}`);
+                return installSkillStubs();
+            }).then(({ installed }) => {
+                if (installed > 0)
+                    console.log(`[install] ${installed} stub${installed !== 1 ? 's' : ''} updated`);
+            }).catch(() => { });
+        }, 5 * 60 * 1000);
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            console.log(`   SkillVault is already running on port ${MCP_PORT}`);
+            process.exit(0);
         }
-    }
-    return { installed, skipped, errors };
+        console.error('Server error:', err);
+    });
 }
 // ── Main ──
 async function main() {
     if (inviteCode) {
         await setup(inviteCode);
-        if (!statusFlag && !refreshFlag) {
+        if (!statusFlag && !refreshFlag)
             process.exit(0);
-        }
     }
     if (statusFlag) {
         await showStatus();
@@ -619,20 +755,27 @@ async function main() {
     }
     if (refreshFlag) {
         await refreshTokens();
-        // Also sync after refresh
-        console.log('   Syncing skills...\n');
         await syncSkills();
-        const result = await installDecryptedSkills();
-        if (result.installed > 0) {
-            console.log(`\n   ✅ ${result.installed} skill${result.installed !== 1 ? 's' : ''} updated`);
-        }
-        if (result.errors.length > 0) {
-            console.log(`   ⚠️  ${result.errors.length} error${result.errors.length !== 1 ? 's' : ''}: ${result.errors.join('; ')}`);
+        const result = await installSkillStubs();
+        if (result.installed > 0)
+            console.log(`   ✅ ${result.installed} stub${result.installed !== 1 ? 's' : ''} updated`);
+        console.log('');
+        process.exit(0);
+    }
+    if (syncFlag) {
+        const config = loadConfig();
+        if (!config) {
+            console.log('🔐 Not set up. Run: npx skillvault --invite YOUR_CODE\n');
+            process.exit(1);
         }
+        console.log('🔐 SkillVault Sync\n');
+        await syncSkills();
+        const result = await installSkillStubs();
+        console.log(`\n   ✅ ${result.installed} installed, ${result.skipped} up to date`);
         console.log('');
         process.exit(0);
     }
-    // Default: sync + install (replaces old MCP server start)
+    // Default: start MCP server
     const config = loadConfig();
     if (!config) {
         console.log('🔐 SkillVault\n');
@@ -640,25 +783,7 @@ async function main() {
         console.log('   npx skillvault --invite YOUR_CODE\n');
         process.exit(1);
     }
-    console.log('🔐 SkillVault Sync\n');
-    const syncResult = await syncSkills();
-    const installResult = await installDecryptedSkills();
-    const total = installResult.installed + installResult.skipped;
-    if (installResult.installed > 0) {
-        console.log(`\n   ✅ ${installResult.installed} skill${installResult.installed !== 1 ? 's' : ''} installed, ${installResult.skipped} up to date`);
-    }
-    else if (total > 0) {
-        console.log(`\n   ✅ All ${total} skill${total !== 1 ? 's' : ''} up to date`);
-    }
-    else {
-        console.log('\n   No skills found. Your publishers may not have assigned any skills yet.');
-    }
-    if (syncResult.errors.length > 0 || installResult.errors.length > 0) {
-        const allErrors = [...syncResult.errors, ...installResult.errors];
-        console.log(`   ⚠️  ${allErrors.length} error${allErrors.length !== 1 ? 's' : ''}: ${allErrors.join('; ')}`);
-    }
-    console.log('');
-    process.exit(0);
+    startServer();
 }
 main().catch((err) => {
     console.error('Fatal:', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillvault",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SkillVault — secure skill distribution for Claude Code",
   "type": "module",
   "bin": {