@swarmvaultai/engine 0.1.27 → 0.1.29

package/dist/index.js

@@ -21,19 +21,35 @@ import {
   uniqueBy,
   writeFileIfChanged,
   writeJsonFile
-} from "./chunk-LEUV6TWJ.js";
+} from "./chunk-IHMJCCXR.js";
 
 // src/agents.ts
+import crypto from "crypto";
 import fs from "fs/promises";
 import path from "path";
+import YAML from "yaml";
 var managedStart = "<!-- swarmvault:managed:start -->";
 var managedEnd = "<!-- swarmvault:managed:end -->";
 var legacyManagedStart = "<!-- vault:managed:start -->";
 var legacyManagedEnd = "<!-- vault:managed:end -->";
+var claudeSearchMatcher = "Glob|Grep";
+var claudeSessionMatchers = ["startup", "resume", "clear", "compact"];
+var geminiSessionMatcher = "startup";
+var geminiSearchMatcher = "glob|grep|search|find";
+var copilotHookVersion = 1;
+var agentFileKinds = {
+  agents: "AGENTS.md",
+  claude: "CLAUDE.md",
+  gemini: "GEMINI.md",
+  cursor: ".cursor/rules/swarmvault.mdc",
+  aider: "CONVENTIONS.md",
+  copilot: ".github/copilot-instructions.md"
+};
 function buildManagedBlock(target) {
-  const body = [
+  const heading = target === "aider" ? "# SwarmVault Conventions" : target === "copilot" ? "# SwarmVault Repository Instructions" : "# SwarmVault Rules";
+  return [
     managedStart,
-    "# SwarmVault Rules",
+    heading,
     "",
     "- Read `swarmvault.schema.md` before compile or query style work. It is the canonical schema path.",
     "- Treat `raw/` as immutable source input.",
@@ -46,55 +62,77 @@ function buildManagedBlock(target) {
     managedEnd,
     ""
   ].join("\n");
-  if (target === "cursor") {
-    return body;
-  }
-  return body;
 }
-var claudeHookMatcher = "Glob|Grep";
-var claudeHookCommand = "if [ -f wiki/graph/report.md ]; then echo 'swarmvault: Graph report exists. Read wiki/graph/report.md before broad raw-file searching.'; fi";
-async function installClaudeHook(rootDir) {
-  const settingsPath = path.join(rootDir, ".claude", "settings.json");
-  await ensureDir(path.dirname(settingsPath));
-  let settings = {};
-  if (await fileExists(settingsPath)) {
-    try {
-      settings = JSON.parse(await fs.readFile(settingsPath, "utf8"));
-    } catch {
-      settings = {};
-    }
-  }
-  const hooks = settings.hooks ?? {};
-  const preToolUse = hooks.PreToolUse ?? [];
-  const exists = preToolUse.some((entry) => entry.matcher === claudeHookMatcher && JSON.stringify(entry).includes("swarmvault:"));
-  if (!exists) {
-    preToolUse.push({
-      matcher: claudeHookMatcher,
-      hooks: [{ type: "command", command: claudeHookCommand }]
-    });
-  }
-  settings.hooks = { ...hooks, PreToolUse: preToolUse };
-  await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}
-`, "utf8");
-  return settingsPath;
+function supportsAgentHook(agent) {
+  return agent === "claude" || agent === "opencode" || agent === "gemini" || agent === "copilot";
 }
-function targetPathForAgent(rootDir, agent) {
+function primaryTargetPathForAgent(rootDir, agent) {
   switch (agent) {
     case "codex":
     case "goose":
     case "pi":
     case "opencode":
-      return path.join(rootDir, "AGENTS.md");
+      return path.join(rootDir, agentFileKinds.agents);
     case "claude":
-      return path.join(rootDir, "CLAUDE.md");
+      return path.join(rootDir, agentFileKinds.claude);
     case "gemini":
-      return path.join(rootDir, "GEMINI.md");
+      return path.join(rootDir, agentFileKinds.gemini);
     case "cursor":
-      return path.join(rootDir, ".cursor", "rules", "swarmvault.mdc");
+      return path.join(rootDir, agentFileKinds.cursor);
+    case "aider":
+      return path.join(rootDir, agentFileKinds.aider);
+    case "copilot":
+      return path.join(rootDir, agentFileKinds.copilot);
     default:
       throw new Error(`Unsupported agent ${String(agent)}`);
   }
 }
+function hookScriptPathForAgent(rootDir, agent) {
+  switch (agent) {
+    case "claude":
+      return path.join(rootDir, ".claude", "hooks", "swarmvault-graph-first.js");
+    case "opencode":
+      return path.join(rootDir, ".opencode", "plugins", "swarmvault-graph-first.js");
+    case "gemini":
+      return path.join(rootDir, ".gemini", "hooks", "swarmvault-graph-first.js");
+    case "copilot":
+      return path.join(rootDir, ".github", "hooks", "swarmvault-graph-first.js");
+    default:
+      return null;
+  }
+}
+function hookConfigPathForAgent(rootDir, agent) {
+  switch (agent) {
+    case "claude":
+      return path.join(rootDir, ".claude", "settings.json");
+    case "gemini":
+      return path.join(rootDir, ".gemini", "settings.json");
+    case "copilot":
+      return path.join(rootDir, ".github", "hooks", "swarmvault-graph-first.json");
+    default:
+      return null;
+  }
+}
+function targetsForAgent(rootDir, agent, options = {}) {
+  const targets = [primaryTargetPathForAgent(rootDir, agent)];
+  if (agent === "copilot") {
+    targets.push(path.join(rootDir, agentFileKinds.agents));
+  }
+  if (agent === "aider") {
+    targets.push(path.join(rootDir, ".aider.conf.yml"));
+  }
+  if (options.hook && supportsAgentHook(agent)) {
+    const configPath = hookConfigPathForAgent(rootDir, agent);
+    const scriptPath = hookScriptPathForAgent(rootDir, agent);
+    if (configPath) {
+      targets.push(configPath);
+    }
+    if (scriptPath) {
+      targets.push(scriptPath);
+    }
+  }
+  return [...new Set(targets)];
+}
 async function upsertManagedBlock(filePath, block) {
   const existing = await fileExists(filePath) ? await fs.readFile(filePath, "utf8") : "";
   if (!existing) {
@@ -115,51 +153,593 @@ async function upsertManagedBlock(filePath, block) {
 ${block}
 `, "utf8");
 }
