promptgraph-mcp 2.1.4 → 2.1.5

package/README.md

@@ -1,54 +1,59 @@
 # PromptGraph
 
-**Stop burning 50,000 tokens on skills you won't use.**
+**Semantic skill router and marketplace for Claude Code.**
 
-PromptGraph is an MCP server that gives Claude Code a semantic skill index — vector search, skill graph, and a community marketplace. Instead of cramming every `.md` into your system prompt, Claude finds and loads only the one skill it needs.
+Instead of loading every `.md` skill into your context, Claude calls `pg_search` and loads only the one skill it needs.
 
 [![npm](https://img.shields.io/npm/v/promptgraph-mcp?color=7C3AED&label=npm)](https://www.npmjs.com/package/promptgraph-mcp)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ---
 
-## Why
-
-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. Claude calls `pg_search` → gets the right skill path + a content snippet → reads only that file when needed.
+## How it works
 
 ```
-Before:  route across all 40 skills  →  40 × read overhead
-After:   1 pg_search call + snippet  →  read only what you need
+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
 ```
 
+**Index:** SQLite + Float32 BLOB embeddings, flat cosine search in-memory.
+No external vector DB, no API key, no cloud.
+
+**File watcher:** `chokidar` detects `.md` changes and reindexes automatically (MCP server mode only).
+
 ---
 
-## Features
+## Benchmarks (measured on real hardware)
 
-- 🔍 **Semantic search** — finds skills by meaning, not just keywords (HNSW, O(log N))
-- 📦 **Marketplace** — browse and install community skills with one command
-- 🧩 **Skill bundles** — install curated packs (e.g. `engineering-essentials`)
-- 🔗 **Dependency graph** — tracks which skills call other skills (`pg_callers`, `pg_impact`)
-- ⚡ **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, OpenCode, Cursor, Windsurf, and any MCP client
+| Operation | Result |
+|---|---|
+| 88 new skills indexed (first time, cold ONNX) | **49.5 s** |
+| 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** |
+| Model size (BGE-Small-EN-v1.5, one-time download) | **23 MB** |
+| Embedding dimensions | **384** |
+| Max chunks per skill | **2** |
+| Embedding batch size | **256** |
+
+> ONNX model initialization (~2–3 min) happens once on first use and is cached in `~/.claude/.promptgraph/model-cache/`.
 
 ---
 
 ## Quick Start
 
 ```bash
-# one-time global install (recommended — faster than npx every time)
 npm install -g promptgraph-mcp@latest
 pg init
-
-# or without installing
-npx promptgraph-mcp init
 ```
 
-`init` downloads the embedding model (~23 MB, once), indexes your skills, and prints the config to paste into `settings.json`.
+`pg init` downloads the model (~23 MB, once), indexes your local skills, and prints the config snippet.
 
-### Add to Claude Code (`~/.claude/settings.json`)
+### Claude Code (`~/.claude/settings.json`)
 
 ```json
 {
@@ -61,7 +66,11 @@ npx promptgraph-mcp init
 }
 ```
 
-### Add to OpenCode (`~/.config/opencode/opencode.json`)
+### Claude Desktop / Cursor / Windsurf / Cline
+
+Same config — any MCP-compatible client works.
+
+### OpenCode (`~/.config/opencode/opencode.json`)
 
 ```json
 {
@@ -75,112 +84,104 @@ npx promptgraph-mcp init
 }
 ```
 
-> `pg setup` auto-detects OpenCode and writes this config for you.
+> `pg setup` auto-detects installed clients and writes config automatically.
 
-### Move your skills out of `commands/`
+---
+
+## CLI
 
 ```bash
-mkdir -p ~/.claude/skills-store
-mv ~/.claude/commands/*.md ~/.claude/skills-store/
-mv ~/.claude/skills-store/pg.md ~/.claude/commands/   # keep only the router
+pg init                    # first-time setup
+pg status                  # show indexed sources, repos, installed bundles
+pg reindex                 # full reindex (semantic search, slow)
+pg reindex --fast          # keyword-only reindex (~30s, no embeddings)
+pg search "deploy"         # search from terminal
+pg import owner/repo       # clone and index any GitHub repo of .md skills
+pg marketplace             # browse skills by category
+pg marketplace bundles     # browse curated bundles
+pg bundle install <id>     # install a bundle
+pg validate my-skill.md    # validate before publishing
+pg doctor                  # clean orphaned DB rows
+pg update                  # update to latest version
 ```
 
 ---
 
 ## Marketplace
 
-Browse and install community skills without leaving your terminal:
-
 ```bash
-pg marketplace        # browse skills
-pg marketplace bundles  # browse bundles
-```
-
-Or ask Claude directly:
-
-```
-install pg-a1b2c3          # by code
-install systematic-debugging  # by name
+pg marketplace             # 🛠 Engineering  💻 Coding  🤖 AI Tools  🔒 Security  🎨 Creative
+pg marketplace Engineering # filter by category
+pg marketplace bundles     # install whole repos as skill bundles
 ```
 
-**Publish your own skill:**
+**Bundles** install an entire GitHub repo as a skill source — auto-detects `skills/`, `commands/`, `prompts/` subdirectory.
 
+Example:
 ```bash
-pg publish ~/.claude/skills-store/my-skill.md
+pg bundle install elementalsouls-claude-bughunter   # 88 security skills from GitHub
+pg bundle install engineering-essentials            # 4 curated workflow skills
 ```
 
-> Skills are validated automatically — dangerous patterns, prompt injection, and junk are rejected by CI before they enter the registry.
-
----
+**Publish your skill** (auto-validated, no manual review):
 
-## CLI
+Open an issue on [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) with label `skill-submission`. The bot fetches, validates, commits, and closes the issue automatically.
 
-```bash
-pg init             # first-time setup
-pg reindex          # re-index all skills
-pg search "deploy"  # search from terminal
-pg list             # list all indexed skills
-pg marketplace      # browse registry
-pg import owner/repo   # import any GitHub repo full of .md skills
-pg validate my-skill.md
-pg doctor           # clean up orphaned data
-```
+Anti-spam checks: min 200 chars, 2+ headers, code/bullets required, prompt injection detection, duplicate URL/description check, 3 submissions per user per 24h.
 
 ---
 
-## MCP Tools (used by Claude automatically)
+## MCP Tools
+
+Claude uses these automatically when the MCP server is running:
 
 | Tool | What it does |
 |---|---|
-| `pg_search` | Semantic skill search by task description |
+| `pg_search` | Semantic search by task description |
 | `pg_list` | List all indexed skills |
 | `pg_context` | Full skill details + callers/callees |
 | `pg_callers` | Which skills reference this one |
 | `pg_callees` | Which skills this one calls |
 | `pg_impact` | What breaks if this skill changes |
 | `pg_marketplace_browse` | Browse community registry |
-| `pg_marketplace_install` | Install a skill by code, id, or name |
+| `pg_marketplace_install` | Install a skill by code or name |
 | `pg_bundle_browse` | Browse skill bundles |
 | `pg_bundle_install` | Install a bundle |
-| `pg_top_rated` | Highest-rated local skills |
-| `pg_rate` | Rate a skill (success/fail) |
+| `pg_top_rated` | Highest-rated skills |
+| `pg_rate` | Rate a skill after use |
 
 ---
 
-## Token Savings
+## Search modes
 
-| | Before PromptGraph | After PromptGraph |
+| Mode | How | Quality |
 |---|---|---|
-| Skills in system prompt | All 40+ every session | 1 router (~150 tokens) |
-| Tokens per session | 20,000 – 50,000 | ~300 + 1 skill on demand |
-| Skills you can have | ~30 before it gets painful | Unlimited |
+| After `pg reindex` | Cosine similarity on 384-dim BGE vectors | Semantic — finds by meaning |
+| After `pg reindex --fast` | SQLite FTS5 BM25 | Keyword — exact word match |
 
----
+Search falls back to FTS5 automatically if no embeddings exist.
 
-## How It Works
+---
 
-```
-pg_search("refactor without breaking tests")
-  → embed query  →  HNSW ANN search  →  rank by cosine + rating boost
-  → return top skill path
-  → Claude reads only that file
-```
+## Skill filtering
 
-Embeddings are stored in SQLite. The HNSW index ([vectra](https://github.com/Stevenic/vectra)) keeps search sub-millisecond even at thousands of skills. Skills are re-indexed automatically via `chokidar` file watcher.
+When importing a GitHub repo, PromptGraph:
+1. Looks for a dedicated subdir (`skills/`, `commands/`, `prompts/`, `agents/`, `templates/`, etc.) — indexes only that dir if found with 2+ `.md` files
+2. Falls back to repo root with content quality filter: min 150 chars, 2+ headers, must have code blocks or bullet points, skips readme/changelog/license/docs
 
 ---
 
 ## Requirements
 
 - Node.js 18+
-- Claude Code or Claude Desktop (any MCP-compatible client)
+- Any MCP-compatible client (Claude Code, Claude Desktop, Cline, OpenCode, Cursor, Windsurf…)
 
 ---
 
 ## Related
 
-- 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry
+- 📋 [promptgraph-registry](https://github.com/NeiP4n/promptgraph-registry) — community skill registry and auto-publish bot
 
 ---
 
-*Built with [Claude](https://claude.com/claude-code) by Anthropic.*
+*Built with [Claude Code](https://claude.com/claude-code).*

package/index.js

@@ -33,8 +33,7 @@ function showHelp() {
     ['search <query>',      'Search skills from the terminal'],
     ['import <owner/repo>', 'Import skills from GitHub'],
     ['status',              'Show installed skills, repos, and bundles'],
-    ['marketplace [cat]',   'Browse skills by category (Engineering, Coding, …)'],
-    ['marketplace bundles', 'Browse skill bundles grouped by category'],
+    ['marketplace',         'Interactive TUI: browse + search + install skills & bundles'],
     ['validate <file.md>',  'Validate a skill before publishing'],
     ['doctor',              'Clean orphaned chunks/edges/ratings'],
     ['update',              'Update to the latest version from npm'],
@@ -177,182 +176,34 @@ if (args[0] === 'status') {
   process.exit(0);
 }
 
-if (args[0] === 'marketplace' && (args[1] === 'bundles' || args[1] === 'bundle')) {
-  const { browseBundles } = await import('./marketplace.js');
-  const purple = chalk.hex('#7C3AED');
-  const spin = (await import('./cli.js')).spinner('Fetching bundles...');
-  spin.start();
-  const bundles = await browseBundles(1000);
-  spin.stop();
-  (await import('./cli.js')).clearScreen();
-
-  if (bundles?.error) { error(bundles.error); process.exit(1); }
-
-  console.log();
-  console.log('  ' + purple.bold('PromptGraph Bundles') + chalk.gray('   curated skill sets'));
-  console.log('  ' + chalk.gray(`${bundles.length} bundle${bundles.length === 1 ? '' : 's'}`));
-  console.log('  ' + chalk.gray('─'.repeat(54)));
-  console.log();
-
-  if (!bundles.length) {
-    info('No bundles yet.');
-    console.log(chalk.gray('  github.com/NeiP4n/promptgraph-registry\n'));
-    process.exit(0);
-  }
-
-  const CATEGORY_ICONS = { Engineering: '🛠', 'AI Tools': '🤖', Coding: '💻', Creative: '🎨', Security: '🔒', Community: '🌐' };
-
-  const wrapB = (t, w, ind) => {
-    const words = (t || '').split(/\s+/); const lines = []; let line = '';
-    for (const x of words) { if ((line + ' ' + x).trim().length > w) { lines.push(line.trim()); line = x; } else line += ' ' + x; }
-    if (line.trim()) lines.push(line.trim());
-    return lines.map(l => ind + chalk.gray(l)).join('\n');
-  };
-
-  // Group by category
-  const byCategory = {};
-  for (const b of bundles) {
-    const cat = b.category || 'Community';
-    (byCategory[cat] = byCategory[cat] || []).push(b);
-  }
-
-  let globalIdx = 1;
-  for (const [cat, items] of Object.entries(byCategory)) {
-    const icon = CATEGORY_ICONS[cat] || '📦';
-    console.log('  ' + chalk.hex('#7C3AED').bold(`${icon}  ${cat}`));
-    console.log('  ' + chalk.gray('─'.repeat(50)));
-    for (const b of items) {
-      const stars = b.stars > 0 ? chalk.yellow('★ ' + b.stars) : chalk.gray('★ 0');
-      const countLabel = b.repo_url
-        ? chalk.blue((b.skillCount ? b.skillCount + ' skills · ' : '') + 'GitHub')
-        : chalk.gray((b.skills?.length || 0) + ' skills');
-      console.log('  ' + chalk.gray(globalIdx++ + '.') + ' ' + chalk.white.bold(b.id) + '   ' + stars + '   ' + countLabel);
-      console.log(wrapB(b.description, 64, '     '));
-      console.log('     ' + chalk.gray('includes: ') + (b.repo_url ? chalk.blue(b.repo_url) : chalk.gray((b.skills || []).join(', '))));
-      if (b.tags?.length) console.log('     ' + purple(b.tags.map(t => '#' + t).join(' ')));
-      console.log('     ' + chalk.gray('install:  ') + chalk.cyan(`pg bundle install ${b.id}`));
-      console.log();
-    }
-  }
-
-  console.log(
-    boxen(
-      chalk.dim('install bundle ') + chalk.cyan(`pg bundle install <id>`) + '\n' +
-      chalk.dim('add repo       ') + chalk.cyan(`pg bundle add-repo <owner/repo>`) + '\n' +
-      chalk.dim('browse skills  ') + chalk.cyan(`${bin} marketplace`),
-      { padding: { top: 0, bottom: 0, left: 1, right: 1 }, borderStyle: 'round', borderColor: '#4B5563', dimBorder: true }
-    )
-  );
-  console.log();
-  process.exit(0);
-}
-
 if (args[0] === 'marketplace') {
-  const { browseMarketplace } = await import('./marketplace.js');
-  const purple = chalk.hex('#7C3AED');
-  const W = 60;
-
-  // Support: pg marketplace <category> or pg marketplace <page>
-  const arg1 = args[1];
-  const pageArg = parseInt(arg1);
-  const categoryFilter = (!arg1 || isNaN(pageArg)) ? (arg1 || null) : null;
-  const PER_PAGE = categoryFilter ? 1000 : 10;
-  const page = categoryFilter ? 1 : Math.max(1, pageArg || 1);
-
-  const { clearScreen } = await import('./cli.js');
-  const spin = (await import('./cli.js')).spinner('Fetching registry...');
-  spin.start();
-  let all = await browseMarketplace(1000);
-  spin.stop();
-  clearScreen();
-
-  if (all?.error) { error(all.error); process.exit(1); }
-  if (!all.length) {
-    info('Registry is empty. Be the first to contribute!');
-    console.log(chalk.gray('  github.com/NeiP4n/promptgraph-registry\n'));
-    process.exit(0);
-  }
-
-  const SKILL_CAT_ICONS = { Engineering: '🛠', 'AI Tools': '🤖', Coding: '💻', Creative: '🎨', Security: '🔒', Community: '🌐' };
-
-  const wrap = (text, width, indent) => {
-    const words = (text || '').split(/\s+/);
-    const lines = []; let line = '';
-    for (const w of words) {
-      if ((line + ' ' + w).trim().length > width) { lines.push(line.trim()); line = w; }
-      else line += ' ' + w;
-    }
-    if (line.trim()) lines.push(line.trim());
-    return lines.map(l => indent + chalk.dim(l)).join('\n');
-  };
-
-  // Filter by category if provided
-  if (categoryFilter) {
-    const matched = categoryFilter.toLowerCase();
-    all = all.filter(s => (s.category || 'community').toLowerCase().includes(matched));
-    if (!all.length) {
-      error(`No skills in category "${categoryFilter}"`);
-      process.exit(1);
-    }
-  }
-
-  // Group by category
-  const byCategory = {};
-  for (const s of all) {
-    const cat = s.category || 'Community';
-    (byCategory[cat] = byCategory[cat] || []).push(s);
-  }
-
-  // header
-  console.log();
-  console.log('  ' + purple.bold('◆ PromptGraph') + chalk.dim('  ·  marketplace'));
-  if (categoryFilter) {
-    console.log('  ' + chalk.dim(`${all.length} skills in "${categoryFilter}"`));
-  } else {
-    const cats = Object.keys(byCategory);
-    console.log('  ' + chalk.dim(`${all.length} skills   ·   ${cats.length} categories`));
+  if (!process.stdout.isTTY) {
+    error('marketplace TUI requires an interactive terminal');
+    process.exit(1);
   }
-  console.log(chalk.dim('  ' + '━'.repeat(W)));
-  console.log();
-
-  // Display grouped by category
-  for (const [cat, items] of Object.entries(byCategory)) {
-    const icon = SKILL_CAT_ICONS[cat] || '📦';
-    console.log('  ' + purple.bold(`${icon}  ${cat}`) + chalk.dim(`  (${items.length})`));
-
-    // If not filtering and category has many, paginate within category
-    const showItems = (categoryFilter || items.length <= 5) ? items : items.slice(0, 5);
-    for (const s of showItems) {
-      const code = s.code ? chalk.hex('#A78BFA')(s.code) : '';
-      const stars = chalk.yellow('★') + chalk.dim(' ' + (s.stars || 0));
-      console.log('    ' + chalk.bold.white(s.id) + '   ' + code + '  ' + stars);
-      console.log(wrap(s.description, W - 6, '      '));
-      if (s.tags?.length) console.log('      ' + chalk.dim(s.tags.map(t => '#' + t).join(' ')));
-      console.log('      ' + chalk.dim('install: ') + chalk.cyan(`${bin} install ${s.code || s.id}`));
-      console.log();
-    }
-    if (!categoryFilter && items.length > 5) {
-      console.log('      ' + chalk.dim(`... and ${items.length - 5} more · `) + chalk.cyan(`${bin} marketplace ${cat}`));
-      console.log();
+  const { browseMarketplace, browseBundles, installSkill, installBundle } = await import('./marketplace.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 { runTUI } = await import('./tui.js');
+  await runTUI(
+    Array.isArray(skills) ? skills : [],
+    Array.isArray(bundles) ? bundles : [],
+    async (item) => {
+      if (item.type === 'bundle') {
+        const r = await installBundle(item.id);
+        if (r?.error) throw new Error(r.error);
+      } else {
+        const r = await installSkill(item.code || item.id);
+        if (r?.error) throw new Error(r.error);
+      }
     }
-  }
-
-  console.log(chalk.dim('  ' + '━'.repeat(W)));
-  console.log();
-
-  const exCode = all[0]?.code || all[0]?.id || 'pg-xxxxxx';
-  const cats = Object.keys(byCategory).map(c => chalk.cyan(`${bin} marketplace ${c}`)).join('  ');
-  console.log(
-    boxen(
-      chalk.dim('categories     ') + cats + '\n' +
-      chalk.dim('install skill  ') + chalk.white('install ') + chalk.hex('#A78BFA')(exCode) + '\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('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);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptgraph-mcp",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "main": "index.js",
   "type": "module",
   "bin": {

package/tui.js

@@ -0,0 +1,331 @@
+/**
+ * Interactive marketplace TUI — nano-style keyboard navigation
+ * Arrow keys, search, install, categories — all in one screen
+ */
+import readline from 'readline';
+import chalk from 'chalk';
+import process from 'process';
+
+const ESC        = '\x1b';
+const HIDE       = '\x1b[?25l';
+const SHOW       = '\x1b[?25h';
+const HOME       = '\x1b[H';
+const CLEAR      = '\x1b[2J\x1b[H';
+const CLEAR_EOL  = '\x1b[K';
+
+const purple  = chalk.hex('#7C3AED');
+const dim     = chalk.dim;
+const bold    = chalk.bold;
+const cyan    = chalk.cyan;
+const yellow  = chalk.yellow;
+const green   = chalk.green;
+const red     = chalk.red;
+const blue    = chalk.blue;
+const white   = chalk.white;
+
+const CAT_ICON = { Engineering:'🛠', 'AI Tools':'🤖', Coding:'💻', Creative:'🎨', Security:'🔒', Community:'🌐' };
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function termSize() {
+  return { cols: process.stdout.columns || 100, rows: process.stdout.rows || 30 };
+}
+
+function write(s) { process.stdout.write(s); }
+function moveTo(row, col) { write(`\x1b[${row};${col}H`); }
+function clearLine() { write('\x1b[2K\r'); }
+
+function truncate(s, n) {
+  s = String(s || '');
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+// ── build item list ───────────────────────────────────────────────────────────
+
+function buildItems(skills, bundles) {
+  const items = [];
+  // skills
+  for (const s of skills) {
+    items.push({ type: 'skill', id: s.id, name: s.name || s.id, description: s.description || '', category: s.category || 'Community', tags: s.tags || [], stars: s.stars || 0, code: s.code });
+  }
+  // bundles
+  for (const b of bundles) {
+    items.push({ type: 'bundle', id: b.id, name: b.name || b.id, description: b.description || '', category: b.category || 'Community', tags: b.tags || [], stars: b.stars || 0, skillCount: b.skillCount, repo_url: b.repo_url, skills: b.skills });
+  }
+  return items;
+}
+
+function filterItems(items, query, tab) {
+  let filtered = items;
+  if (tab === 'skills')  filtered = items.filter(i => i.type === 'skill');
+  if (tab === 'bundles') filtered = items.filter(i => i.type === 'bundle');
+  if (query) {
+    const q = query.toLowerCase();
+    filtered = filtered.filter(i =>
+      i.id.includes(q) || i.name.toLowerCase().includes(q) ||
+      i.description.toLowerCase().includes(q) ||
+      i.category.toLowerCase().includes(q) ||
+      (i.tags || []).some(t => t.includes(q))
+    );
+  }
+  return filtered;
+}
+
+// ── render ────────────────────────────────────────────────────────────────────
+
+function render(state) {
+  const { cols, rows } = termSize();
+  const HEADER_ROWS = 4;
+  const FOOTER_ROWS = 3;
+  const LIST_ROWS = rows - HEADER_ROWS - FOOTER_ROWS;
+
+  const { items, cursor, scroll, query, searching, tab, status } = state;
+
+  write(HOME);
+
+  // ── header ─────────────────────────────────────────────────────────────────
+  const title = purple.bold(' ◆ PromptGraph Marketplace ');
+  const tabs = ['all', 'skills', 'bundles'].map(t =>
+    t === tab ? cyan.bold(`[${t}]`) : dim(`[${t}]`)
+  ).join(' ');
+  write(truncate(title + ' '.repeat(4) + tabs, cols) + CLEAR_EOL + '\n');
+
+  // search bar
+  const searchLabel = searching ? green('/ ') : dim('/ ');
+  const searchVal   = searching ? white(query) + (Math.floor(Date.now()/500)%2 ? '▌' : ' ') : dim(query || 'type / to search');
+  write(' ' + searchLabel + truncate(searchVal, cols - 4) + CLEAR_EOL + '\n');
+
+  const countLabel = dim(` ${items.length} items`);
+  const hint = dim(status ? (status.ok ? green(' ✓ ' + status.msg) : red(' ✗ ' + status.msg)) : '');
+  write(countLabel + hint + CLEAR_EOL + '\n');
+  write(dim('─'.repeat(cols)) + CLEAR_EOL + '\n');
+
+  // ── list ───────────────────────────────────────────────────────────────────
+  let lastCat = null;
+  let lineIdx = 0;
+  let rendered = 0;
+
+  for (let i = scroll; i < items.length && rendered < LIST_ROWS; i++) {
+    const item = items[i];
+    const selected = i === cursor;
+    const bg = selected ? '\x1b[48;2;60;40;120m' : '';
+    const reset = selected ? '\x1b[0m' : '';
+
+    // category header
+    if (item.category !== lastCat) {
+      if (rendered >= LIST_ROWS) break;
+      const icon = CAT_ICON[item.category] || '📦';
+      write(bg + ' ' + purple(icon + '  ' + item.category) + reset + CLEAR_EOL + '\n');
+      lastCat = item.category;
+      rendered++;
+    }
+
+    if (rendered >= LIST_ROWS) break;
+
+    // item row
+    const sel   = selected ? cyan('▶') : ' ';
+    const type  = item.type === 'bundle' ? blue('⊞') : dim('·');
+    const name  = selected ? white.bold(item.name) : white(item.name);
+    const stars = item.stars > 0 ? yellow('★' + item.stars) : dim('★0');
+    const extra = item.type === 'bundle'
+      ? (item.skillCount ? blue(item.skillCount + ' skills') : blue('GitHub'))
+      : (item.code ? dim(item.code) : '');
+    const desc  = dim(truncate(item.description, cols - 42));
+
+    const left  = ` ${sel} ${type} ${truncate(item.name, 28).padEnd(28)} ${stars}  ${extra.padEnd(12)}`;
+    write(bg + truncate(left, cols - desc.length - 2) + ' ' + desc + reset + CLEAR_EOL + '\n');
+    rendered++;
+  }
+
+  // fill empty rows
+  while (rendered < LIST_ROWS) {
+    write(CLEAR_EOL + '\n');
+    rendered++;
+  }
+
+  // ── footer ─────────────────────────────────────────────────────────────────
+  write(dim('─'.repeat(cols)) + CLEAR_EOL + '\n');
+  const sel = items[cursor];
+  if (sel && !searching) {
+    const installCmd = sel.type === 'bundle' ? `bundle install ${sel.id}` : `install ${sel.code || sel.id}`;
+    write(dim(` Enter`) + ' install  ' + dim('Tab') + ' switch  ' + dim('/') + ' search  ' + dim('q') + ' quit' + CLEAR_EOL + '\n');
+    write(dim(` → pg ${installCmd}`) + CLEAR_EOL + '\n');
+  } else if (searching) {
+    write(dim(' Type to filter  ') + cyan('Enter') + dim(' confirm  ') + cyan('Esc') + dim(' cancel') + CLEAR_EOL + '\n');
+    write(CLEAR_EOL + '\n');
+  } else {
+    write(dim(' ↑↓ navigate  Enter install  Tab switch  / search  q quit') + CLEAR_EOL + '\n');
+    write(CLEAR_EOL + '\n');
+  }
+}
+
+// ── clamp scroll ─────────────────────────────────────────────────────────────
+
+function clampScroll(state) {
+  const { rows } = termSize();
+  const HEADER_ROWS = 4, FOOTER_ROWS = 3;
+  const LIST_ROWS = rows - HEADER_ROWS - FOOTER_ROWS;
+  const { cursor, items } = state;
+
+  // ensure cursor visible — approximate (category headers add extra rows)
+  if (cursor < state.scroll) state.scroll = cursor;
+  if (cursor >= state.scroll + LIST_ROWS - 2) state.scroll = cursor - LIST_ROWS + 3;
+  if (state.scroll < 0) state.scroll = 0;
+  if (state.scroll >= items.length) state.scroll = Math.max(0, items.length - 1);
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+export async function runTUI(allSkills, allBundles, installFn) {
+  const allItems = buildItems(allSkills, allBundles);
+
+  const state = {
+    tab: 'all',
+    query: '',
+    searching: false,
+    cursor: 0,
+    scroll: 0,
+    items: allItems,
+    status: null,
+    installing: false,
+  };
+
+  function refresh(q, t) {
+    state.items = filterItems(allItems, q ?? state.query, t ?? state.tab);
+    if (state.cursor >= state.items.length) state.cursor = Math.max(0, state.items.length - 1);
+    clampScroll(state);
+    render(state);
+  }
+
+  // Setup terminal
+  write(HIDE + CLEAR);
+  readline.emitKeypressEvents(process.stdin);
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+
+  function cleanup() {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    write(SHOW + CLEAR);
+    process.stdin.pause();
+  }
+
+  process.on('SIGINT', cleanup);
+  process.on('exit', cleanup);
+
+  // Initial render
+  refresh();
+
+  // Status blink timer
+  let statusTimer = null;
+  function setStatus(ok, msg) {
+    state.status = { ok, msg };
+    clearTimeout(statusTimer);
+    render(state);
+    statusTimer = setTimeout(() => { state.status = null; render(state); }, 3000);
+  }
+
+  // Keypress handler
+  process.stdin.on('keypress', async (ch, key) => {
+    if (!key) return;
+
+    if (state.searching) {
+      if (key.name === 'escape') {
+        state.searching = false;
+        state.query = '';
+        refresh();
+      } else if (key.name === 'return') {
+        state.searching = false;
+        refresh();
+      } else if (key.name === 'backspace') {
+        state.query = state.query.slice(0, -1);
+        refresh();
+      } else if (ch && !key.ctrl && !key.meta && ch.length === 1) {
+        state.query += ch;
+        refresh();
+      }
+      return;
+    }
+
+    // Normal mode
+    if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+      cleanup();
+      return;
+    }
+
+    if (key.name === 'slash' || ch === '/') {
+      state.searching = true;
+      render(state);
+      return;
+    }
+
+    if (key.name === 'tab') {
+      const tabs = ['all', 'skills', 'bundles'];
+      state.tab = tabs[(tabs.indexOf(state.tab) + 1) % tabs.length];
+      state.cursor = 0;
+      state.scroll = 0;
+      refresh(state.query, state.tab);
+      return;
+    }
+
+    if (key.name === 'up') {
+      if (state.cursor > 0) state.cursor--;
+      clampScroll(state);
+      render(state);
+      return;
+    }
+
+    if (key.name === 'down') {
+      if (state.cursor < state.items.length - 1) state.cursor++;
+      clampScroll(state);
+      render(state);
+      return;
+    }
+
+    if (key.name === 'pageup') {
+      state.cursor = Math.max(0, state.cursor - 10);
+      clampScroll(state);
+      render(state);
+      return;
+    }
+
+    if (key.name === 'pagedown') {
+      state.cursor = Math.min(state.items.length - 1, state.cursor + 10);
+      clampScroll(state);
+      render(state);
+      return;
+    }
+
+    if (key.name === 'home') { state.cursor = 0; state.scroll = 0; render(state); return; }
+    if (key.name === 'end')  { state.cursor = state.items.length - 1; clampScroll(state); render(state); return; }
+
+    if (key.name === 'return' || key.name === 'i') {
+      const sel = state.items[state.cursor];
+      if (!sel || state.installing) return;
+      state.installing = true;
+      setStatus(null, `Installing ${sel.id}…`);
+      try {
+        await installFn(sel);
+        setStatus(true, `Installed ${sel.id}`);
+      } catch (e) {
+        setStatus(false, e.message.slice(0, 60));
+      } finally {
+        state.installing = false;
+      }
+      return;
+    }
+
+    if (key.name === 'escape') {
+      state.query = '';
+      refresh();
+      return;
+    }
+  });
+
+  // Resize handler
+  process.stdout.on('resize', () => { clampScroll(state); render(state); });
+
+  // Keep alive
+  return new Promise(resolve => {
+    process.stdin.once('close', resolve);
+    process.on('SIGINT', resolve);
+  });
+}