promptgraph-mcp 2.6.0 → 2.6.2

package/README.md

@@ -14,13 +14,17 @@ Instead of loading every `.md` skill into your context, Claude calls `pg_search`
 ```
 pg_search("refactor without breaking tests")
   → embed query (BGE-Small-EN, 384-dim)
-  → flat cosine similarity over in-memory index
-  → return top skill path + snippet
-  → Claude reads only that file
+  → ANN index (HNSW by default, flat fallback) — topK×4 candidates
+  → BM25 (FTS5) — topK×4 candidates
+  → hybrid merge (embedWeight × cosine + bm25Weight × BM25)
+  → term-overlap reranker (TF frequency + header-position boost)
+  → return topK skill paths + snippets
+  → Claude reads only the files it needs
 ```
 
-**Index:** SQLite + Float32 BLOB embeddings, flat cosine search in-memory.
-No external vector DB, no API key, no cloud.
+**Index:** SQLite + Float32 BLOB embeddings + HNSW approximate nearest neighbor (configurable: `PG_VECTOR_STORE=flat` for brute-force cosine). No external vector DB, no API key, no cloud.
+
+**Reranker:** lightweight term-overlap scorer (binary overlap + TF frequency + header-position boost). Not a cross-encoder — disable via `PG_RERANKER=0`.
 
 **File watcher:** `chokidar` detects `.md` changes and reindexes automatically (MCP server mode only).
 
@@ -34,16 +38,27 @@ No external vector DB, no API key, no cloud.
 | 88 skills reindexed (unchanged, hash match) | **< 1 s** |
 | `pg reindex --fast` (3000 files, keyword only) | **~30 s** |
 | `pg reindex` full embed (3000 files) | **~30 min** |
-| Semantic search query | **< 50 ms** |
+| Semantic search query (HNSW) | **< 50 ms** |
+| Semantic search query (flat, brute-force) | **< 200 ms** |
 | Model size (BGE-Small-EN-v1.5, one-time download) | **23 MB** |
 | Embedding dimensions | **384** |
-| Max chunks per skill | **2** |
+| Max chunks per skill | **8** (configurable: `PG_MAX_CHUNKS`) |
 | Embedding batch size | **256** |
 
 > ONNX model initialization (~2–3 min) happens once on first use and is cached in `~/.claude/.promptgraph/model-cache/`.
 
 ---
 
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PG_VECTOR_STORE` | `hnsw` | Vector index: `hnsw` (ANN, faster at scale) or `flat` (brute-force cosine) |
+| `PG_RERANKER` | `1` | Enable term-overlap reranker after hybrid search (set `0` to disable) |
+| `PG_MAX_CHUNKS` | `8` | Max semantic chunks per skill (higher = more detail per long file, more embedding cost) |
+
+---
+
 ## Quick Start
 
 ```bash
@@ -154,9 +169,15 @@ Claude uses these automatically when the MCP server is running:
 
 ## Search modes
 
-Search falls back to FTS5 automatically if no embeddings exist. When embeddings are
-available, results are a hybrid of semantic similarity (embedding cosine) and keyword
-relevance (BM25) — giving you the best of both approaches.
+Search runs a multi-stage pipeline:
+
+1. **ANN retrieval** — HNSW approximate nearest neighbor (default) or flat brute-force cosine (`PG_VECTOR_STORE=flat`)
+2. **BM25 keyword** — SQLite FTS5
+3. **Hybrid fusion** — weighted sum (embedding × embedWeight + BM25 × bm25Weight, adaptive per query)
+4. **Reranker** — term-overlap rescoring with TF frequency and header-position boost (disable via `PG_RERANKER=0`)
+5. **Rating boost** — success/fail history adjusts final ranking
+
+Falls back to FTS5 only if no embeddings exist.
 
 ---
 

package/chunker.js

@@ -1,6 +1,6 @@
 const CHUNK_SIZE = 800;
 const CHUNK_OVERLAP = 100;
