@theglitchking/semantic-pages 0.9.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for semantic-pages - Semantic search + knowledge graph MCP server with auto-wiring for .claude/.vault and hit-em-with-the-docs companion",
-    "version": "0.9.0"
+    "version": "0.10.0"
   },
   "plugins": [
     {
       "name": "semantic-pages",
       "description": "Semantic search + knowledge graph MCP server for markdown vaults. Auto-wires a read/write vault at .claude/.vault, and a read-only docs index at .documentation when hit-em-with-the-docs is also installed.",
-      "version": "0.9.0",
+      "version": "0.10.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "semantic-pages",
   "description": "Semantic search + knowledge graph MCP server for markdown vaults. Auto-wires a read/write vault at .claude/.vault, and a read-only docs index at .documentation when hit-em-with-the-docs is also installed.",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/commands/healthcheck.md

@@ -0,0 +1,6 @@
+---
+description: Verify the local semantic-pages install starts cleanly; self-heals npx-cache ERR_MODULE_NOT_FOUND
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-pages healthcheck` and relay the output. If it reports a fragile `.mcp.json` form, suggest running `/semantic-pages:normalize-config`.

package/commands/normalize-config.md

@@ -0,0 +1,6 @@
+---
+description: Rewrite fragile npx-@latest entries in .mcp.json to the stable node-against-node_modules form
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/semantic-pages normalize-config` and report the result to the user. Mention that `.mcp.json.bak` was created as a safety backup, and that the MCPs need to be toggled in `/mcp` to pick up the change.

package/dist/cli/index.js

@@ -2,8 +2,8 @@
 
 // src/cli/index.ts
 import { program } from "commander";
-import { resolve, join } from "path";
-import { existsSync } from "fs";
+import { resolve, join, dirname, relative } from "path";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "fs";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
 import { registerUpdateCommands } from "@theglitchking/claude-plugin-runtime";
@@ -23,6 +23,40 @@ function runRelink(cwd) {
     stdio: "inherit"
   });
 }
