promptgraph-mcp 1.5.25 → 1.7.0

package/README.md

@@ -11,13 +11,13 @@ PromptGraph is an MCP server that gives Claude Code a semantic skill index — v
 
 ## Why
 
-Claude Code dumps every file in `~/.claude/commands/` into the system prompt — every session, every message. At 40+ skills that's **20,000–50,000 wasted tokens before you say a word.**
+Claude Code loads skill metadata from `~/.claude/commands/` each session. With 40+ skills that's thousands of tokens in routing overhead before you say a word. More importantly, when Claude loads and executes a full skill file (typically 1,000–5,000 tokens each), the cost multiplies fast.
 
-PromptGraph replaces that with one tiny router skill (`~150 tokens`) and a local vector index. When you ask something, Claude calls `pg_search` → gets the right skill path → reads only that file.
+PromptGraph replaces that with one tiny router skill (`~150 tokens`) and a local vector index. Claude calls `pg_search` → gets the right skill path + a content snippet → reads only that file when needed.
 
 ```
-Before:  all 40 skills loaded  →  ~40,000 tokens wasted
-After:   1 router + 1 match    →  ~300 tokens total
+Before:  route across all 40 skills  →  40 × read overhead
+After:   1 pg_search call + snippet  →  read only what you need
 ```
 
 ---
@@ -31,7 +31,7 @@ After:   1 router + 1 match    →  ~300 tokens total
 - ⚡ **Local embeddings** — `fastembed` BGE-Small-EN, 23 MB, no API key needed
 - 👁️ **File watcher** — auto-reindexes when you add or edit skills
 - 🛡️ **Validator** — blocks malicious/junk skills before they reach your machine
-- 🌐 **MCP-native** — works with Claude Code, Claude Desktop, Cline, and any MCP client
+- 🌐 **MCP-native** — works with Claude Code, Claude Desktop, Cline, OpenCode, Cursor, Windsurf, and any MCP client
 
 ---
 