-const MAX_CHUNKS = 2;
+const MAX_CHUNKS = parseInt(process.env.PG_MAX_CHUNKS, 10) || 32;
 
 export function chunkText(text) {
   // Split on markdown h1/h2/h3 headers to preserve semantic boundaries

package/commands/bundle.js

@@ -0,0 +1,150 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+import { spawnSync } from 'child_process';
+
+export default async function handler(args, bin) {
+  if (args[1] === 'update') {
+    const { loadConfig: _lcUpd, SKILLS_STORE_DIR: _ssDir } = await import('../config.js');
+    const { indexSource } = await import('../indexer.js');
+    const cfg = _lcUpd();
+    const githubSources = cfg.sources.filter(s => s.source.startsWith('github:'));
+
+    if (!githubSources.length) { info('No GitHub bundles installed.'); process.exit(0); }
+
+    const targetId = args[2];
+    const toUpdate = targetId
+      ? githubSources.filter(s => s.source.toLowerCase().includes(targetId.toLowerCase()))
+      : githubSources;
+
+    if (!toUpdate.length) { error(`No installed bundle matching "${targetId}"`); process.exit(1); }
+
+    let updated = 0, unchanged = 0, failed = 0;
+
+    for (const src of toUpdate) {
+      const repoName = src.source.replace('github:', '');
+      const dest = src.dir.replace(/[/\\]skills$|[/\\]commands$|[/\\]prompts$/, '');
+      const repoRoot = fs.existsSync(path.join(dest, '.git')) ? dest : src.dir;
+
+      if (!fs.existsSync(path.join(repoRoot, '.git'))) {
+        console.log(chalk.gray(`  skip ${repoName} (not a git repo)`));
+        continue;
+      }
+
+      process.stdout.write(`  Checking ${chalk.white(repoName)}... `);
+
+      const before = spawnSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8', timeout: 30000 }).stdout.trim();
+
+      const fetch = spawnSync('git', ['-C', repoRoot, 'fetch', '--depth=1', 'origin'], { stdio: 'pipe', timeout: 60000 });
+      if (fetch.status !== 0) {
+        console.log(chalk.red('fetch failed'));
+        failed++;
+        continue;
+      }
+      const reset = spawnSync('git', ['-C', repoRoot, 'reset', '--hard', 'origin/HEAD'], { stdio: 'pipe', timeout: 30000 });
+      if (reset.status !== 0) {
+        spawnSync('git', ['-C', repoRoot, 'reset', '--hard', 'origin/main'], { stdio: 'pipe', timeout: 30000 });
+      }
+
+      const after = spawnSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8', timeout: 30000 }).stdout.trim();
+
+      if (before === after) {
+        console.log(chalk.gray('already up to date'));
+        unchanged++;
+        continue;
+      }
+
+      const diff = spawnSync('git', ['-C', repoRoot, 'diff', '--name-only', before, after], { encoding: 'utf8', timeout: 15000 });
+      const changedMd = (diff.stdout || '').split('\n').filter(f => f.endsWith('.md')).length;
+      console.log(chalk.green(`${changedMd} files changed`) + chalk.gray(` (${before.slice(0,7)} → ${after.slice(0,7)})`));
+
+      await indexSource(src.dir, src.source);
+      updated++;
+    }
+
+    console.log();
+    if (updated)   success(`Updated ${updated} bundle(s)`);
+    if (unchanged) info(chalk.gray(`${unchanged} already up to date`));
+    if (failed)    error(`${failed} failed`);
+    process.exit(failed > 0 ? 1 : 0);
+  }
+
+  if (args[1] === 'install') {
+    const { installBundle } = await import('../marketplace.js');
+    const result = await installBundle(args[2]);
+    if (result?.error) { error(result.error); process.exit(1); }
+    success(result.type === 'repo_import' ? `Imported from ${result.repo_url}` : `Installed ${result.installed?.length || 0} skills`);
+    process.exit(0);
+  }
+  if (args[1] === 'add-repo') {
+    const doPush = args[args.length - 1] === '--push';
+    const repoArg = doPush ? args[2] : args[2];
+    if (!repoArg || !repoArg.includes('/')) { error('Usage: pg bundle add-repo <owner/repo> [--push]'); process.exit(1); }
+    const repo = repoArg.replace('https://github.com/', '').replace('.git', '');
+
+    const { detectSkillsDirFromAPI: _detectDir } = await import('../github-import.js');
+    process.stdout.write(chalk.gray(`  Checking ${repo} for skill subdirectory... `));
+    const detected = await _detectDir(repo);
+    if (!detected) {
+      console.log(chalk.red('none found'));
+      error(
+        `Cannot publish: no skill subdirectory found in ${repo}\n` +
+        `  Expected: skills/, prompts/, commands/, agents/, or any folder with .md files\n` +
+        `  Visit: https://github.com/${repo}`
+      );
+      process.exit(1);
+    }
+    console.log(chalk.green(`found: ${detected.label}/`));
+    const name = repo.split('/')[1].replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    const id = repo.replace('/', '-').toLowerCase();
+    const bundle = {
+      id, name, repo_url: repo, author: repo.split('/')[0],
+      description: `Skills from ${repo}`,
+      tags: ['community'],
+      stars: 0
+    };
+    const json = JSON.stringify(bundle, null, 2);
+
+    if (doPush) {
+      const registryDir = path.join(os.tmpdir(), 'pg-push-registry');
+      const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+      const git = (gArgs, opts = {}) => { const r = spawnSync('git', gArgs, { ...opts, env: gitEnv, stdio: 'pipe', timeout: 60000 }); if (r.status !== 0) { error(r.stderr?.toString() || r.stdout?.toString() || 'git error'); process.exit(1); } return r; };
+      if (fs.existsSync(registryDir)) {
+        git(['-C', registryDir, 'pull']);
+      } else {
+        git(['clone', '--depth=1', 'https://github.com/NeiP4n/promptgraph-registry.git', registryDir]);
+      }
+      const regFile = path.join(registryDir, 'registry.json');
+      const reg = JSON.parse(fs.readFileSync(regFile, 'utf8'));
+      if (reg.bundles.find(b => b.id === id)) { error(`Bundle "${id}" already exists`); process.exit(1); }
+      reg.bundles.push(bundle);
+      reg.updated = new Date().toISOString().slice(0, 10);
+      fs.writeFileSync(regFile, JSON.stringify(reg, null, 2) + '\n');
+      fs.writeFileSync(path.join(registryDir, 'bundles', `${id}.json`), json + '\n');
+      git(['-C', registryDir, 'config', 'user.email', 'pg-bot@promptgraph.ai']);
+      git(['-C', registryDir, 'config', 'user.name', 'PromptGraph Bot']);
+      git(['-C', registryDir, 'add', '-A']);
+      git(['-C', registryDir, 'commit', '-m', `bundle: ${name} (${repo})`]);
+      git(['-C', registryDir, 'push']);
+      success(`Bundle "${id}" pushed to registry`);
+    } else {
+      const tmp = path.join(os.tmpdir(), `pg-bundle-${id}.json`);
+      fs.writeFileSync(tmp, json);
+      const { publishBundle } = await import('../marketplace.js');
+      const result = await publishBundle(tmp);
+      fs.unlinkSync(tmp);
+      if (result?.error) { error(result.error); process.exit(1); }
+      if (result.gh_not_installed) {
+        console.log('\n' + result.instructions);
+        console.log(chalk.gray('\nBundle JSON:\n') + chalk.white(json));
+      } else {
+        success(`Bundle proposed! Submit: ${result.submit_url}`);
+      }
+    }
+    process.exit(0);
+  }
+  error('Usage: pg bundle install <id>  |  pg bundle add-repo <owner/repo> [--push]');
+  process.exit(1);
+}

package/commands/doctor.js

@@ -0,0 +1,15 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+
+export default async function handler(args, bin) {
+  const { runDoctor } = await import('../doctor.js');
+  const spin = (await import('../cli.js')).spinner('Checking database...');
+  spin.start();
+  const r = runDoctor();
+  spin.stop();
+  success('Database checked');
+  info(`Removed: ${r.orphanChunks} chunks, ${r.orphanRatings} ratings, ${r.orphanFromEdges + r.danglingEdges} edges`);
+  if (r.duplicatePaths > 0) info(chalk.yellow(`Warning: ${r.duplicatePaths} duplicate paths`));
+  info(chalk.gray(`Now: ${r.totalSkills} skills, ${r.totalChunks} chunks, ${r.totalEdges} edges`));
+  process.exit(0);
+}

package/commands/import.js

@@ -0,0 +1,7 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+
+export default async function handler(args, bin) {
+  const { importFromGitHub } = await import('../github-import.js');
+  await importFromGitHub(args[1]);
+  process.exit(0);
+}

package/commands/init.js

@@ -0,0 +1,37 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import boxen from 'boxen';
+
+export default async function handler(args, bin) {
+  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();
+  console.log(
+    boxen(
+      chalk.white.bold('Add to Claude Code settings.json:') + '\n\n' +
+      chalk.gray(JSON.stringify({ mcpServers: { promptgraph: { command: 'npx', args: ['promptgraph-mcp'] } } }, null, 2)),
+      { padding: 1, borderStyle: 'round', borderColor: '#7C3AED', dimBorder: true }
+    )
+  );
+  process.exit(0);
+}

package/commands/marketplace.js

@@ -0,0 +1,114 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+
+export default async function handler(args, bin) {
+  if (!process.stdout.isTTY) {
+    error('marketplace TUI requires an interactive terminal');
+    process.exit(1);
+  }
+  const { browseMarketplace, browseBundles, installSkill, installBundle } = await import('../marketplace.js');
+  const { loadConfig: _lcMkt } = await import('../config.js');
+  const { getDb: _getDbMkt } = await import('../db.js');
+  const { spinner: spin2 } = await import('../cli.js');
+  const sp = spin2('Fetching marketplace...');
+  sp.start();
+  const [skills, bundles] = await Promise.all([browseMarketplace(1000), browseBundles(1000)]);
+  sp.stop();
+
+  if (skills?.error) { error(skills.error); process.exit(1); }
+
+  const { getCachedCount, refreshCountsInBackground } = await import('../bundle-counts.js');
+  const bundlesWithCounts = (Array.isArray(bundles) ? bundles : []).map(b => {
+    if (!b.repo_url) return b;
+    const cached = getCachedCount(b.repo_url);
+    return cached !== null ? { ...b, skillCount: cached } : b;
+  });
+  refreshCountsInBackground(bundlesWithCounts);
+
+  const installedSet = new Set();
+  try {
+    const cfg = _lcMkt();
+    const db = _getDbMkt();
+    const { SKILLS_STORE_DIR } = await import('../config.js');
+    const githubDir = path.join(SKILLS_STORE_DIR, 'github');
+
+    for (const b of (Array.isArray(bundles) ? bundles : [])) {
+      if (b.repo_url) {
+        const owner = b.repo_url.split('/')[0];
+        const repo  = b.repo_url.split('/')[1];
+        const clonedName = `${owner}-${repo}`;
+        const clonedDir  = path.join(githubDir, clonedName);
+        const dirExists  = fs.existsSync(clonedDir) &&
+          fs.readdirSync(clonedDir).length > 0;
+        if (dirExists) installedSet.add(b.id);
+      } else if (Array.isArray(b.skills)) {
+        const allOnDisk = b.skills.every(sid => {
+          const row = db.prepare('SELECT path FROM skills WHERE id = ?').get(sid);
+          return row && fs.existsSync(row.path);
+        });
+        if (b.skills.length > 0 && allOnDisk) installedSet.add(b.id);
+      }
+    }
+
+    for (const row of db.prepare('SELECT id, path FROM skills WHERE source = ?').all('marketplace')) {
+      if (fs.existsSync(row.path)) installedSet.add(row.id);
+    }
+  } catch {}
+
+  const { runTUI } = await import('../tui.js');
+  const { loadConfig: _lcR, saveConfig: _scR, SKILLS_STORE_DIR: _ssR } = await import('../config.js');
+  const { getDb: _getDbR } = await import('../db.js');
+
+  await runTUI(
+    Array.isArray(skills) ? skills : [],
+    bundlesWithCounts,
+    async (item) => {
+      if (item.type === 'bundle') {
+        const r = await installBundle(item.id);
+        if (r?.error) throw new Error(r.error);
+        installedSet.add(item.id);
+      } else {
+        const r = await installSkill(item.code || item.id);
+        if (r?.error) throw new Error(r.error);
+        installedSet.add(item.id);
+        if (item.code) installedSet.add(item.code);
+      }
+    },
+    installedSet,
+    async (item) => {
+      const cfg = _lcR();
+      const db  = _getDbR();
+      if (item.type === 'bundle' && item.repo_url) {
+        const owner = item.repo_url.split('/')[0];
+        const repo  = item.repo_url.split('/')[1];
+        const clonedName = `${owner}-${repo}`;
+        const clonedDir  = path.join(_ssR, 'github', clonedName);
+        if (fs.existsSync(clonedDir)) fs.rmSync(clonedDir, { recursive: true, force: true });
+        const src = `github:${clonedName}`;
+        cfg.sources = cfg.sources.filter(s => s.source !== src && !s.dir.startsWith(clonedDir));
+        _scR(cfg);
+        db.prepare('DELETE FROM skills WHERE source = ?').run(src);
+        db.prepare('DELETE FROM chunks WHERE skill_id NOT IN (SELECT id FROM skills)').run();
+      } else if (item.type === 'bundle') {
+        const mktDir = path.join(_ssR, 'marketplace');
+        for (const sid of (item.skills || [])) {
+          const row = db.prepare('SELECT path FROM skills WHERE id = ?').get(sid);
+          if (row?.path && fs.existsSync(row.path)) fs.unlinkSync(row.path);
+          db.prepare('DELETE FROM skills WHERE id = ?').run(sid);
+          db.prepare('DELETE FROM chunks WHERE skill_id = ?').run(sid);
+        }
+      } else {
+        const row = db.prepare('SELECT path FROM skills WHERE id = ?').get(item.id);
+        if (row?.path && fs.existsSync(row.path)) fs.unlinkSync(row.path);
+        db.prepare('DELETE FROM skills WHERE id = ?').run(item.id);
+        db.prepare('DELETE FROM chunks WHERE skill_id = ?').run(item.id);
+      }
+      installedSet.delete(item.id);
+      if (item.code) installedSet.delete(item.code);
+    }
+  );
+  process.exit(0);
+}

package/commands/reindex.js

@@ -0,0 +1,10 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+
+export default async function handler(args, bin) {
+  const { indexAll } = await import('../indexer.js');
+  const fast = args.includes('--fast');
+  if (fast) info(chalk.yellow('Fast mode — skipping embeddings (keyword search only)'));
+  await indexAll({ fast });
+  process.exit(0);
+}

package/commands/search.js

@@ -0,0 +1,55 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import { VALID_TRUST_LEVELS, TRUST_LEVEL_BOOST } from '../marketplace.js';
+
+export default async function handler(args, bin) {
+  const trustFilter = args.find(a => a.startsWith('--trust='));
+  const filteredArgs = args.filter(a => !a.startsWith('--trust='));
+  const query = filteredArgs.slice(1).join(' ');
+  if (!query) { error('Usage: ' + bin + ' search <query> [--trust=verified]'); process.exit(1); }
+
+  if (trustFilter) {
+    const level = trustFilter.split('=')[1];
+    if (!VALID_TRUST_LEVELS.includes(level)) {
+      error('Invalid trust level. Valid: ' + VALID_TRUST_LEVELS.join(', '));
+      process.exit(1);
+    }
+  }
+
+  const { search: searchSkills } = await import('../search.js');
+  const { getDb } = await import('../db.js');
+  const { getByTrustLevel } = await import('../marketplace.js');
+  const spin = (await import('../cli.js')).spinner('Searching...');
+  spin.start();
+  let results = await searchSkills(query, 10);
+  spin.stop();
+
+  // Apply trust filter after search
+  if (trustFilter) {
+    const level = trustFilter.split('=')[1];
+    const entries = await getByTrustLevel(level);
+    const allowed = new Set(entries.map(e => e.id));
+    results = results.filter(r => allowed.has(r.id));
+  }
+
+  // Enrich results with trust level
+  const db = getDb();
+  const enriched = results.map(s => {
+    const re = db.prepare('SELECT trust_level FROM registry_entries WHERE id = ?').get(s.id);
+    return { ...s, trustLevel: re ? re.trust_level : 'unknown' };
+  });
+
+  if (!enriched.length) { info('No results for: ' + query); process.exit(0); }
+  const purple = chalk.hex('#7C3AED');
+  console.log();
+  enriched.forEach((s, i) => {
+    const score = chalk.dim((s.score * 100).toFixed(0) + '%');
+    const trustBadge = s.trustLevel !== 'unknown' && s.trustLevel !== 'community'
+      ? ' ' + purple(s.trustLevel) : '';
+    console.log('  ' + chalk.dim(String(i + 1) + '.') + ' ' + chalk.bold.white(s.name) + trustBadge + '  ' + score);
+    console.log('     ' + chalk.dim(s.description || ''));
+    console.log('     ' + purple(s.source) + '  ' + chalk.dim(s.path));
+    console.log();
+  });
+  process.exit(0);
+}

package/commands/setup.js

@@ -0,0 +1,19 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+
+export default async function handler(args, bin) {
+  const { detectPlatforms, PLATFORMS } = await import('../platform.js');
+  const platformId = args[1];
+  if (!platformId) {
+    section('Detected platforms');
+    detectPlatforms().forEach(p => info(`${chalk.white(p.id.padEnd(16))} ${chalk.gray(p.name)}`));
+    console.log(chalk.gray('\n  Usage: promptgraph-mcp setup <platform-id>\n'));
+  } else {
+    const platform = PLATFORMS[platformId];
+    if (!platform) { error(`Unknown platform: ${platformId}`); process.exit(1); }
+    platform.addMcp(platform);
+    success(`Registered in ${chalk.white(platform.name)}`);
+    info(chalk.gray(platform.configPath));
+  }
+  process.exit(0);
+}

package/commands/status.js

@@ -0,0 +1,110 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+import boxen from 'boxen';
+
+export default async function handler(args, bin) {
+  const { loadConfig: _lc } = await import('../config.js');
+  const { getDb } = await import('../db.js');
+  const { fetchText } = await import('../marketplace.js');
+  const purple = chalk.hex('#7C3AED');
+  const cfg = _lc();
+  const db = getDb();
+
+  const sourceCounts = new Map();
+  for (const row of db.prepare('SELECT source, COUNT(*) as n FROM skills GROUP BY source').all()) {
+    sourceCounts.set(row.source, row.n);
+  }
+  const totalSkills = db.prepare('SELECT COUNT(*) as n FROM skills').get().n;
+  const totalBundles = cfg.sources.filter(s => s.source.startsWith('github:')).length;
+
+  let marketSkills = 0, marketBundles = 0;
+  try {
+    const REGISTRY_URL = 'https://raw.githubusercontent.com/NeiP4n/promptgraph-registry/main/registry.json';
+    const reg = JSON.parse(await fetchText(REGISTRY_URL));
+    marketSkills = reg.skills?.length || 0;
+    marketBundles = reg.bundles?.length || 0;
+  } catch {}
+
+  console.log();
+  console.log('  ' + purple.bold('◆ PromptGraph Status'));
+  console.log('  ' + chalk.gray('─'.repeat(56)));
+  console.log();
+
+  const skillsLine = chalk.bold.white(`${totalSkills} skills`) +
+    (marketSkills ? chalk.gray(` / ${marketSkills} in registry`) : '');
+  const bundlesLine = chalk.bold.white(`${totalBundles} repos`) +
+    (marketBundles ? chalk.gray(` / ${marketBundles} in marketplace`) : '');
+  console.log('  ' + skillsLine + chalk.gray('   ·   ') + bundlesLine);
+  console.log();
+
+  const githubSources = cfg.sources.filter(s => s.source.startsWith('github:'));
+  const localSources  = cfg.sources.filter(s => !s.source.startsWith('github:'));
+
+  if (localSources.length) {
+    console.log('  ' + purple('📁  Local'));
+    for (const s of localSources) {
+      const n = sourceCounts.get(s.source) || 0;
+      const exists = fs.existsSync(s.dir);
+      const label = exists ? chalk.white(s.source) : chalk.gray(s.source + ' (missing)');
+      console.log('    ' + label + chalk.gray(`  ${n} skills  ·  ${s.dir}`));
+    }
+    console.log();
+  }
+
+  if (githubSources.length) {
+    console.log('  ' + purple('🌐  GitHub repos'));
+    for (const s of githubSources) {
+      const n = sourceCounts.get(s.source) || 0;
+      const repoName = s.source.replace('github:', '');
+      const exists = fs.existsSync(s.dir);
+      const label = exists ? chalk.white(repoName) : chalk.gray(repoName + ' (not cloned)');
+      console.log('    ' + label + chalk.gray(`  ${n} skills`));
+      console.log('      ' + chalk.dim(s.dir));
+    }
+    console.log();
+  }
+
+  const marketplaceDir = path.join(os.homedir(), '.claude', 'skills-store', 'marketplace');
+  const installedBundles = fs.existsSync(marketplaceDir)
+    ? fs.readdirSync(marketplaceDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name)
+    : [];
+
+  if (installedBundles.length) {
+    let registryBundles = [];
+    try {
+      const REGISTRY_URL = 'https://raw.githubusercontent.com/NeiP4n/promptgraph-registry/main/registry.json';
+      const text = await fetchText(REGISTRY_URL);
+      registryBundles = JSON.parse(text).bundles || [];
+    } catch {}
+
+    console.log('  ' + purple('📦  Installed marketplace bundles'));
+    for (const b of installedBundles) {
+      const bundle = registryBundles.find(rb => rb.id === b);
+      const name = bundle ? chalk.white.bold(bundle.name || b) : chalk.white(b);
+      const cat  = bundle?.category ? chalk.dim(` [${bundle.category}]`) : '';
+      const n    = sourceCounts.get('marketplace') || 0;
+      console.log(`    ${name}${cat}  ${chalk.gray(n + ' skills')}`);
+    }
+    console.log();
+  }
+
+  const emptyRepos = githubSources.filter(s => (sourceCounts.get(s.source) || 0) === 0 && fs.existsSync(s.dir));
+  if (emptyRepos.length) {
+    console.log('  ' + chalk.yellow(`⚠  ${emptyRepos.length} repo(s) not indexed`) + chalk.gray('  →  run: ') + chalk.cyan(`${bin} reindex`));
+    console.log();
+  }
+
+  console.log(
+    boxen(
+      chalk.dim('full reindex   ') + chalk.cyan(`${bin} reindex`) + '\n' +
+      chalk.dim('install bundle ') + chalk.cyan(`${bin} bundle install <id>`) + '\n' +
+      chalk.dim('browse market  ') + 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);
+}

package/commands/train.js

@@ -0,0 +1,18 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+
+export default async function handler(args, bin) {
+  const { train: trainModel } = await import('../src/filter/train.js');
+  const spin = (await import('../cli.js')).spinner('Training classifier...');
+  spin.start();
+  try {
+    const model = await trainModel();
+    spin.stop();
+    success(`Classifier trained (${model.counts.good} good, ${model.counts.bad} bad examples)`);
+  } catch (e) {
+    spin.stop();
+    error(`Training failed: ${e.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}

package/commands/update.js

@@ -0,0 +1,49 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+
+export default async function handler(args, bin) {
+  const { spawnSync } = await import('child_process');
+  const { createRequire } = await import('module');
+  const https = (await import('https')).default;
+  const req = createRequire(import.meta.url);
+  const currentVersion = req('../package.json').version;
+
+  const spin = (await import('../cli.js')).spinner('Checking latest version...');
+  spin.start();
+  let latest = null;
+  try {
+    latest = await new Promise((res, rej) => {
+      const r = https.get('https://registry.npmjs.org/promptgraph-mcp/latest',
+        { headers: { Accept: 'application/json' }, timeout: 8000 },
+        (resp) => {
+          let d = ''; resp.setEncoding('utf8');
+          resp.on('data', c => d += c);
+          resp.on('end', () => { try { res(JSON.parse(d).version); } catch { rej(new Error('bad response')); } });
+        }
+      );
+      r.on('error', rej);
+      r.on('timeout', () => { r.destroy(new Error('timeout')); });
+    });
+  } catch {}
+  spin.stop();
+
+  if (!latest) { error('Could not reach npm registry. Check your network.'); process.exit(1); }
+  if (latest === currentVersion) {
+    success(`Already on latest version ${chalk.white.bold('v' + currentVersion)}`);
+    process.exit(0);
+  }
+
+  info(`Current: ${chalk.gray('v' + currentVersion)}  →  Latest: ${chalk.white.bold('v' + latest)}`);
+  const updateSpin = (await import('../cli.js')).spinner(`Installing promptgraph-mcp@latest (v${latest})...`);
+  updateSpin.start();
+  const result = spawnSync('npm', ['install', '-g', 'promptgraph-mcp@latest'], { encoding: 'utf8', stdio: 'pipe', shell: true });
+  updateSpin.stop();
+
+  if (result.status !== 0) {
+    error('Update failed:');
+    console.log(chalk.gray(result.stderr || result.stdout));
+    process.exit(1);
+  }
+  success(`Updated to ${chalk.white.bold('v' + latest)}`);
+  process.exit(0);
+}

package/commands/validate.js

@@ -0,0 +1,63 @@
+import { colors, banner, success, error, info, section, table } from '../cli.js';
+import chalk from 'chalk';
+import fs from 'fs';
+
+export default async function handler(args, bin) {
+  const { validateSkill } = await import('../validator.js');
+  const file = args[1];
+  if (!file) { error('Usage: ' + bin + ' validate <skill.md>'); process.exit(1); }
+
+  const raw = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+
+  if (raw) {
+    const { filterWithClassifier, isSkillFile: _isSkill } = await import('../parser.js');
+    const { hardFilter } = await import('../src/filter/hard-filter.js');
+    const { loadModel } = await import('../src/filter/train.js');
+    const { embed } = await import('../embedder.js');
+    const { classify } = await import('../src/filter/classifier.js');
+
+    const hfResult = hardFilter(file, raw);
+    const willIndex = _isSkill(file, raw);
+    const scoreLabel = willIndex ? chalk.green('✓ will be indexed') : chalk.red('✗ will be skipped by indexer');
+    console.log(chalk.bold('\n  Indexing check: ') + scoreLabel);
+
+    const signals = [];
+    if (!hfResult.pass) {
+      signals.push(chalk.red(`✗ hard filter: ${hfResult.reason}`));
+    } else {
+      signals.push(chalk.green('✓ hard filter passed'));
+    }
+
+    const centroids = loadModel();
+    if (centroids) {
+      try {
+        const vec = await embed(raw);
+        const decision = classify(vec, centroids, raw, file);
+        const pct = (decision.score * 100).toFixed(0);
+        if (decision.label === 'skill') signals.push(chalk.green(`✓ classifier: skill (${pct}%)`));
+        else if (decision.label === 'unsure') signals.push(chalk.yellow(`? classifier: unsure (${pct}%)`));
+        else signals.push(chalk.red(`✗ classifier: reject (${pct}%)`));
+      } catch {
+        signals.push(chalk.gray('  classifier: embed failed (skip)'));
+      }
+    } else {
+      signals.push(chalk.gray('  classifier: no model (run `pg train`)'));
+    }
+
+    if (signals.length) {
+      signals.forEach(s => console.log('    ' + s));
+    }
+    console.log();
+  }
+
+  const result = validateSkill(file);
+  result.warnings.forEach(w => console.log(chalk.yellow('⚠') + '  ' + chalk.gray(w)));
+  if (result.ok) {
+    success('Skill is valid — ready to publish');
+    process.exit(0);
+  } else {
+    error('Validation failed:');
+    result.errors.forEach(e => console.log('   ' + chalk.red('•') + ' ' + e));
+    process.exit(1);
+  }
+}

package/index.js

@@ -87,7 +87,7 @@ const COMMAND_MAP = {
 
 if (COMMAND_MAP[args[0]]) {
   const mod = await import(COMMAND_MAP[args[0]])
-  await mod.handler(args, bin)
+  await mod.default(args, bin)
   // handler calls process.exit() internally
 }
 

package/marketplace.js

@@ -561,9 +561,38 @@ export function pruneInvalidRepos() {
 
 // ── Trust level system ─────────────────────────────────────────────────────────
 const VALID_TRUST_LEVELS = ['verified', 'official', 'community', 'trusted', 'unknown']
+const TRUST_LEVEL_BOOST = { verified: 1.15, official: 1.10, trusted: 1.05, community: 1.0, unknown: 0.95 }
+
+// Popularity = log(downloads+1) × (rating+1), then decayed by age (days since last_update, halved every 180 days)
+function calcPopularity(downloads = 0, rating = 0, lastUpdateStr = null) {
+  const logDownloads = Math.log10((downloads || 0) + 1)
+  const ratingFactor = ((rating || 0) + 1) / 6  // normalised to 0–1
+  let pop = logDownloads * ratingFactor * 100
+
+  if (lastUpdateStr) {
+    const daysSince = (Date.now() - new Date(lastUpdateStr + 'Z').getTime()) / 86400000
+    if (daysSince > 0) {
+      pop *= Math.pow(0.5, daysSince / 180)  // half-life 180 days
+    }
+  }
+  return Math.round(pop * 100) / 100
+}
 
-function calcPopularity(downloads = 0, rating = 0) {
-  return Math.round((downloads || 0) * ((rating || 0) + 1) * 100) / 100
+// Auto-promote threshold: downloads at which a skill graduates to the next trust level
+const AUTO_PROMOTE_THRESHOLDS = [
+  { minDownloads: 10000, level: 'verified' },
+  { minDownloads: 1000,  level: 'official' },
+  { minDownloads: 100,   level: 'trusted' },
+]
+
+function autoPromote(downloads, currentLevel) {
+  const rank = VALID_TRUST_LEVELS.indexOf(currentLevel || 'unknown')
+  for (const t of AUTO_PROMOTE_THRESHOLDS) {
+    if (downloads >= t.minDownloads && VALID_TRUST_LEVELS.indexOf(t.level) > rank) {
+      return t.level
+    }
+  }
+  return null
 }
 
 export async function setTrustLevel(name, level) {
@@ -586,28 +615,36 @@ export async function getByTrustLevel(level) {
     return { error: `Invalid trust level "${level}". Must be one of: ${VALID_TRUST_LEVELS.join(', ')}` }
   }
   if (level) {
-    return db.prepare('SELECT * FROM registry_entries WHERE trust_level = ? ORDER BY id').all(level)
+    return db.prepare('SELECT * FROM registry_entries WHERE trust_level = ? ORDER BY downloads DESC, popularity DESC').all(level)
   }
-  return db.prepare('SELECT * FROM registry_entries ORDER BY id').all()
+  return db.prepare('SELECT * FROM registry_entries ORDER BY downloads DESC, popularity DESC').all()
 }
 
 export async function incrementDownloads(name) {
   const db = getDb()
   const id = String(name)
-  const existing = db.prepare('SELECT downloads, rating FROM registry_entries WHERE id = ?').get(id)
+  const existing = db.prepare('SELECT downloads, rating, last_update, trust_level FROM registry_entries WHERE id = ?').get(id)
   if (existing) {
     const newDownloads = (existing.downloads || 0) + 1
-    const pop = calcPopularity(newDownloads, existing.rating || 0)
+    const pop = calcPopularity(newDownloads, existing.rating || 0, existing.last_update)
     db.prepare('UPDATE registry_entries SET downloads = ?, popularity = ?, last_update = datetime(\'now\') WHERE id = ?')
       .run(newDownloads, pop, id)
+
+    // Auto-promote if threshold crossed
+    const newLevel = autoPromote(newDownloads, existing.trust_level)
+    if (newLevel) {
+      db.prepare('UPDATE registry_entries SET trust_level = ? WHERE id = ?').run(newLevel, id)
+    }
   } else {
     const pop = calcPopularity(1, 0)
-    db.prepare('INSERT INTO registry_entries (id, downloads, popularity, last_update) VALUES (?, 1, ?, datetime(\'now\'))')
+    db.prepare('INSERT INTO registry_entries (id, downloads, popularity, trust_level, last_update) VALUES (?, 1, ?, \'unknown\', datetime(\'now\'))')
       .run(id, pop)
   }
   return { ok: true }
 }
 
+export { VALID_TRUST_LEVELS, TRUST_LEVEL_BOOST, calcPopularity, autoPromote }
+
 export async function rateSkill(name, rating) {
   const db = getDb()
   if (typeof rating !== 'number' || rating < 0 || rating > 5) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "promptgraph-mcp",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "files": [
     "*.js",
-    "src/**/*.js",
+    "commands/",
+    "src/",
     "README.md"
   ],
   "main": "index.js",

package/search.js

@@ -1,6 +1,7 @@
 import { embed, cosineSimilarity } from './embedder.js';
 import { getDb, blobToVec } from './db.js';
 import { annSearch } from './ann.js';
+import { TRUST_LEVEL_BOOST } from './marketplace.js';
 
 function getHybridWeights(query) {
   const hasTechTerms = /[A-Z]|\d/.test(query);
@@ -10,11 +11,25 @@ function getHybridWeights(query) {
 
 function applyRatingBoost(db, id, score) {
   const r = db.prepare('SELECT success, fail FROM ratings WHERE skill_id = ?').get(id);
+  let boost = 1.0;
   if (r && (r.success + r.fail) > 3) {
-    const rating = r.success / (r.success + r.fail);
-    return score * (0.85 + 0.15 * rating);
+    boost *= (0.85 + 0.15 * (r.success / (r.success + r.fail)));
   }
-  return score;
+
+  // Trust level boost (verified/official/trusted rank higher)
+  const re = db.prepare('SELECT trust_level, popularity FROM registry_entries WHERE id = ?').get(id);
+  if (re) {
+    boost *= (TRUST_LEVEL_BOOST[re.trust_level] || 1.0);
+    // Popularity bump: top 20% of skills get +5%, rest unchanged
+    if (re.popularity > 0) {
+      const top20 = db.prepare('SELECT popularity FROM registry_entries ORDER BY popularity DESC LIMIT 1').get();
+      if (top20 && re.popularity >= top20.popularity * 0.2) {
+        boost *= 1.05;
+      }
+    }
+  }
+
+  return score * boost;
 }
 
 function normalizeBM25(raw) {
@@ -114,13 +129,13 @@ export async function search(query, topK = 5) {
   if (rerankerEnabled) {
     const { Reranker } = await import('./src/reranker/reranker.js')
     const reranker = new Reranker()
-    const topN = ordered.slice(0, 20)
+    const topN = ordered.slice(0, Math.max(50, topK * 6))
       .map(({ id, score }) => {
         const s = skillWithSnippet(db, id, score)
         return s ? { id, text: s.snippet, score } : null
       })
       .filter(Boolean)
-    const reranked = await reranker.rerank(query, topN)
+    const reranked = await reranker.rerank(query, topN, topK)
     return reranked.map(r => skillWithSnippet(db, r.id, applyRatingBoost(db, r.id, r.score))).filter(Boolean)
   }
 

package/src/reranker/reranker.js

@@ -1,28 +1,92 @@
+// Term-overlap reranker with phrase matching and IDF-like weighting.
+// Replace `rerank()` with a cross-encoder (BGE Reranker / MiniLM via ONNX)
+// for deeper semantic reranking. This class is the plug-in point.
 export class Reranker {
   constructor(modelName = 'default', device = 'cpu') {
     this.modelName = modelName
     this.device = device
   }
 
-  // Term-overlap boost on top of hybrid search scores
-  // This is a lightweight reranker that ranks by term overlap ratio.
-  // Replace with BGE Reranker / MiniLM cross-encoder via ONNX for deeper semantic reranking.
-  async rerank(query, results) {
+  rerank(query, results, topK = 5) {
     if (!results || results.length === 0) return []
 
-    const queryTerms = (query.toLowerCase().match(/\w+/g) || []).slice(0, 50)
-    const queryTermCount = queryTerms.length || 1
+    const rawTerms = (query.toLowerCase().match(/\w+/g) || [])
+    if (rawTerms.length === 0) return results.slice(0, topK)
 
-    const scored = results.map(r => {
-      const text = (r.text || '').toLowerCase()
-      const termOverlap = queryTerms.filter(t => text.includes(t)).length / queryTermCount
+    const unigrams = rawTerms
+    const bigrams = []
+    const trigrams = []
+    for (let i = 0; i < rawTerms.length - 1; i++) bigrams.push(rawTerms[i] + ' ' + rawTerms[i + 1])
+    for (let i = 0; i < rawTerms.length - 2; i++) trigrams.push(rawTerms[i] + ' ' + rawTerms[i + 1] + ' ' + rawTerms[i + 2])
+
+    const texts = results.map(r => (r.text || '').toLowerCase())
+
+    // Term doc-frequency
+    const termDf = {}
+    for (const t of unigrams) {
+      termDf[t] = texts.filter(txt => txt.includes(t)).length
+    }
+    const nResults = results.length
+
+    // First pass: compute raw tfIdf for each result
+    const tfIdfValues = texts.map(text => {
+      let sum = 0
+      for (const term of unigrams) {
+        const df = termDf[term] || 1
+        const idf = 1 + Math.log10((nResults + 1) / df)
+        let idx = -1
+        let count = 0
+        while ((idx = text.indexOf(term, idx + 1)) !== -1) count++
+        sum += count * idf
+      }
+      return sum
+    })
+
+    const maxTfIdf = Math.max(...tfIdfValues, 1)
+
+    const scored = results.map((r, idx) => {
+      const text = texts[idx]
+      const lines = text.split('\n')
+
+      // 1. N-gram overlap
+      const unigramMatch = unigrams.filter(t => text.includes(t)).length / unigrams.length
+      const bigramMatch = bigrams.length > 0 ? bigrams.filter(b => text.includes(b)).length / bigrams.length : 0
+      const trigramMatch = trigrams.length > 0 ? trigrams.filter(t => text.includes(t)).length / trigrams.length : 0
+      const ngramScore = 0.4 * unigramMatch + 0.35 * bigramMatch + 0.25 * trigramMatch
+
+      // 2. IDF-weighted TF (normalised by max across results)
+      const tfIdfScore = tfIdfValues[idx] / maxTfIdf
+
+      // 3. Exact phrase proximity — consecutive same-order term matches
+      let phraseBoost = 0
+      if (rawTerms.length >= 2) {
+        const textWords = text.split(/\s+/)
+        let bestRun = 0
+        for (let i = 0; i < textWords.length - rawTerms.length + 1; i++) {
+          let matchLen = 0
+          for (let j = 0; j < rawTerms.length; j++) {
+            if (textWords[i + j] === rawTerms[j]) matchLen++
+            else break
+          }
+          if (matchLen >= 2) bestRun = Math.max(bestRun, matchLen)
+        }
+        phraseBoost = bestRun / rawTerms.length
+      }
+
+      // 4. Header position boost
+      const headerText = lines.slice(0, 3).join(' ').toLowerCase()
+      const headerOverlap = unigrams.filter(t => headerText.includes(t)).length / unigrams.length
+
+      // Blend
+      const overlapScore = 0.25 * ngramScore + 0.25 * tfIdfScore + 0.25 * phraseBoost + 0.15 * headerOverlap + 0.10 * unigramMatch
 
       return {
-        ...r,
-        score: 0.8 * (r.score || 0) + 0.2 * termOverlap,
+        id: r.id,
+        text: r.text,
+        score: 0.70 * (r.score || 0) + 0.30 * overlapScore,
       }
     })
 
-    return scored.sort((a, b) => b.score - a.score).slice(0, 5)
+    return scored.sort((a, b) => b.score - a.score).slice(0, topK)
   }
 }

package/src/store/index.js

@@ -7,7 +7,7 @@ export function getStore(type = null) {
   if (_store) return _store;
 
   if (!type) {
-    type = process.env.PG_VECTOR_STORE || 'flat';
+    type = process.env.PG_VECTOR_STORE || 'hnsw';
   }
 
   _store = type === 'hnsw' ? new HNSWVectorStore() : new FlatVectorStore();