promptgraph-mcp 2.9.57 → 2.9.59

package/README.md

@@ -11,10 +11,11 @@ Instead of loading every `.md` skill into context, Claude calls `pg_search` and
 
 ## Features
 
-- **Semantic search** — BGE-Small-EN embeddings, local, no API key required
+- **Semantic search** — BGE-Small-EN embeddings (fastembed), local, no API key required
 - **Token savings** — loads one skill on demand instead of all `.md` files (~20k+ tokens/session)
 - **Fast reindex** — persistent embed cache makes re-indexing unchanged skills near-instant
-- **Low RAM** — first index uses ~0.85 GB (vs 5+ GB in older versions)
+- **Flexible layouts** — finds skills in nested subfolders and in `.github/`, `.claude/`, `.opencode/` dot-folders (GitHub Copilot / agent conventions)
+- **Any local folder** — `pg add-dir <path>` indexes a folder that isn't a default source
 - **Marketplace** — browse and install community skill bundles via TUI or MCP tools
 - **Publishing** — publish skills/bundles to the registry hands-off via GitHub CLI
 - **Multi-platform** — Claude Code, OpenCode, Claude Desktop, Cursor, Windsurf, Cline, Codex
@@ -87,6 +88,44 @@ pg bundle add-repo <owner/repo> # Publish your GitHub repo to the registry (requ
 
 ---
 