+async function writeOwnedFile(filePath, content, executable = false) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, {
+    encoding: "utf8",
+    mode: executable ? 493 : 420
+  });
+  if (executable) {
+    await fs.chmod(filePath, 493);
+  }
+}
+async function readJsonWithWarnings(filePath, fallback, label) {
+  if (!await fileExists(filePath)) {
+    return { data: fallback, warnings: [] };
+  }
+  try {
+    const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+    return { data: parsed, warnings: [] };
+  } catch {
+    return {
+      data: fallback,
+      warnings: [`Could not parse ${label}. Left the existing file unchanged.`]
+    };
+  }
+}
+async function installClaudeHook(rootDir) {
+  const settingsPath = path.join(rootDir, ".claude", "settings.json");
+  const scriptPath = path.join(rootDir, ".claude", "hooks", "swarmvault-graph-first.js");
+  await writeOwnedFile(scriptPath, buildClaudeHookScript(), true);
+  await ensureDir(path.dirname(settingsPath));
+  const { data: settings, warnings } = await readJsonWithWarnings(settingsPath, {}, ".claude/settings.json");
+  if (warnings.length > 0 && await fileExists(settingsPath)) {
+    return { path: settingsPath, warnings };
+  }
+  const hooks = settings.hooks ?? {};
+  const sessionStart = hooks.SessionStart ?? [];
+  const preToolUse = hooks.PreToolUse ?? [];
+  const sessionCommand = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/swarmvault-graph-first.js" session-start';
+  const preToolUseCommand = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/swarmvault-graph-first.js" pre-tool-use';
+  for (const matcher of claudeSessionMatchers) {
+    if (!sessionStart.some((entry) => entry.matcher === matcher && JSON.stringify(entry).includes("swarmvault-graph-first.js"))) {
+      sessionStart.push({
+        matcher,
+        hooks: [{ type: "command", command: sessionCommand }]
+      });
+    }
+  }
+  if (!preToolUse.some((entry) => entry.matcher === claudeSearchMatcher && JSON.stringify(entry).includes("swarmvault-graph-first.js"))) {
+    preToolUse.push({
+      matcher: claudeSearchMatcher,
+      hooks: [{ type: "command", command: preToolUseCommand }]
+    });
+  }
+  settings.hooks = { ...hooks, SessionStart: sessionStart, PreToolUse: preToolUse };
+  await fs.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}
+`, "utf8");
+  return { path: settingsPath, warnings: [] };
+}
+function buildClaudeHookScript() {
+  return `#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+${markerStateSnippet("claude").trim()}
+
+async function readInput() {
+  let body = "";
+  for await (const chunk of process.stdin) {
+    body += chunk;
+  }
+  if (!body.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return {};
+  }
+}
+
+function emit(value) {
+  process.stdout.write(\`\${JSON.stringify(value)}\\n\`);
+}
+
+const mode = process.argv[2] ?? "";
+const input = await readInput();
+const cwd = resolveInputCwd(input);
+const reportNote = "SwarmVault graph report exists at wiki/graph/report.md. Read it before broad grep/glob searching.";
+
+if (!(await hasReport(cwd))) {
+  emit({});
+  process.exit(0);
+}
+
+if (mode === "session-start") {
+  await resetSession(cwd);
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: reportNote
+    }
+  });
+  process.exit(0);
+}
+
+const toolName = resolveToolName(input);
+if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
+  await markReportRead(cwd);
+  emit({});
+  process.exit(0);
+}
+
+if (isBroadSearchTool(toolName) && !(await hasSeenReport(cwd))) {
+  emit({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: reportNote
+    }
+  });
+  process.exit(0);
+}
+
+emit({});
+`;
+}
+function markerStateSnippet(agentKey) {
+  return `
+function markerState(cwd) {
+  const hash = crypto.createHash("sha256").update(cwd).digest("hex");
+  const dir = path.join(os.tmpdir(), "swarmvault-agent-hooks", "${agentKey}", hash);
+  return {
+    dir,
+    markerPath: path.join(dir, "report-read")
+  };
+}
+
+function isReportPath(value, cwd) {
+  if (typeof value !== "string" || value.length === 0) {
+    return false;
+  }
+  const reportSuffix = path.join("wiki", "graph", "report.md");
+  const normalized = value.replaceAll("\\\\", "/");
+  const reportNormalized = reportSuffix.replaceAll("\\\\", "/");
+  if (normalized.endsWith(reportNormalized)) {
+    return true;
+  }
+  return path.resolve(cwd, value) === path.resolve(cwd, reportSuffix);
+}
+
+function collectCandidatePaths(node, acc = []) {
+  if (typeof node === "string") {
+    acc.push(node);
+    return acc;
+  }
+  if (!node || typeof node !== "object") {
+    return acc;
+  }
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectCandidatePaths(item, acc);
+    }
+    return acc;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (["path", "filePath", "file_path", "paths", "target", "targets"].includes(key)) {
+      collectCandidatePaths(value, acc);
+      continue;
+    }
+    collectCandidatePaths(value, acc);
+  }
+  return acc;
+}
+
+function resolveInputCwd(input) {
+  return path.resolve(
+    input?.cwd ??
+      input?.directory ??
+      input?.workspace?.cwd ??
+      input?.toolInput?.cwd ??
+      process.cwd()
+  );
+}
+
+function resolveToolName(input) {
+  return String(input?.toolName ?? input?.tool_name ?? input?.tool?.name ?? input?.name ?? "");
+}
+
+async function hasReport(cwd) {
+  try {
+    await fs.access(path.join(cwd, "wiki", "graph", "report.md"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function markReportRead(cwd) {
+  const state = markerState(cwd);
+  await fs.mkdir(state.dir, { recursive: true });
+  await fs.writeFile(state.markerPath, "seen\\n", "utf8");
+}
+
+async function hasSeenReport(cwd) {
+  const state = markerState(cwd);
+  try {
+    await fs.access(state.markerPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resetSession(cwd) {
+  const state = markerState(cwd);
+  await fs.rm(state.dir, { recursive: true, force: true });
+}
+
+function isBroadSearchTool(toolName) {
+  return /grep|glob|search|find/i.test(toolName);
+}
+`;
+}
+function buildGeminiHookScript() {
+  return `#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+${markerStateSnippet("gemini").trim()}
+
+async function readInput() {
+  let body = "";
+  for await (const chunk of process.stdin) {
+    body += chunk;
+  }
+  if (!body.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return {};
+  }
+}
+
+function emit(value) {
+  process.stdout.write(\`\${JSON.stringify(value)}\\n\`);
+}
+
+const mode = process.argv[2] ?? "";
+const input = await readInput();
+const cwd = resolveInputCwd(input);
+const reportNote = "SwarmVault graph report exists at wiki/graph/report.md. Read it before broad grep/glob searching.";
+
+if (!(await hasReport(cwd))) {
+  emit({});
+  process.exit(0);
+}
+
+if (mode === "session-start") {
+  await resetSession(cwd);
+  emit({
+    systemMessage: reportNote,
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: "SwarmVault graph report: wiki/graph/report.md"
+    }
+  });
+  process.exit(0);
+}
+
+const toolName = resolveToolName(input);
+if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
+  await markReportRead(cwd);
+  emit({});
+  process.exit(0);
+}
+
+if (isBroadSearchTool(toolName) && !(await hasSeenReport(cwd))) {
+  emit({ systemMessage: reportNote });
+  process.exit(0);
+}
+
+emit({});
+`;
+}
+function buildCopilotHookScript() {
+  return `#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+${markerStateSnippet("copilot").trim()}
+
+async function readInput() {
+  let body = "";
+  for await (const chunk of process.stdin) {
+    body += chunk;
+  }
+  if (!body.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(body);
+  } catch {
+    return {};
+  }
+}
+
+function emit(value) {
+  if (value !== undefined) {
+    process.stdout.write(\`\${JSON.stringify(value)}\\n\`);
+  }
+}
+
+const mode = process.argv[2] ?? "";
+const input = await readInput();
+const cwd = resolveInputCwd(input);
+const reportNote = "SwarmVault graph report exists at wiki/graph/report.md. Read it before broad grep/glob searching.";
+
+if (!(await hasReport(cwd))) {
+  emit({});
+  process.exit(0);
+}
+
+if (mode === "session-start") {
+  await resetSession(cwd);
+  emit({});
+  process.exit(0);
+}
+
+const toolName = resolveToolName(input);
+if (collectCandidatePaths(input).some((value) => isReportPath(value, cwd))) {
+  await markReportRead(cwd);
+  emit({});
+  process.exit(0);
+}
+
+if (isBroadSearchTool(toolName) && !(await hasSeenReport(cwd))) {
+  emit({
+    permissionDecision: "deny",
+    permissionDecisionReason: reportNote
+  });
+  process.exit(0);
+}
+
+emit({});
+`;
+}
+function buildOpenCodePlugin() {
+  return `import path from "node:path";
+
+const reportRelativePath = path.join("wiki", "graph", "report.md");
+
+export const name = "swarmvault-graph-first";
+
+export default async function swarmvaultGraphFirst({ client }) {
+  let reportSeen = false;
+
+  async function hasReport(cwd) {
+    try {
+      await Bun.file(path.join(cwd, reportRelativePath)).arrayBuffer();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async function note(message) {
+    if (client?.app?.log) {
+      await client.app.log({
+        level: "info",
+        message
+      });
+    }
+  }
+
+  return {
+    async "session.created"(input) {
+      reportSeen = false;
+      const cwd = input?.session?.cwd ?? process.cwd();
+      if (await hasReport(cwd)) {
+        await note("SwarmVault graph report exists. Read wiki/graph/report.md before broad workspace searching.");
+      }
+    },
+    async "tool.execute.before"(input) {
+      const cwd = input?.session?.cwd ?? process.cwd();
+      if (!(await hasReport(cwd))) {
+        return;
+      }
+
+      const argsText = JSON.stringify(input?.args ?? {});
+      if (argsText.includes("wiki/graph/report.md")) {
+        reportSeen = true;
+        return;
+      }
+
+      if (!reportSeen && ["glob", "grep"].includes(String(input?.tool ?? ""))) {
+        await note("SwarmVault graph report exists. Read wiki/graph/report.md before broad workspace searching.");
+      }
+    }
+  };
+}
+`;
+}
+async function installGeminiHook(rootDir) {
+  const settingsPath = path.join(rootDir, ".gemini", "settings.json");
+  const scriptPath = path.join(rootDir, ".gemini", "hooks", "swarmvault-graph-first.js");
+  await writeOwnedFile(scriptPath, buildGeminiHookScript(), true);
+  const { data: settings, warnings } = await readJsonWithWarnings(settingsPath, {}, ".gemini/settings.json");
+  if (warnings.length > 0 && await fileExists(settingsPath)) {
+    return { paths: [settingsPath, scriptPath], warnings };
+  }
+  const hooks = settings.hooks ?? {};
+  const sessionStart = hooks.SessionStart ?? [];
+  const beforeTool = hooks.BeforeTool ?? [];
+  const sessionCommand = "node .gemini/hooks/swarmvault-graph-first.js session-start";
+  const beforeToolCommand = "node .gemini/hooks/swarmvault-graph-first.js before-tool";
+  if (!sessionStart.some((entry) => entry.matcher === geminiSessionMatcher && JSON.stringify(entry).includes("swarmvault-graph-first.js"))) {
+    sessionStart.push({
+      matcher: geminiSessionMatcher,
+      hooks: [{ name: "swarmvault-graph-first", type: "command", command: sessionCommand }]
+    });
+  }
+  if (!beforeTool.some((entry) => entry.matcher === geminiSearchMatcher && JSON.stringify(entry).includes("swarmvault-graph-first.js"))) {
+    beforeTool.push({
+      matcher: geminiSearchMatcher,
+      hooks: [{ name: "swarmvault-graph-first", type: "command", command: beforeToolCommand }]
+    });
+  }
+  settings.hooks = {
+    ...hooks,
+    SessionStart: sessionStart,
+    BeforeTool: beforeTool
+  };
+  await writeOwnedFile(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+  return { paths: [settingsPath, scriptPath], warnings: [] };
+}
+async function mergeAiderConfig(rootDir) {
+  const configPath = path.join(rootDir, ".aider.conf.yml");
+  const readTarget = "CONVENTIONS.md";
+  if (!await fileExists(configPath)) {
+    const document = new YAML.Document();
+    document.set("read", [readTarget]);
+    await writeOwnedFile(configPath, `${document.toString()}`);
+    return { path: configPath, warnings: [] };
+  }
+  try {
+    const source = await fs.readFile(configPath, "utf8");
+    const document = YAML.parseDocument(source);
+    if (document.errors.length > 0) {
+      return {
+        path: configPath,
+        warnings: ["Could not parse .aider.conf.yml. Left the existing file unchanged; add `read: CONVENTIONS.md` manually."]
+      };
+    }
+    const currentRead = document.get("read", true);
+    const values = typeof currentRead === "string" ? [currentRead] : Array.isArray(currentRead) ? currentRead.filter((item) => typeof item === "string") : [];
+    if (!values.includes(readTarget)) {
+      document.set("read", [...values, readTarget]);
+      await writeOwnedFile(configPath, `${document.toString()}`);
+    }
+    return { path: configPath, warnings: [] };
+  } catch {
+    return {
+      path: configPath,
+      warnings: ["Could not parse .aider.conf.yml. Left the existing file unchanged; add `read: CONVENTIONS.md` manually."]
+    };
+  }
+}
+async function installCopilotHook(rootDir) {
+  const hooksDir = path.join(rootDir, ".github", "hooks");
+  const scriptPath = path.join(hooksDir, "swarmvault-graph-first.js");
+  const configPath = path.join(hooksDir, "swarmvault-graph-first.json");
+  await writeOwnedFile(scriptPath, buildCopilotHookScript(), true);
+  const config = {
+    version: copilotHookVersion,
+    hooks: {
+      sessionStart: [
+        {
+          type: "command",
+          bash: "node .github/hooks/swarmvault-graph-first.js session-start",
+          powershell: "node .github/hooks/swarmvault-graph-first.js session-start",
+          cwd: ".",
+          timeoutSec: 10
+        }
+      ],
+      preToolUse: [
+        {
+          matcher: "glob|grep",
+          type: "command",
+          bash: "node .github/hooks/swarmvault-graph-first.js pre-tool-use",
+          powershell: "node .github/hooks/swarmvault-graph-first.js pre-tool-use",
+          cwd: ".",
+          timeoutSec: 10
+        }
+      ]
+    }
+  };
+  await writeOwnedFile(configPath, `${JSON.stringify(config, null, 2)}
+`);
+  return { paths: [configPath, scriptPath], warnings: [] };
+}
+async function installOpenCodeHook(rootDir) {
+  const pluginPath = path.join(rootDir, ".opencode", "plugins", "swarmvault-graph-first.js");
+  await writeOwnedFile(pluginPath, buildOpenCodePlugin());
+  return { paths: [pluginPath], warnings: [] };
+}
+function stableKeyForAgent(rootDir, agent) {
+  if (agent === "codex" || agent === "goose" || agent === "pi") {
+    return `shared:${path.join(rootDir, agentFileKinds.agents)}`;
+  }
+  return `${agent}:${crypto.createHash("sha1").update(targetsForAgent(rootDir, agent, { hook: supportsAgentHook(agent) }).join("\n")).digest("hex")}`;
+}
 async function installAgent(rootDir, agent, options = {}) {
   await initWorkspace(rootDir);
-  const target = targetPathForAgent(rootDir, agent);
+  const target = primaryTargetPathForAgent(rootDir, agent);
+  const warnings = [];
   switch (agent) {
     case "codex":
     case "goose":
     case "pi":
     case "opencode":
-      await upsertManagedBlock(target, buildManagedBlock("agents"));
-      return target;
-    case "claude": {
+      await upsertManagedBlock(path.join(rootDir, agentFileKinds.agents), buildManagedBlock("agents"));
+      break;
+    case "claude":
       await upsertManagedBlock(target, buildManagedBlock("claude"));
-      if (options.claudeHook) {
-        await installClaudeHook(rootDir);
-      }
-      return target;
-    }
-    case "gemini": {
+      break;
+    case "gemini":
       await upsertManagedBlock(target, buildManagedBlock("gemini"));
-      return target;
-    }
-    case "cursor": {
-      const rulesDir = path.dirname(target);
-      await ensureDir(rulesDir);
-      await fs.writeFile(target, `${buildManagedBlock("cursor")}
-`, "utf8");
-      return target;
-    }
+      break;
+    case "cursor":
+      await writeOwnedFile(target, `${buildManagedBlock("cursor")}
+`);
+      break;
+    case "aider":
+      await upsertManagedBlock(target, buildManagedBlock("aider"));
+      break;
+    case "copilot":
+      await upsertManagedBlock(path.join(rootDir, agentFileKinds.agents), buildManagedBlock("agents"));
+      await upsertManagedBlock(target, buildManagedBlock("copilot"));
+      break;
     default:
       throw new Error(`Unsupported agent ${String(agent)}`);
   }
+  if (agent === "aider") {
+    const aiderResult = await mergeAiderConfig(rootDir);
+    warnings.push(...aiderResult.warnings);
+  }
+  if (options.hook && supportsAgentHook(agent)) {
+    if (agent === "claude") {
+      const result = await installClaudeHook(rootDir);
+      warnings.push(...result.warnings);
+    }
+    if (agent === "opencode") {
+      const result = await installOpenCodeHook(rootDir);
+      warnings.push(...result.warnings);
+    }
+    if (agent === "gemini") {
+      const result = await installGeminiHook(rootDir);
+      warnings.push(...result.warnings);
+    }
+    if (agent === "copilot") {
+      const result = await installCopilotHook(rootDir);
+      warnings.push(...result.warnings);
+    }
+  }
+  const targets = targetsForAgent(rootDir, agent, options);
+  return warnings.length > 0 ? { agent, target, targets, warnings } : { agent, target, targets };
 }
 async function installConfiguredAgents(rootDir) {
   const { config } = await initWorkspace(rootDir);
-  const dedupedTargets = /* @__PURE__ */ new Map();
+  const dedupedAgents = /* @__PURE__ */ new Map();
   for (const agent of config.agents) {
-    const target = targetPathForAgent(rootDir, agent);
-    if (!dedupedTargets.has(target)) {
-      dedupedTargets.set(target, agent);
+    const key = stableKeyForAgent(rootDir, agent);
+    if (!dedupedAgents.has(key)) {
+      dedupedAgents.set(key, agent);
     }
   }
   return Promise.all(
-    [...dedupedTargets.values()].map(
+    [...dedupedAgents.values()].map(
       (agent) => installAgent(rootDir, agent, {
-        claudeHook: agent === "claude"
+        hook: supportsAgentHook(agent)
       })
     )
   );
@@ -179,8 +759,38 @@ var NODE_COLORS = {
 function xmlEscape(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
-function cypherEscape(value) {
-  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+function cypherStringLiteral(value) {
+  let escaped = "";
+  for (const char of value) {
+    switch (char) {
+      case "\\":
+        escaped += "\\\\";
+        break;
+      case "'":
+        escaped += "\\'";
+        break;
+      case "\n":
+        escaped += "\\n";
+        break;
+      case "\r":
+        escaped += "\\r";
+        break;
+      case "	":
+        escaped += "\\t";
+        break;
+      case "\b":
+        escaped += "\\b";
+        break;
+      case "\f":
+        escaped += "\\f";
+        break;
+      default: {
+        const code = char.codePointAt(0) ?? 0;
+        escaped += code < 32 || code === 8232 || code === 8233 ? `\\u${code.toString(16).padStart(4, "0")}` : char;
+      }
+    }
+  }
+  return `'${escaped}'`;
 }
 function relationType(relation) {
   const normalized = relation.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
@@ -456,33 +1066,33 @@ function renderCypher(graph) {
   for (const node of [...graph.nodes].sort((left, right) => left.id.localeCompare(right.id))) {
     const page = node.pageId ? pageById2.get(node.pageId) : void 0;
     const props = [
-      `id: '${cypherEscape(node.id)}'`,
-      `label: '${cypherEscape(node.label)}'`,
-      `type: '${cypherEscape(node.type)}'`,
-      `sourceIds: '${cypherEscape(JSON.stringify(node.sourceIds))}'`,
-      `projectIds: '${cypherEscape(JSON.stringify(node.projectIds))}'`,
-      node.pageId ? `pageId: '${cypherEscape(node.pageId)}'` : "",
-      page?.path ? `pagePath: '${cypherEscape(page.path)}'` : "",
-      node.language ? `language: '${cypherEscape(node.language)}'` : "",
-      node.symbolKind ? `symbolKind: '${cypherEscape(node.symbolKind)}'` : "",
-      node.communityId ? `communityId: '${cypherEscape(node.communityId)}'` : "",
+      `id: ${cypherStringLiteral(node.id)}`,
+      `label: ${cypherStringLiteral(node.label)}`,
+      `type: ${cypherStringLiteral(node.type)}`,
+      `sourceIds: ${cypherStringLiteral(JSON.stringify(node.sourceIds))}`,
+      `projectIds: ${cypherStringLiteral(JSON.stringify(node.projectIds))}`,
+      node.pageId ? `pageId: ${cypherStringLiteral(node.pageId)}` : "",
+      page?.path ? `pagePath: ${cypherStringLiteral(page.path)}` : "",
+      node.language ? `language: ${cypherStringLiteral(node.language)}` : "",
+      node.symbolKind ? `symbolKind: ${cypherStringLiteral(node.symbolKind)}` : "",
+      node.communityId ? `communityId: ${cypherStringLiteral(node.communityId)}` : "",
       node.degree !== void 0 ? `degree: ${node.degree}` : "",
       node.bridgeScore !== void 0 ? `bridgeScore: ${node.bridgeScore}` : "",
       node.isGodNode !== void 0 ? `isGodNode: ${node.isGodNode}` : ""
     ].filter(Boolean).join(", ");
-    lines.push(`MERGE (n:SwarmNode {id: '${cypherEscape(node.id)}'}) SET n += { ${props} };`);
+    lines.push(`MERGE (n:SwarmNode {id: ${cypherStringLiteral(node.id)}}) SET n += { ${props} };`);
   }
   lines.push("");
   for (const hyperedge of [...graph.hyperedges ?? []].sort((left, right) => left.id.localeCompare(right.id))) {
     const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
     lines.push(
-      `MERGE (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}) SET h += { id: '${cypherEscape(hyperedgeNodeId)}', label: '${cypherEscape(
+      `MERGE (h:SwarmNode {id: ${cypherStringLiteral(hyperedgeNodeId)}}) SET h += { id: ${cypherStringLiteral(hyperedgeNodeId)}, label: ${cypherStringLiteral(
         hyperedge.label
-      )}', type: 'hyperedge', relation: '${cypherEscape(hyperedge.relation)}', evidenceClass: '${cypherEscape(
+      )}, type: ${cypherStringLiteral("hyperedge")}, relation: ${cypherStringLiteral(hyperedge.relation)}, evidenceClass: ${cypherStringLiteral(
         hyperedge.evidenceClass
-      )}', confidence: ${hyperedge.confidence}, sourcePageIds: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}', why: '${cypherEscape(
+      )}, confidence: ${hyperedge.confidence}, sourcePageIds: ${cypherStringLiteral(JSON.stringify(hyperedge.sourcePageIds))}, why: ${cypherStringLiteral(
         hyperedge.why
-      )}' };`
+      )} };`
     );
   }
   if ((graph.hyperedges ?? []).length) {
@@ -492,22 +1102,22 @@ function renderCypher(graph) {
     const hyperedgeNodeId = exportHyperedgeNodeId(hyperedge);
     for (const nodeId of hyperedge.nodeIds) {
       lines.push(
-        `MATCH (h:SwarmNode {id: '${cypherEscape(hyperedgeNodeId)}'}), (n:SwarmNode {id: '${cypherEscape(nodeId)}'})`,
-        `MERGE (h)-[r:GROUP_MEMBER {id: '${cypherEscape(`member:${hyperedge.id}:${nodeId}`)}'}]->(n)`,
-        `SET r += { relation: 'group_member', status: 'inferred', evidenceClass: '${cypherEscape(
+        `MATCH (h:SwarmNode {id: ${cypherStringLiteral(hyperedgeNodeId)}}), (n:SwarmNode {id: ${cypherStringLiteral(nodeId)}})`,
+        `MERGE (h)-[r:GROUP_MEMBER {id: ${cypherStringLiteral(`member:${hyperedge.id}:${nodeId}`)}}]->(n)`,
+        `SET r += { relation: ${cypherStringLiteral("group_member")}, status: ${cypherStringLiteral("inferred")}, evidenceClass: ${cypherStringLiteral(
           hyperedge.evidenceClass
-        )}', confidence: ${hyperedge.confidence}, provenance: '${cypherEscape(JSON.stringify(hyperedge.sourcePageIds))}' };`
+        )}, confidence: ${hyperedge.confidence}, provenance: ${cypherStringLiteral(JSON.stringify(hyperedge.sourcePageIds))} };`
       );
     }
   }
   lines.push("");
   for (const edge of [...graph.edges].sort((left, right) => left.id.localeCompare(right.id))) {
     lines.push(
-      `MATCH (a:SwarmNode {id: '${cypherEscape(edge.source)}'}), (b:SwarmNode {id: '${cypherEscape(edge.target)}'})`,
-      `MERGE (a)-[r:${relationType(edge.relation)} {id: '${cypherEscape(edge.id)}'}]->(b)`,
-      `SET r += { relation: '${cypherEscape(edge.relation)}', status: '${cypherEscape(edge.status)}', evidenceClass: '${cypherEscape(
+      `MATCH (a:SwarmNode {id: ${cypherStringLiteral(edge.source)}}), (b:SwarmNode {id: ${cypherStringLiteral(edge.target)}})`,
+      `MERGE (a)-[r:${relationType(edge.relation)} {id: ${cypherStringLiteral(edge.id)}}]->(b)`,
+      `SET r += { relation: ${cypherStringLiteral(edge.relation)}, status: ${cypherStringLiteral(edge.status)}, evidenceClass: ${cypherStringLiteral(
         edge.evidenceClass
-      )}', confidence: ${edge.confidence}, provenance: '${cypherEscape(JSON.stringify(edge.provenance))}'${edge.similarityReasons?.length ? `, similarityReasons: '${cypherEscape(JSON.stringify(edge.similarityReasons))}'` : ""} };`
+      )}, confidence: ${edge.confidence}, provenance: ${cypherStringLiteral(JSON.stringify(edge.provenance))}${edge.similarityReasons?.length ? `, similarityReasons: ${cypherStringLiteral(JSON.stringify(edge.similarityReasons))}` : ""} };`
     );
   }
   lines.push("");
@@ -536,6 +1146,7 @@ async function exportGraphFormat(rootDir, format, outputPath) {
 // src/hooks.ts
 import fs3 from "fs/promises";
 import path3 from "path";
+import process2 from "process";
 var hookStart = "# >>> swarmvault hook >>>";
 var hookEnd = "# <<< swarmvault hook <<<";
 async function findNearestGitRoot(startPath) {
@@ -562,12 +1173,22 @@ async function findNearestGitRoot(startPath) {
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
+function resolveSwarmvaultExecutableCandidate() {
+  const argvPath = process2.argv[1];
+  if (typeof argvPath === "string" && argvPath.trim() && (argvPath.includes(`${path3.sep}@swarmvaultai${path3.sep}cli${path3.sep}`) || argvPath.includes(`${path3.sep}packages${path3.sep}cli${path3.sep}`))) {
+    return path3.resolve(argvPath);
+  }
+  return "swarmvault";
+}
 function managedHookBlock(vaultRoot) {
+  const resolvedExecutable = resolveSwarmvaultExecutableCandidate();
   return [
     hookStart,
     `cd ${shellQuote(vaultRoot)} || exit 0`,
-    "if command -v swarmvault >/dev/null 2>&1; then",
-    "  swarmvault watch --repo --once >/dev/null 2>&1 || printf '[swarmvault hook] refresh failed\\n' >&2",
+    `swarmvault_bin=${shellQuote(resolvedExecutable)}`,
+    '[ ! -x "$swarmvault_bin" ] && swarmvault_bin=$(command -v swarmvault 2>/dev/null || true)',
+    'if [ -n "$swarmvault_bin" ] && [ -x "$swarmvault_bin" ]; then',
+    `  "$swarmvault_bin" watch --repo --once >/dev/null 2>&1 || printf '[swarmvault hook] refresh failed\\n' >&2`,
     "fi",
     hookEnd,
     ""
@@ -667,7 +1288,7 @@ import { pathToFileURL } from "url";
 import { Readability } from "@mozilla/readability";
 import matter3 from "gray-matter";
 import ignore from "ignore";
-import { JSDOM } from "jsdom";
+import { JSDOM as JSDOM2 } from "jsdom";
 import mime from "mime-types";
 import TurndownService from "turndown";
 
@@ -792,6 +1413,55 @@ function collectCallNamesFromText(text, availableNames, selfName) {
   }
   return uniqueBy(names, (name) => name);
 }
+function goReceiverBinding(node) {
+  if (!node) {
+    return {};
+  }
+  const names = uniqueBy(
+    node.descendantsOfType(["identifier", "type_identifier"]).filter((item) => item !== null).map((item) => normalizeSymbolReference(item.text)).filter(Boolean),
+    (item) => item
+  );
+  if (names.length === 0) {
+    return {};
+  }
+  if (names.length === 1) {
+    return { typeName: names[0] };
+  }
+  return {
+    variableName: names[0],
+    typeName: names.at(-1)
+  };
+}
+function goCalledSymbolName(node, receiver) {
+  if (!node) {
+    return void 0;
+  }
+  if (node.type === "selector_expression") {
+    const targetName = normalizeSymbolReference(
+      extractIdentifier(node.childForFieldName("operand") ?? node.childForFieldName("object") ?? node.namedChildren.at(0) ?? null) ?? ""
+    );
+    const fieldName = normalizeSymbolReference(
+      extractIdentifier(node.childForFieldName("field") ?? findNamedChild(node, "field_identifier") ?? node.namedChildren.at(-1) ?? null) ?? ""
+    );
+    if (!fieldName) {
+      return void 0;
+    }
+    if (receiver.variableName && receiver.typeName && targetName === receiver.variableName) {
+      return `${receiver.typeName}.${fieldName}`;
+    }
+    return fieldName;
+  }
+  return normalizeSymbolReference(extractIdentifier(node) ?? "");
+}
+function goCallNamesFromBody(bodyNode, receiver) {
+  if (!bodyNode) {
+    return [];
+  }
+  return uniqueBy(
+    bodyNode.descendantsOfType("call_expression").filter((item) => item !== null).map((callNode) => goCalledSymbolName(callNode.childForFieldName("function") ?? callNode.namedChildren.at(0) ?? null, receiver)).filter((name) => Boolean(name)),
+    (name) => name
+  );
+}
 function finalizeCodeAnalysis(manifest, language, imports, draftSymbols, exportLabels, diagnostics, metadata) {
   const topLevelNames = new Set(draftSymbols.map((symbol) => symbol.name));
   for (const symbol of draftSymbols) {
@@ -1278,7 +1948,9 @@ function goCodeAnalysis(manifest, rootNode, diagnostics) {
       if (!name) {
         continue;
       }
-      const receiverType = child.type === "method_declaration" ? normalizeSymbolReference(nodeText(child.childForFieldName("receiver")).replace(/[()]/g, " ").split(/\s+/).at(-1) ?? "") : "";
+      const receiver = child.type === "method_declaration" ? goReceiverBinding(child.childForFieldName("receiver")) : {};
+      const receiverType = receiver.typeName ?? "";
+      const bodyNode = child.childForFieldName("body");
       const symbolName = receiverType ? `${receiverType}.${name}` : name;
       const exported = exportedByCapitalization(name);
       draftSymbols.push({
@@ -1286,10 +1958,10 @@ function goCodeAnalysis(manifest, rootNode, diagnostics) {
         kind: "function",
         signature: singleLineSignature(child.text),
         exported,
-        callNames: [],
+        callNames: goCallNamesFromBody(bodyNode, receiver),
         extendsNames: [],
         implementsNames: [],
-        bodyText: nodeText(child.childForFieldName("body"))
+        bodyText: nodeText(bodyNode)
       });
       if (exported) {
         exportLabels.push(symbolName);
@@ -2819,6 +3491,8 @@ async function analyzeCodeSource(manifest, extractedText, schemaHash) {
 import fs6 from "fs/promises";
 import os from "os";
 import path6 from "path";
+import { strFromU8, unzipSync } from "fflate";
+import { JSDOM } from "jsdom";
 import { z } from "zod";
 var imageVisionExtractionSchema = z.object({
   title: z.string().min(1).nullable().optional(),
@@ -2995,6 +3669,49 @@ function normalizePdfMetadata(raw) {
   }
   return Object.keys(metadata).length ? metadata : void 0;
 }
+function normalizeDocumentText(raw) {
+  return raw.replace(/\r\n/g, "\n").split(/\n{2,}/).map((section) => normalizeWhitespace(section)).filter(Boolean).join("\n\n").trim();
+}
+function parseDocxCoreMetadata(bytes) {
+  try {
+    const archive = unzipSync(new Uint8Array(bytes));
+    const coreXml = archive["docProps/core.xml"];
+    if (!coreXml) {
+      return void 0;
+    }
+    const dom = new JSDOM(strFromU8(coreXml), { contentType: "text/xml" });
+    const document = dom.window.document;
+    const valuesByLocalName = /* @__PURE__ */ new Map();
+    for (const node of Array.from(document.getElementsByTagName("*"))) {
+      const localName = node.localName?.trim().toLowerCase();
+      const text = normalizeWhitespace(node.textContent ?? "");
+      if (!localName || !text || valuesByLocalName.has(localName)) {
+        continue;
+      }
+      valuesByLocalName.set(localName, text);
+    }
+    const metadata = {};
+    const mappings = [
+      ["title", "title"],
+      ["author", "creator"],
+      ["subject", "subject"],
+      ["description", "description"],
+      ["keywords", "keywords"],
+      ["last_modified_by", "lastmodifiedby"],
+      ["created", "created"],
+      ["modified", "modified"]
+    ];
+    for (const [targetKey, sourceKey] of mappings) {
+      const value = valuesByLocalName.get(sourceKey);
+      if (value) {
+        metadata[targetKey] = value;
+      }
+    }
+    return Object.keys(metadata).length ? metadata : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function extractPdfText(input) {
   try {
     const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
@@ -3042,6 +3759,35 @@ async function extractPdfText(input) {
     };
   }
 }
+async function extractDocxText(input) {
+  try {
+    const mammoth = await import("mammoth");
+    const result = await mammoth.extractRawText({
+      buffer: input.bytes
+    });
+    const extractedText = normalizeDocumentText(result.value);
+    const warnings = result.messages.map((message) => normalizeWhitespace(message.message)).filter(Boolean).map((message) => truncate(message, 240));
+    const artifact = {
+      ...extractionMetadata("docx", input.mimeType, "docx_text"),
+      metadata: parseDocxCoreMetadata(input.bytes),
+      warnings: warnings.length ? warnings : void 0
+    };
+    if (!extractedText) {
+      artifact.warnings = [...artifact.warnings ?? [], "DOCX text extraction completed but produced no extractable text."];
+    }
+    return {
+      extractedText: extractedText || void 0,
+      artifact
+    };
+  } catch (error) {
+    return {
+      artifact: {
+        ...extractionMetadata("docx", input.mimeType, "docx_text"),
+        warnings: [`DOCX text extraction failed: ${error instanceof Error ? truncate(error.message, 240) : "unknown error"}`]
+      }
+    };
+  }
+}
 
 // src/logs.ts
 import fs7 from "fs/promises";
@@ -3352,6 +4098,9 @@ function inferKind(mimeType, filePath) {
   if (mimeType === "application/pdf" || filePath.toLowerCase().endsWith(".pdf")) {
     return "pdf";
   }
+  if (mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document" || filePath.toLowerCase().endsWith(".docx")) {
+    return "docx";
+  }
   if (mimeType.startsWith("image/")) {
     return "image";
   }
@@ -3530,7 +4279,7 @@ async function fetchResolvedText(url) {
   };
 }
 function domTextFromHtml(html, baseUrl) {
-  const dom = new JSDOM(`<body>${html}</body>`, { url: baseUrl });
+  const dom = new JSDOM2(`<body>${html}</body>`, { url: baseUrl });
   return normalizeWhitespace(dom.window.document.body.textContent ?? "");
 }
 async function captureArxivMarkdown(input, options) {
@@ -3540,7 +4289,7 @@ async function captureArxivMarkdown(input, options) {
   }
   const normalizedUrl = `https://arxiv.org/abs/${arxivId}`;
   const html = await fetchText(normalizedUrl);
-  const dom = new JSDOM(html, { url: normalizedUrl });
+  const dom = new JSDOM2(html, { url: normalizedUrl });
   const document = dom.window.document;
   const metaTitle = document.querySelector('meta[name="citation_title"]')?.getAttribute("content")?.trim();
   const headingTitle = document.querySelector("h1.title")?.textContent?.trim();
@@ -3649,7 +4398,7 @@ async function captureArticleMarkdown(rootDir, input, options, extra = { sourceT
   if (!resolved.contentType.includes("html")) {
     throw new Error(`Unsupported article content type: ${resolved.contentType}`);
   }
-  const dom = new JSDOM(resolved.text, { url: resolved.finalUrl });
+  const dom = new JSDOM2(resolved.text, { url: resolved.finalUrl });
   const document = dom.window.document;
   const canonicalHref = document.querySelector('link[rel="canonical"]')?.getAttribute("href")?.trim();
   const canonicalUrl = canonicalHref ? normalizeOriginUrl(new URL(canonicalHref, resolved.finalUrl).toString()) : resolved.finalUrl;
@@ -3768,6 +4517,22 @@ function extractMarkdownReferences(content) {
   }
   return references;
 }
+function extractHtmlLocalReferences(html, baseUrl) {
+  const dom = new JSDOM2(html, { url: baseUrl });
+  const document = dom.window.document;
+  const references = [];
+  for (const image of [...document.querySelectorAll("img[src]")]) {
+    const src = image.getAttribute("src");
+    if (!src) {
+      continue;
+    }
+    const normalized = normalizeLocalReference(src);
+    if (normalized) {
+      references.push(normalized);
+    }
+  }
+  return references;
+}
 function normalizeRemoteReference(value, baseUrl) {
   const trimmed = value.trim().replace(/^<|>$/g, "");
   const [withoutTitle] = trimmed.split(/\s+(?=(?:[^"]*"[^"]*")*[^"]*$)/, 1);
@@ -3803,7 +4568,7 @@ function extractMarkdownImageReferences(content, baseUrl) {
   return references;
 }
 async function convertHtmlToMarkdown(html, url) {
-  const dom = new JSDOM(html, { url });
+  const dom = new JSDOM2(html, { url });
   const article = new Readability(dom.window.document).parse();
   const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
   const body = article?.content ?? dom.window.document.body.innerHTML;
@@ -4006,7 +4771,7 @@ async function collectRemoteImageAttachments(assetUrls, options) {
   return { attachments, skippedCount };
 }
 function extractHtmlImageReferences(html, baseUrl) {
-  const dom = new JSDOM(html, { url: baseUrl });
+  const dom = new JSDOM2(html, { url: baseUrl });
   const document = dom.window.document;
   const references = [];
   for (const image of [...document.querySelectorAll("img[src]")]) {
@@ -4022,7 +4787,7 @@ function extractHtmlImageReferences(html, baseUrl) {
   return references;
 }
 function rewriteHtmlImageReferences(html, baseUrl, replacements) {
-  const dom = new JSDOM(html, { url: baseUrl });
+  const dom = new JSDOM2(html, { url: baseUrl });
   const document = dom.window.document;
   for (const image of [...document.querySelectorAll("img[src]")]) {
     const src = image.getAttribute("src");
@@ -4037,6 +4802,22 @@ function rewriteHtmlImageReferences(html, baseUrl, replacements) {
   }
   return dom.serialize();
 }
+function rewriteHtmlLocalReferences(html, baseUrl, replacements) {
+  const dom = new JSDOM2(html, { url: baseUrl });
+  const document = dom.window.document;
+  for (const image of [...document.querySelectorAll("img[src]")]) {
+    const src = image.getAttribute("src");
+    if (!src) {
+      continue;
+    }
+    const normalized = normalizeLocalReference(src);
+    const replacement = normalized ? replacements.get(normalized) : void 0;
+    if (replacement) {
+      image.setAttribute("src", replacement);
+    }
+  }
+  return dom.serialize();
+}
 function rewriteMarkdownImageReferences(content, baseUrl, replacements) {
   return content.replace(/(!\[[^\]]*]\()([^)]+)(\))/g, (fullMatch, prefix, target, suffix) => {
     const normalized = normalizeRemoteReference(target, baseUrl);
@@ -4177,7 +4958,7 @@ function preparedMatchesManifest(manifest, prepared, contentHash) {
   return manifest.contentHash === contentHash && manifest.extractionHash === (prepared.extractionHash ?? buildExtractionHash(prepared.extractedText, prepared.extractionArtifact)) && manifest.title === prepared.title && manifest.sourceKind === prepared.sourceKind && manifest.sourceType === prepared.sourceType && manifest.sourceClass === prepared.sourceClass && manifest.language === prepared.language && manifest.mimeType === prepared.mimeType && manifest.repoRelativePath === prepared.repoRelativePath;
 }
 function shouldDeferWatchSemanticRefresh(sourceKind) {
-  return sourceKind === "markdown" || sourceKind === "text" || sourceKind === "html" || sourceKind === "pdf" || sourceKind === "image";
+  return sourceKind === "markdown" || sourceKind === "text" || sourceKind === "html" || sourceKind === "pdf" || sourceKind === "docx" || sourceKind === "image";
 }
 function pendingSemanticRefreshId(changeType, repoRoot, relativePath) {
   return `pending:${changeType}:${sha256(`${toPosix(repoRoot)}:${relativePath}`).slice(0, 12)}`;
@@ -4441,6 +5222,12 @@ async function prepareFileInput(rootDir, absoluteInput, repoRoot, sourceClass) {
     const extracted = await extractPdfText({ mimeType, bytes: payloadBytes });
     extractedText = extracted.extractedText;
     extractionArtifact = extracted.artifact;
+  } else if (sourceKind === "docx") {
+    title = path10.basename(absoluteInput, path10.extname(absoluteInput));
+    const extracted = await extractDocxText({ mimeType, bytes: payloadBytes });
+    title = extracted.artifact.metadata?.title?.trim() || title;
+    extractedText = extracted.extractedText;
+    extractionArtifact = extracted.artifact;
   } else if (sourceKind === "image") {
     title = path10.basename(absoluteInput, path10.extname(absoluteInput));
     const extracted = await extractImageWithVision(rootDir, {
@@ -4558,6 +5345,11 @@ async function prepareUrlInput(rootDir, input, options) {
       const extracted = await extractPdfText({ mimeType, bytes: payloadBytes });
       extractedText = extracted.extractedText;
       extractionArtifact = extracted.artifact;
+    } else if (sourceKind === "docx") {
+      const extracted = await extractDocxText({ mimeType, bytes: payloadBytes });
+      title = extracted.artifact.metadata?.title?.trim() || title;
+      extractedText = extracted.extractedText;
+      extractionArtifact = extracted.artifact;
     } else if (sourceKind === "image") {
       const extracted = await extractImageWithVision(rootDir, {
         title,
@@ -4591,11 +5383,11 @@ async function collectInboxAttachmentRefs(inputDir, files) {
   for (const absolutePath of files) {
     const mimeType = guessMimeType(absolutePath);
     const sourceKind = inferKind(mimeType, absolutePath);
-    if (sourceKind !== "markdown") {
+    if (sourceKind !== "markdown" && sourceKind !== "html") {
       continue;
     }
     const content = await fs9.readFile(absolutePath, "utf8");
-    const refs = extractMarkdownReferences(content);
+    const refs = sourceKind === "html" ? extractHtmlLocalReferences(content, pathToFileURL(absolutePath).toString()) : extractMarkdownReferences(content);
     if (!refs.length) {
       continue;
     }
@@ -4673,8 +5465,50 @@ async function prepareInboxMarkdownInput(absolutePath, attachmentRefs) {
     contentHash
   };
 }
+async function prepareInboxHtmlInput(absolutePath, attachmentRefs) {
+  const originalBytes = await fs9.readFile(absolutePath);
+  const originalHtml = originalBytes.toString("utf8");
+  const initialConversion = await convertHtmlToMarkdown(originalHtml, pathToFileURL(absolutePath).toString());
+  const attachments = [];
+  for (const attachmentRef of attachmentRefs) {
+    const bytes = await fs9.readFile(attachmentRef.absolutePath);
+    attachments.push({
+      relativePath: sanitizeAssetRelativePath(attachmentRef.relativeRef),
+      mimeType: guessMimeType(attachmentRef.absolutePath),
+      originalPath: toPosix(attachmentRef.absolutePath),
+      bytes
+    });
+  }
+  const contentHash = buildCompositeHash(originalBytes, attachments);
+  const fallbackTitle = path10.basename(absolutePath, path10.extname(absolutePath));
+  const title = initialConversion.title || fallbackTitle;
+  const sourceId = `${slugify(title)}-${contentHash.slice(0, 8)}`;
+  const replacements = new Map(
+    attachmentRefs.map((attachmentRef) => [
+      attachmentRef.relativeRef.replace(/\\/g, "/"),
+      `../assets/${sourceId}/${sanitizeAssetRelativePath(attachmentRef.relativeRef)}`
+    ])
+  );
+  const rewrittenHtml = rewriteHtmlLocalReferences(originalHtml, pathToFileURL(absolutePath).toString(), replacements);
+  const converted = rewrittenHtml === originalHtml ? initialConversion : await convertHtmlToMarkdown(rewrittenHtml, pathToFileURL(absolutePath).toString());
+  const extractionArtifact = createHtmlReadabilityExtractionArtifact("html", "text/html");
+  return {
+    title: converted.title || title,
+    originType: "file",
+    sourceKind: "html",
+    originalPath: toPosix(absolutePath),
+    mimeType: "text/html",
+    storedExtension: path10.extname(absolutePath) || ".html",
+    payloadBytes: Buffer.from(rewrittenHtml, "utf8"),
+    extractedText: converted.markdown,
+    extractionArtifact,
+    extractionHash: buildExtractionHash(converted.markdown, extractionArtifact),
+    attachments,
+    contentHash
+  };
+}
 function isSupportedInboxKind(sourceKind) {
-  return ["markdown", "text", "html", "pdf", "image"].includes(sourceKind);
+  return ["markdown", "text", "html", "pdf", "docx", "image"].includes(sourceKind);
 }
 async function ingestInput(rootDir, input, options) {
   const { paths } = await initWorkspace(rootDir);
@@ -4834,7 +5668,7 @@ async function importInbox(rootDir, inputDir) {
       skipped.push({ path: toPosix(path10.relative(rootDir, absolutePath)), reason: `unsupported_kind:${sourceKind}` });
       continue;
     }
-    const prepared = sourceKind === "markdown" && refsBySource.has(absolutePath) ? await prepareInboxMarkdownInput(absolutePath, refsBySource.get(absolutePath) ?? []) : await prepareFileInput(rootDir, absolutePath);
+    const prepared = sourceKind === "markdown" && refsBySource.has(absolutePath) ? await prepareInboxMarkdownInput(absolutePath, refsBySource.get(absolutePath) ?? []) : sourceKind === "html" && refsBySource.has(absolutePath) ? await prepareInboxHtmlInput(absolutePath, refsBySource.get(absolutePath) ?? []) : await prepareFileInput(rootDir, absolutePath);
     const result = await persistPreparedInput(rootDir, prepared, paths);
     if (!result.isNew) {
       skipped.push({ path: toPosix(path10.relative(rootDir, absolutePath)), reason: "duplicate_content" });
@@ -6108,8 +6942,14 @@ async function loadPageContents(rootDir, graph) {
   await Promise.all(
     graph.pages.map(async (page) => {
       const absolutePath = path16.join(paths.wikiDir, page.path);
-      const content = await fs12.readFile(absolutePath, "utf8").catch(() => "");
-      contents.set(page.id, content);
+      const content = await fs12.readFile(absolutePath, "utf8").catch(() => {
+        process.stderr.write(`[swarmvault] Warning: could not read page ${page.path} for embedding
+`);
+        return "";
+      });
+      if (content) {
+        contents.set(page.id, content);
+      }
     })
   );
   return contents;
@@ -9207,7 +10047,7 @@ async function resolveImageGenerationProvider(rootDir) {
   if (!providerConfig) {
     throw new Error(`No provider configured with id "${preferredProviderId}" for task "imageProvider".`);
   }
-  const { createProvider: createProvider2 } = await import("./registry-YGVTLIZH.js");
+  const { createProvider: createProvider2 } = await import("./registry-5SYH3Y3U.js");
   return createProvider2(preferredProviderId, providerConfig, rootDir);
 }
 async function generateOutputArtifacts(rootDir, input) {
@@ -9768,8 +10608,64 @@ function deriveGraphMetrics(nodes, edges) {
 function resetGraphNodeMetrics(nodes) {
   return nodes.map(({ communityId: _communityId, degree: _degree, bridgeScore: _bridgeScore, isGodNode: _isGodNode, ...node }) => node);
 }
+function manifestRepoPath(manifest) {
+  return toPosix(manifest.repoRelativePath ?? path20.basename(manifest.originalPath ?? manifest.storedPath));
+}
+function goPackageScopeKey(manifest, analysis) {
+  if (analysis.code?.language !== "go") {
+    return null;
+  }
+  const packageName = analysis.code.namespace?.trim();
+  if (!packageName) {
+    return null;
+  }
+  return `${packageName}:${path20.posix.dirname(manifestRepoPath(manifest))}`;
+}
+function buildGoPackageSymbolLookups(analyses, manifestsById) {
+  const lookups = /* @__PURE__ */ new Map();
+  for (const analysis of analyses) {
+    if (analysis.code?.language !== "go") {
+      continue;
+    }
+    const manifest = manifestsById.get(analysis.sourceId);
+    if (!manifest) {
+      continue;
+    }
+    const scopeKey = goPackageScopeKey(manifest, analysis);
+    if (!scopeKey) {
+      continue;
+    }
+    const current = lookups.get(scopeKey) ?? {
+      byName: /* @__PURE__ */ new Map(),
+      methodIdsByShortName: /* @__PURE__ */ new Map()
+    };
+    for (const symbol of analysis.code.symbols) {
+      current.byName.set(symbol.name, symbol.id);
+      const separator = symbol.name.lastIndexOf(".");
+      if (separator > 0) {
+        const shortName = symbol.name.slice(separator + 1);
+        const matches = current.methodIdsByShortName.get(shortName) ?? /* @__PURE__ */ new Set();
+        matches.add(symbol.id);
+        current.methodIdsByShortName.set(shortName, matches);
+      }
+    }
+    lookups.set(scopeKey, current);
+  }
+  return new Map(
+    [...lookups.entries()].map(([scopeKey, value]) => [
+      scopeKey,
+      {
+        byName: value.byName,
+        uniqueMethodIdsByShortName: new Map(
+          [...value.methodIdsByShortName.entries()].filter(([, ids]) => ids.size === 1).map(([shortName, ids]) => [shortName, [...ids][0]])
+        )
+      }
+    ])
+  );
+}
 function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
   const manifestsById = new Map(manifests.map((manifest) => [manifest.sourceId, manifest]));
+  const goPackageSymbolLookups = buildGoPackageSymbolLookups(analyses, manifestsById);
   const sourceNodes = manifests.map((manifest) => ({
     id: `source:${manifest.sourceId}`,
     type: "source",
@@ -9916,6 +10812,10 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
         }
       }
       const symbolIdsByName = new Map(analysis.code.symbols.map((symbol) => [symbol.name, symbol.id]));
+      const goPackageLookup = analysis.code.language === "go" ? goPackageSymbolLookups.get(goPackageScopeKey(manifest, analysis) ?? "") : void 0;
+      const localSymbolIdsByName = goPackageLookup?.byName ?? symbolIdsByName;
+      const localGoMethodIdsByShortName = goPackageLookup?.uniqueMethodIdsByShortName ?? /* @__PURE__ */ new Map();
+      const resolveLocalSymbolId = (targetName) => localSymbolIdsByName.get(targetName) ?? (analysis.code?.language === "go" ? localGoMethodIdsByShortName.get(targetName) : void 0);
       for (const rationale of analysis.rationales) {
         const targetSymbolId = rationale.symbolName ? symbolIdsByName.get(rationale.symbolName) : void 0;
         const targetId = targetSymbolId ?? moduleId;
@@ -9968,9 +10868,31 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           }
         }
       }
+      if (analysis.code.language === "go") {
+        for (const symbol of analysis.code.symbols) {
+          const separator = symbol.name.lastIndexOf(".");
+          if (separator <= 0) {
+            continue;
+          }
+          const receiverTypeId = localSymbolIdsByName.get(symbol.name.slice(0, separator));
+          if (!receiverTypeId || receiverTypeId === symbol.id) {
+            continue;
+          }
+          pushEdge({
+            id: `${receiverTypeId}->${symbol.id}:defines:receiver`,
+            source: receiverTypeId,
+            target: symbol.id,
+            relation: "defines",
+            status: "extracted",
+            evidenceClass: "extracted",
+            confidence: 1,
+            provenance: [analysis.sourceId]
+          });
+        }
+      }
       for (const symbol of analysis.code.symbols) {
         for (const targetName of symbol.calls) {
-          const targetId = symbolIdsByName.get(targetName);
+          const targetId = resolveLocalSymbolId(targetName);
           if (!targetId || targetId === symbol.id) {
             continue;
           }
@@ -9986,7 +10908,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           });
         }
         for (const targetName of symbol.extends) {
-          const targetId = symbolIdsByName.get(targetName) ?? importedSymbolIdsByName.get(targetName);
+          const targetId = resolveLocalSymbolId(targetName) ?? importedSymbolIdsByName.get(targetName);
           if (!targetId) {
             continue;
           }
@@ -10002,7 +10924,7 @@ function buildGraph(manifests, analyses, pages, sourceProjects, _codeIndex) {
           });
         }
         for (const targetName of symbol.implements) {
-          const targetId = symbolIdsByName.get(targetName) ?? importedSymbolIdsByName.get(targetName);
+          const targetId = resolveLocalSymbolId(targetName) ?? importedSymbolIdsByName.get(targetName);
           if (!targetId) {
             continue;
           }
@@ -12482,7 +13404,7 @@ async function bootstrapDemo(rootDir, input) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "0.1.27";
+var SERVER_VERSION = "0.1.29";
 async function createMcpServer(rootDir) {
   const server = new McpServer({
     name: "swarmvault",
@@ -13140,7 +14062,7 @@ import mime2 from "mime-types";
 
 // src/watch.ts
 import path23 from "path";
-import process2 from "process";
+import process3 from "process";
 import chokidar from "chokidar";
 var MAX_BACKOFF_MS = 3e4;
 var BACKOFF_THRESHOLD = 3;
@@ -13405,7 +14327,7 @@ async function watchVault(rootDir, options = {}) {
       consecutiveFailures++;
       pending = true;
       if (consecutiveFailures >= CRITICAL_THRESHOLD) {
-        process2.stderr.write(
+        process3.stderr.write(
           `[swarmvault watch] ${consecutiveFailures} consecutive failures. Check vault state. Continuing at max backoff.
 `
         );
@@ -13416,51 +14338,33 @@ async function watchVault(rootDir, options = {}) {
       }
     } finally {
       const finishedAt = /* @__PURE__ */ new Date();
-      await recordSession(rootDir, {
-        operation: "watch",
-        title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
-        startedAt: startedAt.toISOString(),
-        finishedAt: finishedAt.toISOString(),
-        success,
-        error,
-        changedPages,
-        lintFindingCount,
-        lines: [
-          `reasons=${runReasons.join(",") || "none"}`,
-          `imported=${importedCount}`,
-          `scanned=${scannedCount}`,
-          `attachments=${attachmentCount}`,
-          `repo_scanned=${repoScannedCount}`,
-          `repo_imported=${repoImportedCount}`,
-          `repo_updated=${repoUpdatedCount}`,
-          `repo_removed=${repoRemovedCount}`,
-          `lint=${lintFindingCount ?? 0}`
-        ]
-      });
-      await appendWatchRun(rootDir, {
-        startedAt: startedAt.toISOString(),
-        finishedAt: finishedAt.toISOString(),
-        durationMs: finishedAt.getTime() - startedAt.getTime(),
-        inputDir: paths.inboxDir,
-        reasons: runReasons,
-        importedCount: importedCount + repoImportedCount + repoUpdatedCount,
-        scannedCount: scannedCount + repoScannedCount,
-        attachmentCount,
-        changedPages,
-        repoImportedCount,
-        repoUpdatedCount,
-        repoRemovedCount,
-        repoScannedCount,
-        pendingSemanticRefreshCount,
-        pendingSemanticRefreshPaths,
-        lintFindingCount,
-        success,
-        error
-      });
-      await writeWatchStatusArtifact(rootDir, {
-        generatedAt: finishedAt.toISOString(),
-        watchedRepoRoots,
-        lastRun: {
+      try {
+        await recordSession(rootDir, {
+          operation: "watch",
+          title: `Watch cycle for ${paths.inboxDir}${options.repo ? " and tracked repos" : ""}`,
+          startedAt: startedAt.toISOString(),
+          finishedAt: finishedAt.toISOString(),
+          success,
+          error,
+          changedPages,
+          lintFindingCount,
+          lines: [
+            `reasons=${runReasons.join(",") || "none"}`,
+            `imported=${importedCount}`,
+            `scanned=${scannedCount}`,
+            `attachments=${attachmentCount}`,
+            `repo_scanned=${repoScannedCount}`,
+            `repo_imported=${repoImportedCount}`,
+            `repo_updated=${repoUpdatedCount}`,
+            `repo_removed=${repoRemovedCount}`,
+            `lint=${lintFindingCount ?? 0}`
+          ]
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to record session log.\n");
+      }
+      try {
+        await appendWatchRun(rootDir, {
           startedAt: startedAt.toISOString(),
           finishedAt: finishedAt.toISOString(),
           durationMs: finishedAt.getTime() - startedAt.getTime(),
@@ -13479,9 +14383,39 @@ async function watchVault(rootDir, options = {}) {
           lintFindingCount,
           success,
           error
-        },
-        pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
-      });
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to append watch run.\n");
+      }
+      try {
+        await writeWatchStatusArtifact(rootDir, {
+          generatedAt: finishedAt.toISOString(),
+          watchedRepoRoots,
+          lastRun: {
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            inputDir: paths.inboxDir,
+            reasons: runReasons,
+            importedCount: importedCount + repoImportedCount + repoUpdatedCount,
+            scannedCount: scannedCount + repoScannedCount,
+            attachmentCount,
+            changedPages,
+            repoImportedCount,
+            repoUpdatedCount,
+            repoRemovedCount,
+            repoScannedCount,
+            pendingSemanticRefreshCount,
+            pendingSemanticRefreshPaths,
+            lintFindingCount,
+            success,
+            error
+          },
+          pendingSemanticRefresh: await readPendingSemanticRefresh(rootDir)
+        });
+      } catch {
+        process3.stderr.write("[swarmvault watch] Failed to write watch status artifact.\n");
+      }
       running = false;
       if (pending && !closed) {
         schedule("queued");