@contextstream/mcp-server 0.4.64 → 0.4.66

package/dist/index.js

@@ -1720,7 +1720,7 @@ function buildHooksConfig(options) {
           {
             type: "command",
             command: getHookCommand("session-start"),
-            timeout: 10
+            timeout: 15
           }
         ]
       }
@@ -4879,9 +4879,11 @@ function readHookInput() {
   }
 }
 function writeHookOutput(output) {
+  const eventName = output?.hookEventName || (typeof process.env.HOOK_EVENT_NAME === "string" ? process.env.HOOK_EVENT_NAME.trim() : "");
+  const canUseHookSpecificOutput = HOOK_SPECIFIC_OUTPUT_EVENTS.has(eventName);
   const payload = output && (output.additionalContext || output.blocked || output.reason) ? {
-    hookSpecificOutput: output.additionalContext ? {
-      hookEventName: output.hookEventName,
+    hookSpecificOutput: output.additionalContext && canUseHookSpecificOutput ? {
+      hookEventName: eventName,
       additionalContext: output.additionalContext
     } : void 0,
     additionalContext: output.additionalContext,
@@ -5082,11 +5084,12 @@ async function fetchFastContext(config, body) {
     return null;
   }
 }
-var DEFAULT_API_URL2;
+var DEFAULT_API_URL2, HOOK_SPECIFIC_OUTPUT_EVENTS;
 var init_common = __esm({
   "src/hooks/common.ts"() {
     "use strict";
     DEFAULT_API_URL2 = "https://api.contextstream.io";
+    HOOK_SPECIFIC_OUTPUT_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "UserPromptSubmit", "PostToolUse"]);
   }
 });
 
@@ -7107,10 +7110,7 @@ After compaction, call session_init(is_post_compact=true) to restore context.${c
 User instructions: ${customInstructions}` : ""}`;
   console.log(
     JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreCompact",
-        additionalContext: context
-      }
+      additionalContext: context
     })
   );
   process.exit(0);
@@ -7542,10 +7542,7 @@ async function runSessionInitHook() {
   });
   console.log(
     JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: formattedContext
-      }
+      additionalContext: formattedContext
     })
   );
   process.exit(0);
@@ -12913,6 +12910,46 @@ function normalizeNodeType(input) {
       );
   }
 }