+## Where your skills can live
+
+PromptGraph scans each registered source folder **recursively**, so any layout works:
+
+```
+my-skills/
+  commit-message.md                  # flat file — name from filename
+  refactor/SKILL.md                  # folder skill — name from the folder ("refactor")
+  cloud/deploy/SKILL.md              # nested categories — all found
+  .github/skills/my-skill/SKILL.md   # GitHub Copilot / agent convention
+  .claude/skills/...                 # Claude dot-folder
+```
+
+- **Subfolders** at any depth are scanned.
+- **Generic filenames** (`SKILL.md`, `index.md`, `agent.md`, …) take their name from the parent folder, so `cloud/deploy/SKILL.md` and `cloud/infra/SKILL.md` stay distinct instead of colliding.
+- **Dot-folders** `.github/{skills,prompts,agents,commands}`, `.claude/`, `.opencode/` are indexed. Other `.github` paths (`workflows`, `plugins`, …) are skipped.
+- **Doc/meta files** (`README`, `CHANGELOG`, `LICENSE`, files in `docs/`, `tests/`, `assets/`, …) are filtered out automatically.
+
+To index a folder that isn't a configured source:
+
+```bash
+pg add-dir /path/to/skills      # registers it + indexes recursively
+pg status                       # confirm it shows up with the right count
+```
+
+---
+
+## Data & config location
+
+PromptGraph stores its config, SQLite DB, and ANN index in:
+
+- `~/.promptgraph/` — fresh installs on any platform
+- `~/.claude/.promptgraph/` — kept for existing Claude Code installs (not migrated, so the index isn't orphaned)
+
+Your **skill files** stay wherever you put them (the platform skills dir or any `add-dir` folder) — only the derived index lives here.
+
+---
+
 ## OpenCode — `/pg` slash commands
 
 After `pg setup opencode`, two slash commands are available inside OpenCode:
@@ -135,12 +174,12 @@ The registry bot reads the submitted JSON and publishes within minutes.
 
 ## Skill bundles with tools
 
-A bundle can ship both skill files (`.md`) and tool scripts (`.py`, `.sh`, `.js`, etc.). When installed:
+A bundle can ship both skill files (`.md`) and tool scripts (`.py`, `.sh`, `.bash`, `.js`, `.ts`, `.rb`). When installed:
 - All `.md` files go to the skills directory
-- Script files are placed alongside them
+- Script files are cloned alongside them (sparse-checkout fetches them with the skills)
 - On Linux/macOS scripts are made executable (`chmod +x`)
 
-Bundle authors: set `has_tools: true` and include `tool_files` entries in your bundle manifest.
+For **repo bundles** (`pg bundle add-repo <owner/repo>`), scripts are detected automatically — `has_tools` and the 🔧 badge are set from the real files in the repo, no manifest needed. For **skill-list bundles**, list scripts explicitly in `tool_files`.
 
 ---
 
@@ -157,6 +196,12 @@ Bundle authors: set `has_tools: true` and include `tool_files` entries in your b
 
 ## Troubleshooting
 
+**Only some of my skills got indexed:**
+Check `pg status` for the `Found N files` count. If it's lower than expected:
+- The skills live outside a registered source → `pg add-dir <that-folder>`.
+- Generic `SKILL.md` files used to collide on name (fixed) — make sure you're on the latest version (`pg update`).
+- Files named like docs (`README`, `01-intro`, …) or under `docs/`/`tests/` are filtered by design.
+
 **Marketplace shows no bundles:**
 ```bash
 pg doctor --reset-dead

package/commands/bundle.js

@@ -137,7 +137,8 @@ export default async function handler(args, bin) {
     const hasScripts = hasScriptsQuick || deepResult.hasScripts;
     console.log(chalk.green(`  ✓ ${deepResult.passed}/${deepResult.total} skills valid${hasScripts ? '  🔧 scripts detected' : ''}`));
 
-    const name = repo.split('/')[1].replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    const { bundleDisplayName } = await import('../github-import.js');
+    const name = bundleDisplayName(repo);
     const id = repo.replace('/', '-').toLowerCase();
     const bundle = {
       id, name, repo_url: repo, author: repo.split('/')[0],

package/github-import.js

@@ -22,6 +22,25 @@ export const SCRIPT_GLOBS = ['**/*.py', '**/*.sh', '**/*.bash', '**/*.js', '**/*
 // (e.g. microsoft/skills). Recognized as skill locations despite .github being a skip dir.
 const COPILOT_SKILL_DIRS = new Set(['skills', 'prompts', 'agents', 'commands']);
 
+// Repo names too generic to make a good bundle title on their own — prefix the owner.
+const GENERIC_REPO_NAMES = new Set([
+  'skills', 'skill', 'prompts', 'prompt', 'agents', 'agent', 'commands', 'command',
+  'tools', 'toolkit', 'mcp', 'ai', 'claude', 'plugins', 'plugin', 'templates', 'library',
+]);
+
+// Build a human-friendly bundle name from "owner/repo". For generic repo names
+// (owner/skills → "Owner Skills") the owner is prefixed so titles aren't all "Skills".
+export function bundleDisplayName(ownerRepo) {
+  const [owner, repo = ''] = ownerRepo.replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '').split('/');
+  const titlecase = (s) => s.replace(/[-_.]+/g, ' ').replace(/\s+/g, ' ').trim().replace(/\b\w/g, (c) => c.toUpperCase());
+  const repoName = titlecase(repo);
+  if (GENERIC_REPO_NAMES.has(repo.toLowerCase())) {
+    const ownerName = titlecase(owner);
+    return repoName ? `${ownerName} ${repoName}` : ownerName;
+  }
+  return repoName || titlecase(owner);
+}
+
 // ── helpers ───────────────────────────────────────────────────────────────────
 
 const repoStats = new Map()
@@ -225,9 +244,14 @@ async function detectSkillsDirFromAPI(ownerRepo) {
     return null; // repo not found or inaccessible
   }
   if (!tree || !Array.isArray(tree.tree)) return null;
+  const paths = tree.tree.filter(f => f.type === 'blob').map(f => f.path);
+  return selectSkillSubdir(paths);
+}
 
-  const blobs = tree.tree.filter(f => f.type === 'blob');
-  if (blobs.length === 0) return null;
+// Pure subdir-selection logic over a flat list of repo file paths (no network).
+// Returns { subdir, label, validMdCount, hasScripts } or null. Exported for tests.
+export function selectSkillSubdir(allPaths) {
+  if (!Array.isArray(allPaths) || allPaths.length === 0) return null;
 
   // A path is a valid skill .md if the filename isn't meta (readme/license/…) and no
   // path segment is a skip dir (docs/tests/assets/…). Exception: .github/{skills,
@@ -245,17 +269,17 @@ async function detectSkillsDirFromAPI(ownerRepo) {
     }
     return true;
   };
-  const mdBlobs = blobs.filter(f => isValidMd(f.path));
-  if (mdBlobs.length === 0) return null;
+  const mdPaths = allPaths.filter(isValidMd);
+  if (mdPaths.length === 0) return null;
 
-  const countUnder  = (prefix) => mdBlobs.filter(f => f.path.startsWith(prefix)).length;
-  const scriptUnder = (prefix) => blobs.some(f => f.path.startsWith(prefix) && SCRIPT_EXTS_API.has(path.extname(f.path).toLowerCase()));
+  const countUnder  = (prefix) => mdPaths.filter(p => p.startsWith(prefix)).length;
+  const scriptUnder = (prefix) => allPaths.some(p => p.startsWith(prefix) && SCRIPT_EXTS_API.has(path.extname(p).toLowerCase()));
 
   // Map of top-level dir names (lowercase -> real casing)
   const topDirs = new Map();
-  for (const f of blobs) {
-    const idx = f.path.indexOf('/');
-    if (idx > 0) { const d = f.path.slice(0, idx); topDirs.set(d.toLowerCase(), d); }
+  for (const p of allPaths) {
+    const idx = p.indexOf('/');
+    if (idx > 0) { const d = p.slice(0, idx); topDirs.set(d.toLowerCase(), d); }
   }
 
   // 1. Known skill dir names (priority order) — counted recursively
@@ -280,7 +304,7 @@ async function detectSkillsDirFromAPI(ownerRepo) {
   }
 
   // 2. Root-level .md files (skills kept directly at repo root)
-  const rootMd = mdBlobs.filter(f => !f.path.includes('/')).length;
+  const rootMd = mdPaths.filter(p => !p.includes('/')).length;
 
   // 3. Best non-skip top-level subdir by recursive .md count
   let best = null, bestCount = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptgraph-mcp",
-  "version": "2.9.57",
+  "version": "2.9.59",
   "files": [
     "*.js",
     "commands/",