@@ -61,6 +61,22 @@ npx promptgraph-mcp init
 }
 ```
 
+### Add to OpenCode (`~/.config/opencode/opencode.json`)
+
+```json
+{
+  "mcp": {
+    "promptgraph": {
+      "type": "local",
+      "command": ["npx", "promptgraph-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> `pg setup` auto-detects OpenCode and writes this config for you.
+
 ### Move your skills out of `commands/`
 
 ```bash

package/ann.js

@@ -1,61 +1,60 @@
-import { LocalIndex } from 'vectra';
-import path from 'path';
-import os from 'os';
-import { getDb } from './db.js';
-
-const INDEX_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'hnsw-index');
-
-let _index = null;
+import { getDb, blobToVec } from './db.js';
+
+// In-memory flat index — no external dependency.
+// For typical skill counts (<5000) this is faster than vectra's disk-based HNSW
+// because all data fits in RAM and no I/O is needed per query.
+let _cache = null;
+let _cacheChunkCount = -1;
+
+function loadCache(db) {
+  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
+  if (_cache && count === _cacheChunkCount) return _cache;
+  const rows = db.prepare('SELECT skill_id, embedding FROM chunks').all();
+  _cache = rows.map(r => ({
+    skill_id: r.skill_id,
+    vec: new Float32Array(blobToVec(r.embedding)),
+  }));
+  _cacheChunkCount = count;
+  return _cache;
+}
 
-async function getIndex() {
-  if (_index) return _index;
-  _index = new LocalIndex(INDEX_PATH);
-  if (!await _index.isIndexCreated()) {
-    await _index.createIndex({ version: 1, deleteIfExists: true });
+function cosineSim(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
   }
-  return _index;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-8);
 }
 
+// Called after reindex — invalidate cache so next search reloads
 export async function buildAnnIndex() {
-  const index = await getIndex();
-  await index.createIndex({ version: 1, deleteIfExists: true });
-
+  _cache = null;
+  _cacheChunkCount = -1;
   const db = getDb();
-  const chunks = db.prepare('SELECT skill_id, chunk_index, embedding FROM chunks').all();
-
-  // Batch ALL inserts into a single disk write — vectra otherwise
-  // persists the whole index on every insertItem (O(N^2) I/O).
-  await index.beginUpdate();
-  try {
-    for (const chunk of chunks) {
-      const vec = JSON.parse(chunk.embedding);
-      await index.insertItem({
-        vector: vec,
-        metadata: { skill_id: chunk.skill_id, chunk_index: chunk.chunk_index },
-      });
-    }
-    await index.endUpdate();
-  } catch (e) {
-    try { index.cancelUpdate(); } catch {}
-    throw e;
-  }
-
-  _index = null; // force reload so queries see fresh index
-  console.error(`[PromptGraph] ANN index built: ${chunks.length} chunks`);
+  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
+  console.error(`[PromptGraph] In-memory index ready: ${count} chunks`);
 }
 
 export async function annSearch(queryVec, topK = 20) {
   try {
-    const index = await getIndex();
-    if (!await index.isIndexCreated()) return null;
-    const items = await index.listItems();
-    if (!items || items.length === 0) return null;
+    const db = getDb();
+    const cache = loadCache(db);
+    if (!cache.length) return null;
+
+    const qArr = new Float32Array(queryVec);
+    const bestBySkill = new Map();
+    for (const entry of cache) {
+      const score = cosineSim(qArr, entry.vec);
+      const prev = bestBySkill.get(entry.skill_id);
+      if (!prev || score > prev) bestBySkill.set(entry.skill_id, score);
+    }
 
-    const results = await index.queryItems(queryVec, topK);
-    return results.map(r => ({
-      skill_id: r.item.metadata.skill_id,
-      score: r.score,
-    }));
+    return [...bestBySkill.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, topK)
+      .map(([skill_id, score]) => ({ skill_id, score }));
   } catch {
     return null;
   }

package/chunker.js

@@ -2,15 +2,24 @@ const CHUNK_SIZE = 800;
 const CHUNK_OVERLAP = 100;
 
 export function chunkText(text) {
-  const words = text.split(/\s+/);
+  // Split on markdown h1/h2/h3 headers to preserve semantic boundaries
+  const sections = text.split(/(?=\n#{1,3} )/);
   const chunks = [];
-  let i = 0;
 
-  while (i < words.length) {
-    const chunk = words.slice(i, i + CHUNK_SIZE).join(' ');
-    chunks.push(chunk);
-    if (i + CHUNK_SIZE >= words.length) break;
-    i += CHUNK_SIZE - CHUNK_OVERLAP;
+  for (const section of sections) {
+    const words = section.split(/\s+/).filter(Boolean);
+    if (words.length === 0) continue;
+
+    if (words.length <= CHUNK_SIZE) {
+      chunks.push(section.trim());
+    } else {
+      let i = 0;
+      while (i < words.length) {
+        chunks.push(words.slice(i, i + CHUNK_SIZE).join(' '));
+        if (i + CHUNK_SIZE >= words.length) break;
+        i += CHUNK_SIZE - CHUNK_OVERLAP;
+      }
+    }
   }
 
   return chunks.length > 0 ? chunks : [text];

package/config.js

@@ -3,7 +3,9 @@ import path from 'path';
 import os from 'os';
 import readline from 'readline';
 
-const CONFIG_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'config.json');
+export const PROMPTGRAPH_DIR = path.join(os.homedir(), '.claude', '.promptgraph');
+export const SKILLS_STORE_DIR = path.join(os.homedir(), '.claude', 'skills-store');
+const CONFIG_PATH = path.join(PROMPTGRAPH_DIR, 'config.json');
 
 const DEFAULTS = {
   sources: [

package/db.js

@@ -1,9 +1,9 @@
 import Database from 'better-sqlite3';
 import path from 'path';
-import os from 'os';
 import fs from 'fs';
+import { PROMPTGRAPH_DIR } from './config.js';
 
-const DB_PATH = path.join(os.homedir(), '.claude', '.promptgraph', 'promptgraph.db');
+const DB_PATH = path.join(PROMPTGRAPH_DIR, 'promptgraph.db');
 
 let _db = null;
 
@@ -30,7 +30,7 @@ export function getDb() {
       skill_id TEXT NOT NULL,
       chunk_index INTEGER NOT NULL,
       text TEXT NOT NULL,
-      embedding TEXT NOT NULL,
+      embedding BLOB NOT NULL,
       UNIQUE(skill_id, chunk_index)
     );
 
@@ -54,9 +54,33 @@ export function getDb() {
     db.exec('ALTER TABLE skills ADD COLUMN hash TEXT');
   }
 
+  // migrate: convert JSON text embeddings to Float32 BLOB (one-time, ~10x smaller)
+  const textEmbeddings = db.prepare("SELECT COUNT(*) as n FROM chunks WHERE typeof(embedding) = 'text'").get();
+  if (textEmbeddings?.n > 0) {
+    const rows = db.prepare("SELECT rowid, embedding FROM chunks WHERE typeof(embedding) = 'text'").all();
+    const upd = db.prepare('UPDATE chunks SET embedding = ? WHERE rowid = ?');
+    db.transaction(() => {
+      for (const row of rows) {
+        const vec = JSON.parse(row.embedding);
+        upd.run(Buffer.from(new Float32Array(vec).buffer), row.rowid);
+      }
+    })();
+    console.error(`[PromptGraph] Migrated ${textEmbeddings.n} embeddings TEXT→BLOB`);
+  }
+
   return db;
 }
 
 export function skillId(source, name) {
   return `${source}::${name}`;
 }
+
+export function vecToBlob(vec) {
+  return Buffer.from(new Float32Array(vec).buffer);
+}
+
+export function blobToVec(blob) {
+  if (typeof blob === 'string') return JSON.parse(blob);
+  const buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+  return Array.from(new Float32Array(buf.buffer, buf.byteOffset, buf.length / 4));
+}

package/index.js

@@ -12,7 +12,7 @@ const args = process.argv.slice(2);
 const rawBin = process.argv[1]?.split(/[\\/]/).pop()?.replace(/\.js$/, '');
 const bin = (rawBin && rawBin !== 'index') ? rawBin : 'pg';
 
-const KNOWN_COMMANDS = new Set(['init', 'reindex', 'import', 'setup', 'validate', 'marketplace', 'doctor', 'help', '--help', '-h']);
+const KNOWN_COMMANDS = new Set(['init', 'reindex', 'import', 'setup', 'validate', 'marketplace', 'doctor', 'search', 'help', '--help', '-h']);
 
 function showHelp() {
   console.log(
@@ -26,6 +26,7 @@ function showHelp() {
   const cmds = [
     ['init',                'First-time setup + index all skills'],
     ['reindex',             'Re-index all skills'],
+    ['search <query>',      'Search skills from the terminal'],
     ['import <owner/repo>', 'Import skills from GitHub'],
     ['marketplace [page]',  'Browse the community skill registry'],
     ['validate <file.md>',  'Validate a skill before publishing'],
@@ -36,7 +37,7 @@ function showHelp() {
   for (const [cmd, desc] of cmds) {
     console.log('  ' + chalk.hex('#7C3AED')((bin + ' ' + cmd).padEnd(28)) + chalk.gray(desc));
   }
-  console.log(chalk.gray('\nPlatforms: claude-code, claude-desktop, cline, codex, cursor, windsurf'));
+  console.log(chalk.gray('\nPlatforms: claude-code, claude-desktop, cline, codex, cursor, windsurf, opencode'));
   console.log(chalk.gray('\n  github.com/NeiP4n/promptgraph  ·  npmjs.com/package/promptgraph-mcp\n'));
 }
 
@@ -115,8 +116,14 @@ if (args[0] === 'marketplace' && (args[1] === 'bundles' || args[1] === 'bundle')
     console.log();
   });
 
-  console.log('  ' + chalk.gray('─'.repeat(54)));
-  console.log('  ' + chalk.gray('Installs all skills in the set. Run ') + chalk.cyan(`${bin} marketplace`) + chalk.gray(' for single skills.'));
+  console.log(
+    boxen(
+      chalk.dim('install bundle ') + chalk.white('install bundle ') + chalk.hex('#A78BFA')('engineering-essentials') + '\n' +
+      chalk.dim('browse skills  ') + chalk.cyan(`${bin} marketplace`) + '\n' +
+      chalk.dim('publish bundle ') + chalk.white('/pg-publish ') + chalk.hex('#A78BFA')('<bundle.json>'),
+      { padding: { top: 0, bottom: 0, left: 1, right: 1 }, borderStyle: 'round', borderColor: '#4B5563', dimBorder: true }
+    )
+  );
   console.log();
   process.exit(0);
 }
@@ -189,10 +196,21 @@ if (args[0] === 'marketplace') {
     if (page > 1) nav.push(chalk.dim('‹ ') + chalk.cyan(`${bin} marketplace ${page - 1}`));
     if (page < totalPages) nav.push(chalk.cyan(`${bin} marketplace ${page + 1}`) + chalk.dim(' ›'));
     console.log('  ' + nav.join('     '));
+    console.log();
   }
-  console.log('  ' + chalk.dim('install   ') + chalk.cyan('tell your AI:') + ' ' + chalk.white('install ') + chalk.hex('#A78BFA')(slice[0].code || slice[0].id));
-  console.log('  ' + chalk.dim('bundles   ') + chalk.cyan(`${bin} marketplace bundles`));
-  console.log('  ' + chalk.dim('publish   ') + chalk.cyan('tell your AI:') + ' ' + chalk.white('/pg-publish <file>'));
+
+  const exCode = slice[0]?.code || slice[0]?.id || 'pg-xxxxxx';
+  console.log(
+    boxen(
+      chalk.dim('install skill  ') + chalk.white('install ') + chalk.hex('#A78BFA')(exCode) + '\n' +
+      chalk.dim('install bundle ') + chalk.white('install bundle ') + chalk.hex('#A78BFA')('engineering-essentials') + '\n' +
+      chalk.dim('from GitHub    ') + chalk.white('install ') + chalk.hex('#A78BFA')('https://github.com/owner/repo/blob/main/skill.md') + '\n' +
+      chalk.dim('publish skill  ') + chalk.white('/pg-publish ') + chalk.hex('#A78BFA')('<file.md>') + '\n' +
+      chalk.dim('publish bundle ') + chalk.white('/pg-publish ') + chalk.hex('#A78BFA')('<bundle.json>') + '\n' +
+      chalk.dim('view bundles   ') + chalk.cyan(`${bin} marketplace bundles`),
+      { padding: { top: 0, bottom: 0, left: 1, right: 1 }, borderStyle: 'round', borderColor: '#4B5563', dimBorder: true }
+    )
+  );
   console.log();
   process.exit(0);
 }
@@ -213,6 +231,27 @@ if (args[0] === 'validate') {
   }
 }
 
+if (args[0] === 'search') {
+  const query = args.slice(1).join(' ');
+  if (!query) { error('Usage: ' + bin + ' search <query>'); process.exit(1); }
+  const { search: searchSkills } = await import('./search.js');
+  const spin = (await import('./cli.js')).spinner('Searching...');
+  spin.start();
+  const results = await searchSkills(query, 10);
+  spin.stop();
+  if (!results.length) { info('No results for: ' + query); process.exit(0); }
+  const purple = chalk.hex('#7C3AED');
+  console.log();
+  results.forEach((s, i) => {
+    const score = chalk.dim((s.score * 100).toFixed(0) + '%');
+    console.log('  ' + chalk.dim(String(i + 1) + '.') + ' ' + chalk.bold.white(s.name) + '  ' + score);
+    console.log('     ' + chalk.dim(s.description || ''));
+    console.log('     ' + purple(s.source) + '  ' + chalk.dim(s.path));
+    console.log();
+  });
+  process.exit(0);
+}
+
 if (args[0] === 'import') {
   const { importFromGitHub } = await import('./github-import.js');
   await importFromGitHub(args[1]);
@@ -239,6 +278,24 @@ if (args[0] === 'setup') {
 if (args[0] === 'init') {
   const { promptConfig } = await import('./config.js');
   const { indexAll } = await import('./indexer.js');
+  const os = await import('os');
+  const fs = await import('fs');
+  const path = await import('path');
+  const commandsDir = path.default.join(os.default.homedir(), '.claude', 'commands');
+  if (!fs.default.existsSync(commandsDir)) {
+    console.log(chalk.yellow('⚠') + '  ' + chalk.gray('~/.claude/commands/ not found — is Claude Code installed?'));
+    console.log(chalk.gray('   Install from: https://claude.ai/download\n'));
+  }
+  if (!args.includes('--yes') && !args.includes('-y')) {
+    const readline = await import('readline');
+    const rl = readline.default.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(r => rl.question(
+      chalk.yellow('  ⚠') + chalk.gray('  First run downloads ~23 MB embedding model (BGE-Small-EN).\n  Proceed? [Y/n] '), r
+    ));
+    rl.close();
+    if (answer.trim().toLowerCase() === 'n') { info('Aborted.'); process.exit(0); }
+  }
+  console.log(chalk.gray('\n  Downloading embedding model (~23 MB, one-time)...\n'));
   const config = await promptConfig();
   await indexAll();
   console.log();
@@ -263,8 +320,9 @@ const { Server } = await import('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
 const { CallToolRequestSchema, ListToolsRequestSchema } = await import('@modelcontextprotocol/sdk/types.js');
 const { search, getContext, getCallers, getCallees, getImpact, listAll } = await import('./search.js');
+const { loadConfig: _loadConfig, saveConfig: _saveConfig } = await import('./config.js');
 const { startWatcher } = await import('./watcher.js');
-const { browseMarketplace, installSkill, publishSkill, getTopRated, recordUse, recordSuccess, recordFail, browseBundles, installBundle } = await import('./marketplace.js');
+const { browseMarketplace, installSkill, installSkillFromUrl, publishSkill, publishBundle, getTopRated, recordUse, recordSuccess, recordFail, browseBundles, installBundle } = await import('./marketplace.js');
 
 const server = new Server(
   { name: 'promptgraph', version: '1.0.0' },
@@ -386,6 +444,45 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['bundle_id'],
       },
     },
+    {
+      name: 'pg_config',
+      description: 'Get or update PromptGraph config. action="get" returns current sources. action="add_source" adds a directory.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['get', 'add_source', 'remove_source'] },
+          dir: { type: 'string', description: 'Directory path (for add_source)' },
+          source: { type: 'string', description: 'Source label (for add_source/remove_source)' },
+        },
+        required: ['action'],
+      },
+    },
+    {
+      name: 'pg_install_url',
+      description: 'Install a skill directly from a GitHub URL or raw URL. Validates before saving.',
+      inputSchema: {
+        type: 'object',
+        properties: { url: { type: 'string', description: 'GitHub blob URL or raw URL of a .md skill file' } },
+        required: ['url'],
+      },
+    },
+    {
+      name: 'pg_bundle_publish',
+      description: 'Publish a bundle definition to GitHub Gist and get a registry submission link. Pass a JSON object or path to a .json file.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          bundle: {
+            description: 'Bundle definition object { id, name, description, skills[], tags[] } OR file path to .json',
+            oneOf: [
+              { type: 'object' },
+              { type: 'string' },
+            ],
+          },
+        },
+        required: ['bundle'],
+      },
+    },
   ],
 }));
 
@@ -413,6 +510,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'pg_marketplace_publish': result = await publishSkill(args.file_path); break;
       case 'pg_bundle_browse': result = await browseBundles(args.top_k || 20); break;
       case 'pg_bundle_install': result = await installBundle(args.bundle_id); break;
+      case 'pg_install_url': result = await installSkillFromUrl(args.url); break;
+      case 'pg_bundle_publish': result = await publishBundle(args.bundle); break;
+      case 'pg_config': {
+        const cfg = _loadConfig();
+        if (args.action === 'get') {
+          result = { sources: cfg.sources };
+        } else if (args.action === 'add_source') {
+          if (!args.dir || !args.source) throw new Error('dir and source required for add_source');
+          if (cfg.sources.find(s => s.source === args.source)) throw new Error(`Source "${args.source}" already exists`);
+          cfg.sources.push({ dir: args.dir, source: args.source });
+          _saveConfig(cfg);
+          result = { ok: true, sources: cfg.sources };
+        } else if (args.action === 'remove_source') {
+          if (!args.source) throw new Error('source required for remove_source');
+          const before = cfg.sources.length;
+          cfg.sources = cfg.sources.filter(s => s.source !== args.source);
+          if (cfg.sources.length === before) throw new Error(`Source "${args.source}" not found`);
+          _saveConfig(cfg);
+          result = { ok: true, sources: cfg.sources };
+        } else {
+          throw new Error(`Unknown action: ${args.action}`);
+        }
+        break;
+      }
       default: throw new Error(`Unknown tool: ${name}`);
     }
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -426,3 +547,11 @@ startWatcher();
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('[PromptGraph] MCP server running');
+
+const { getDb: _getDb } = await import('./db.js');
+const shutdown = () => {
+  try { _getDb().close(); } catch {}
+  process.exit(0);
+};
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/indexer.js

@@ -4,7 +4,7 @@ import fs from 'fs';
 import path from 'path';
 import { parseSkillFile, isSkillFile } from './parser.js';
 import { embedBatch, BATCH_SIZE } from './embedder.js';
-import { getDb, skillId } from './db.js';
+import { getDb, skillId, vecToBlob } from './db.js';
 import { loadConfig } from './config.js';
 import { chunkText } from './chunker.js';
 import { buildAnnIndex } from './ann.js';
@@ -54,7 +54,7 @@ async function indexBatch(db, skills) {
     }
     for (let i = 0; i < allChunks.length; i++) {
       const { id, chunkIndex, text } = allChunks[i];
-      upsertChunk.run(id, chunkIndex, text, JSON.stringify(embeddings[i]));
+      upsertChunk.run(id, chunkIndex, text, vecToBlob(embeddings[i]));
     }
   })();
 
@@ -161,9 +161,9 @@ export async function indexAll() {
         const eta = count > 0 ? Math.round((total - count) * (Date.now() - start) / count / 1000) : '?';
         progress(count, total, { skipped, eta, errors });
       }
-    } catch {
+    } catch (e) {
       errors++;
-      // Remove stale record if the file was previously indexed but now fails to parse
+      console.error(`[PromptGraph] Error indexing ${file}: ${e.message}`);
       try {
         const stale = db.prepare('SELECT id FROM skills WHERE path = ?').get(file);
         if (stale) {
@@ -181,9 +181,6 @@ export async function indexAll() {
     count += batch.length;
   }
 
-  // rebuild all edges for unchanged skills too (fixes edge loss bug)
-  rebuildEdgesForUnchanged(db);
-
   progress(total, total, { skipped, errors });
   progressDone();
   const spin = spinner('Building ANN index...');
@@ -195,13 +192,6 @@ export async function indexAll() {
   info(chalk.gray(`Time: ${elapsed}s`));
 }
 
-function rebuildEdgesForUnchanged(db) {
-  // For skills that were skipped (hash unchanged), their edges were not touched.
-  // This is correct — we only delete+rebuild edges for skills that were re-indexed.
-  // No action needed here: edges for unchanged skills remain intact.
-  // The global DELETE FROM edges at the start was the bug — it's now removed.
-}
-
 export async function indexFile(filePath, source) {
   const db = getDb();
   const skill = parseSkillFile(filePath, source);

package/marketplace.js

@@ -1,15 +1,43 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import https from 'https';
 import { createHash } from 'crypto';
 import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
 import { getDb } from './db.js';
-import { validateSkill } from './validator.js';
-import { loadConfig, saveConfig } from './config.js';
+import { validateSkill, validateBundle } from './validator.js';
+import { loadConfig, saveConfig, PROMPTGRAPH_DIR, SKILLS_STORE_DIR } from './config.js';
 
 const REGISTRY_URL = 'https://raw.githubusercontent.com/NeiP4n/promptgraph-registry/main/registry.json';
-const SKILLS_DIR = path.join(os.homedir(), '.claude', 'skills-store', 'marketplace');
+const SKILLS_DIR = path.join(SKILLS_STORE_DIR, 'marketplace');
+
+// Atomically write content to dest via tmp — cleans up on failure
+function writeSkillAtomic(dest, content) {
+  const tmpPath = dest + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, content);
+    const v = validateSkill(tmpPath);
+    if (!v.ok) { fs.unlinkSync(tmpPath); return v; }
+    fs.renameSync(tmpPath, dest);
+    return { ok: true };
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    return { ok: false, errors: [e.message] };
+  }
+}
+
+// Convert GitHub blob URL → raw URL
+// https://github.com/owner/repo/blob/branch/path/file.md
+// → https://raw.githubusercontent.com/owner/repo/branch/path/file.md
+function githubToRaw(url) {
+  const m = url.match(/^https?:\/\/github\.com\/([^/]+\/[^/]+)\/blob\/(.+)$/);
+  if (m) return `https://raw.githubusercontent.com/${m[1]}/${m[2]}`;
+  return null; // already raw or not a github URL
+}
+
+const _require = createRequire(import.meta.url);
+const PKG_VERSION = (() => { try { return _require('./package.json').version; } catch { return '1.x'; } })();
+const UA = `promptgraph-mcp/${PKG_VERSION}`;
 
 // Deterministic short code from an id. Same id always yields the same code,
 // so codes auto-generate — no need to assign them by hand.
@@ -20,7 +48,7 @@ export function codeFor(id) {
 // node:https GET — reliable and fast on Windows (undici fetch can hang ~10s there).
 function httpGet(url) {
   return new Promise((resolve, reject) => {
-    const req = https.get(url, { headers: { 'User-Agent': 'promptgraph-mcp' }, timeout: 8000, family: 4 }, (res) => {
+    const req = https.get(url, { headers: { 'User-Agent': UA }, timeout: 8000, family: 4 }, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
         return httpGet(res.headers.location).then(resolve, reject);
       }
@@ -43,18 +71,17 @@ async function rawFetch(url) {
   try {
     return await httpGet(url);
   } catch {
-    const res = await fetch(url, { headers: { 'User-Agent': 'promptgraph-mcp' } });
+    const res = await fetch(url, { headers: { 'User-Agent': UA } });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
     return await res.text();
   }
 }
 
 // Disk cache for the registry (network to GitHub raw can be slow on some networks).
-const CACHE_DIR = path.join(os.homedir(), '.claude', '.promptgraph');
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 
 async function fetchText(url) {
-  const cacheFile = path.join(CACHE_DIR, 'registry-cache.json');
+  const cacheFile = path.join(PROMPTGRAPH_DIR, 'registry-cache.json');
   const isRegistry = url === REGISTRY_URL;
 
   if (isRegistry && fs.existsSync(cacheFile)) {
@@ -70,7 +97,7 @@ async function fetchText(url) {
 
   if (isRegistry) {
     try {
-      fs.mkdirSync(CACHE_DIR, { recursive: true });
+      fs.mkdirSync(PROMPTGRAPH_DIR, { recursive: true });
       fs.writeFileSync(cacheFile, text);
     } catch {}
   }
@@ -91,8 +118,31 @@ export async function browseMarketplace(topK = 20) {
   }
 }
 
+export async function installSkillFromUrl(url) {
+  try {
+    const rawUrl = githubToRaw(url) || url;
+    const content = await fetchText(rawUrl);
+    fs.mkdirSync(SKILLS_DIR, { recursive: true });
+    ensureMarketplaceSource();
+
+    // derive filename from URL
+    const urlName = rawUrl.split('/').pop().replace(/[^a-z0-9-_.]/gi, '-');
+    const dest = path.join(SKILLS_DIR, urlName.endsWith('.md') ? urlName : urlName + '.md');
+    const v = writeSkillAtomic(dest, content);
+    if (!v.ok) return { error: 'Downloaded skill failed validation', issues: v.errors };
+    return { success: true, path: dest, url: rawUrl };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
 export async function installSkill(query) {
   try {
+    // GitHub URL or raw URL → direct install
+    if (query.startsWith('http://') || query.startsWith('https://')) {
+      return installSkillFromUrl(query);
+    }
+
     const text = await fetchText(REGISTRY_URL);
     const registry = JSON.parse(text);
     const q = String(query).trim().toLowerCase();
@@ -107,7 +157,7 @@ export async function installSkill(query) {
         (b.code || codeFor(b.id)).toLowerCase() === q || b.id?.toLowerCase() === q
       );
       if (bundle) return { error: `"${query}" is a bundle. Use pg_bundle_install("${bundle.id}") instead.` };
-      return { error: `No skill matching "${query}" (try a code like pg-xxxxxx, an id, or a name)` };
+      return { error: `No skill matching "${query}" (try a code, id, name, or GitHub URL)` };
     }
     if (!skill.raw_url) return { error: `Skill "${skill.id}" has no download URL` };
     const skillId = skill.id;
@@ -117,17 +167,8 @@ export async function installSkill(query) {
     const dest = path.join(SKILLS_DIR, `${skillId}.md`);
 
     const content = await fetchText(skill.raw_url);
-
-    // Validate before writing — reject malicious or junk downloads
-    const tmpPath = dest + '.tmp';
-    fs.writeFileSync(tmpPath, content);
-    const validation = validateSkill(tmpPath);
-    if (!validation.ok) {
-      fs.unlinkSync(tmpPath);
-      return { error: 'Downloaded skill failed validation', issues: validation.errors };
-    }
-    fs.renameSync(tmpPath, dest);
-
+    const v = writeSkillAtomic(dest, content);
+    if (!v.ok) return { error: 'Downloaded skill failed validation', issues: v.errors };
     return { success: true, path: dest, name: skill.name };
   } catch (e) {
     return { error: e.message };
@@ -173,17 +214,16 @@ export async function installBundle(bundleId) {
     const installed = [];
     const failed = [];
 
+    const delay = (ms) => new Promise(r => setTimeout(r, ms));
     for (const skillId of bundle.skills || []) {
       const skill = registry.skills?.find(s => s.id === skillId);
       if (!skill?.raw_url) { failed.push(skillId); continue; }
       try {
+        if (installed.length > 0) await delay(300); // rate limit: 300ms between requests
         const content = await fetchText(skill.raw_url);
         const dest = path.join(SKILLS_DIR, `${skillId}.md`);
-        const tmpPath = dest + '.tmp';
-        fs.writeFileSync(tmpPath, content);
-        const validation = validateSkill(tmpPath);
-        if (!validation.ok) { fs.unlinkSync(tmpPath); failed.push(skillId); continue; }
-        fs.renameSync(tmpPath, dest);
+        const v = writeSkillAtomic(dest, content);
+        if (!v.ok) { failed.push(skillId); continue; }
         installed.push(skillId);
       } catch {
         failed.push(skillId);
@@ -196,34 +236,88 @@ export async function installBundle(bundleId) {
   }
 }
 
+function ghPublish(filePath, desc) {
+  try {
+    const result = spawnSync('gh', ['gist', 'create', filePath, '--desc', desc, '--public'], { encoding: 'utf8' });
+    if (result.error?.code === 'ENOENT') return { ok: false, no_gh: true };
+    if (result.status !== 0) return { ok: false, error: result.stderr?.trim() || 'gh CLI error — run: gh auth login' };
+    return { ok: true, url: result.stdout.trim() };
+  } catch {
+    return { ok: false, no_gh: true };
+  }
+}
+
+const REGISTRY_ISSUES = 'https://github.com/NeiP4n/promptgraph-registry/issues/new';
+
 export async function publishSkill(filePath) {
   if (!fs.existsSync(filePath)) return { error: `File not found: ${filePath}` };
 
-  // validate before publishing — block junk and malicious skills
   const validation = validateSkill(filePath);
   if (!validation.ok) {
     return { error: 'Validation failed', issues: validation.errors, warnings: validation.warnings };
   }
 
   const name = path.basename(filePath, '.md');
+  const gh = ghPublish(filePath, `PromptGraph skill: ${name}`);
 
-  try {
-    const result = spawnSync(
-      'gh',
-      ['gist', 'create', filePath, '--desc', `PromptGraph skill: ${name}`, '--public'],
-      { encoding: 'utf8' }
-    );
-    if (result.status !== 0) {
-      return { error: result.stderr?.trim() || 'gh CLI error. Run: gh auth login' };
-    }
+  if (gh.no_gh) {
+    const content = fs.readFileSync(filePath, 'utf8');
     return {
       success: true,
-      url: result.stdout.trim(),
-      message: `Published! Submit to registry: https://github.com/NeiP4n/promptgraph-registry/issues/new`,
+      gh_not_installed: true,
+      instructions: [
+        '1. Install gh CLI: https://cli.github.com',
+        '   OR manually create a public Gist at https://gist.github.com with the file content',
+        `2. Submit to registry: ${REGISTRY_ISSUES}`,
+        `3. Paste the Gist URL in the issue`,
+      ].join('\n'),
+      file_content: content,
+    };
+  }
+  if (!gh.ok) return { error: gh.error };
+  return { success: true, url: gh.url, message: `Published! Submit to registry: ${REGISTRY_ISSUES}` };
+}
+
+export async function publishBundle(bundleDef) {
+  // bundleDef: { id, name, description, skills: [...], tags: [...] }
+  // OR a path to a .json file
+  let def = bundleDef;
+  if (typeof bundleDef === 'string') {
+    if (!fs.existsSync(bundleDef)) return { error: `File not found: ${bundleDef}` };
+    try { def = JSON.parse(fs.readFileSync(bundleDef, 'utf8')); }
+    catch (e) { return { error: `Invalid JSON: ${e.message}` }; }
+  }
+
+  const validation = validateBundle(def);
+  if (!validation.ok) {
+    return { error: 'Bundle validation failed', issues: validation.errors, warnings: validation.warnings };
+  }
+
+  const bundleJson = JSON.stringify(def, null, 2);
+  const tmpFile = path.join(PROMPTGRAPH_DIR, `bundle-${def.id}.json`);
+  fs.mkdirSync(PROMPTGRAPH_DIR, { recursive: true });
+  fs.writeFileSync(tmpFile, bundleJson);
+
+  const gh = ghPublish(tmpFile, `PromptGraph bundle: ${def.name}`);
+  try { fs.unlinkSync(tmpFile); } catch {}
+
+  if (gh.no_gh) {
+    const issueUrl = `${REGISTRY_ISSUES}?title=Bundle%3A+${encodeURIComponent(def.name)}&body=${encodeURIComponent('Bundle definition:\n\n```json\n' + bundleJson + '\n```')}`;
+    return {
+      success: true,
+      gh_not_installed: true,
+      instructions: [
+        '1. Install gh CLI: https://cli.github.com',
+        `   OR open this pre-filled issue directly: ${issueUrl}`,
+        '2. Paste the bundle JSON shown below into the issue body',
+      ].join('\n'),
+      bundle_json: bundleJson,
+      submit_url: issueUrl,
     };
-  } catch {
-    return { error: 'gh CLI not found. Install from: https://cli.github.com' };
   }
+  if (!gh.ok) return { error: gh.error };
+  const issueUrl = `${REGISTRY_ISSUES}?title=Bundle%3A+${encodeURIComponent(def.name)}&body=Gist%3A+${encodeURIComponent(gh.url)}`;
+  return { success: true, gist_url: gh.url, submit_url: issueUrl, message: `Bundle published! Submit: ${issueUrl}` };
 }
 
 export function getTopRated(topK = 10) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptgraph-mcp",
-  "version": "1.5.25",
+  "version": "1.7.0",
   "main": "index.js",
   "type": "module",
   "bin": {
@@ -42,13 +42,12 @@
     "fastembed": "^2.1.0",
     "glob": "^13.0.6",
     "gray-matter": "^4.0.3",
-    "ora": "^9.4.0",
-    "vectra": "^0.15.0"
+    "ora": "^9.4.0"
   },
   "devDependencies": {
     "vitest": "^4.1.8"
   },
   "overrides": {
-    "tar": "^7.5.16"
+    "tar": "^6.2.1"
   }
 }

package/pg-hook.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { embed, cosineSimilarity } from './embedder.js';
-import { getDb } from './db.js';
+import { getDb, blobToVec } from './db.js';
+import { annSearch } from './ann.js';
 
 let input = '';
 process.stdin.on('data', d => input += d);
@@ -13,19 +14,34 @@ process.stdin.on('end', async () => {
     const queryVec = await embed(prompt);
     const db = getDb();
 
-    // search over chunks, deduplicate by skill
-    const chunks = db.prepare('SELECT skill_id, embedding FROM chunks').all();
-    const bestBySkill = new Map();
-    for (const chunk of chunks) {
-      const score = cosineSimilarity(queryVec, JSON.parse(chunk.embedding));
-      const prev = bestBySkill.get(chunk.skill_id);
-      if (!prev || score > prev) bestBySkill.set(chunk.skill_id, score);
-    }
+    // Use ANN index (fast). Fall back to brute-force only if ANN unavailable.
+    let topIds;
+    const annResults = await annSearch(queryVec, 15);
 
-    const topIds = [...bestBySkill.entries()]
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, 3)
-      .filter(([, score]) => score > 0.55);
+    if (annResults && annResults.length > 0) {
+      const bestBySkill = new Map();
+      for (const r of annResults) {
+        const prev = bestBySkill.get(r.skill_id);
+        if (!prev || r.score > prev) bestBySkill.set(r.skill_id, r.score);
+      }
+      topIds = [...bestBySkill.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .filter(([, score]) => score > 0.55);
+    } else {
+      // Fallback: brute-force (only before first reindex)
+      const chunks = db.prepare('SELECT skill_id, embedding FROM chunks').all();
+      const bestBySkill = new Map();
+      for (const chunk of chunks) {
+        const score = cosineSimilarity(queryVec, blobToVec(chunk.embedding));
+        const prev = bestBySkill.get(chunk.skill_id);
+        if (!prev || score > prev) bestBySkill.set(chunk.skill_id, score);
+      }
+      topIds = [...bestBySkill.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .filter(([, score]) => score > 0.55);
+    }
 
     if (topIds.length === 0) process.exit(0);
 

package/platform.js

@@ -1,80 +1,102 @@
 import os from 'os';
 import path from 'path';
 import fs from 'fs';
+import { spawnSync } from 'child_process';
 
 const HOME = os.homedir();
 
+const STD_ENTRY = { command: 'npx', args: ['promptgraph-mcp'] };
+const OC_ENTRY  = { type: 'local', command: ['npx', 'promptgraph-mcp'], enabled: true };
+
+// Shared helper: write standard mcpServers entry (Claude Code, Cursor, Windsurf, Codex format)
+function addStdMcp(configPath) {
+  const json = readJson(configPath) || {};
+  json.mcpServers = json.mcpServers || {};
+  json.mcpServers.promptgraph = STD_ENTRY;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  writeJson(configPath, json);
+}
+
+// Cline uses servers.promptgraph (not mcpServers)
+function addClineMcp(configPath) {
+  const json = readJson(configPath) || {};
+  json.servers = json.servers || {};
+  json.servers.promptgraph = STD_ENTRY;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  writeJson(configPath, json);
+}
+
+// OpenCode uses mcp.promptgraph with type/command/enabled
+function addOpenCodeMcp(configPath) {
+  const json = readJson(configPath) || {};
+  json.mcp = json.mcp || {};
+  json.mcp.promptgraph = OC_ENTRY;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  writeJson(configPath, json);
+}
+
 export const PLATFORMS = {
   'claude-code': {
     name: 'Claude Code',
     configPath: path.join(HOME, '.claude', 'settings.json'),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath);
-      json.mcpServers = json.mcpServers || {};
-      json.mcpServers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addStdMcp(config.configPath),
   },
   'claude-desktop': {
     name: 'Claude Desktop',
     configPath: getClaudeDesktopConfig(),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath);
-      json.mcpServers = json.mcpServers || {};
-      json.mcpServers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addStdMcp(config.configPath),
   },
   'cline': {
     name: 'Cline (VS Code)',
     configPath: path.join(HOME, '.vscode', 'mcp.json'),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath) || { servers: {} };
-      json.servers = json.servers || {};
-      json.servers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      fs.mkdirSync(path.dirname(config.configPath), { recursive: true });
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addClineMcp(config.configPath),
   },
   'codex': {
     name: 'OpenAI Codex CLI',
     configPath: path.join(HOME, '.codex', 'config.json'),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath) || {};
-      json.mcpServers = json.mcpServers || {};
-      json.mcpServers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      fs.mkdirSync(path.dirname(config.configPath), { recursive: true });
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addStdMcp(config.configPath),
   },
   'cursor': {
     name: 'Cursor',
     configPath: path.join(HOME, '.cursor', 'mcp.json'),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath) || { mcpServers: {} };
-      json.mcpServers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      fs.mkdirSync(path.dirname(config.configPath), { recursive: true });
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addStdMcp(config.configPath),
   },
   'windsurf': {
     name: 'Windsurf',
     configPath: path.join(HOME, '.codeium', 'windsurf', 'mcp_config.json'),
-    addMcp: (config, serverPath) => {
-      const json = readJson(config.configPath) || { mcpServers: {} };
-      json.mcpServers.promptgraph = { command: 'npx', args: ['promptgraph-mcp'] };
-      fs.mkdirSync(path.dirname(config.configPath), { recursive: true });
-      writeJson(config.configPath, json);
-    },
+    addMcp: (config) => addStdMcp(config.configPath),
+  },
+  'opencode': {
+    name: 'OpenCode',
+    configPath: getOpenCodeConfig(),
+    addMcp: (config) => addOpenCodeMcp(config.configPath),
   },
 };
 
 export function detectPlatforms() {
   return Object.entries(PLATFORMS)
-    .filter(([, p]) => p.configPath && fs.existsSync(path.dirname(p.configPath)))
+    .filter(([id, p]) => {
+      if (!p.configPath) return false;
+      if (fs.existsSync(path.dirname(p.configPath))) return true;
+      if (id === 'opencode') return isOpenCodeInstalled();
+      return false;
+    })
     .map(([id, p]) => ({ id, ...p }));
 }
 
+function isOpenCodeInstalled() {
+  try {
+    const r = spawnSync('opencode', ['--version'], { encoding: 'utf8', timeout: 3000 });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function getOpenCodeConfig() {
+  if (process.platform === 'win32') return path.join(HOME, 'AppData', 'Roaming', 'opencode', 'opencode.json');
+  if (process.platform === 'darwin') return path.join(HOME, 'Library', 'Application Support', 'opencode', 'opencode.json');
+  return path.join(HOME, '.config', 'opencode', 'opencode.json');
+}
+
 function getClaudeDesktopConfig() {
   if (process.platform === 'win32') {
     const base = process.env.LOCALAPPDATA || '';

package/search.js

@@ -1,5 +1,5 @@
 import { embed, cosineSimilarity } from './embedder.js';
-import { getDb } from './db.js';
+import { getDb, blobToVec } from './db.js';
 import { annSearch } from './ann.js';
 
 function applyRatingBoost(db, id, score) {
@@ -28,10 +28,7 @@ export async function search(query, topK = 5) {
       .map(([id, score]) => ({ id, score: applyRatingBoost(db, id, score) }))
       .sort((a, b) => b.score - a.score)
       .slice(0, topK)
-      .map(({ id, score }) => {
-        const skill = db.prepare('SELECT id, name, description, path, source FROM skills WHERE id = ?').get(id);
-        return skill ? { ...skill, score } : null;
-      })
+      .map(({ id, score }) => skillWithSnippet(db, id, score))
       .filter(Boolean);
   }
 
@@ -39,7 +36,7 @@ export async function search(query, topK = 5) {
   const chunks = db.prepare('SELECT skill_id, embedding FROM chunks').all();
   const bestBySkill = new Map();
   for (const chunk of chunks) {
-    const score = cosineSimilarity(queryVec, JSON.parse(chunk.embedding));
+    const score = cosineSimilarity(queryVec, blobToVec(chunk.embedding));
     const prev = bestBySkill.get(chunk.skill_id);
     if (!prev || score > prev) bestBySkill.set(chunk.skill_id, score);
   }
@@ -47,13 +44,18 @@ export async function search(query, topK = 5) {
     .map(([id, score]) => ({ id, score: applyRatingBoost(db, id, score) }))
     .sort((a, b) => b.score - a.score)
     .slice(0, topK)
-    .map(({ id, score }) => {
-      const skill = db.prepare('SELECT id, name, description, path, source FROM skills WHERE id = ?').get(id);
-      return skill ? { ...skill, score } : null;
-    })
+    .map(({ id, score }) => skillWithSnippet(db, id, score))
     .filter(Boolean);
 }
 
+function skillWithSnippet(db, id, score) {
+  const skill = db.prepare('SELECT id, name, description, path, source, content FROM skills WHERE id = ?').get(id);
+  if (!skill) return null;
+  const { content, ...rest } = skill;
+  const snippet = content?.replace(/^---[\s\S]*?---\n?/, '').trim().slice(0, 400) || '';
+  return { ...rest, score, snippet };
+}
+
 export function getContext(nameOrId) {
   const db = getDb();
   let skill = db.prepare('SELECT * FROM skills WHERE id = ?').get(nameOrId);
@@ -108,7 +110,7 @@ export function getImpact(nameOrId) {
     const callers = db.prepare('SELECT from_skill FROM edges WHERE to_skill = ?').all(cur).map(r => r.from_skill);
     queue.push(...callers);
   }
-  visited.delete(id);
+  visited.delete(res.id);
   return [...visited];
 }
 

package/validator.js

@@ -87,6 +87,47 @@ export function validateSkill(filePath) {
   return { ok: errors.length === 0, errors, warnings };
 }
 
+const BUNDLE_ID_RE = /^[a-z0-9][a-z0-9-]{1,63}$/;
+
+export function validateBundle(def) {
+  const errors = [];
+  const warnings = [];
+
+  if (!def.id || typeof def.id !== 'string') {
+    errors.push('Missing required field: id');
+  } else if (!BUNDLE_ID_RE.test(def.id)) {
+    errors.push(`Invalid id "${def.id}". Use lowercase, digits, hyphens (2-64 chars).`);
+  }
+
+  if (!def.name || typeof def.name !== 'string' || def.name.trim().length < 3) {
+    errors.push('Missing or too short field: name (min 3 chars)');
+  }
+
+  if (!def.description || typeof def.description !== 'string' || def.description.trim().length < 15) {
+    errors.push('Missing or too short field: description (min 15 chars)');
+  }
+
+  if (!Array.isArray(def.skills) || def.skills.length < 2) {
+    errors.push('Field "skills" must be an array with at least 2 skill IDs');
+  } else {
+    for (const s of def.skills) {
+      if (typeof s !== 'string' || !BUNDLE_ID_RE.test(s)) {
+        errors.push(`Invalid skill id in bundle: "${s}"`);
+      }
+    }
+  }
+
+  if (def.tags && !Array.isArray(def.tags)) {
+    errors.push('Field "tags" must be an array of strings');
+  }
+
+  if (def.skills?.length > 20) {
+    warnings.push('Bundle has more than 20 skills — consider splitting into sub-bundles');
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
 // CLI: node validator.js <file>
 if (import.meta.url === `file://${process.argv[1]}`) {
   const file = process.argv[2];

package/watcher.js

@@ -25,8 +25,11 @@ export function startWatcher() {
 }
 
 function getSource(filePath, config) {
-  for (const { dir, source } of config.sources) {
-    if (filePath.startsWith(dir)) return source;
+  const normFile = path.resolve(filePath);
+  // Sort longest-first so skills-store/marketplace wins over skills-store
+  const sorted = [...config.sources].sort((a, b) => b.dir.length - a.dir.length);
+  for (const { dir, source } of sorted) {
+    if (normFile.startsWith(path.resolve(dir))) return source;
   }
   return 'unknown';
 }