+function normalizeTags(tags) {
+  if (!tags || tags.length === 0) return void 0;
+  const normalized = Array.from(
+    new Set(
+      tags.map((tag) => String(tag ?? "").trim()).filter(Boolean)
+    )
+  );
+  return normalized.length > 0 ? normalized : void 0;
+}
+function extractEventTags(item) {
+  const tags = [];
+  if (Array.isArray(item.tags)) {
+    tags.push(...item.tags.filter((t) => typeof t === "string"));
+  }
+  const metaTags = item.metadata?.tags;
+  if (Array.isArray(metaTags)) {
+    tags.push(...metaTags.filter((t) => typeof t === "string"));
+  }
+  return tags;
+}
+function extractEffectiveEventType(item) {
+  for (const field of ["event_type", "node_type", "type"]) {
+    const val = item[field];
+    if (typeof val === "string" && val.trim()) return val.trim();
+  }
+  for (const field of ["original_type", "node_type", "event_type", "type"]) {
+    const val = item.metadata?.[field];
+    if (typeof val === "string" && val.trim()) return val.trim();
+  }
+  return "unknown";
+}
+function isLessonResult(item) {
+  const effectiveType = extractEffectiveEventType(item);
+  if (effectiveType === "lesson") return true;
+  const tags = extractEventTags(item);
+  if (tags.some((t) => t === "lesson" || t === "lesson_system")) return true;
+  const content = typeof item.content === "string" ? item.content : "";
+  if (content.includes("### Prevention") && content.includes("### Trigger")) return true;
+  return false;
+}
 function pickString(value) {
   if (typeof value !== "string") return null;
   const trimmed = value.trim();
@@ -13448,7 +13485,12 @@ var ContextStreamClient = class _ContextStreamClient {
     if (!body.content || body.content.trim().length === 0) {
       throw new Error("content is required and cannot be empty");
     }
-    return request(this.config, "/memory/events", { body: withDefaults });
+    const normalizedTags = normalizeTags(body.tags);
+    const apiBody = {
+      ...withDefaults,
+      ...normalizedTags ? { tags: normalizedTags } : {}
+    };
+    return request(this.config, "/memory/events", { body: apiBody });
   }
   bulkIngestEvents(body) {
     return request(this.config, "/memory/events/ingest", { body: this.withDefaults(body) });
@@ -13461,6 +13503,8 @@ var ContextStreamClient = class _ContextStreamClient {
     const query = new URLSearchParams();
     if (params?.limit) query.set("limit", String(params.limit));
     if (withDefaults.project_id) query.set("project_id", withDefaults.project_id);
+    if (params?.event_type) query.set("event_type", params.event_type);
+    if (params?.tags && params.tags.length > 0) query.set("tags", params.tags.join(","));
     const suffix = query.toString() ? `?${query.toString()}` : "";
     return request(this.config, `/memory/events/workspace/${withDefaults.workspace_id}${suffix}`, {
       method: "GET"
@@ -14863,7 +14907,7 @@ var ContextStreamClient = class _ContextStreamClient {
   async captureContext(params) {
     const withDefaults = this.withDefaults(params);
     let apiEventType = "manual_note";
-    const tags = params.tags || [];
+    const tags = [...params.tags || []];
     switch (params.event_type) {
       case "conversation":
         apiEventType = "chat";
@@ -14906,18 +14950,20 @@ var ContextStreamClient = class _ContextStreamClient {
         apiEventType = "manual_note";
         tags.push(params.event_type);
     }
+    const normalizedTags = normalizeTags(tags);
     return this.createMemoryEvent({
       workspace_id: withDefaults.workspace_id,
       project_id: withDefaults.project_id,
       event_type: apiEventType,
       title: params.title,
       content: params.content,
+      tags: normalizedTags,
       provenance: params.provenance,
       code_refs: params.code_refs,
       metadata: {
         original_type: params.event_type,
         session_id: params.session_id,
-        tags,
+        ...normalizedTags ? { tags: normalizedTags } : {},
         importance: params.importance || "medium",
         captured_at: (/* @__PURE__ */ new Date()).toISOString(),
         source: "mcp_auto_capture"
@@ -14933,8 +14979,9 @@ var ContextStreamClient = class _ContextStreamClient {
     const metadata = {
       ...params.metadata || {}
     };
-    if (params.tags && params.tags.length > 0) {
-      metadata.tags = params.tags;
+    const normalizedTags = normalizeTags(params.tags);
+    if (normalizedTags) {
+      metadata.tags = normalizedTags;
     }
     if (!metadata.captured_at) {
       metadata.captured_at = (/* @__PURE__ */ new Date()).toISOString();
@@ -14948,6 +14995,7 @@ var ContextStreamClient = class _ContextStreamClient {
       event_type: params.event_type,
       title: params.title,
       content: params.content,
+      tags: normalizedTags,
       provenance: params.provenance,
       code_refs: params.code_refs,
       metadata
@@ -14967,6 +15015,7 @@ var ContextStreamClient = class _ContextStreamClient {
    */
   async sessionRemember(params) {
     const withDefaults = this.withDefaults(params);
+    const normalizedTags = normalizeTags(params.tags);
     if (!withDefaults.workspace_id) {
       throw new Error(
         "workspace_id is required for session_remember. Set defaultWorkspaceId in config or provide workspace_id."
@@ -14978,7 +15027,8 @@ var ContextStreamClient = class _ContextStreamClient {
         workspace_id: withDefaults.workspace_id,
         project_id: withDefaults.project_id,
         importance: params.importance,
-        await_indexing: params.await_indexing
+        await_indexing: params.await_indexing,
+        ...normalizedTags ? { tags: normalizedTags } : {}
       }
     });
   }
@@ -15818,14 +15868,13 @@ ${context}`;
       });
       if (!searchResult?.results) return [];
       const lessons = searchResult.results.filter((item) => {
-        const tags = item.metadata?.tags || [];
-        const isLesson = tags.includes("lesson") || tags.includes("lesson_system");
-        if (!isLesson) return false;
+        if (!isLessonResult(item)) return false;
+        const tags = extractEventTags(item);
         const severityTag = tags.find((t) => t.startsWith("severity:"));
         const severity = severityTag?.split(":")[1] || item.metadata?.importance || "medium";
         return severity === "critical" || severity === "high";
       }).slice(0, limit).map((item) => {
-        const tags = item.metadata?.tags || [];
+        const tags = extractEventTags(item);
         const severityTag = tags.find((t) => t.startsWith("severity:"));
         const severity = severityTag?.split(":")[1] || item.metadata?.importance || "medium";
         const category = tags.find(
@@ -15839,7 +15888,7 @@ ${context}`;
         ) || "unknown";
         const content = item.content || "";
         const preventionMatch = content.match(/### Prevention\n([\s\S]*?)(?:\n\n|\n\*\*|$)/);
-        const prevention = preventionMatch?.[1]?.trim() || content.slice(0, 200);
+        const prevention = preventionMatch?.[1]?.trim() || content.slice(0, 1e3);
         return {
           title: item.title || "Lesson",
           severity,
@@ -17045,6 +17094,7 @@ ${context}`;
     if (withDefaults.project_id) query.set("project_id", withDefaults.project_id);
     if (params?.doc_type) query.set("doc_type", params.doc_type);
     if (params?.is_personal !== void 0) query.set("is_personal", String(params.is_personal));
+    if (params?.query) query.set("query", params.query);
     if (params?.page) query.set("page", String(params.page));
     if (params?.per_page) query.set("per_page", String(params.per_page));
     const suffix = query.toString() ? `?${query.toString()}` : "";
@@ -17093,6 +17143,55 @@ ${context}`;
     return request(this.config, `/docs/${params.doc_id}`, { method: "DELETE" });
   }
   // -------------------------------------------------------------------------
+  // Skill methods (portable instruction + action bundles)
+  // -------------------------------------------------------------------------
+  async listSkills(params) {
+    const withDefaults = this.withDefaults(params || {});
+    const query = new URLSearchParams();
+    if (withDefaults.workspace_id) query.set("workspace_id", withDefaults.workspace_id);
+    if (params?.project_id) query.set("project_id", params.project_id);
+    if (params?.scope) query.set("scope", params.scope);
+    if (params?.status) query.set("status", params.status);
+    if (params?.category) query.set("category", params.category);
+    if (params?.query) query.set("query", params.query);
+    if (params?.is_personal !== void 0) query.set("is_personal", String(params.is_personal));
+    if (params?.limit) query.set("limit", String(params.limit));
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return request(this.config, `/skills${suffix}`, { method: "GET" });
+  }
+  async getSkill(skillId) {
+    return request(this.config, `/skills/${skillId}`, { method: "GET" });
+  }
+  async createSkill(params) {
+    return request(this.config, "/skills", { body: this.withDefaults(params) });
+  }
+  async updateSkill(skillId, params) {
+    return request(this.config, `/skills/${skillId}`, {
+      method: "PATCH",
+      body: params
+    });
+  }
+  async runSkill(skillId, params) {
+    return request(this.config, `/skills/${skillId}/run`, {
+      body: params || {}
+    });
+  }
+  async deleteSkill(skillId) {
+    return request(this.config, `/skills/${skillId}`, { method: "DELETE" });
+  }
+  async importSkills(params) {
+    return request(this.config, "/skills/import", { body: this.withDefaults(params) });
+  }
+  async exportSkills(params) {
+    const withDefaults = this.withDefaults(params || {});
+    return request(this.config, "/skills/export", { body: withDefaults });
+  }
+  async shareSkill(skillId, scope) {
+    return request(this.config, `/skills/${skillId}/share`, {
+      body: { scope }
+    });
+  }
+  // -------------------------------------------------------------------------
   // Transcript methods (conversation session storage)
   // -------------------------------------------------------------------------
   /**
@@ -17184,14 +17283,14 @@ ${context}`;
 };
 
 // src/tools.ts
-init_files();
-init_rules_templates();
-init_version();
 import * as fs5 from "node:fs";
 import * as path6 from "node:path";
 import { execFile } from "node:child_process";
 import { homedir as homedir4 } from "node:os";
 import { promisify as promisify2 } from "node:util";
+init_files();
+init_rules_templates();
+init_version();
 
 // src/tool-catalog.ts
 var TOOL_CATALOG = [
@@ -17694,6 +17793,56 @@ function classifyIndexConfidence(indexed, apiIndexed, locallyIndexed, freshness)
     reason: "Index state is inferred but lacks corroborating API/local metadata."
   };
 }
+function classifyGraphIngestIndexState(input) {
+  const { statusResult, locallyIndexed } = input;
+  const candidates = candidateObjects(statusResult);
+  const projectIndexState = readString(candidates, "project_index_state")?.toLowerCase();
+  const indexInProgress = apiResultIsIndexing(statusResult);
+  const indexed = apiResultReportsIndexed(statusResult) || locallyIndexed;
+  const indexedAt = extractIndexTimestamp(statusResult);
+  const ageHours = indexedAt !== void 0 ? Math.floor((Date.now() - indexedAt.getTime()) / (1e3 * 60 * 60)) : void 0;
+  const freshness = classifyIndexFreshness(indexed, ageHours);
+  if (indexInProgress) {
+    return {
+      state: "indexing",
+      freshness,
+      indexInProgress,
+      indexed,
+      projectIndexState,
+      ageHours
+    };
+  }
+  const explicitlyMissing = projectIndexState === "missing" || projectIndexState === "not_indexed" || projectIndexState === "unindexed";
+  if (!indexed || explicitlyMissing) {
+    return {
+      state: "missing",
+      freshness,
+      indexInProgress,
+      indexed,
+      projectIndexState,
+      ageHours
+    };
+  }
+  const explicitlyStale = projectIndexState === "stale";
+  if (freshness === "stale" || explicitlyStale) {
+    return {
+      state: "stale",
+      freshness,
+      indexInProgress,
+      indexed,
+      projectIndexState,
+      ageHours
+    };
+  }
+  return {
+    state: "ready",
+    freshness,
+    indexInProgress,
+    indexed,
+    projectIndexState,
+    ageHours
+  };
+}
 
 // src/todo-utils.ts
 function normalizeTodoStatus(status) {
@@ -17942,6 +18091,32 @@ After updating, restart the AI tool to use the new version.
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 `.trim();
 }
+function generateSuggestedRulesNotice(result) {
+  const suggestedRules = result.suggested_rules;
+  if (!suggestedRules || suggestedRules.length === 0) {
+    return "";
+  }
+  const ruleLines = suggestedRules.slice(0, 3).map((rule, i) => {
+    const cat = rule.category || "general";
+    const confidence = rule.confidence ? `${Math.round(rule.confidence * 100)}%` : "?";
+    const count = rule.occurrence_count || 0;
+    const keywords = (rule.keywords || []).join(", ");
+    return `${i + 1}. [${cat}] ${rule.instruction || ""}  (confidence: ${confidence}, seen ${count}x)
+   Keywords: ${keywords}
+   Rule ID: ${rule.id}`;
+  });
+  return `
+
+\u{1F4A1} [SUGGESTED_RULES] ContextStream detected recurring patterns and generated rule suggestions.
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+Present these to the user. They can accept or reject each one.
+
+${ruleLines.join("\n")}
+
+To accept: session(action="suggested_rule_action", rule_id="<id>", rule_action="accept")
+To reject: session(action="suggested_rule_action", rule_id="<id>", rule_action="reject")
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`;
+}
 var DEFAULT_PARAM_DESCRIPTIONS = {
   api_key: "ContextStream API key.",
   apiKey: "ContextStream API key.",
@@ -19219,6 +19394,8 @@ var CONSOLIDATED_TOOLS = /* @__PURE__ */ new Set([
   // Consolidates slack_*, github_*, notion_*, integrations_*
   "media",
   // Consolidates media indexing, search, and clip retrieval for Remotion/FFmpeg
+  "skill",
+  // Skill management: list, get, create, update, run, delete, import, export, share
   "help"
   // Consolidates session_tools, auth_me, mcp_server_version, etc.
 ]);
@@ -19238,6 +19415,7 @@ function mapToolToConsolidatedDomain(toolName) {
     return "integration";
   }
   if (toolName.startsWith("media_")) return "media";
+  if (toolName.startsWith("skill_")) return "skill";
   if (toolName === "session_tools" || toolName === "auth_me" || toolName === "mcp_server_version" || toolName === "tools_enable_bundle") {
     return "help";
   }
@@ -19333,6 +19511,31 @@ function toStructured(data) {
   }
   return void 0;
 }
+function formatSkillDetail(skill) {
+  const lines = [
+    `**${skill.title || skill.name || "?"}** (${skill.name || "?"})`,
+    `- ID: ${skill.id || "?"}`,
+    `- Scope: ${skill.scope || "personal"} | Status: ${skill.status || "active"}`
+  ];
+  if (skill.description) lines.push(`- Description: ${skill.description}`);
+  if (skill.trigger_patterns?.length) lines.push(`- Triggers: ${skill.trigger_patterns.join(", ")}`);
+  if (skill.categories?.length) lines.push(`- Categories: ${skill.categories.join(", ")}`);
+  if (skill.priority != null) lines.push(`- Priority: ${skill.priority}`);
+  if (skill.version) lines.push(`- Version: ${skill.version}`);
+  if (skill.instruction_body) {
+    const body = String(skill.instruction_body);
+    lines.push(`
+### Instruction
+${body.length > 2e3 ? body.slice(0, 2e3) + "\u2026" : body}`);
+  }
+  return lines.join("\n");
+}
+function formatRunResult(result) {
+  if (result.instruction) return result.instruction;
+  if (result.output) return `Skill output:
+${result.output}`;
+  return JSON.stringify(result, null, 2);
+}
 function readStatNumber(payload, key) {
   if (!payload || typeof payload !== "object") return void 0;
   const direct = payload[key];
@@ -20231,6 +20434,9 @@ Hint: Run session_init(folder_path="<your_project_path>") first to establish a s
     if ("data" in value) return extractCollectionArray(value.data);
     return void 0;
   }
+  function normalizeDocLookupText(value) {
+    return value.toLowerCase().replace(/[^a-z0-9\s]/g, " ").replace(/\s+/g, " ").trim();
+  }
   function tokenizeForDocMatch(query) {
     const stopWords = /* @__PURE__ */ new Set([
       "the",
@@ -20248,23 +20454,99 @@ Hint: Run session_init(folder_path="<your_project_path>") first to establish a s
       "find",
       "plan",
       "phase",
-      "phases"
+      "phases",
+      "get",
+      "open",
+      "show",
+      "read"
     ]);
-    return query.split(/[^A-Za-z0-9]+/).map((term) => term.trim().toLowerCase()).filter((term) => term.length >= 3 && !stopWords.has(term));
+    return normalizeDocLookupText(query).split(/\s+/).map((term) => term.trim()).filter((term) => term.length >= 3 && !stopWords.has(term));
   }
-  function scoreDocMatch(doc, terms) {
-    const title = String(doc?.title ?? doc?.name ?? doc?.summary ?? "").toLowerCase();
-    const content = String(doc?.content ?? "").toLowerCase();
-    const haystack = `${title} ${content}`;
-    return terms.reduce((score, term) => haystack.includes(term) ? score + 1 : score, 0);
+  function scoreDocMatch(doc, query, terms) {
+    const rawQuery = query.trim();
+    const normalizedQuery = normalizeDocLookupText(rawQuery);
+    const titleRaw = String(doc?.title ?? doc?.name ?? doc?.summary ?? "").trim();
+    const title = normalizeDocLookupText(titleRaw);
+    const docId = String(doc?.id ?? "").trim();
+    if (docId && rawQuery && docId.toLowerCase() === rawQuery.toLowerCase()) {
+      return { doc, score: 100, exact: true, source: "doc_id" };
+    }
+    if (title && normalizedQuery && title === normalizedQuery) {
+      return { doc, score: 95, exact: true, source: "exact_title" };
+    }
+    if (title && normalizedQuery && title.includes(normalizedQuery) && normalizedQuery.length >= 8) {
+      return { doc, score: 80, exact: false, source: "title_contains_query" };
+    }
+    if (terms.length === 0) {
+      return { doc, score: 0, exact: false, source: "term_overlap" };
+    }
+    const matchedTerms = terms.filter((term) => title.includes(term)).length;
+    if (matchedTerms === 0) {
+      return { doc, score: 0, exact: false, source: "term_overlap" };
+    }
+    if (matchedTerms === terms.length) {
+      return {
+        doc,
+        score: 60 + matchedTerms * 5,
+        exact: false,
+        source: "all_terms"
+      };
+    }
+    return {
+      doc,
+      score: matchedTerms * 10,
+      exact: false,
+      source: "term_overlap"
+    };
   }
-  function rankDocsForQuery(docs, query, limit) {
+  function rankDocsForQueryMatches(docs, query, limit) {
     const terms = tokenizeForDocMatch(query);
-    if (terms.length === 0) return docs.slice(0, limit);
-    const scored = docs.map((doc, idx) => ({ idx, score: scoreDocMatch(doc, terms) }));
+    const scored = docs.map((doc, idx) => ({ idx, ...scoreDocMatch(doc, query, terms) }));
     scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
-    const matched = scored.filter((entry) => entry.score > 0).slice(0, limit).map((entry) => docs[entry.idx]);
-    return matched.length > 0 ? matched : docs.slice(0, limit);
+    return scored.filter((entry) => entry.score > 0).slice(0, limit);
+  }
+  function rankDocsForQuery(docs, query, limit) {
+    const rankedMatches = rankDocsForQueryMatches(docs, query, limit);
+    return rankedMatches.length > 0 ? rankedMatches.map((entry) => entry.doc) : docs.slice(0, limit);
+  }
+  function selectResolvedDocMatch(matches) {
+    if (matches.length === 0) return void 0;
+    if (matches[0].exact) return matches[0];
+    const top = matches[0];
+    const second = matches[1];
+    if (top.score >= 80 && (!second || second.score <= 40)) {
+      return top;
+    }
+    return void 0;
+  }
+  function extractMemorySearchResults(response) {
+    const result = response?.data ?? response;
+    if (Array.isArray(result?.results)) return result.results;
+    if (Array.isArray(result?.items)) return result.items;
+    return [];
+  }
+  function buildHybridMemoryDocResults(memoryResults, docMatches, limit) {
+    const docs = docMatches.map((match) => ({
+      entity_type: "doc",
+      id: match.doc?.id ?? "unknown",
+      title: match.doc?.title ?? match.doc?.name ?? "Untitled",
+      preview: String(match.doc?.content ?? "").slice(0, 150),
+      score: match.score,
+      match_source: match.source,
+      doc_type: match.doc?.doc_type ?? "general"
+    }));
+    const memory = memoryResults.map((item) => ({
+      entity_type: "memory",
+      id: item?.id ?? item?.node_id ?? "unknown",
+      title: item?.title ?? item?.summary ?? item?.name ?? "Untitled",
+      preview: String(item?.content ?? item?.details ?? "").slice(0, 150),
+      score: Math.round(Number(item?.score ?? 0) * 100),
+      match_source: "memory_search",
+      node_type: item?.node_type ?? item?.event_type ?? item?.type ?? "unknown"
+    }));
+    const combined = [...docs, ...memory];
+    combined.sort((a, b) => Number(b.score || 0) - Number(a.score || 0));
+    return combined.slice(0, limit);
   }
   async function findDocsFallback(workspaceId, candidateProjectIds, query, limit) {
     const uniqueCandidates = [];
@@ -20398,6 +20680,137 @@ Hint: Run session_init(folder_path="<your_project_path>") first to establish a s
       }
     })();
   }
+  async function runGraphIngestWithPreflight(projectId, wait) {
+    const folderPath = resolveFolderPath(void 0, sessionManager);
+    const localIndexProjectId = folderPath ? await indexedProjectIdForFolder(folderPath) : void 0;
+    const locallyIndexed = localIndexProjectId === projectId;
+    const suggestedPath = folderPath || "<your_project_path>";
+    let statusResult = {};
+    try {
+      statusResult = await client.projectIndexStatus(projectId);
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error;
+    }
+    const preflight = classifyGraphIngestIndexState({
+      statusResult,
+      locallyIndexed
+    });
+    const preflightData = {
+      index_state: preflight.state,
+      index_freshness: preflight.freshness,
+      index_age_hours: preflight.ageHours ?? null,
+      index_in_progress: preflight.indexInProgress,
+      project_index_state: preflight.projectIndexState ?? null,
+      locally_indexed: locallyIndexed
+    };
+    if (preflight.state === "indexing") {
+      const deferred = {
+        status: "deferred",
+        wait,
+        reason: "Project index refresh is in progress. Graph ingest is deferred until index refresh completes.",
+        preflight: {
+          ...preflightData,
+          auto_refresh_started: false,
+          graph_ingest_executed: false
+        },
+        next_step: `Run project(action="index_status") and retry graph(action="ingest") when freshness is not stale.`
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Project indexing is currently in progress; graph ingest was deferred to avoid rebuilding edges from stale embeddings.
+
+${formatContent(deferred)}`
+          }
+        ],
+        structuredContent: deferred
+      };
+    }
+    if (preflight.state === "stale" || preflight.state === "missing") {
+      const validPath = folderPath ? await validateReadableDirectory(folderPath) : void 0;
+      if (!validPath?.ok) {
+        return errorResult(
+          `Graph ingest is blocked because the project index is ${preflight.state} and no readable project folder is available for auto-refresh.
+Run project(action="ingest_local", path="${suggestedPath}") first, then retry graph(action="ingest").`
+        );
+      }
+      if (!preflight.indexInProgress) {
+        startBackgroundIngest(projectId, validPath.resolvedPath, { force: true }, { preflight: true });
+      }
+      const deferred = {
+        status: "deferred",
+        wait,
+        reason: `Project index is ${preflight.state}. Started index refresh before graph ingest to avoid destructive edge rebuilds from stale embeddings.`,
+        preflight: {
+          ...preflightData,
+          auto_refresh_started: !preflight.indexInProgress,
+          auto_refresh_path: validPath.resolvedPath,
+          auto_refresh_force: true,
+          graph_ingest_executed: false
+        },
+        next_step: `Monitor with project(action="index_status"), then rerun graph(action="ingest").`
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Project index is ${preflight.state}; started index refresh and deferred graph ingest to prevent stale-edge rebuild.
+
+${formatContent(deferred)}`
+          }
+        ],
+        structuredContent: deferred
+      };
+    }
+    let estimate = null;
+    try {
+      const stats = await client.projectStatistics(projectId);
+      estimate = estimateGraphIngestMinutes(stats);
+    } catch (error) {
+      logDebug(`Failed to fetch project statistics for graph estimate: ${error}`);
+    }
+    const result = await client.graphIngest({ project_id: projectId, wait });
+    const estimateText = estimate ? `Estimated time: ${estimate.min}-${estimate.max} min${estimate.basis ? ` (based on ${estimate.basis})` : ""}.` : "Estimated time varies with repo size.";
+    const note = `Graph ingestion is running ${wait ? "synchronously" : "asynchronously"} and can take a few minutes. ${estimateText}`;
+    const structured = toStructured(result);
+    const structuredContent = structured && typeof structured === "object" ? {
+      ...structured,
+      wait,
+      note,
+      preflight: {
+        ...preflightData,
+        auto_refresh_started: false,
+        graph_ingest_executed: true
+      },
+      ...estimate ? {
+        estimate_minutes: { min: estimate.min, max: estimate.max },
+        estimate_basis: estimate.basis
+      } : {}
+    } : {
+      wait,
+      note,
+      preflight: {
+        ...preflightData,
+        auto_refresh_started: false,
+        graph_ingest_executed: true
+      },
+      ...estimate ? {
+        estimate_minutes: { min: estimate.min, max: estimate.max },
+        estimate_basis: estimate.basis
+      } : {}
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${note}
+${formatContent(result)}`
+        }
+      ],
+      structuredContent
+    };
+  }
   function summarizeVideoTextExtraction(metadata) {
     if (!metadata || typeof metadata !== "object") return void 0;
     const extraction = metadata.video_text_extraction;
@@ -21446,6 +21859,201 @@ Access: Free`,
       };
     }
   );
+  registerTool(
+    "skill",
+    {
+      title: "Manage reusable skills",
+      description: `Manage and execute reusable skills (instruction + action bundles). Skills are portable across projects, sessions, and tools.
+
+Actions:
+- list: Browse skills (filter by scope, status, category)
+- get: Get skill details by ID or name
+- create: Define a new skill with name, instruction, and triggers
+- update: Modify an existing skill
+- run: Execute a skill (by ID or name)
+- delete: Remove a skill
+- import: Import skills from file or content (supports markdown, JSON, cursorrules, claude_md)
+- export: Export skills in various formats
+- share: Change skill visibility scope`,
+      inputSchema: external_exports.object({
+        action: external_exports.enum(["list", "get", "create", "update", "run", "delete", "import", "export", "share"]).describe("The action to perform"),
+        skill_id: external_exports.string().optional().describe("Skill ID (UUID)"),
+        name: external_exports.string().optional().describe("Skill name (slug, e.g. 'deploy-checker')"),
+        title: external_exports.string().optional().describe("Skill display title"),
+        description: external_exports.string().optional().describe("Skill description"),
+        instruction_body: external_exports.string().optional().describe("Markdown instruction text (the prompt)"),
+        trigger_patterns: external_exports.array(external_exports.string()).optional().describe("Keywords/phrases for auto-activation"),
+        trigger_regex: external_exports.string().optional().describe("Optional regex for advanced trigger matching"),
+        categories: external_exports.array(external_exports.string()).optional().describe("Tags for discovery/filtering"),
+        actions: external_exports.any().optional().describe("Action steps array [{type, tool, params, ...}]"),
+        params: external_exports.any().optional().describe("Parameters passed to skill execution"),
+        dry_run: external_exports.boolean().optional().describe("Preview execution without running"),
+        scope: external_exports.enum(["personal", "team", "public", "all"]).optional().describe("Visibility scope"),
+        status: external_exports.enum(["active", "draft", "archived"]).optional().describe("Skill status"),
+        is_personal: external_exports.boolean().optional().describe("Whether skill is personal"),
+        priority: external_exports.number().optional().describe("Skill priority 0-100 (higher = matched first)"),
+        content: external_exports.string().optional().describe("Content string for import"),
+        file_path: external_exports.string().optional().describe("Local file path for import"),
+        format: external_exports.enum(["auto", "json", "markdown", "skills_md", "cursorrules", "claude_md", "aider", "zip"]).optional().describe("Import/export format"),
+        source_tool: external_exports.string().optional().describe("Source tool name (for import provenance)"),
+        source_file: external_exports.string().optional().describe("Source filename (for import provenance)"),
+        skill_ids: external_exports.array(external_exports.string()).optional().describe("Skill IDs for export"),
+        change_summary: external_exports.string().optional().describe("Summary of changes (for version history)"),
+        workspace_id: external_exports.string().optional().describe("Workspace ID (UUID)"),
+        project_id: external_exports.string().optional().describe("Project ID (UUID)"),
+        query: external_exports.string().optional().describe("Search query"),
+        category: external_exports.string().optional().describe("Filter by category tag"),
+        limit: external_exports.number().optional().describe("Max results to return")
+      })
+    },
+    async (input) => {
+      const action = input.action;
+      switch (action) {
+        case "list": {
+          const result = await client.listSkills({
+            workspace_id: input.workspace_id,
+            project_id: input.project_id,
+            scope: input.scope,
+            status: input.status,
+            category: input.category,
+            query: input.query,
+            is_personal: input.is_personal,
+            limit: input.limit
+          });
+          const items = result.items || [];
+          let text = `Found ${items.length} skill(s).
+`;
+          for (const item of items) {
+            const name = item.name || "?";
+            const title = item.title || "?";
+            const scope = item.scope || "?";
+            const status = item.status || "?";
+            const id = item.id || "?";
+            text += `- ${title} (${name}) [${scope}|${status}] id=${id}
+`;
+          }
+          return { content: [{ type: "text", text }] };
+        }
+        case "get": {
+          let skillData;
+          if (input.skill_id) {
+            skillData = await client.getSkill(input.skill_id);
+          } else if (input.name) {
+            const result = await client.listSkills({
+              workspace_id: input.workspace_id,
+              query: input.name,
+              limit: 1
+            });
+            skillData = result.items?.find((s) => s.name === input.name) || result.items?.[0];
+            if (!skillData) throw new Error(`Skill '${input.name}' not found`);
+          } else {
+            throw new Error("Either skill_id or name is required for 'get'");
+          }
+          const detail = formatSkillDetail(skillData);
+          return { content: [{ type: "text", text: detail }] };
+        }
+        case "create": {
+          if (!input.name) throw new Error("'name' is required for create");
+          if (!input.instruction_body) throw new Error("'instruction_body' is required for create");
+          const result = await client.createSkill({
+            name: input.name,
+            title: input.title || input.name,
+            instruction_body: input.instruction_body,
+            description: input.description,
+            trigger_patterns: input.trigger_patterns,
+            trigger_regex: input.trigger_regex,
+            categories: input.categories,
+            actions: input.actions,
+            scope: input.scope,
+            is_personal: input.is_personal,
+            priority: input.priority,
+            workspace_id: input.scope === "team" ? input.workspace_id : void 0,
+            project_id: void 0,
+            // Skills are account-level by default
+            source_tool: input.source_tool,
+            source_file: input.source_file
+          });
+          return { content: [{ type: "text", text: `Skill '${input.name}' created (id=${result.id || "?"}).` }] };
+        }
+        case "update": {
+          if (!input.skill_id) throw new Error("'skill_id' is required for update");
+          const result = await client.updateSkill(input.skill_id, {
+            title: input.title,
+            description: input.description,
+            instruction_body: input.instruction_body,
+            trigger_patterns: input.trigger_patterns,
+            trigger_regex: input.trigger_regex,
+            categories: input.categories,
+            actions: input.actions,
+            scope: input.scope,
+            status: input.status,
+            is_personal: input.is_personal,
+            priority: input.priority,
+            change_summary: input.change_summary
+          });
+          return { content: [{ type: "text", text: `Skill ${input.skill_id} updated (version=${result.version || 0}).` }] };
+        }
+        case "run": {
+          let resolvedId = input.skill_id;
+          if (!resolvedId && input.name) {
+            const result2 = await client.listSkills({
+              workspace_id: input.workspace_id,
+              query: input.name,
+              limit: 1
+            });
+            const found = result2.items?.find((s) => s.name === input.name) || result2.items?.[0];
+            if (!found?.id) throw new Error(`Skill '${input.name}' not found`);
+            resolvedId = found.id;
+          }
+          if (!resolvedId) throw new Error("Either skill_id or name is required for 'run'");
+          const result = await client.runSkill(resolvedId, {
+            params: input.params,
+            dry_run: input.dry_run
+          });
+          return { content: [{ type: "text", text: formatRunResult(result) }] };
+        }
+        case "delete": {
+          if (!input.skill_id) throw new Error("'skill_id' is required for delete");
+          await client.deleteSkill(input.skill_id);
+          return { content: [{ type: "text", text: `Skill ${input.skill_id} deleted.` }] };
+        }
+        case "import": {
+          let importContent = input.content;
+          if (!importContent && input.file_path) {
+            const { readFile: readFile4 } = await import("fs/promises");
+            importContent = await readFile4(input.file_path, "utf-8");
+          }
+          if (!importContent) throw new Error("Either 'content' or 'file_path' is required for import");
+          const result = await client.importSkills({
+            content: importContent,
+            format: input.format,
+            source_tool: input.source_tool,
+            source_file: input.source_file || input.file_path,
+            scope: input.scope,
+            workspace_id: input.workspace_id
+          });
+          return { content: [{ type: "text", text: `Import complete: ${result.imported || 0} imported, ${result.skipped || 0} skipped (duplicates).` }] };
+        }
+        case "export": {
+          const result = await client.exportSkills({
+            skill_ids: input.skill_ids,
+            format: input.format,
+            scope: input.scope,
+            workspace_id: input.workspace_id
+          });
+          return { content: [{ type: "text", text: result.content || JSON.stringify(result, null, 2) }] };
+        }
+        case "share": {
+          if (!input.skill_id) throw new Error("'skill_id' is required for share");
+          if (!input.scope) throw new Error("'scope' is required for share");
+          const result = await client.shareSkill(input.skill_id, input.scope);
+          return { content: [{ type: "text", text: `Skill ${input.skill_id} shared with scope=${result.scope || input.scope}.` }] };
+        }
+        default:
+          throw new Error(`Invalid skill action: '${action}'. Valid: list, get, create, update, run, delete, import, export, share`);
+      }
+    }
+  );
   registerTool(
     "memory_bulk_ingest",
     {
@@ -21468,15 +22076,24 @@ Access: Free`,
     "memory_list_events",
     {
       title: "List memory events",
-      description: "List memory events (optionally scoped)",
+      description: "List memory events (optionally scoped). Supports tag-based and event_type filtering for precise provenance tracking.",
       inputSchema: external_exports.object({
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional(),
-        limit: external_exports.number().optional()
+        limit: external_exports.number().optional(),
+        tags: external_exports.array(external_exports.string()).optional().describe("Filter events that contain ALL of these tags"),
+        event_type: external_exports.string().optional().describe("Filter by event type (e.g. decision, lesson, manual_note)")
       })
     },
     async (input) => {
       const result = await client.listMemoryEvents(input);
+      if (input.tags && input.tags.length > 0 && result.items) {
+        const requiredTags = input.tags;
+        result.items = result.items.filter((item) => {
+          const itemTags = extractEventTags(item);
+          return requiredTags.every((tag) => itemTags.includes(tag));
+        });
+      }
       return {
         content: [{ type: "text", text: formatContent(result) }]
       };
@@ -21530,16 +22147,24 @@ Access: Free`,
     "memory_search",
     {
       title: "Memory-aware search",
-      description: "Search memory events/notes",
+      description: "Search memory events/notes. Supports optional tag-based pre-filtering.",
       inputSchema: external_exports.object({
         query: external_exports.string(),
         workspace_id: external_exports.string().uuid().optional(),
         project_id: external_exports.string().uuid().optional(),
-        limit: external_exports.number().optional()
+        limit: external_exports.number().optional(),
+        tags: external_exports.array(external_exports.string()).optional().describe("Filter results that contain ALL of these tags")
       })
     },
     async (input) => {
       const result = await client.memorySearch(input);
+      if (input.tags && input.tags.length > 0 && result.results) {
+        const requiredTags = input.tags;
+        result.results = result.results.filter((item) => {
+          const itemTags = extractEventTags(item);
+          return requiredTags.every((tag) => itemTags.includes(tag));
+        });
+      }
       return {
         content: [{ type: "text", text: formatContent(result) }]
       };
@@ -21753,43 +22378,7 @@ Access: Free`,
         );
       }
       const wait = input.wait ?? false;
-      let estimate = null;
-      try {
-        const stats = await client.projectStatistics(projectId);
-        estimate = estimateGraphIngestMinutes(stats);
-      } catch (error) {
-        logDebug(`Failed to fetch project statistics for graph estimate: ${error}`);
-      }
-      const result = await client.graphIngest({ project_id: projectId, wait });
-      const estimateText = estimate ? `Estimated time: ${estimate.min}-${estimate.max} min${estimate.basis ? ` (based on ${estimate.basis})` : ""}.` : "Estimated time varies with repo size.";
-      const note = `Graph ingestion is running ${wait ? "synchronously" : "asynchronously"} and can take a few minutes. ${estimateText}`;
-      const structured = toStructured(result);
-      const structuredContent = structured && typeof structured === "object" ? {
-        ...structured,
-        wait,
-        note,
-        ...estimate ? {
-          estimate_minutes: { min: estimate.min, max: estimate.max },
-          estimate_basis: estimate.basis
-        } : {}
-      } : {
-        wait,
-        note,
-        ...estimate ? {
-          estimate_minutes: { min: estimate.min, max: estimate.max },
-          estimate_basis: estimate.basis
-        } : {}
-      };
-      return {
-        content: [
-          {
-            type: "text",
-            text: `${note}
-${formatContent(result)}`
-          }
-        ],
-        structuredContent
-      };
+      return runGraphIngestWithPreflight(projectId, wait);
     }
   );
   registerTool(
@@ -23363,9 +23952,8 @@ Returns lessons filtered by:
         // Fetch more to filter
       });
       const lessons = (searchResult.results || []).filter((item) => {
-        const tags = item.metadata?.tags || [];
-        const isLesson = tags.includes("lesson");
-        if (!isLesson) return false;
+        if (!isLessonResult(item)) return false;
+        const tags = extractEventTags(item);
         if (input.category && !tags.includes(input.category)) {
           return false;
         }
@@ -23384,7 +23972,7 @@ Returns lessons filtered by:
         };
       }
       const formattedLessons = lessons.map((lesson, i) => {
-        const tags = lesson.metadata?.tags || [];
+        const tags = extractEventTags(lesson);
         const severity = tags.find((t) => t.startsWith("severity:"))?.split(":")[1] || "medium";
         const category = tags.find(
           (t) => [
@@ -23403,7 +23991,7 @@ Returns lessons filtered by:
         }[severity] || "\u26AA";
         return `${i + 1}. ${severityEmoji} **${lesson.title}**
    Category: ${category} | Severity: ${severity}
-   ${lesson.content?.slice(0, 200)}...`;
+   ${lesson.content?.slice(0, 500)}...`;
       }).join("\n\n");
       return {
         content: [
@@ -24406,6 +24994,7 @@ Action: ${cp.suggested_action === "prepare_save" ? "Consider saving important de
       const instructionsLine = result.instructions ? `
 
 [INSTRUCTIONS] ${result.instructions}` : "";
+      const suggestedRulesLine = generateSuggestedRulesNotice(result);
       const contextRulesLine = `
 
 ${CONTEXT_CALL_REMINDER}`;
@@ -24418,6 +25007,7 @@ ${rulesWarningLine}` : "",
         versionWarningLine ? `
 
 ${versionWarningLine}` : "",
+        suggestedRulesLine,
         contextPressureWarning,
         semanticHints,
         instructionsLine,
@@ -26150,7 +26740,8 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               workspace_id: workspaceId,
               project_id: projectId,
               content: input.content,
-              importance
+              importance,
+              tags: input.tags
             });
             const rememberHint = getCaptureHint("preference");
             const resultWithHint = { ...result, hint: rememberHint };
@@ -26787,7 +27378,7 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
           order: external_exports.number().optional().describe("Task order within plan"),
           task_ids: external_exports.array(external_exports.string().uuid()).optional().describe("Task IDs for reorder_tasks"),
           blocked_reason: external_exports.string().optional().describe("Reason when task is blocked"),
-          tags: external_exports.array(external_exports.string()).optional().describe("Tags for task"),
+          tags: external_exports.array(external_exports.string()).optional().describe("Tags for event or task categorization"),
           // Batch import params
           events: external_exports.array(
             external_exports.object({
@@ -26824,7 +27415,7 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
           diagram_id: external_exports.string().uuid().optional().describe("Diagram ID for get_diagram/update_diagram/delete_diagram"),
           diagram_type: external_exports.enum(["flowchart", "sequence", "class", "er", "gantt", "mindmap", "pie", "other"]).optional().describe("Mermaid diagram type"),
           // Doc params
-          doc_id: external_exports.string().uuid().optional().describe("Doc ID for get_doc/update_doc/delete_doc"),
+          doc_id: external_exports.string().optional().describe("Doc ID for get_doc/update_doc/delete_doc. For get_doc, accepts UUID or title/query text."),
           doc_type: external_exports.enum(["roadmap", "spec", "general"]).optional().describe("Document type"),
           milestones: external_exports.array(
             external_exports.object({
@@ -26859,6 +27450,7 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               event_type: input.event_type,
               title: input.title,
               content: input.content,
+              tags: input.tags,
               metadata: input.metadata,
               provenance: input.provenance,
               code_refs: input.code_refs
@@ -27020,13 +27612,42 @@ ${formatContent(result)}`
             if (!input.query) {
               return errorResult("search requires: query");
             }
-            const result = await client.memorySearch({
-              workspace_id: workspaceId,
-              project_id: projectId,
+            const [memoryResult, docsResult] = await Promise.all([
+              client.memorySearch({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                query: input.query,
+                limit: input.limit
+              }),
+              workspaceId ? client.docsList({
+                workspace_id: workspaceId,
+                project_id: projectId,
+                per_page: Math.max(10, Math.min(input.limit ?? 10, 25))
+              }) : Promise.resolve(void 0)
+            ]);
+            const memoryItems = extractMemorySearchResults(memoryResult);
+            const docsItems = extractCollectionArray(docsResult ?? {}) ?? [];
+            const docMatches = rankDocsForQueryMatches(
+              docsItems,
+              input.query,
+              Math.max(1, Math.min(input.limit ?? 10, 25))
+            );
+            const hybridResults = buildHybridMemoryDocResults(
+              memoryItems,
+              docMatches,
+              Math.max(1, Math.min(input.limit ?? 10, 25))
+            );
+            const outputText = formatContent({
               query: input.query,
-              limit: input.limit
+              results: hybridResults,
+              memory_results: memoryItems,
+              doc_matches: docMatches.map((entry) => ({
+                ...entry.doc,
+                match_score: entry.score,
+                exact_match: entry.exact,
+                match_source: entry.source
+              }))
             });
-            const outputText = formatContent(result);
             trackToolTokenSavings(client, "memory_search", outputText, {
               workspace_id: workspaceId,
               project_id: projectId
@@ -27402,17 +28023,80 @@ ${formatContent(result)}`
             if (!input.doc_id) {
               return errorResult("get_doc requires: doc_id");
             }
-            const getDocResult = await client.docsGet({ doc_id: input.doc_id });
+            const directDocId = normalizeUuid(input.doc_id);
+            if (directDocId) {
+              const getDocResult = await client.docsGet({ doc_id: directDocId });
+              return {
+                content: [{ type: "text", text: formatContent(getDocResult) }]
+              };
+            }
+            if (!workspaceId) {
+              return errorResult(
+                "get_doc title/query lookups require workspace_id. Call session_init first or pass a doc UUID."
+              );
+            }
+            const candidateProjectIds = [projectId, explicitProjectId, void 0];
+            const fallback = await findDocsFallback(
+              workspaceId,
+              candidateProjectIds,
+              input.doc_id,
+              Math.max(10, Math.min(input.limit ?? 20, 30))
+            );
+            const rankedMatches = rankDocsForQueryMatches(
+              fallback?.docs ?? [],
+              input.doc_id,
+              Math.max(1, Math.min(input.limit ?? 10, 10))
+            );
+            const resolved = selectResolvedDocMatch(rankedMatches);
+            if (resolved) {
+              const resolvedDocId = String(resolved.doc?.id ?? "");
+              if (normalizeUuid(resolvedDocId)) {
+                const getDocResult = await client.docsGet({ doc_id: resolvedDocId });
+                return {
+                  content: [
+                    {
+                      type: "text",
+                      text: `Resolved doc query "${input.doc_id}" to doc ID ${resolvedDocId}.
+
+${formatContent(
+                        getDocResult
+                      )}`
+                    }
+                  ]
+                };
+              }
+            }
+            const topMatches = rankedMatches.slice(0, 5).map((entry) => ({
+              ...entry.doc ?? {},
+              match_score: entry.score,
+              exact_match: entry.exact,
+              match_source: entry.source
+            }));
+            const noMatchMessage = topMatches.length > 0 ? `Could not resolve "${input.doc_id}" to a single doc confidently.` : `No docs found matching "${input.doc_id}".`;
             return {
-              content: [{ type: "text", text: formatContent(getDocResult) }]
+              content: [
+                {
+                  type: "text",
+                  text: `${noMatchMessage}
+
+${formatContent({
+                    query: input.doc_id,
+                    doc_matches: topMatches
+                  })}`
+                }
+              ]
             };
           }
           case "update_doc": {
             if (!input.doc_id) {
               return errorResult("update_doc requires: doc_id");
             }
+            const updateDocId = normalizeUuid(input.doc_id);
+            if (!updateDocId) {
+              return errorResult("update_doc requires a valid UUID doc_id.");
+            }
             const updateDocResult = await client.docsUpdate({
-              doc_id: input.doc_id,
+              doc_id: updateDocId,
               title: input.title,
               content: input.content,
               doc_type: input.doc_type,
@@ -27426,7 +28110,11 @@ ${formatContent(result)}`
             if (!input.doc_id) {
               return errorResult("delete_doc requires: doc_id");
             }
-            const deleteDocResult = await client.docsDelete({ doc_id: input.doc_id });
+            const deleteDocId = normalizeUuid(input.doc_id);
+            if (!deleteDocId) {
+              return errorResult("delete_doc requires a valid UUID doc_id.");
+            }
+            const deleteDocResult = await client.docsDelete({ doc_id: deleteDocId });
             return {
               content: [{ type: "text", text: formatContent(deleteDocResult) }]
             };
@@ -27841,13 +28529,7 @@ ${formatContent(result)}`
             if (!projectId) {
               return errorResult("ingest requires: project_id");
             }
-            const result = await client.graphIngest({
-              project_id: projectId,
-              wait: input.wait
-            });
-            return {
-              content: [{ type: "text", text: formatContent(result) }]
-            };
+            return runGraphIngestWithPreflight(projectId, input.wait ?? false);
           }
           case "circular_dependencies": {
             if (!projectId) {
@@ -31705,6 +32387,7 @@ init_hooks_config();
 init_files();
 var EDITOR_LABELS = {
   codex: "Codex CLI",
+  opencode: "OpenCode",
   claude: "Claude Code",
   cursor: "Cursor / VS Code",
   cline: "Cline",
@@ -31714,7 +32397,7 @@ var EDITOR_LABELS = {
   antigravity: "Antigravity (Google)"
 };
 function supportsProjectMcpConfig(editor) {
-  return editor === "cursor" || editor === "claude" || editor === "kilo" || editor === "roo" || editor === "antigravity";
+  return editor === "opencode" || editor === "cursor" || editor === "claude" || editor === "kilo" || editor === "roo" || editor === "antigravity";
 }
 function normalizeInput(value) {
   return value.trim();
@@ -31960,6 +32643,28 @@ async function isCodexInstalled() {
   ].filter((candidate) => Boolean(candidate));
   return anyPathExists(candidates);
 }
+function openCodeConfigPath() {
+  const home = homedir6();
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path8.join(home, "AppData", "Roaming");
+    return path8.join(appData, "opencode", "opencode.json");
+  }
+  const configRoot = xdgConfigHome || path8.join(home, ".config");
+  return path8.join(configRoot, "opencode", "opencode.json");
+}
+async function isOpenCodeInstalled() {
+  const configPath = openCodeConfigPath();
+  const configDir = path8.dirname(configPath);
+  const home = homedir6();
+  const candidates = [
+    configDir,
+    configPath,
+    path8.join(home, ".bun", "bin", "opencode"),
+    path8.join(home, ".local", "bin", "opencode")
+  ];
+  return anyPathExists(candidates);
+}
 async function isClaudeInstalled() {
   const home = homedir6();
   const candidates = [path8.join(home, ".claude"), path8.join(home, ".config", "claude")];
@@ -32031,10 +32736,12 @@ async function isAntigravityInstalled() {
     const localApp = process.env.LOCALAPPDATA;
     const programFiles = process.env.ProgramFiles;
     const programFilesX86 = process.env["ProgramFiles(x86)"];
-    if (localApp) candidates.push(path8.join(localApp, "Programs", "Antigravity", "Antigravity.exe"));
+    if (localApp)
+      candidates.push(path8.join(localApp, "Programs", "Antigravity", "Antigravity.exe"));
     if (localApp) candidates.push(path8.join(localApp, "Antigravity", "Antigravity.exe"));
     if (programFiles) candidates.push(path8.join(programFiles, "Antigravity", "Antigravity.exe"));
-    if (programFilesX86) candidates.push(path8.join(programFilesX86, "Antigravity", "Antigravity.exe"));
+    if (programFilesX86)
+      candidates.push(path8.join(programFilesX86, "Antigravity", "Antigravity.exe"));
   } else {
     candidates.push("/usr/bin/antigravity");
     candidates.push("/usr/local/bin/antigravity");
@@ -32047,6 +32754,8 @@ async function isEditorInstalled(editor) {
   switch (editor) {
     case "codex":
       return isCodexInstalled();
+    case "opencode":
+      return isOpenCodeInstalled();
     case "claude":
       return isClaudeInstalled();
     case "cursor":
@@ -32066,6 +32775,8 @@ async function isEditorInstalled(editor) {
   }
 }
 var IS_WINDOWS = process.platform === "win32";
+var DEFAULT_CONTEXTSTREAM_API_URL = "https://api.contextstream.io";
+var OPENCODE_CONFIG_SCHEMA_URL = "https://opencode.ai/config.json";
 function escapeTomlString(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
@@ -32112,6 +32823,26 @@ function buildContextStreamVsCodeServer(params) {
     env
   };
 }
+function buildContextStreamOpenCodeEnvironment(params) {
+  const environment = {
+    CONTEXTSTREAM_API_KEY: "{env:CONTEXTSTREAM_API_KEY}"
+  };
+  if (normalizeApiUrl(params.apiUrl) !== DEFAULT_CONTEXTSTREAM_API_URL) {
+    environment.CONTEXTSTREAM_API_URL = params.apiUrl;
+  }
+  if (params.contextPackEnabled === false) {
+    environment.CONTEXTSTREAM_CONTEXT_PACK = "false";
+  }
+  return environment;
+}
+function buildContextStreamOpenCodeLocalServer(params) {
+  return {
+    type: "local",
+    command: ["npx", "-y", "contextstream-mcp"],
+    environment: buildContextStreamOpenCodeEnvironment(params),
+    enabled: true
+  };
+}
 function stripJsonComments(input) {
   return input.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
 }
@@ -32170,6 +32901,32 @@ async function upsertJsonVsCodeMcpConfig(filePath, server) {
   if (!exists) return "created";
   return before === after ? "skipped" : "updated";
 }
+async function upsertOpenCodeMcpConfig(filePath, server) {
+  await fs7.mkdir(path8.dirname(filePath), { recursive: true });
+  const exists = await fileExists(filePath);
+  let root = {};
+  if (exists) {
+    const raw = await fs7.readFile(filePath, "utf8").catch(() => "");
+    const parsed = tryParseJsonLike(raw);
+    if (!parsed.ok) throw new Error(`Invalid JSON in ${filePath}: ${parsed.error}`);
+    root = parsed.value;
+  }
+  if (!root || typeof root !== "object" || Array.isArray(root)) root = {};
+  if (!root.mcp || typeof root.mcp !== "object" || Array.isArray(root.mcp)) root.mcp = {};
+  const before = JSON.stringify({
+    schema: root.$schema ?? null,
+    contextstream: root.mcp.contextstream ?? null
+  });
+  root.$schema = OPENCODE_CONFIG_SCHEMA_URL;
+  root.mcp.contextstream = server;
+  const after = JSON.stringify({
+    schema: root.$schema ?? null,
+    contextstream: root.mcp.contextstream ?? null
+  });
+  await fs7.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
+  if (!exists) return "created";
+  return before === after ? "skipped" : "updated";
+}
 function claudeDesktopConfigPath() {
   const home = homedir6();
   if (process.platform === "darwin") {
@@ -32374,9 +33131,7 @@ async function selectProjectForCurrentDirectory(client, cwd, workspaceId, dryRun
   }
   console.log("\nProject selection (current directory):");
   options.forEach((opt, i) => console.log(`  ${i + 1}) ${opt.label}`));
-  const choiceRaw = normalizeInput(
-    await rl.question(`Choose [1-${options.length}] (default 1): `)
-  );
+  const choiceRaw = normalizeInput(await rl.question(`Choose [1-${options.length}] (default 1): `));
   const choiceNum = Number.parseInt(choiceRaw || "1", 10);
   const selected = Number.isFinite(choiceNum) ? options[choiceNum - 1] : options[0];
   if (!selected || selected.kind === "skip") {
@@ -32442,7 +33197,9 @@ ${colors.bright}Updating index for '${projectName}'...${colors.reset}`);
       }
     }
     if (!projectId) {
-      console.log(`${colors.yellow}! Could not resolve project ID for ${projectName}${colors.reset}`);
+      console.log(
+        `${colors.yellow}! Could not resolve project ID for ${projectName}${colors.reset}`
+      );
       return;
     }
   } catch (err) {
@@ -32460,7 +33217,9 @@ ${colors.bright}Updating index for '${projectName}'...${colors.reset}`);
       console.log(`${colors.dim}No indexable files found${colors.reset}`);
       return;
     } else {
-      console.log(`${colors.dim}Found ${totalFiles.toLocaleString()} files for indexing${colors.reset}`);
+      console.log(
+        `${colors.dim}Found ${totalFiles.toLocaleString()} files for indexing${colors.reset}`
+      );
     }
   } catch {
     console.log(`${colors.dim}Scanning files...${colors.reset}`);
@@ -32480,7 +33239,9 @@ ${colors.bright}Updating index for '${projectName}'...${colors.reset}`);
     const percentage = (progress * 100).toFixed(1);
     const speed = filesPerSec.toFixed(1);
     const size = formatBytes(bytesIndexed);
-    process.stdout.write(`\r${colors.cyan}${spinner}${colors.reset} ${progressBar} ${colors.bright}${percentage}%${colors.reset} | ${colors.green}${filesIndexed.toLocaleString()}${colors.reset}/${totalFiles.toLocaleString()} files | ${colors.magenta}${size}${colors.reset} | ${colors.blue}${speed} files/s${colors.reset}   `);
+    process.stdout.write(
+      `\r${colors.cyan}${spinner}${colors.reset} ${progressBar} ${colors.bright}${percentage}%${colors.reset} | ${colors.green}${filesIndexed.toLocaleString()}${colors.reset}/${totalFiles.toLocaleString()} files | ${colors.magenta}${size}${colors.reset} | ${colors.blue}${speed} files/s${colors.reset}   `
+    );
   };
   const progressInterval = setInterval(updateProgress, 80);
   const ingestWithRetry = async (batch, maxRetries = 3) => {
@@ -32798,7 +33559,7 @@ Code: ${device.user_code}`);
         );
       }
     }
-    const NO_HOOKS_EDITORS2 = ["codex", "aider", "antigravity"];
+    const NO_HOOKS_EDITORS2 = ["codex", "opencode", "aider", "antigravity"];
     const getModeForEditor = (editor) => NO_HOOKS_EDITORS2.includes(editor) ? "full" : "bootstrap";
     const detectedPlanName = await client.getPlanName();
     const detectedGraphTier = await client.getGraphTier();
@@ -32809,7 +33570,9 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
     const contextPackEnabled = !!detectedPlanName && ["pro", "team", "enterprise"].some((p) => detectedPlanName.toLowerCase().includes(p));
     console.log("\nAuto-Update:");
     console.log("  When enabled, ContextStream will automatically update to the latest version");
-    console.log("  on new sessions (checks daily). You can disable this if you prefer manual updates.");
+    console.log(
+      "  on new sessions (checks daily). You can disable this if you prefer manual updates."
+    );
     const currentAutoUpdate = isAutoUpdateEnabled();
     const autoUpdateChoice = normalizeInput(
       await rl.question(`Enable auto-update? [${currentAutoUpdate ? "Y/n" : "y/N"}]: `)
@@ -32823,6 +33586,7 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
     }
     const editors = [
       "codex",
+      "opencode",
       "claude",
       "cursor",
       "cline",
@@ -32896,7 +33660,20 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
     const mcpScope = mcpChoice === "2" && hasCodex && !hasProjectMcpEditors ? "skip" : mcpChoice === "4" ? "skip" : mcpChoice === "1" ? "global" : mcpChoice === "2" ? "project" : "both";
     const mcpServer = buildContextStreamMcpServer({ apiUrl, apiKey, contextPackEnabled });
     const mcpServerClaude = buildContextStreamMcpServer({ apiUrl, apiKey, contextPackEnabled });
+    const mcpServerOpenCode = buildContextStreamOpenCodeLocalServer({
+      apiUrl,
+      apiKey,
+      contextPackEnabled
+    });
     const vsCodeServer = buildContextStreamVsCodeServer({ apiUrl, apiKey, contextPackEnabled });
+    let hasPrintedOpenCodeEnvNote = false;
+    const printOpenCodeEnvNote = () => {
+      if (hasPrintedOpenCodeEnvNote) return;
+      hasPrintedOpenCodeEnvNote = true;
+      console.log(
+        "  OpenCode reads CONTEXTSTREAM_API_KEY from your environment. Export it before launching OpenCode."
+      );
+    };
     const needsGlobalMcpConfig = mcpScope === "global" || mcpScope === "both" || mcpScope === "project" && hasCodex;
     if (needsGlobalMcpConfig) {
       console.log("\nInstalling global MCP config...");
@@ -32948,6 +33725,20 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
             );
             continue;
           }
+          if (editor === "opencode") {
+            const filePath = openCodeConfigPath();
+            if (dryRun) {
+              writeActions.push({ kind: "mcp-config", target: filePath, status: "dry-run" });
+              console.log(`- ${EDITOR_LABELS[editor]}: would update ${filePath}`);
+              printOpenCodeEnvNote();
+              continue;
+            }
+            const status = await upsertOpenCodeMcpConfig(filePath, mcpServerOpenCode);
+            writeActions.push({ kind: "mcp-config", target: filePath, status });
+            console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
+            printOpenCodeEnvNote();
+            continue;
+          }
           if (editor === "cursor") {
             const filePath = path8.join(homedir6(), ".cursor", "mcp.json");
             if (dryRun) {
@@ -32990,6 +33781,8 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
       kilo: "kilo",
       codex: null,
       // No hooks API
+      opencode: null,
+      // No hooks API
       aider: null,
       // No hooks API
       antigravity: null
@@ -33030,6 +33823,12 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
     if (scope === "global" || scope === "both") {
       console.log("\nInstalling global rules...");
       for (const editor of configuredEditors) {
+        if (editor === "opencode") {
+          console.log(
+            `- ${EDITOR_LABELS[editor]}: rules are not auto-generated yet (MCP config only).`
+          );
+          continue;
+        }
         const filePath = globalRulesPathForEditor(editor);
         if (!filePath) {
           console.log(
@@ -33170,6 +33969,21 @@ Applying to ${projects.length} project(s)...`);
               }
               continue;
             }
+            if (editor === "opencode") {
+              const openCodePath = path8.join(projectPath, "opencode.json");
+              if (dryRun) {
+                writeActions.push({
+                  kind: "mcp-config",
+                  target: openCodePath,
+                  status: "dry-run"
+                });
+              } else {
+                const status = await upsertOpenCodeMcpConfig(openCodePath, mcpServerOpenCode);
+                writeActions.push({ kind: "mcp-config", target: openCodePath, status });
+              }
+              printOpenCodeEnvNote();
+              continue;
+            }
             if (editor === "kilo") {
               const kiloPath = path8.join(projectPath, ".kilocode", "mcp.json");
               if (dryRun) {
@@ -33201,6 +34015,7 @@ Applying to ${projects.length} project(s)...`);
       for (const editor of selectedEditors) {
         if (scope !== "project" && scope !== "both") continue;
         if (!configuredEditors.includes(editor)) continue;
+        if (editor === "opencode") continue;
         const rule = generateRuleContent(editor, {
           workspaceName,
           workspaceId: workspaceId && workspaceId !== "dry-run" ? workspaceId : void 0,
@@ -33240,11 +34055,15 @@ Applying to ${projects.length} project(s)...`);
             console.log("PROJECT INDEXING");
             console.log("\u2500".repeat(60));
             if (filesIndexed === 0) {
-              console.log("Indexing enables semantic code search and AI-powered graph knowledge for rich AI context.");
+              console.log(
+                "Indexing enables semantic code search and AI-powered graph knowledge for rich AI context."
+              );
             } else {
               console.log("Your project index is stale and could use a refresh.");
             }
-            console.log("Powered by our blazing-fast Rust engine, indexing typically takes under a minute,");
+            console.log(
+              "Powered by our blazing-fast Rust engine, indexing typically takes under a minute,"
+            );
             console.log("though larger projects may take a bit longer.\n");
             console.log("Your code is private and securely stored.\n");
             const indexChoice = normalizeInput(
@@ -33259,7 +34078,9 @@ Applying to ${projects.length} project(s)...`);
             if (indexingEnabled) {
               await indexProjectWithProgress(client, process.cwd(), cwdConfig.workspace_id);
             } else {
-              console.log("\nIndexing skipped for now. You can start it later with: contextstream-mcp index <path>");
+              console.log(
+                "\nIndexing skipped for now. You can start it later with: contextstream-mcp index <path>"
+              );
             }
           }
         } catch {
@@ -33269,8 +34090,12 @@ Applying to ${projects.length} project(s)...`);
       console.log("\n" + "\u2500".repeat(60));
       console.log("PROJECT INDEXING");
       console.log("\u2500".repeat(60));
-      console.log("Indexing enables semantic code search and AI-powered graph knowledge for rich AI context.");
-      console.log("Powered by our blazing-fast Rust engine, indexing typically takes under a minute,");
+      console.log(
+        "Indexing enables semantic code search and AI-powered graph knowledge for rich AI context."
+      );
+      console.log(
+        "Powered by our blazing-fast Rust engine, indexing typically takes under a minute,"
+      );
       console.log("though larger projects may take a bit longer.\n");
       console.log("Your code is private and securely stored.\n");
       const indexChoice = normalizeInput(
@@ -33292,7 +34117,9 @@ Applying to ${projects.length} project(s)...`);
           await indexProjectWithProgress(client, projectPath, workspaceId);
         }
       } else {
-        console.log("\nIndexing skipped for now. You can start it later with: contextstream-mcp index <path>");
+        console.log(
+          "\nIndexing skipped for now. You can start it later with: contextstream-mcp index <path>"
+        );
       }
     }
     console.log("\nDone.");
@@ -33313,7 +34140,9 @@ Applying to ${projects.length} project(s)...`);
       "- For UI-based MCP setup (Cline/Kilo/Roo global), see https://contextstream.io/docs/mcp"
     );
     console.log("");
-    console.log("You're all set! ContextStream gives your AI persistent memory, semantic code search, and cross-session context.");
+    console.log(
+      "You're all set! ContextStream gives your AI persistent memory, semantic code search, and cross-session context."
+    );
     console.log("More at: https://contextstream.io/docs/mcp");
   } finally {
     rl.close();