+function findLocalBin(cwd) {
+  const p = join(cwd, "node_modules", "@theglitchking", "semantic-pages", "bin", "semantic-pages");
+  return existsSync(p) ? p : null;
+}
+function localBinArg(cwd) {
+  const abs = findLocalBin(cwd);
+  if (!abs) return null;
+  const rel = relative(cwd, abs);
+  return rel.startsWith("..") ? abs : `./${rel}`;
+}
+function readJsonSafe(path) {
+  try {
+    const raw = readFileSync(path, "utf8");
+    return raw.trim() ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function isNpxForm(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const cmd = entry.command;
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  return cmd === "npx" && args.some((a) => typeof a === "string" && a.includes(PKG_NAME));
+}
+function extractNotesPath(entry) {
+  const args = Array.isArray(entry?.args) ? entry.args : [];
+  const i = args.indexOf("--notes");
+  if (i === -1 || i + 1 >= args.length) return null;
+  return String(args[i + 1]);
+}
+function extractExtraFlags(entry) {
+  const args = Array.isArray(entry?.args) ? entry.args : [];
+  return args.filter((a) => typeof a === "string" && a.startsWith("--") && a !== "--notes");
+}
 var TOOL_HELP = {
   // Search
   search_semantic: {
@@ -277,5 +311,122 @@ registerUpdateCommands(program, {
   configFile: "semantic-pages.json",
   onAfterUpdate: (cwd) => runRelink(cwd)
 });
+program.command("normalize-config").description(
+  "Rewrite fragile `npx @latest` entries in .mcp.json to the stable node-against-node_modules form (with backup and validation)"
+).option("--dry-run", "print the proposed changes but don't write").action((opts) => {
+  const cwd = process.cwd();
+  const mcpPath = join(cwd, ".mcp.json");
+  if (!existsSync(mcpPath)) {
+    console.log("no .mcp.json in current directory \u2014 nothing to do");
+    process.exit(0);
+  }
+  const data = readJsonSafe(mcpPath);
+  if (!data || typeof data !== "object" || !data.mcpServers || typeof data.mcpServers !== "object") {
+    console.error(`could not parse ${mcpPath}`);
+    process.exit(1);
+  }
+  const bin = localBinArg(cwd);
+  if (!bin) {
+    console.error(
+      `no local install found at ./node_modules/@theglitchking/semantic-pages/bin/semantic-pages.
+run 'npm install --save @theglitchking/semantic-pages' first, then re-run this command.`
+    );
+    process.exit(1);
+  }
+  const rewritten = [];
+  for (const [key, entry] of Object.entries(data.mcpServers)) {
+    if (!isNpxForm(entry)) continue;
+    const notes = extractNotesPath(entry) ?? "./.claude/.vault";
+    const extra = extractExtraFlags(entry);
+    data.mcpServers[key] = {
+      type: "stdio",
+      command: "node",
+      args: [bin, "--notes", notes, ...extra]
+    };
+    rewritten.push(key);
+  }
+  if (rewritten.length === 0) {
+    console.log("no npx-form entries found \u2014 .mcp.json is already in the stable form.");
+    process.exit(0);
+  }
+  console.log(`Rewriting ${rewritten.length} entr${rewritten.length === 1 ? "y" : "ies"}: ${rewritten.join(", ")}`);
+  if (opts.dryRun) {
+    console.log("--- proposed .mcp.json:");
+    console.log(JSON.stringify(data, null, 2));
+    console.log("--- (dry-run; no changes written)");
+    process.exit(0);
+  }
+  const bakPath = join(dirname(mcpPath), ".mcp.json.bak");
+  try {
+    writeFileSync(bakPath, readFileSync(mcpPath, "utf8"));
+    console.log(`backup written: ${bakPath}`);
+  } catch (err) {
+    console.error(`could not write backup: ${err.message}`);
+    process.exit(1);
+  }
+  writeFileSync(mcpPath, JSON.stringify(data, null, 2) + "\n");
+  const verify = spawnSync("node", [bin, "--version"], { cwd, stdio: "pipe", timeout: 15e3 });
+  if (verify.status !== 0) {
+    console.error(`verification failed (exit ${verify.status}):
+${verify.stderr?.toString() || ""}`);
+    console.error(`rolling back from ${bakPath}`);
+    writeFileSync(mcpPath, readFileSync(bakPath, "utf8"));
+    process.exit(1);
+  }
+  console.log(`\u2713 .mcp.json normalized and verified. Toggle the MCPs in /mcp to reconnect.`);
+  process.exit(0);
+});
+program.command("healthcheck").description(
+  "Verify the local install starts cleanly; self-heal common npx-cache corruption (ERR_MODULE_NOT_FOUND)"
+).action(() => {
+  const cwd = process.cwd();
+  const bin = findLocalBin(cwd);
+  if (!bin) {
+    console.error(`no local install at ./node_modules/@theglitchking/semantic-pages/bin/semantic-pages`);
+    console.error(`run 'npm install --save @theglitchking/semantic-pages' to install.`);
+    process.exit(1);
+  }
+  const mcpPath = join(cwd, ".mcp.json");
+  if (existsSync(mcpPath)) {
+    const data = readJsonSafe(mcpPath);
+    const entries = data?.mcpServers && typeof data.mcpServers === "object" ? Object.entries(data.mcpServers) : [];
+    const fragile = entries.filter(([, e]) => isNpxForm(e)).map(([k]) => k);
+    if (fragile.length > 0) {
+      console.warn(
+        `\u26A0\uFE0F  .mcp.json uses the fragile npx-@latest form for: ${fragile.join(", ")}`
+      );
+      console.warn(`   Rewrite to the stable form:`);
+      console.warn(`     npx --no @theglitchking/semantic-pages normalize-config`);
+    }
+  }
+  const r = spawnSync("node", [bin, "--version"], { cwd, stdio: "pipe", timeout: 15e3 });
+  if (r.status === 0) {
+    console.log(`\u2713 local install starts cleanly (v${r.stdout?.toString().trim()})`);
+    process.exit(0);
+  }
+  const stderr = r.stderr?.toString() ?? "";
+  if (stderr.includes("ERR_MODULE_NOT_FOUND")) {
+    const match = stderr.match(/([\/~][^'"\s]*\/_npx\/[^\/'"\s]+)/);
+    if (match) {
+      const bad = match[1];
+      console.warn(`detected broken npx cache at ${bad} \u2014 clearing and retrying...`);
+      try {
+        rmSync(bad, { recursive: true, force: true });
+      } catch {
+      }
+      const r2 = spawnSync("node", [bin, "--version"], { cwd, stdio: "pipe", timeout: 15e3 });
+      if (r2.status === 0) {
+        console.log(`\u2713 cleared npx cache and verified (v${r2.stdout?.toString().trim()})`);
+        process.exit(0);
+      }
+      console.error(`retry still failed:
+${r2.stderr?.toString() || ""}`);
+    } else {
+      console.error(`ERR_MODULE_NOT_FOUND but could not locate offending cache path in the error.`);
+    }
+  }
+  console.error(stderr || `local install failed (exit ${r.status})`);
+  process.exit(1);
+});
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cli/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { program } from \"commander\";\nimport { resolve, join } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { spawnSync } from \"node:child_process\";\nimport { registerUpdateCommands } from \"@theglitchking/claude-plugin-runtime\";\n\nconst require_ = createRequire(import.meta.url);\nconst { version } = require_(\"../../package.json\") as { version: string };\n\nconst PKG_NAME = \"@theglitchking/semantic-pages\";\n\nfunction runRelink(cwd: string) {\n  const linker = join(cwd, \"node_modules\", \"@theglitchking\", \"semantic-pages\", \"scripts\", \"link-skills.js\");\n  const script = existsSync(linker) ? linker : resolve(process.cwd(), \"scripts\", \"link-skills.js\");\n  if (!existsSync(script)) {\n    console.error(\"link-skills.js not found — is the package installed?\");\n    return;\n  }\n  spawnSync(process.execPath, [script], {\n    cwd,\n    env: { ...process.env, INIT_CWD: cwd },\n    stdio: \"inherit\",\n  });\n}\n\nconst TOOL_HELP: Record<string, { description: string; args: string; examples: string[] }> = {\n  // Search\n  search_semantic: {\n    description: \"Vector similarity search — find notes by meaning, not just keywords\",\n    args: '{ \"query\": \"string\", \"limit?\": 10 }',\n    examples: [\n      '{ \"query\": \"microservices architecture\", \"limit\": 5 }',\n      '{ \"query\": \"how to deploy to production\" }',\n    ],\n  },\n  search_text: {\n    description: \"Full-text keyword or regex search with optional filters\",\n    args: '{ \"pattern\": \"string\", \"regex?\": false, \"caseSensitive?\": false, \"pathGlob?\": \"string\", \"tagFilter?\": [\"string\"], \"limit?\": 20 }',\n    examples: [\n      '{ \"pattern\": \"RabbitMQ\" }',\n      '{ \"pattern\": \"OAuth\\\\\\\\d\", \"regex\": true }',\n      '{ \"pattern\": \"deploy\", \"pathGlob\": \"devops/**\", \"tagFilter\": [\"kubernetes\"] }',\n    ],\n  },\n  search_graph: {\n    description: \"Graph traversal — find notes connected to a concept via wikilinks and tags\",\n    args: '{ \"concept\": \"string\", \"maxDepth?\": 2 }',\n    examples: [\n      '{ \"concept\": \"microservices\" }',\n      '{ \"concept\": \"auth\", \"maxDepth\": 3 }',\n    ],\n  },\n  search_hybrid: {\n    description: \"Combined semantic + graph search — vector results re-ranked by graph proximity\",\n    args: '{ \"query\": \"string\", \"limit?\": 10 }',\n    examples: [\n      '{ \"query\": \"event driven architecture\", \"limit\": 5 }',\n    ],\n  },\n\n  // Read\n  read_note: {\n    description: \"Read the full content of a specific note by path\",\n    args: '{ \"path\": \"string\" }',\n    examples: [\n      '{ \"path\": \"project-overview.md\" }',\n      '{ \"path\": \"notes/meeting-2024-01-15.md\" }',\n    ],\n  },\n  read_multiple_notes: {\n    description: \"Batch read multiple notes in one call\",\n    args: '{ \"paths\": [\"string\"] }',\n    examples: [\n      '{ \"paths\": [\"overview.md\", \"architecture.md\", \"deployment.md\"] }',\n    ],\n  },\n  list_notes: {\n    description: \"List all indexed notes with metadata (title, tags, link count)\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n\n  // Write\n  create_note: {\n    description: \"Create a new markdown note with optional YAML frontmatter\",\n    args: '{ \"path\": \"string\", \"content\": \"string\", \"frontmatter?\": {} }',\n    examples: [\n      '{ \"path\": \"new-guide.md\", \"content\": \"# Guide\\\\n\\\\nContent here.\" }',\n      '{ \"path\": \"tagged.md\", \"content\": \"Content.\", \"frontmatter\": { \"title\": \"Tagged Note\", \"tags\": [\"test\"] } }',\n    ],\n  },\n  update_note: {\n    description: \"Edit note content — overwrite, append, prepend, or patch by heading\",\n    args: '{ \"path\": \"string\", \"content\": \"string\", \"mode\": \"overwrite|append|prepend|patch-by-heading\", \"heading?\": \"string\" }',\n    examples: [\n      '{ \"path\": \"guide.md\", \"content\": \"New content.\", \"mode\": \"overwrite\" }',\n      '{ \"path\": \"guide.md\", \"content\": \"\\\\n## Appendix\\\\nExtra info.\", \"mode\": \"append\" }',\n      '{ \"path\": \"guide.md\", \"content\": \"Updated architecture section.\", \"mode\": \"patch-by-heading\", \"heading\": \"Architecture\" }',\n    ],\n  },\n  delete_note: {\n    description: \"Delete a note permanently (requires confirm=true)\",\n    args: '{ \"path\": \"string\", \"confirm\": true }',\n    examples: [\n      '{ \"path\": \"old-note.md\", \"confirm\": true }',\n      '{ \"path\": \"old-note.md\", \"confirm\": false }  // returns warning, does not delete',\n    ],\n  },\n  move_note: {\n    description: \"Move or rename a note — automatically updates wikilinks across the vault\",\n    args: '{ \"from\": \"string\", \"to\": \"string\" }',\n    examples: [\n      '{ \"from\": \"user-service.md\", \"to\": \"auth-service.md\" }',\n      '{ \"from\": \"old/note.md\", \"to\": \"new/location/note.md\" }',\n    ],\n  },\n\n  // Metadata\n  get_frontmatter: {\n    description: \"Read parsed YAML frontmatter from a note as JSON\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"project-overview.md\" }'],\n  },\n  update_frontmatter: {\n    description: \"Set or delete YAML frontmatter keys — pass null to delete a key\",\n    args: '{ \"path\": \"string\", \"fields\": {} }',\n    examples: [\n      '{ \"path\": \"note.md\", \"fields\": { \"status\": \"active\", \"priority\": 1 } }',\n      '{ \"path\": \"note.md\", \"fields\": { \"deprecated_field\": null } }  // deletes the key',\n    ],\n  },\n  manage_tags: {\n    description: \"Add, remove, or list tags on a note (frontmatter and inline)\",\n    args: '{ \"path\": \"string\", \"action\": \"add|remove|list\", \"tags?\": [\"string\"] }',\n    examples: [\n      '{ \"path\": \"note.md\", \"action\": \"list\" }',\n      '{ \"path\": \"note.md\", \"action\": \"add\", \"tags\": [\"important\", \"reviewed\"] }',\n      '{ \"path\": \"note.md\", \"action\": \"remove\", \"tags\": [\"draft\"] }',\n    ],\n  },\n  rename_tag: {\n    description: \"Rename a tag across all notes in the vault (frontmatter + inline)\",\n    args: '{ \"oldTag\": \"string\", \"newTag\": \"string\" }',\n    examples: ['{ \"oldTag\": \"architecture\", \"newTag\": \"arch\" }'],\n  },\n\n  // Graph\n  backlinks: {\n    description: \"Find all notes that link TO a given note via [[wikilinks]]\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"microservices.md\" }'],\n  },\n  forwardlinks: {\n    description: \"Find all notes linked FROM a given note\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"project-overview.md\" }'],\n  },\n  graph_path: {\n    description: \"Find the shortest path between two notes in the knowledge graph\",\n    args: '{ \"from\": \"string\", \"to\": \"string\" }',\n    examples: ['{ \"from\": \"project-overview.md\", \"to\": \"user-service.md\" }'],\n  },\n  graph_statistics: {\n    description: \"Knowledge graph stats — most connected nodes, orphans, density\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n\n  // System\n  get_stats: {\n    description: \"Vault and index statistics — note count, chunks, embeddings, graph density\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n  reindex: {\n    description: \"Force a full reindex of the vault\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n};\n\nconst TOOL_CATEGORIES: Record<string, string[]> = {\n  Search: [\"search_semantic\", \"search_text\", \"search_graph\", \"search_hybrid\"],\n  Read: [\"read_note\", \"read_multiple_notes\", \"list_notes\"],\n  Write: [\"create_note\", \"update_note\", \"delete_note\", \"move_note\"],\n  Metadata: [\"get_frontmatter\", \"update_frontmatter\", \"manage_tags\", \"rename_tag\"],\n  Graph: [\"backlinks\", \"forwardlinks\", \"graph_path\", \"graph_statistics\"],\n  System: [\"get_stats\", \"reindex\"],\n};\n\nfunction printToolList() {\n  console.log(\"\\nSemantic Pages — 21 MCP Tools\\n\");\n  console.log(\"Usage: These tools are available via MCP when the server is running.\");\n  console.log(\"       Run `semantic-pages tools <name>` for details on a specific tool.\\n\");\n\n  for (const [category, tools] of Object.entries(TOOL_CATEGORIES)) {\n    console.log(`  ${category}:`);\n    for (const name of tools) {\n      const tool = TOOL_HELP[name];\n      console.log(`    ${name.padEnd(24)} ${tool.description}`);\n    }\n    console.log();\n  }\n\n  console.log(\"Run `semantic-pages tools <tool-name>` for arguments and examples.\");\n}\n\nfunction printToolDetail(name: string) {\n  const tool = TOOL_HELP[name];\n  if (!tool) {\n    console.error(`Unknown tool: ${name}`);\n    console.error(`Run \\`semantic-pages tools\\` to see all available tools.`);\n    process.exit(1);\n  }\n\n  console.log(`\\n  ${name}`);\n  console.log(`  ${\"─\".repeat(name.length)}`);\n  console.log(`  ${tool.description}\\n`);\n  console.log(`  Arguments:`);\n  console.log(`    ${tool.args}\\n`);\n  console.log(`  Examples:`);\n  for (const ex of tool.examples) {\n    console.log(`    ${ex}`);\n  }\n  console.log();\n}\n\nprogram\n  .name(\"semantic-pages\")\n  .description(\n    \"Semantic search + knowledge graph MCP server for markdown files\\n\\n\" +\n    \"  Start MCP server:  semantic-pages --notes ./vault\\n\" +\n    \"  Show vault stats:  semantic-pages --notes ./vault --stats\\n\" +\n    \"  Force reindex:     semantic-pages --notes ./vault --reindex\\n\" +\n    \"  List MCP tools:    semantic-pages tools\\n\" +\n    \"  Tool details:      semantic-pages tools search_semantic\"\n  )\n  .version(version);\n\nprogram\n  .command(\"tools [name]\")\n  .description(\"List all MCP tools, or show details for a specific tool\")\n  .action((name?: string) => {\n    if (name) {\n      printToolDetail(name);\n    } else {\n      printToolList();\n    }\n    process.exit(0);\n  });\n\nprogram\n  .command(\"serve\", { isDefault: true })\n  .description(\"Start the MCP server (default command)\")\n  .requiredOption(\"--notes <path>\", \"Path to markdown notes directory\")\n  .option(\"--reindex\", \"Force full reindex and exit\")\n  .option(\"--stats\", \"Show vault statistics and exit\")\n  .option(\"--wait-for-ready\", \"Block startup until index is fully built before serving (default: index in background; tools return 'Indexing in progress' until ready)\")\n  .option(\"--read-only\", \"Suppress write tools (create_note, update_note, delete_note, move_note, update_frontmatter, manage_tags, rename_tag) — use for shared docs vaults owned by another tool\")\n  .option(\"--model <name>\", \"Embedding model to use (default: all-MiniLM-L6-v2, fast; use nomic-ai/nomic-embed-text-v1.5 for higher quality)\")\n  .option(\"--workers <n>\", \"Number of worker threads for parallel embedding\", parseInt)\n  .option(\"--batch-size <n>\", \"Texts per ONNX forward pass (default: 8)\", parseInt)\n  .option(\"--no-quantized\", \"Use full-precision model instead of quantized (slower, slightly higher quality)\")\n  .option(\"--no-watch\", \"Disable file watcher\")\n  .action(async (opts) => {\n    const notesPath = resolve(opts.notes);\n\n    if (!existsSync(notesPath)) {\n      console.error(`Error: notes directory not found: ${notesPath}`);\n      process.exit(1);\n    }\n\n    if (opts.stats) {\n      const { Indexer } = await import(\"../core/indexer.js\");\n      const indexer = new Indexer(notesPath);\n      const docs = await indexer.indexAll();\n      console.log(`Notes: ${docs.length}`);\n      console.log(`Chunks: ${docs.reduce((n: number, d: any) => n + d.chunks.length, 0)}`);\n      console.log(`Wikilinks: ${docs.reduce((n: number, d: any) => n + d.wikilinks.length, 0)}`);\n      console.log(`Tags: ${new Set(docs.flatMap((d: any) => d.tags)).size} unique`);\n      process.exit(0);\n    }\n\n    if (opts.reindex) {\n      const { createServer } = await import(\"../mcp/server.js\");\n      await createServer(notesPath, {\n        watch: false,\n        waitForReady: true,\n        model: opts.model,\n        workers: opts.workers,\n        batchSize: opts.batchSize,\n        quantized: opts.quantized,\n        onProgress: (embedded, total) => {\n          process.stderr.write(`\\rEmbedding ${embedded}/${total} chunks...`);\n        },\n      });\n      process.stderr.write(\"\\n\");\n      console.log(\"Reindex complete.\");\n      process.exit(0);\n    }\n\n    // Default: start MCP server on stdio\n    const { startServer } = await import(\"../mcp/server.js\");\n    await startServer(notesPath, {\n      watch: opts.watch,\n      waitForReady: opts.waitForReady,\n      model: opts.model,\n      workers: opts.workers,\n      batchSize: opts.batchSize,\n      quantized: opts.quantized,\n      readOnly: opts.readOnly,\n    });\n  });\n\nregisterUpdateCommands(program, {\n  packageName: PKG_NAME,\n  pluginName: \"semantic-pages\",\n  configFile: \"semantic-pages.json\",\n  onAfterUpdate: (cwd) => runRelink(cwd),\n});\n\nprogram.parse();\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/cli/index.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { program } from \"commander\";\nimport { resolve, join, dirname, relative } from \"node:path\";\nimport { existsSync, readFileSync, writeFileSync, rmSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { spawnSync } from \"node:child_process\";\nimport { registerUpdateCommands } from \"@theglitchking/claude-plugin-runtime\";\n\nconst require_ = createRequire(import.meta.url);\nconst { version } = require_(\"../../package.json\") as { version: string };\n\nconst PKG_NAME = \"@theglitchking/semantic-pages\";\n\nfunction runRelink(cwd: string) {\n  const linker = join(cwd, \"node_modules\", \"@theglitchking\", \"semantic-pages\", \"scripts\", \"link-skills.js\");\n  const script = existsSync(linker) ? linker : resolve(process.cwd(), \"scripts\", \"link-skills.js\");\n  if (!existsSync(script)) {\n    console.error(\"link-skills.js not found — is the package installed?\");\n    return;\n  }\n  spawnSync(process.execPath, [script], {\n    cwd,\n    env: { ...process.env, INIT_CWD: cwd },\n    stdio: \"inherit\",\n  });\n}\n\nfunction findLocalBin(cwd: string): string | null {\n  const p = join(cwd, \"node_modules\", \"@theglitchking\", \"semantic-pages\", \"bin\", \"semantic-pages\");\n  return existsSync(p) ? p : null;\n}\n\nfunction localBinArg(cwd: string): string | null {\n  const abs = findLocalBin(cwd);\n  if (!abs) return null;\n  const rel = relative(cwd, abs);\n  return rel.startsWith(\"..\") ? abs : `./${rel}`;\n}\n\nfunction readJsonSafe(path: string): any {\n  try {\n    const raw = readFileSync(path, \"utf8\");\n    return raw.trim() ? JSON.parse(raw) : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Returns the fragile npx-form pattern we used to write in pre-0.10.0\n * SessionStart hooks, so normalize-config can detect and rewrite it.\n */\nfunction isNpxForm(entry: any): boolean {\n  if (!entry || typeof entry !== \"object\") return false;\n  const cmd = entry.command;\n  const args = Array.isArray(entry.args) ? entry.args : [];\n  return cmd === \"npx\" && args.some((a: unknown) => typeof a === \"string\" && a.includes(PKG_NAME));\n}\n\nfunction isLocalForm(entry: any): boolean {\n  if (!entry || typeof entry !== \"object\") return false;\n  const cmd = entry.command;\n  const args = Array.isArray(entry.args) ? entry.args : [];\n  return (\n    cmd === \"node\" &&\n    args.some((a: unknown) => typeof a === \"string\" && a.includes(\"node_modules/@theglitchking/semantic-pages\"))\n  );\n}\n\nfunction extractNotesPath(entry: any): string | null {\n  const args = Array.isArray(entry?.args) ? entry.args : [];\n  const i = args.indexOf(\"--notes\");\n  if (i === -1 || i + 1 >= args.length) return null;\n  return String(args[i + 1]);\n}\n\nfunction extractExtraFlags(entry: any): string[] {\n  const args = Array.isArray(entry?.args) ? entry.args : [];\n  return args.filter((a: unknown): a is string => typeof a === \"string\" && a.startsWith(\"--\") && a !== \"--notes\");\n}\n\nconst TOOL_HELP: Record<string, { description: string; args: string; examples: string[] }> = {\n  // Search\n  search_semantic: {\n    description: \"Vector similarity search — find notes by meaning, not just keywords\",\n    args: '{ \"query\": \"string\", \"limit?\": 10 }',\n    examples: [\n      '{ \"query\": \"microservices architecture\", \"limit\": 5 }',\n      '{ \"query\": \"how to deploy to production\" }',\n    ],\n  },\n  search_text: {\n    description: \"Full-text keyword or regex search with optional filters\",\n    args: '{ \"pattern\": \"string\", \"regex?\": false, \"caseSensitive?\": false, \"pathGlob?\": \"string\", \"tagFilter?\": [\"string\"], \"limit?\": 20 }',\n    examples: [\n      '{ \"pattern\": \"RabbitMQ\" }',\n      '{ \"pattern\": \"OAuth\\\\\\\\d\", \"regex\": true }',\n      '{ \"pattern\": \"deploy\", \"pathGlob\": \"devops/**\", \"tagFilter\": [\"kubernetes\"] }',\n    ],\n  },\n  search_graph: {\n    description: \"Graph traversal — find notes connected to a concept via wikilinks and tags\",\n    args: '{ \"concept\": \"string\", \"maxDepth?\": 2 }',\n    examples: [\n      '{ \"concept\": \"microservices\" }',\n      '{ \"concept\": \"auth\", \"maxDepth\": 3 }',\n    ],\n  },\n  search_hybrid: {\n    description: \"Combined semantic + graph search — vector results re-ranked by graph proximity\",\n    args: '{ \"query\": \"string\", \"limit?\": 10 }',\n    examples: [\n      '{ \"query\": \"event driven architecture\", \"limit\": 5 }',\n    ],\n  },\n\n  // Read\n  read_note: {\n    description: \"Read the full content of a specific note by path\",\n    args: '{ \"path\": \"string\" }',\n    examples: [\n      '{ \"path\": \"project-overview.md\" }',\n      '{ \"path\": \"notes/meeting-2024-01-15.md\" }',\n    ],\n  },\n  read_multiple_notes: {\n    description: \"Batch read multiple notes in one call\",\n    args: '{ \"paths\": [\"string\"] }',\n    examples: [\n      '{ \"paths\": [\"overview.md\", \"architecture.md\", \"deployment.md\"] }',\n    ],\n  },\n  list_notes: {\n    description: \"List all indexed notes with metadata (title, tags, link count)\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n\n  // Write\n  create_note: {\n    description: \"Create a new markdown note with optional YAML frontmatter\",\n    args: '{ \"path\": \"string\", \"content\": \"string\", \"frontmatter?\": {} }',\n    examples: [\n      '{ \"path\": \"new-guide.md\", \"content\": \"# Guide\\\\n\\\\nContent here.\" }',\n      '{ \"path\": \"tagged.md\", \"content\": \"Content.\", \"frontmatter\": { \"title\": \"Tagged Note\", \"tags\": [\"test\"] } }',\n    ],\n  },\n  update_note: {\n    description: \"Edit note content — overwrite, append, prepend, or patch by heading\",\n    args: '{ \"path\": \"string\", \"content\": \"string\", \"mode\": \"overwrite|append|prepend|patch-by-heading\", \"heading?\": \"string\" }',\n    examples: [\n      '{ \"path\": \"guide.md\", \"content\": \"New content.\", \"mode\": \"overwrite\" }',\n      '{ \"path\": \"guide.md\", \"content\": \"\\\\n## Appendix\\\\nExtra info.\", \"mode\": \"append\" }',\n      '{ \"path\": \"guide.md\", \"content\": \"Updated architecture section.\", \"mode\": \"patch-by-heading\", \"heading\": \"Architecture\" }',\n    ],\n  },\n  delete_note: {\n    description: \"Delete a note permanently (requires confirm=true)\",\n    args: '{ \"path\": \"string\", \"confirm\": true }',\n    examples: [\n      '{ \"path\": \"old-note.md\", \"confirm\": true }',\n      '{ \"path\": \"old-note.md\", \"confirm\": false }  // returns warning, does not delete',\n    ],\n  },\n  move_note: {\n    description: \"Move or rename a note — automatically updates wikilinks across the vault\",\n    args: '{ \"from\": \"string\", \"to\": \"string\" }',\n    examples: [\n      '{ \"from\": \"user-service.md\", \"to\": \"auth-service.md\" }',\n      '{ \"from\": \"old/note.md\", \"to\": \"new/location/note.md\" }',\n    ],\n  },\n\n  // Metadata\n  get_frontmatter: {\n    description: \"Read parsed YAML frontmatter from a note as JSON\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"project-overview.md\" }'],\n  },\n  update_frontmatter: {\n    description: \"Set or delete YAML frontmatter keys — pass null to delete a key\",\n    args: '{ \"path\": \"string\", \"fields\": {} }',\n    examples: [\n      '{ \"path\": \"note.md\", \"fields\": { \"status\": \"active\", \"priority\": 1 } }',\n      '{ \"path\": \"note.md\", \"fields\": { \"deprecated_field\": null } }  // deletes the key',\n    ],\n  },\n  manage_tags: {\n    description: \"Add, remove, or list tags on a note (frontmatter and inline)\",\n    args: '{ \"path\": \"string\", \"action\": \"add|remove|list\", \"tags?\": [\"string\"] }',\n    examples: [\n      '{ \"path\": \"note.md\", \"action\": \"list\" }',\n      '{ \"path\": \"note.md\", \"action\": \"add\", \"tags\": [\"important\", \"reviewed\"] }',\n      '{ \"path\": \"note.md\", \"action\": \"remove\", \"tags\": [\"draft\"] }',\n    ],\n  },\n  rename_tag: {\n    description: \"Rename a tag across all notes in the vault (frontmatter + inline)\",\n    args: '{ \"oldTag\": \"string\", \"newTag\": \"string\" }',\n    examples: ['{ \"oldTag\": \"architecture\", \"newTag\": \"arch\" }'],\n  },\n\n  // Graph\n  backlinks: {\n    description: \"Find all notes that link TO a given note via [[wikilinks]]\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"microservices.md\" }'],\n  },\n  forwardlinks: {\n    description: \"Find all notes linked FROM a given note\",\n    args: '{ \"path\": \"string\" }',\n    examples: ['{ \"path\": \"project-overview.md\" }'],\n  },\n  graph_path: {\n    description: \"Find the shortest path between two notes in the knowledge graph\",\n    args: '{ \"from\": \"string\", \"to\": \"string\" }',\n    examples: ['{ \"from\": \"project-overview.md\", \"to\": \"user-service.md\" }'],\n  },\n  graph_statistics: {\n    description: \"Knowledge graph stats — most connected nodes, orphans, density\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n\n  // System\n  get_stats: {\n    description: \"Vault and index statistics — note count, chunks, embeddings, graph density\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n  reindex: {\n    description: \"Force a full reindex of the vault\",\n    args: \"{}\",\n    examples: [\"{}\"],\n  },\n};\n\nconst TOOL_CATEGORIES: Record<string, string[]> = {\n  Search: [\"search_semantic\", \"search_text\", \"search_graph\", \"search_hybrid\"],\n  Read: [\"read_note\", \"read_multiple_notes\", \"list_notes\"],\n  Write: [\"create_note\", \"update_note\", \"delete_note\", \"move_note\"],\n  Metadata: [\"get_frontmatter\", \"update_frontmatter\", \"manage_tags\", \"rename_tag\"],\n  Graph: [\"backlinks\", \"forwardlinks\", \"graph_path\", \"graph_statistics\"],\n  System: [\"get_stats\", \"reindex\"],\n};\n\nfunction printToolList() {\n  console.log(\"\\nSemantic Pages — 21 MCP Tools\\n\");\n  console.log(\"Usage: These tools are available via MCP when the server is running.\");\n  console.log(\"       Run `semantic-pages tools <name>` for details on a specific tool.\\n\");\n\n  for (const [category, tools] of Object.entries(TOOL_CATEGORIES)) {\n    console.log(`  ${category}:`);\n    for (const name of tools) {\n      const tool = TOOL_HELP[name];\n      console.log(`    ${name.padEnd(24)} ${tool.description}`);\n    }\n    console.log();\n  }\n\n  console.log(\"Run `semantic-pages tools <tool-name>` for arguments and examples.\");\n}\n\nfunction printToolDetail(name: string) {\n  const tool = TOOL_HELP[name];\n  if (!tool) {\n    console.error(`Unknown tool: ${name}`);\n    console.error(`Run \\`semantic-pages tools\\` to see all available tools.`);\n    process.exit(1);\n  }\n\n  console.log(`\\n  ${name}`);\n  console.log(`  ${\"─\".repeat(name.length)}`);\n  console.log(`  ${tool.description}\\n`);\n  console.log(`  Arguments:`);\n  console.log(`    ${tool.args}\\n`);\n  console.log(`  Examples:`);\n  for (const ex of tool.examples) {\n    console.log(`    ${ex}`);\n  }\n  console.log();\n}\n\nprogram\n  .name(\"semantic-pages\")\n  .description(\n    \"Semantic search + knowledge graph MCP server for markdown files\\n\\n\" +\n    \"  Start MCP server:  semantic-pages --notes ./vault\\n\" +\n    \"  Show vault stats:  semantic-pages --notes ./vault --stats\\n\" +\n    \"  Force reindex:     semantic-pages --notes ./vault --reindex\\n\" +\n    \"  List MCP tools:    semantic-pages tools\\n\" +\n    \"  Tool details:      semantic-pages tools search_semantic\"\n  )\n  .version(version);\n\nprogram\n  .command(\"tools [name]\")\n  .description(\"List all MCP tools, or show details for a specific tool\")\n  .action((name?: string) => {\n    if (name) {\n      printToolDetail(name);\n    } else {\n      printToolList();\n    }\n    process.exit(0);\n  });\n\nprogram\n  .command(\"serve\", { isDefault: true })\n  .description(\"Start the MCP server (default command)\")\n  .requiredOption(\"--notes <path>\", \"Path to markdown notes directory\")\n  .option(\"--reindex\", \"Force full reindex and exit\")\n  .option(\"--stats\", \"Show vault statistics and exit\")\n  .option(\"--wait-for-ready\", \"Block startup until index is fully built before serving (default: index in background; tools return 'Indexing in progress' until ready)\")\n  .option(\"--read-only\", \"Suppress write tools (create_note, update_note, delete_note, move_note, update_frontmatter, manage_tags, rename_tag) — use for shared docs vaults owned by another tool\")\n  .option(\"--model <name>\", \"Embedding model to use (default: all-MiniLM-L6-v2, fast; use nomic-ai/nomic-embed-text-v1.5 for higher quality)\")\n  .option(\"--workers <n>\", \"Number of worker threads for parallel embedding\", parseInt)\n  .option(\"--batch-size <n>\", \"Texts per ONNX forward pass (default: 8)\", parseInt)\n  .option(\"--no-quantized\", \"Use full-precision model instead of quantized (slower, slightly higher quality)\")\n  .option(\"--no-watch\", \"Disable file watcher\")\n  .action(async (opts) => {\n    const notesPath = resolve(opts.notes);\n\n    if (!existsSync(notesPath)) {\n      console.error(`Error: notes directory not found: ${notesPath}`);\n      process.exit(1);\n    }\n\n    if (opts.stats) {\n      const { Indexer } = await import(\"../core/indexer.js\");\n      const indexer = new Indexer(notesPath);\n      const docs = await indexer.indexAll();\n      console.log(`Notes: ${docs.length}`);\n      console.log(`Chunks: ${docs.reduce((n: number, d: any) => n + d.chunks.length, 0)}`);\n      console.log(`Wikilinks: ${docs.reduce((n: number, d: any) => n + d.wikilinks.length, 0)}`);\n      console.log(`Tags: ${new Set(docs.flatMap((d: any) => d.tags)).size} unique`);\n      process.exit(0);\n    }\n\n    if (opts.reindex) {\n      const { createServer } = await import(\"../mcp/server.js\");\n      await createServer(notesPath, {\n        watch: false,\n        waitForReady: true,\n        model: opts.model,\n        workers: opts.workers,\n        batchSize: opts.batchSize,\n        quantized: opts.quantized,\n        onProgress: (embedded, total) => {\n          process.stderr.write(`\\rEmbedding ${embedded}/${total} chunks...`);\n        },\n      });\n      process.stderr.write(\"\\n\");\n      console.log(\"Reindex complete.\");\n      process.exit(0);\n    }\n\n    // Default: start MCP server on stdio\n    const { startServer } = await import(\"../mcp/server.js\");\n    await startServer(notesPath, {\n      watch: opts.watch,\n      waitForReady: opts.waitForReady,\n      model: opts.model,\n      workers: opts.workers,\n      batchSize: opts.batchSize,\n      quantized: opts.quantized,\n      readOnly: opts.readOnly,\n    });\n  });\n\nregisterUpdateCommands(program, {\n  packageName: PKG_NAME,\n  pluginName: \"semantic-pages\",\n  configFile: \"semantic-pages.json\",\n  onAfterUpdate: (cwd) => runRelink(cwd),\n});\n\nprogram\n  .command(\"normalize-config\")\n  .description(\n    \"Rewrite fragile `npx @latest` entries in .mcp.json to the stable node-against-node_modules form (with backup and validation)\",\n  )\n  .option(\"--dry-run\", \"print the proposed changes but don't write\")\n  .action((opts: { dryRun?: boolean }) => {\n    const cwd = process.cwd();\n    const mcpPath = join(cwd, \".mcp.json\");\n    if (!existsSync(mcpPath)) {\n      console.log(\"no .mcp.json in current directory — nothing to do\");\n      process.exit(0);\n    }\n    const data = readJsonSafe(mcpPath);\n    if (!data || typeof data !== \"object\" || !data.mcpServers || typeof data.mcpServers !== \"object\") {\n      console.error(`could not parse ${mcpPath}`);\n      process.exit(1);\n    }\n    const bin = localBinArg(cwd);\n    if (!bin) {\n      console.error(\n        `no local install found at ./node_modules/@theglitchking/semantic-pages/bin/semantic-pages.\\n` +\n          `run 'npm install --save @theglitchking/semantic-pages' first, then re-run this command.`,\n      );\n      process.exit(1);\n    }\n    const rewritten: string[] = [];\n    for (const [key, entry] of Object.entries<any>(data.mcpServers)) {\n      if (!isNpxForm(entry)) continue;\n      const notes = extractNotesPath(entry) ?? \"./.claude/.vault\";\n      const extra = extractExtraFlags(entry);\n      data.mcpServers[key] = {\n        type: \"stdio\",\n        command: \"node\",\n        args: [bin, \"--notes\", notes, ...extra],\n      };\n      rewritten.push(key);\n    }\n    if (rewritten.length === 0) {\n      console.log(\"no npx-form entries found — .mcp.json is already in the stable form.\");\n      process.exit(0);\n    }\n    console.log(`Rewriting ${rewritten.length} entr${rewritten.length === 1 ? \"y\" : \"ies\"}: ${rewritten.join(\", \")}`);\n    if (opts.dryRun) {\n      console.log(\"--- proposed .mcp.json:\");\n      console.log(JSON.stringify(data, null, 2));\n      console.log(\"--- (dry-run; no changes written)\");\n      process.exit(0);\n    }\n    // Back up\n    const bakPath = join(dirname(mcpPath), \".mcp.json.bak\");\n    try {\n      writeFileSync(bakPath, readFileSync(mcpPath, \"utf8\"));\n      console.log(`backup written: ${bakPath}`);\n    } catch (err: any) {\n      console.error(`could not write backup: ${err.message}`);\n      process.exit(1);\n    }\n    writeFileSync(mcpPath, JSON.stringify(data, null, 2) + \"\\n\");\n\n    // Verify the local bin starts cleanly. We just run --version — fast and\n    // enough to catch ERR_MODULE_NOT_FOUND type failures.\n    const verify = spawnSync(\"node\", [bin, \"--version\"], { cwd, stdio: \"pipe\", timeout: 15_000 });\n    if (verify.status !== 0) {\n      console.error(`verification failed (exit ${verify.status}):\\n${verify.stderr?.toString() || \"\"}`);\n      console.error(`rolling back from ${bakPath}`);\n      writeFileSync(mcpPath, readFileSync(bakPath, \"utf8\"));\n      process.exit(1);\n    }\n    console.log(`✓ .mcp.json normalized and verified. Toggle the MCPs in /mcp to reconnect.`);\n    process.exit(0);\n  });\n\nprogram\n  .command(\"healthcheck\")\n  .description(\n    \"Verify the local install starts cleanly; self-heal common npx-cache corruption (ERR_MODULE_NOT_FOUND)\",\n  )\n  .action(() => {\n    const cwd = process.cwd();\n    const bin = findLocalBin(cwd);\n    if (!bin) {\n      console.error(`no local install at ./node_modules/@theglitchking/semantic-pages/bin/semantic-pages`);\n      console.error(`run 'npm install --save @theglitchking/semantic-pages' to install.`);\n      process.exit(1);\n    }\n\n    // 1. Warn if .mcp.json uses the fragile form.\n    const mcpPath = join(cwd, \".mcp.json\");\n    if (existsSync(mcpPath)) {\n      const data = readJsonSafe(mcpPath);\n      const entries = data?.mcpServers && typeof data.mcpServers === \"object\" ? Object.entries<any>(data.mcpServers) : [];\n      const fragile = entries.filter(([, e]) => isNpxForm(e)).map(([k]) => k);\n      if (fragile.length > 0) {\n        console.warn(\n          `⚠️  .mcp.json uses the fragile npx-@latest form for: ${fragile.join(\", \")}`,\n        );\n        console.warn(`   Rewrite to the stable form:`);\n        console.warn(`     npx --no @theglitchking/semantic-pages normalize-config`);\n      }\n    }\n\n    // 2. Smoke-test the local bin.\n    const r = spawnSync(\"node\", [bin, \"--version\"], { cwd, stdio: \"pipe\", timeout: 15_000 });\n    if (r.status === 0) {\n      console.log(`✓ local install starts cleanly (v${r.stdout?.toString().trim()})`);\n      process.exit(0);\n    }\n\n    const stderr = r.stderr?.toString() ?? \"\";\n\n    // 3. Self-heal ERR_MODULE_NOT_FOUND in npx cache (rare but the classic\n    //    failure mode that triggered 0.10.0). Extract the offending npx cache\n    //    dir from the error message, rm -rf it, retry once.\n    if (stderr.includes(\"ERR_MODULE_NOT_FOUND\")) {\n      const match = stderr.match(/([\\/~][^'\"\\s]*\\/_npx\\/[^\\/'\"\\s]+)/);\n      if (match) {\n        const bad = match[1];\n        console.warn(`detected broken npx cache at ${bad} — clearing and retrying...`);\n        try { rmSync(bad, { recursive: true, force: true }); } catch {}\n        const r2 = spawnSync(\"node\", [bin, \"--version\"], { cwd, stdio: \"pipe\", timeout: 15_000 });\n        if (r2.status === 0) {\n          console.log(`✓ cleared npx cache and verified (v${r2.stdout?.toString().trim()})`);\n          process.exit(0);\n        }\n        console.error(`retry still failed:\\n${r2.stderr?.toString() || \"\"}`);\n      } else {\n        console.error(`ERR_MODULE_NOT_FOUND but could not locate offending cache path in the error.`);\n      }\n    }\n\n    console.error(stderr || `local install failed (exit ${r.status})`);\n    process.exit(1);\n  });\n\nprogram.parse();\n"],"mappings":"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","names":[]}

package/hooks/reconcile.js

@@ -1,19 +1,28 @@
 // Plugin-specific SessionStart reconciliation for semantic-pages.
 //
-// Ensures <project>/.claude/.vault exists. Reconciles .mcp.json so the
-// "semantic-vault" entry always points at ./.claude/.vault, and adds
-// (or removes) a read-only "semantic-pages" entry pointed at
-// ./.documentation only when hit-em-with-the-docs is enabled and the
-// .documentation directory exists.
+// Responsibilities (all conservative — the user's config always wins):
+//   1. Ensure <project>/.claude/.vault exists.
+//   2. If .mcp.json is missing a "semantic-vault" entry AND the package is
+//      installed locally, add one in the node-against-node_modules form.
+//      Existing entries (any shape) are preserved — if you want to rewrite
+//      a stale entry, run `npx --no @theglitchking/semantic-pages
+//      normalize-config`.
+//   3. If hit-em-with-the-docs is enabled AND ./.documentation exists,
+//      conditionally add a read-only "semantic-pages" entry pointed at
+//      ./.documentation (same preserve-existing rule). Remove it ONLY if
+//      the existing entry matches a shape we recognize as ours.
 //
-// Idempotent: only writes .mcp.json when the computed JSON differs from
-// what's on disk.
+// Any write is preceded by a backup to .mcp.json.bak. Never writes the
+// `npx @latest` form — that shape is fragile (npx cache corruption causes
+// ERR_MODULE_NOT_FOUND) and was the root cause of the 0.10.0 bugfix.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 
 const PKG = "@theglitchking/semantic-pages";
+const VAULT_KEY = "semantic-vault";
+const DOCS_KEY = "semantic-pages";
 
 function readJson(path, fallback = null) {
   try {
@@ -32,6 +41,61 @@ function hewtdEnabled() {
   );
 }
 
+/** Absolute path to the locally-installed bin script, or null. */
+export function findLocalBin(projectRoot) {
+  const p = join(projectRoot, "node_modules", "@theglitchking", "semantic-pages", "bin", "semantic-pages");
+  return existsSync(p) ? p : null;
+}
+
+/** Returns the arg form that goes into .mcp.json for this project. */
+function binArg(projectRoot) {
+  const abs = findLocalBin(projectRoot);
+  if (!abs) return null;
+  const rel = relative(projectRoot, abs);
+  // Always use ./-prefixed relative form so it's machine-portable within the repo.
+  return rel.startsWith("..") ? abs : `./${rel}`;
+}
+
+function buildEntry(binArgStr, notesPath, extraArgs = []) {
+  return {
+    type: "stdio",
+    command: "node",
+    args: [binArgStr, "--notes", notesPath, ...extraArgs],
+  };
+}
+
+/**
+ * Detect an entry as "one of ours" so we can safely remove it when the
+ * condition that created it no longer holds. Matches both shapes we've ever
+ * written: the legacy npx-form and the new node-against-node_modules form.
+ */
+function isOurEntry(entry, notesPath) {
+  if (!entry || typeof entry !== "object") return false;
+  const cmd = entry.command;
+  const args = Array.isArray(entry.args) ? entry.args : [];
+  const argStr = args.map((a) => String(a)).join(" ");
+
+  // Legacy npx form we shipped in 0.8.0 and prior SessionStart hooks.
+  if (cmd === "npx" && argStr.includes(PKG) && argStr.includes(notesPath)) return true;
+  // Current node-against-node_modules form (0.10.0+).
+  if (
+    cmd === "node" &&
+    args.some((a) => typeof a === "string" && a.includes("node_modules/@theglitchking/semantic-pages")) &&
+    argStr.includes(notesPath)
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function backup(mcpPath) {
+  try {
+    if (existsSync(mcpPath)) {
+      writeFileSync(join(dirname(mcpPath), ".mcp.json.bak"), readFileSync(mcpPath, "utf8"));
+    }
+  } catch {}
+}
+
 export function reconcile(projectRoot) {
   const vaultDir = join(projectRoot, ".claude", ".vault");
   const docsDir = join(projectRoot, ".documentation");
@@ -61,30 +125,33 @@ export function reconcile(projectRoot) {
 
   const before = JSON.stringify(data);
 
-  data.mcpServers["semantic-vault"] = {
-    type: "stdio",
-    command: "npx",
-    args: ["-y", `${PKG}@latest`, "--notes", "./.claude/.vault"],
-  };
+  const bin = binArg(projectRoot);
 
+  // VAULT entry: create if missing AND we have a local install. Never
+  // overwrite an existing entry (even if it looks "wrong" — the user
+  // controls their .mcp.json).
+  if (!data.mcpServers[VAULT_KEY]) {
+    if (bin) {
+      data.mcpServers[VAULT_KEY] = buildEntry(bin, "./.claude/.vault");
+    }
+  }
+
+  // DOCS entry: same preserve-existing rule. Conditional on hewtd +
+  // .documentation. When removing, only remove shapes we recognize as ours.
   if (docsWired) {
-    data.mcpServers["semantic-pages"] = {
-      type: "stdio",
-      command: "npx",
-      args: ["-y", `${PKG}@latest`, "--notes", "./.documentation", "--read-only"],
-    };
-  } else if (data.mcpServers["semantic-pages"]) {
-    const existing = data.mcpServers["semantic-pages"];
-    const args = Array.isArray(existing.args) ? existing.args : [];
-    const looksLikeOurs = args.some(
-      (a) => typeof a === "string" && a.includes(".documentation"),
-    );
-    if (looksLikeOurs) delete data.mcpServers["semantic-pages"];
+    if (!data.mcpServers[DOCS_KEY]) {
+      if (bin) {
+        data.mcpServers[DOCS_KEY] = buildEntry(bin, "./.documentation", ["--read-only"]);
+      }
+    }
+  } else if (data.mcpServers[DOCS_KEY] && isOurEntry(data.mcpServers[DOCS_KEY], ".documentation")) {
+    delete data.mcpServers[DOCS_KEY];
   }
 
   const after = JSON.stringify(data);
   if (after === before) return;
 
+  backup(mcpPath);
   mkdirSync(dirname(mcpPath), { recursive: true });
   writeFileSync(mcpPath, JSON.stringify(data, null, 2) + "\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/semantic-pages",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Semantic search + knowledge graph MCP server for markdown vaults. Claude Code plugin with auto-wiring for .claude/.vault and read-only .documentation companion when hit-em-with-the-docs is installed.",
   "type": "module",
   "main": "./dist/core/index.js",