@theglitchking/semantic-memory 1.0.0

package/hooks/vault-context.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+// vault-context.js — Phase 1 activation hook for semantic-sidekick.
+//
+// Dual-mode hook:
+//   SessionStart      → hybrid search seeded from cwd/branch, injected once at session boot
+//   UserPromptSubmit  → text search seeded from prompt, fingerprinted to suppress re-firing
+//
+// Output contract (Claude Code hook protocol):
+//   { "hookSpecificOutput": { "hookEventName": "<event>", "additionalContext": "<text>" } }
+//
+// Fails open: any error logs to stderr and emits an empty additionalContext.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const DEBUG = process.env.SIDEKICK_DEBUG === "1";
+function debug(msg) {
+  if (DEBUG) process.stderr.write(`[vault-context] ${msg}\n`);
+}
+
+function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch (e) {
+    debug(`stdin parse failed: ${e.message}`);
+    return {};
+  }
+}
+
+function emit(eventName, additionalContext) {
+  const out = { hookSpecificOutput: { hookEventName: eventName } };
+  if (additionalContext && additionalContext.trim()) {
+    out.hookSpecificOutput.additionalContext = additionalContext;
+  }
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+function findVaultPath(projectRoot) {
+  // 1. Explicit env override (useful for tests)
+  if (process.env.SIDEKICK_VAULT_PATH) {
+    const p = resolve(process.env.SIDEKICK_VAULT_PATH);
+    return existsSync(p) ? p : null;
+  }
+  // 2. Read .mcp.json → mcpServers.semantic-vault.args[--notes ...]
+  const mcpPath = join(projectRoot, ".mcp.json");
+  if (existsSync(mcpPath)) {
+    try {
+      const data = JSON.parse(readFileSync(mcpPath, "utf8"));
+      const entries = data?.mcpServers || {};
+      for (const [name, entry] of Object.entries(entries)) {
+        if (!entry || typeof entry !== "object") continue;
+        if (name !== "semantic-vault" && name !== "semantic-sidekick") continue;
+        const args = Array.isArray(entry.args) ? entry.args : [];
+        const i = args.indexOf("--notes");
+        if (i >= 0 && i + 1 < args.length) {
+          const p = resolve(projectRoot, args[i + 1]);
+          if (existsSync(p)) return p;
+        }
+      }
+    } catch (e) {
+      debug(`.mcp.json parse failed: ${e.message}`);
+    }
+  }
+  // 3. Default
+  const def = join(projectRoot, ".claude", ".vault");
+  return existsSync(def) ? def : null;
+}
+
+function findCliBin(projectRoot) {
+  // Prefer local installed bin (when sidekick is a dependency)
+  const installed = join(projectRoot, "node_modules", "@theglitchking", "semantic-sidekick", "bin", "semantic-sidekick");
+  if (existsSync(installed)) return installed;
+  // Dev fallback: this hook lives in <repo>/hooks/, the built CLI is at <repo>/dist/cli/index.js
+  const dev = resolve(new URL("../dist/cli/index.js", import.meta.url).pathname);
+  if (existsSync(dev)) return dev;
+  return null;
+}
+
+function runSearchCli(cliBin, args, timeoutMs) {
+  const r = spawnSync("node", [cliBin, "search", ...args], {
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: timeoutMs,
+  });
+  if (r.status !== 0) {
+    debug(`search exited ${r.status}: ${r.stderr?.toString().trim()}`);
+    return null;
+  }
+  try {
+    return JSON.parse(r.stdout.toString());
+  } catch (e) {
+    debug(`search output parse failed: ${e.message}`);
+    return null;
+  }
+}
+
+// Fire-and-forget structured log event via CLI. Hooks don't import core modules;
+// the CLI is the shared log-writing surface so both MCP and hook code land in
+// the same log.md with the same format.
+function logEventViaCli(cliBin, vaultPath, kind, summary, payload) {
+  try {
+    const args = [cliBin, "log-event", "--notes", vaultPath, "--kind", kind, "--summary", summary];
+    if (payload) args.push("--payload", JSON.stringify(payload));
+    const r = spawnSync("node", args, { stdio: ["ignore", "ignore", "pipe"], timeout: 10_000 });
+    if (r.status !== 0) debug(`log-event exit ${r.status}: ${r.stderr?.toString().trim()}`);
+  } catch (e) {
+    debug(`log-event spawn failed: ${e.message}`);
+  }
+}
+
+function queryRecentLogViaCli(cliBin, vaultPath, sinceIso, limit = 20) {
+  try {
+    const args = [cliBin, "log-query", "--notes", vaultPath, "--after", sinceIso, "--limit", String(limit)];
+    const r = spawnSync("node", args, { stdio: ["ignore", "pipe", "pipe"], timeout: 10_000 });
+    if (r.status !== 0) {
+      debug(`log-query exit ${r.status}: ${r.stderr?.toString().trim()}`);
+      return [];
+    }
+    return JSON.parse(r.stdout.toString());
+  } catch (e) {
+    debug(`log-query failed: ${e.message}`);
+    return [];
+  }
+}
+
+export function formatContextBlock(source, query, hits) {
+  if (!hits || hits.length === 0) return "";
+  const lines = [];
+  lines.push(`<vault-context source="${source}" query="${escapeAttr(query)}">`);
+  lines.push(`The vault (semantic-sidekick) was proactively searched. Top hits:`);
+  lines.push("");
+  for (const h of hits.slice(0, 6)) {
+    const score = typeof h.score === "number" ? h.score.toFixed(2) : "";
+    lines.push(`- \`${h.path}\`${score ? ` (score: ${score})` : ""}`);
+    if (h.snippet) {
+      const snip = h.snippet.replace(/\s+/g, " ").slice(0, 240);
+      lines.push(`  > ${snip}`);
+    }
+  }
+  lines.push("");
+  lines.push(`Instructions: This block is injected on every prompt. Apply cite-or-deflect ONLY when the user's prompt is a project prose lookup (how/why/where does X work here, runbook/process question, gotcha or known-issue lookup). For those, read promising hits via \`mcp__semantic-vault__read_note\` and either cite the filenames or say "not in vault" and name the nearest misses. For meta/tool questions, debugging, status checks, directives ("proceed", "merge"), or conversational turns, ignore this block silently. Do NOT narrate "X unrelated" or "not in vault for this" on non-lookup prompts — that is noise, not honest deflection.`);
+  lines.push(`</vault-context>`);
+  return lines.join("\n");
+}
+
+function escapeAttr(s) {
+  return String(s).replace(/["<>&]/g, (c) => ({ '"': "&quot;", "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]);
+}
+
+function sessionSeedQuery(projectRoot) {
+  const parts = [];
+  parts.push(basename(projectRoot));
+  try {
+    const r = spawnSync("git", ["-C", projectRoot, "rev-parse", "--abbrev-ref", "HEAD"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000,
+    });
+    if (r.status === 0) {
+      const branch = r.stdout.toString().trim();
+      if (branch && branch !== "HEAD") parts.push(branch.replace(/[-_/]/g, " "));
+    }
+  } catch {}
+  return parts.join(" ");
+}
+
+function fingerprintPath(projectRoot) {
+  const dir = join(projectRoot, ".claude");
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  return join(dir, ".sidekick-fingerprints.json");
+}
+
+function capturePendingPath(projectRoot) {
+  const dir = join(projectRoot, ".claude");
+  try { mkdirSync(dir, { recursive: true }); } catch {}
+  return join(dir, ".sidekick-capture-pending.json");
+}
+
+const VALID_MODES = new Set(["vault-first", "research", "outage-silence"]);
+
+function modePath(projectRoot) {
+  return join(projectRoot, ".claude", ".sidekick-mode");
+}
+
+function readMode(projectRoot) {
+  try {
+    const m = readFileSync(modePath(projectRoot), "utf8").trim();
+    if (VALID_MODES.has(m)) return m;
+  } catch {}
+  return "vault-first";
+}
+
+function writeMode(projectRoot, mode) {
+  if (!VALID_MODES.has(mode)) return;
+  try {
+    const dir = join(projectRoot, ".claude");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(modePath(projectRoot), mode);
+  } catch (e) {
+    debug(`mode write failed: ${e.message}`);
+  }
+}
+
+function logMaybeModeChange(cliBin, vaultPath, from, to) {
+  if (!cliBin || !vaultPath) return;
+  if (from === to) return;
+  logEventViaCli(cliBin, vaultPath, "mode_change", `${from} → ${to}`, { from, to });
+}
+
+// Keywords that suggest the user is relaying new knowledge worth capturing as a note.
+const CAPTURE_CUES = [
+  /\bbecause\b/i,
+  /\bdecided\b|\bwe chose\b|\bthe decision\b/i,
+  /\bturned out to be\b|\bthe bug was\b|\bthe fix was\b/i,
+  /\bgotcha\b|\bworkaround\b|\bhack\b/i,
+  /\bnew convention\b|\bfrom now on\b|\bgoing forward\b/i,
+];
+
+function detectCaptureCue(prompt) {
+  for (const re of CAPTURE_CUES) {
+    if (re.test(prompt)) return re.source;
+  }
+  return null;
+}
+
+function addCapturePending(projectRoot, prompt, cueSource) {
+  try {
+    const p = capturePendingPath(projectRoot);
+    let state = { items: [] };
+    try { state = JSON.parse(readFileSync(p, "utf8")); } catch {}
+    if (!Array.isArray(state.items)) state.items = [];
+    state.items.push({
+      ts: new Date().toISOString(),
+      cue: cueSource,
+      excerpt: prompt.slice(0, 200),
+    });
+    writeFileSync(p, JSON.stringify(state));
+  } catch (e) {
+    debug(`capture pending write failed: ${e.message}`);
+  }
+}
+
+function resetCapturePending(projectRoot) {
+  try {
+    const p = capturePendingPath(projectRoot);
+    writeFileSync(p, JSON.stringify({ items: [] }));
+  } catch {}
+}
+
+function readCapturePending(projectRoot) {
+  try {
+    const p = capturePendingPath(projectRoot);
+    const state = JSON.parse(readFileSync(p, "utf8"));
+    return Array.isArray(state.items) ? state.items : [];
+  } catch {
+    return [];
+  }
+}
+
+function normalizeFingerprint(prompt) {
+  return createHash("sha1")
+    .update(prompt.toLowerCase().replace(/\s+/g, " ").trim())
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function loadFingerprints(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { recent: [] };
+  }
+}
+
+function saveFingerprints(path, state) {
+  try {
+    writeFileSync(path, JSON.stringify(state));
+  } catch (e) {
+    debug(`fingerprint save failed: ${e.message}`);
+  }
+}
+
+async function handleSessionStart(projectRoot, vaultPath, cliBin) {
+  // Capture the previous mode (if any) before we reset — so future-Claude
+  // can tell, from log.md, that we rolled back from research/outage without
+  // being shown the postmortem prompt (which is the lossy case).
+  const priorMode = readMode(projectRoot);
+  resetCapturePending(projectRoot);
+  writeMode(projectRoot, "vault-first");
+  if (priorMode !== "vault-first") {
+    logMaybeModeChange(cliBin, vaultPath, priorMode, "vault-first");
+  }
+
+  const query = sessionSeedQuery(projectRoot);
+  debug(`sessionstart seed query: "${query}"`);
+  const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "6", query], 30_000);
+
+  // State-delta preload — 14-day window per Phase 4.5 design.
+  const sinceMs = Date.now() - 14 * 24 * 60 * 60 * 1000;
+  const sinceIso = new Date(sinceMs).toISOString();
+  const recentEntries = queryRecentLogViaCli(cliBin, vaultPath, sinceIso, 30);
+
+  const searchBlock = hits && hits.length > 0 ? formatContextBlock("sessionstart", query, hits) : "";
+  const stateBlock = formatStateDeltaBlock(sinceIso, recentEntries);
+
+  const parts = [stateBlock, searchBlock].filter(Boolean);
+  emit("SessionStart", parts.join("\n\n"));
+}
+
+function formatStateDeltaBlock(sinceIso, entries) {
+  if (!entries || entries.length === 0) {
+    return `<vault-state-since date="${sinceIso}">\nNo logged activity in the last 14 days.\n</vault-state-since>`;
+  }
+  const byKind = new Map();
+  for (const e of entries) byKind.set(e.kind, (byKind.get(e.kind) || 0) + 1);
+  const kindSummary = [...byKind.entries()].map(([k, n]) => `${k}=${n}`).join(", ");
+
+  const lines = [`<vault-state-since date="${sinceIso}">`];
+  lines.push(`Totals: ${kindSummary}`);
+  lines.push("");
+  lines.push(`Most recent ${Math.min(entries.length, 6)}:`);
+  for (const e of entries.slice(-6)) {
+    lines.push(`- ${e.ts} · ${e.kind}: ${e.summary}`);
+  }
+  lines.push(`</vault-state-since>`);
+  return lines.join("\n");
+}
+
+function emitStop(additionalContext, block) {
+  // Claude Code's Stop hook schema does NOT accept hookSpecificOutput — unlike
+  // SessionStart / UserPromptSubmit / PostToolUse. Stop-mode fields are all
+  // top-level: decision, reason, continue, stopReason, suppressOutput.
+  // (Emitting hookSpecificOutput.hookEventName="Stop" fails schema validation.)
+  const out = {};
+  if (block) {
+    out.decision = "block";
+    out.reason = additionalContext || "capture pending";
+  }
+  process.stdout.write(JSON.stringify(out) + "\n");
+}
+
+async function handleStop(projectRoot) {
+  const stopHookActive = process.env.CLAUDE_STOP_HOOK_ACTIVE === "1";
+  if (stopHookActive) {
+    // Already blocking — Claude is mid-response to our nudge. Clear and yield.
+    resetCapturePending(projectRoot);
+    emitStop("", false);
+    return;
+  }
+
+  const pending = readCapturePending(projectRoot);
+  const mode = readMode(projectRoot);
+
+  // Mode-specific transition-capture. research-mode and outage-silence each
+  // demand a structured synthesis on session end; vault-first reuses the
+  // Phase 2 generic capture prompt.
+  if (mode === "research" && pending.length > 0) {
+    const lines = [
+      `<vault-transition-capture mode="research" count="${pending.length}">`,
+      `Research session ending. ${pending.length} potential finding${pending.length === 1 ? "" : "s"} accumulated:`,
+      "",
+    ];
+    for (const item of pending.slice(0, 8)) {
+      lines.push(`- "${item.excerpt.replace(/\n/g, " ")}"`);
+    }
+    lines.push("");
+    lines.push(`Mandatory before Stop: call \`mcp__semantic-vault__synthesize_note\` with dry_run=true to preview a research-synthesis note (derived_from the session's filed sources). Review with the user, then apply. A research session that ends without synthesis is lost work.`);
+    lines.push(`</vault-transition-capture>`);
+    resetCapturePending(projectRoot);
+    emitStop(lines.join("\n"), true);
+    return;
+  }
+
+  if (mode === "outage-silence") {
+    const lines = [
+      `<vault-transition-capture mode="outage-silence">`,
+      `Outage session ending. Before closing: draft a postmortem via \`mcp__semantic-vault__synthesize_note\` with \`type: gotcha\` (or \`decision\` if architectural). Include timeline, root cause, fix, preventive actions. Dry-run first, confirm with the user, then apply.`,
+      `</vault-transition-capture>`,
+    ];
+    resetCapturePending(projectRoot);
+    emitStop(lines.join("\n"), true);
+    return;
+  }
+
+  // vault-first default: existing capture-pending behavior.
+  if (pending.length === 0) {
+    emitStop("", false);
+    return;
+  }
+  const lines = [
+    `<vault-capture-prompt count="${pending.length}">`,
+    `This session surfaced ${pending.length} capture-worthy moment${pending.length === 1 ? "" : "s"} (user prompts contained decision/gotcha/fix cues):`,
+    "",
+  ];
+  for (const item of pending.slice(0, 5)) {
+    lines.push(`- cue \`${item.cue}\`: "${item.excerpt.replace(/\n/g, " ")}"`);
+  }
+  lines.push("");
+  lines.push(`Before ending: for each still-unsynthesized item above, either call \`mcp__semantic-vault__synthesize_note\` to file it with provenance, or explicitly acknowledge that it was already captured / not worth capturing.`);
+  lines.push(`</vault-capture-prompt>`);
+  resetCapturePending(projectRoot);
+  emitStop(lines.join("\n"), true);
+}
+
+async function handlePrompt(projectRoot, vaultPath, cliBin, input) {
+  const prompt = typeof input.prompt === "string" ? input.prompt : "";
+  if (!prompt || prompt.length < 8) {
+    emit("UserPromptSubmit", "");
+    return;
+  }
+  // Outage-silence suppresses auto-vault activity. Skill describes the contract;
+  // hook enforces it at the injection layer so even a misrouted turn stays quiet.
+  const mode = readMode(projectRoot);
+  if (mode === "outage-silence") {
+    debug("outage-silence mode — suppressing auto-vault context");
+    emit("UserPromptSubmit", "");
+    return;
+  }
+  const fpPath = fingerprintPath(projectRoot);
+  const state = loadFingerprints(fpPath);
+  const fp = normalizeFingerprint(prompt);
+  const recent = Array.isArray(state.recent) ? state.recent : [];
+  if (recent.includes(fp)) {
+    debug(`fingerprint ${fp} recently fired — suppressing`);
+    emit("UserPromptSubmit", "");
+    return;
+  }
+  const hits = runSearchCli(cliBin, ["--notes", vaultPath, "--limit", "8", prompt], 30_000);
+  state.recent = [fp, ...recent].slice(0, 10);
+  saveFingerprints(fpPath, state);
+  const cue = detectCaptureCue(prompt);
+  if (cue) {
+    addCapturePending(projectRoot, prompt, cue);
+  }
+  if (!hits || hits.length === 0) {
+    emit("UserPromptSubmit", "");
+    return;
+  }
+  const block = formatContextBlock("prompt", prompt.slice(0, 120), hits);
+  emit("UserPromptSubmit", block);
+}
+
+async function main() {
+  const input = readStdinJson();
+  const eventName = input.hook_event_name || process.env.CLAUDE_HOOK_EVENT || "SessionStart";
+  const projectRoot = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  debug(`event=${eventName} projectRoot=${projectRoot}`);
+
+  const vaultPath = findVaultPath(projectRoot);
+  if (!vaultPath) {
+    debug(`no vault found under ${projectRoot}`);
+    emitNoop(eventName);
+    return;
+  }
+  const cliBin = findCliBin(projectRoot);
+  if (!cliBin) {
+    debug(`no CLI bin found`);
+    emitNoop(eventName);
+    return;
+  }
+  debug(`vault=${vaultPath} bin=${cliBin}`);
+
+  try {
+    if (eventName === "UserPromptSubmit") {
+      await handlePrompt(projectRoot, vaultPath, cliBin, input);
+    } else if (eventName === "Stop") {
+      await handleStop(projectRoot);
+    } else {
+      await handleSessionStart(projectRoot, vaultPath, cliBin);
+    }
+  } catch (e) {
+    debug(`handler failed: ${e.message}`);
+    // Record the crash so future-Claude can see that the hook failed here,
+    // not just that nothing happened. Swallow log errors — never mask the real
+    // failure surface (which is the empty emit below).
+    if (cliBin && vaultPath) {
+      logEventViaCli(cliBin, vaultPath, "error", `hook crash (${eventName}): ${e.message}`, {
+        tool: "vault-context-hook",
+        event: eventName,
+        stack: (e.stack || "").split("\n").slice(0, 6).join(" | "),
+      });
+    }
+    emitNoop(eventName);
+  }
+}
+
+// Shape-aware no-op emit. Stop's schema rejects hookSpecificOutput; every other
+// event accepts the SessionStart-style envelope with empty additionalContext.
+function emitNoop(eventName) {
+  if (eventName === "Stop") {
+    process.stdout.write("{}\n");
+  } else {
+    emit(eventName, "");
+  }
+}
+
+// Only run when invoked as a script — guards against test-time imports
+// triggering stdin reads / spawnSync side effects.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@theglitchking/semantic-memory",
+  "version": "1.0.0",
+  "description": "Unified memory-layer plugin for Claude Code. One MCP server, multiple typed corpora (vault, code, plans, docs, research, project-map), unified cross-corpus knowledge graph, conditional tool registration, in-process drift detection, and human↔code translation. Rebrand of @theglitchking/semantic-sidekick at v1.0 — see CHANGELOG for migration.",
+  "type": "module",
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "exports": {
+    ".": "./dist/core/index.js",
+    "./mcp": "./dist/mcp/server.js"
+  },
+  "bin": {
+    "semantic-memory": "bin/semantic-memory",
+    "semantic-sidekick": "bin/semantic-sidekick"
+  },
+  "files": [
+    "bin",
+    "dist",
+    ".claude-plugin",
+    "hooks",
+    "commands",
+    "docs",
+    "scripts/link-skills.js",
+    "scripts/pre-commit-lint.sh",
+    "skills/semantic-first",
+    "skills/vault-first",
+    "skills/research-mode",
+    "skills/outage-silence",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/link-skills.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory-layer",
+    "semantic-search",
+    "knowledge-graph",
+    "multi-corpus",
+    "markdown",
+    "obsidian",
+    "vector-search",
+    "embeddings",
+    "wikilinks",
+    "claude",
+    "llm",
+    "ai",
+    "notes",
+    "vault",
+    "code-search",
+    "drift-detection",
+    "translation"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "optionalDependencies": {
+    "onnxruntime-node": "^1.24.3"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@theglitchking/claude-plugin-runtime": "^0.1.0",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "glob": "^13.0.6",
+    "graphology": "^0.26.0",
+    "graphology-library": "^0.8.0",
+    "graphology-shortest-path": "^2.1.0",
+    "graphology-traversal": "^0.3.1",
+    "gray-matter": "^4.0.3",
+    "hnswlib-node": "^3.0.0",
+    "minimatch": "^10.2.5",
+    "onnxruntime-web": "^1.24.3",
+    "remark-parse": "^11.0.0",
+    "remark-wiki-link": "^2.0.1",
+    "unified": "^11.0.5",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@theglitchking/hit-em-with-the-docs": "latest",
+    "@types/node": "^25.5.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/scripts/link-skills.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Postinstall — delegates to @theglitchking/claude-plugin-runtime.
+// The runtime handles: skill symlinking, default policy config write, and
+// settings.json hook registration with plugin/npm dedup. See the runtime's
+// docs/PLUGIN_AUTHORING_SCAFFOLD.md for the full contract.
+
+import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+try {
+  runPostinstall({
+    packageName: "@theglitchking/semantic-sidekick",
+    pluginName: "semantic-sidekick",
+    configFile: "semantic-sidekick.json",
+    skillsDir: "skills",
+    packageRoot,
+    hookCommand:
+      "node ./node_modules/@theglitchking/semantic-sidekick/hooks/session-start.js",
+  });
+} catch (err) {
+  console.warn(`[semantic-sidekick] postinstall failed: ${err?.message || err}`);
+}

package/scripts/pre-commit-lint.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# semantic-sidekick — template pre-commit hook for vault repos.
+#
+# Install into your vault repo:
+#   cp /path/to/semantic-sidekick/scripts/pre-commit-lint.sh .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#   # set VAULT_PATH below, or export it before commit
+#
+# On each commit this runs the cheap lint rules:
+#   - schema_violations   → blocks commit on error
+#   - missing_provenance  → warns
+#   - stale               → warns
+#
+# Pass STRICT=1 to also block on warnings. Pass SKIP_VAULT_LINT=1 to bypass.
+
+set -euo pipefail
+
+if [[ "${SKIP_VAULT_LINT:-0}" == "1" ]]; then
+  echo "pre-commit-lint: skipped (SKIP_VAULT_LINT=1)"
+  exit 0
+fi
+
+# Default to repo root; override with VAULT_PATH=... when your vault is elsewhere.
+VAULT_PATH="${VAULT_PATH:-$(git rev-parse --show-toplevel)}"
+
+# Locate semantic-sidekick CLI: prefer local install, fall back to npx.
+CLI=""
+if [[ -x "$VAULT_PATH/node_modules/@theglitchking/semantic-sidekick/bin/semantic-sidekick" ]]; then
+  CLI="node $VAULT_PATH/node_modules/@theglitchking/semantic-sidekick/bin/semantic-sidekick"
+elif command -v semantic-sidekick >/dev/null 2>&1; then
+  CLI="semantic-sidekick"
+else
+  CLI="npx --no @theglitchking/semantic-sidekick"
+fi
+
+STRICT_FLAG=""
+if [[ "${STRICT:-0}" == "1" ]]; then
+  STRICT_FLAG="--strict"
+fi
+
+echo "pre-commit-lint: running vault lint against $VAULT_PATH"
+$CLI lint --notes "$VAULT_PATH" $STRICT_FLAG