mindgraph-mcp 0.3.4 → 0.5.0

package/dist/cli.js

@@ -41,20 +41,12 @@ function err(message) {
 async function handleTool(client2, name, args) {
   try {
     switch (name) {
-      case "mindgraph_journal":
-        return await handleJournal(client2, args);
       case "mindgraph_capture":
         return await handleCapture(client2, args);
-      case "mindgraph_argue":
-        return await handleArgue(client2, args);
-      case "mindgraph_inquire":
-        return await handleInquire(client2, args);
+      case "mindgraph_reason":
+        return await handleReason(client2, args);
       case "mindgraph_commit":
         return await handleCommit(client2, args);
-      case "mindgraph_decide":
-        return await handleDecide(client2, args);
-      case "mindgraph_action":
-        return await handleAction(client2, args);
       case "mindgraph_plan":
         return await handlePlan(client2, args);
       case "mindgraph_retrieve":
@@ -69,31 +61,29 @@ async function handleTool(client2, name, args) {
     return err(message);
   }
 }
-async function handleJournal(client2, args) {
-  const { label, content, mood, tags, agent_id } = args;
-  const props = { content };
-  if (mood) props.mood = mood;
-  if (tags) props.tags = tags;
-  const result = await client2.journal(
-    label,
-    props,
-    { agent_id }
-  );
-  return ok(result);
-}
 async function handleCapture(client2, args) {
   const {
     action,
     label,
     summary,
+    content,
     entity_type,
     source_uid,
+    mood,
+    tags,
     confidence,
     salience,
     props,
     agent_id
   } = args;
   switch (action) {
+    case "journal": {
+      if (!content) return err("content is required for action=journal");
+      const journalProps = { content };
+      if (mood) journalProps.mood = mood;
+      if (tags) journalProps.tags = tags;
+      return ok(await client2.journal(label, journalProps, { agent_id }));
+    }
     case "entity": {
       const type = entity_type || "concept";
       const entityProps = { ...props };
@@ -167,58 +157,85 @@ async function handleCapture(client2, args) {
       return err(`Unknown capture action: ${action}`);
   }
 }
-async function handleArgue(client2, args) {
-  const { claim, evidence, warrant, argument, agent_id } = args;
-  const result = await client2.argue({
+async function handleReason(client2, args) {
+  const {
+    action,
+    label,
+    summary,
     claim,
     evidence,
     warrant,
     argument,
-    agent_id
-  });
-  return ok(result);
-}
-async function handleInquire(client2, args) {
-  const { action, label, summary, confidence, salience, props, agent_id } = args;
-  const result = await client2.inquire({
-    action,
-    label,
-    summary,
     confidence,
     salience,
     props,
     agent_id
-  });
-  return ok(result);
+  } = args;
+  if (action === "claim") {
+    const claimObj = claim || (label ? { label, confidence } : null);
+    if (!claimObj) return err("claim object or label is required for action=claim");
+    return ok(
+      await client2.argue({
+        claim: claimObj,
+        evidence,
+        warrant,
+        argument,
+        agent_id
+      })
+    );
+  }
+  if (!label) return err(`label is required for action=${action}`);
+  return ok(
+    await client2.inquire({
+      action,
+      label,
+      summary,
+      confidence,
+      salience,
+      props,
+      agent_id
+    })
+  );
 }
 async function handleCommit(client2, args) {
-  const { action, label, summary, parent_uid, confidence, salience, props, agent_id } = args;
-  const result = await client2.commit({
+  const {
     action,
     label,
     summary,
     parent_uid,
+    decision_uid,
+    chosen_option_uid,
     confidence,
     salience,
     props,
     agent_id
-  });
-  return ok(result);
-}
-async function handleDecide(client2, args) {
-  const { action, label, summary, decision_uid, chosen_option_uid, props, agent_id } = args;
+  } = args;
   switch (action) {
+    case "goal":
+    case "project":
+    case "milestone":
+      if (!label) return err(`label is required for action=${action}`);
+      return ok(
+        await client2.commit({
+          action,
+          label,
+          summary,
+          parent_uid,
+          confidence,
+          salience,
+          props,
+          agent_id
+        })
+      );
     case "open_decision":
       if (!label) return err("label is required for open_decision");
       return ok(await client2.openDecision(label, { summary, props, agent_id }));
     case "add_option":
-      if (!decision_uid) return err("decision_uid is required");
+      if (!decision_uid) return err("decision_uid is required for add_option");
       if (!label) return err("label is required for add_option");
-      return ok(
-        await client2.addOption(decision_uid, label, { summary, props, agent_id })
-      );
+      return ok(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
     case "add_constraint":
-      if (!decision_uid) return err("decision_uid is required");
+      if (!decision_uid) return err("decision_uid is required for add_constraint");
       return ok(
         await client2.deliberate({
           action: "add_constraint",
@@ -229,64 +246,35 @@ async function handleDecide(client2, args) {
           agent_id
         })
       );
-    case "resolve":
-      if (!decision_uid) return err("decision_uid is required");
-      if (!chosen_option_uid) return err("chosen_option_uid is required");
+    case "resolve_decision":
+      if (!decision_uid) return err("decision_uid is required for resolve_decision");
+      if (!chosen_option_uid) return err("chosen_option_uid is required for resolve_decision");
       return ok(
         await client2.resolveDecision(decision_uid, chosen_option_uid, {
           summary,
           agent_id
         })
       );
-    case "get_open":
+    case "get_open_decisions":
       return ok(await client2.getOpenDecisions());
     default:
-      return err(`Unknown decide action: ${action}`);
-  }
-}
-async function handleAction(client2, args) {
-  const { action, label, summary, target_uid, props, agent_id } = args;
-  switch (action) {
-    case "create_flow":
-    case "add_step":
-    case "add_affordance":
-    case "add_control":
-      return ok(
-        await client2.procedure({
-          action,
-          label,
-          summary,
-          target_uid,
-          props,
-          agent_id
-        })
-      );
-    case "assess_risk":
-      return ok(
-        await client2.risk({
-          action: "assess",
-          label,
-          summary,
-          target_uid,
-          props,
-          agent_id
-        })
-      );
-    case "get_assessments":
-      return ok(
-        await client2.risk({
-          action: "get_assessments",
-          target_uid,
-          agent_id
-        })
-      );
-    default:
-      return err(`Unknown action: ${action}`);
+      return err(`Unknown commit action: ${action}`);
   }
 }
 async function handlePlan(client2, args) {
-  const { action, label, summary, plan_uid, task_uid, status, props, agent_id } = args;
+  const {
+    action,
+    label,
+    summary,
+    plan_uid,
+    task_uid,
+    target_uid,
+    status,
+    props,
+    agent_id
+  } = args;
   switch (action) {
+    // Agent planning
     case "create_task":
     case "create_plan":
     case "add_step":
@@ -304,63 +292,70 @@ async function handlePlan(client2, args) {
           agent_id
         })
       );
+    // Execution tracking
     case "start_execution":
+      return ok(await client2.execution({ action: "start", task_uid, agent_id }));
+    case "complete_execution":
+      return ok(await client2.execution({ action: "complete", task_uid, agent_id }));
+    case "fail_execution":
+      return ok(await client2.execution({ action: "fail", task_uid, agent_id }));
+    // Governance
+    case "create_policy":
       return ok(
-        await client2.execution({
-          action: "start",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "create_policy", label, summary, props, agent_id })
       );
-    case "complete_execution":
+    case "request_approval":
       return ok(
-        await client2.execution({
-          action: "complete",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "request_approval", label, summary, props, agent_id })
       );
-    case "fail_execution":
+    case "resolve_approval":
       return ok(
-        await client2.execution({
-          action: "fail",
-          task_uid,
-          agent_id
-        })
+        await client2.governance({ action: "resolve_approval", task_uid, props, agent_id })
       );
-    case "create_policy":
+    case "get_pending":
+      return ok(await client2.governance({ action: "get_pending", agent_id }));
+    // Procedures (merged from mindgraph_action)
+    case "create_flow":
+    case "add_affordance":
+    case "add_control":
       return ok(
-        await client2.governance({
-          action: "create_policy",
+        await client2.procedure({
+          action,
           label,
           summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "request_approval":
+    case "add_procedure_step":
       return ok(
-        await client2.governance({
-          action: "request_approval",
+        await client2.procedure({
+          action: "add_step",
           label,
           summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "resolve_approval":
+    // Risk assessment (merged from mindgraph_action)
+    case "assess_risk":
       return ok(
-        await client2.governance({
-          action: "resolve_approval",
-          task_uid,
+        await client2.risk({
+          action: "assess",
+          label,
+          summary,
+          target_uid,
           props,
           agent_id
         })
       );
-    case "get_pending":
+    case "get_assessments":
       return ok(
-        await client2.governance({
-          action: "get_pending",
+        await client2.risk({
+          action: "get_assessments",
+          target_uid,
           agent_id
         })
       );
@@ -372,6 +367,11 @@ async function handleRetrieve(client2, args) {
   const {
     action,
     query,
+    start_uid,
+    end_uid,
+    max_depth,
+    direction,
+    edge_types,
     node_types,
     layer,
     limit,
@@ -390,7 +390,7 @@ async function handleRetrieve(client2, args) {
           k: limit,
           node_types,
           layer,
-          include_chunks,
+          include_chunks: include_chunks ?? false,
           include_graph
         })
       );
@@ -406,6 +406,31 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    case "semantic":
+      if (!query) return err("query is required for semantic search");
+      return ok(
+        await client2.retrieve({
+          action: "semantic",
+          query,
+          k: limit,
+          node_types,
+          layer,
+          agent_id
+        })
+      );
+    case "hybrid":
+      if (!query) return err("query is required for hybrid search");
+      return ok(
+        await client2.retrieve({
+          action: "hybrid",
+          query,
+          k: limit,
+          node_types,
+          layer,
+          agent_id
+        })
+      );
+    // Structured queries
     case "active_goals":
       return ok(await client2.getGoals());
     case "open_questions":
@@ -437,6 +462,59 @@ async function handleRetrieve(client2, args) {
           agent_id
         })
       );
+    // Document inventory
+    case "document_index":
+      return ok(
+        await client2.getNodes({
+          node_type: "Document",
+          limit: limit ?? 100
+        })
+      );
+    // Graph traversal
+    case "chain":
+      if (!start_uid) return err("start_uid is required for chain traversal");
+      return ok(
+        await client2.traverse({
+          action: "chain",
+          start_uid,
+          max_depth
+        })
+      );
+    case "neighborhood":
+      if (!start_uid) return err("start_uid is required for neighborhood traversal");
+      return ok(
+        await client2.traverse({
+          action: "neighborhood",
+          start_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
+    case "path":
+      if (!start_uid) return err("start_uid is required for path traversal");
+      if (!end_uid) return err("end_uid is required for path traversal");
+      return ok(
+        await client2.traverse({
+          action: "path",
+          start_uid,
+          end_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
+    case "subgraph":
+      if (!start_uid) return err("start_uid is required for subgraph traversal");
+      return ok(
+        await client2.traverse({
+          action: "subgraph",
+          start_uid,
+          max_depth,
+          direction,
+          edge_types
+        })
+      );
     default:
       return err(`Unknown retrieve action: ${action}`);
   }
@@ -493,72 +571,47 @@ var init_tools = __esm({
   "src/tools.ts"() {
     "use strict";
     TOOLS = [
-      {
-        name: "mindgraph_journal",
-        description: "Quick, informal capture for the user's inner world: preferences ('I prefer dark mode'), reflections ('I've been thinking about...'), moods, daily notes, and anything subjective. Use this instead of mindgraph_capture when the content is personal/informal rather than a structured fact about the external world. Good for: likes/dislikes, feelings, habits, reminders-to-self, freeform notes.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            label: {
-              type: "string",
-              description: "Brief title for the journal entry"
-            },
-            content: {
-              type: "string",
-              description: "The journal content/body text"
-            },
-            mood: {
-              type: "string",
-              description: "Emotional tone or mood tag"
-            },
-            tags: {
-              type: "array",
-              items: { type: "string" },
-              description: "Categorization tags"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["label", "content"]
-        }
-      },
       {
         name: "mindgraph_capture",
-        description: "Capture structured facts about the external world into the Reality layer. Use proactively whenever the user mentions a named entity. Actions: 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements about the world, 'source' for documents/URLs/references, 'snippet' for direct quotes from a source. Prefer this over mindgraph_journal when the content is an objective fact rather than a personal note.",
+        description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, 'concept' for abstract ideas. Use 'journal' for quick personal notes, preferences, reflections, moods \u2014 anything subjective or informal. Prefer 'entity'/'observation' for objective facts, 'journal' for personal notes.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
-              enum: ["entity", "observation", "source", "snippet", "concept"],
-              description: "Type of reality to capture"
+              enum: ["entity", "observation", "source", "snippet", "concept", "journal"],
+              description: "Type of knowledge to capture"
             },
             label: {
               type: "string",
-              description: "Name or title"
+              description: "Name, title, or brief heading"
             },
             summary: {
               type: "string",
-              description: "Description or summary text"
+              description: "Description or summary text (for entity/observation/source/snippet/concept)"
+            },
+            content: {
+              type: "string",
+              description: "Journal content/body text (for action=journal)"
             },
             entity_type: {
               type: "string",
-              enum: [
-                "person",
-                "organization",
-                "place",
-                "event",
-                "nation",
-                "concept"
-              ],
+              enum: ["person", "organization", "place", "event", "nation", "concept"],
               description: "Entity subtype (only for action=entity)"
             },
             source_uid: {
               type: "string",
               description: "Source node UID (for snippets)"
             },
+            mood: {
+              type: "string",
+              description: "Emotional tone or mood tag (for action=journal)"
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Categorization tags (for action=journal)"
+            },
             confidence: {
               type: "number",
               minimum: 0,
@@ -584,11 +637,33 @@ var init_tools = __esm({
         }
       },
       {
-        name: "mindgraph_argue",
-        description: "Record a claim WITH supporting evidence. Use when the user states something as true/false and provides reasoning or sources. Creates interconnected Claim + Evidence + Warrant nodes. Set confidence based on evidence strength: 0.9+ for well-sourced facts, 0.5-0.8 for plausible claims, below 0.5 for speculation. Prefer mindgraph_inquire instead when there's a question or hypothesis WITHOUT evidence yet.",
+        name: "mindgraph_reason",
+        description: "Record reasoning, claims, and open questions. Use 'claim' when the user states something as true/false with reasoning \u2014 creates interconnected Claim + Evidence + Warrant nodes. Set confidence by evidence: 0.9+ for well-sourced, 0.5-0.8 for plausible, <0.5 for speculation. Use 'open_question' for questions worth tracking, 'hypothesis' for testable predictions, 'theory' for explanatory frameworks, 'anomaly' for things that don't fit, 'assumption' for unstated beliefs. Prefer 'claim' when evidence exists, other actions when it doesn't yet.",
         inputSchema: {
           type: "object",
           properties: {
+            action: {
+              type: "string",
+              enum: [
+                "claim",
+                "question",
+                "open_question",
+                "hypothesis",
+                "theory",
+                "paradigm",
+                "anomaly",
+                "assumption"
+              ],
+              description: "Type of reasoning to record"
+            },
+            label: {
+              type: "string",
+              description: "The claim, question, or hypothesis statement (used for non-claim actions, or as fallback for claim if claim object omitted)"
+            },
+            summary: {
+              type: "string",
+              description: "Expanded description or context (for non-claim actions)"
+            },
             claim: {
               type: "object",
               properties: {
@@ -602,7 +677,7 @@ var init_tools = __esm({
                 }
               },
               required: ["label"],
-              description: "The central claim being argued"
+              description: "The central claim being argued (for action=claim)"
             },
             evidence: {
               type: "array",
@@ -614,7 +689,7 @@ var init_tools = __esm({
                 },
                 required: ["label"]
               },
-              description: "Supporting evidence items"
+              description: "Supporting evidence items (for action=claim)"
             },
             warrant: {
               type: "object",
@@ -622,61 +697,26 @@ var init_tools = __esm({
                 label: { type: "string" },
                 content: { type: "string" }
               },
-              description: "Logical warrant connecting evidence to claim"
+              description: "Logical warrant connecting evidence to claim (for action=claim)"
             },
             argument: {
               type: "object",
               properties: {
                 label: { type: "string" }
               },
-              description: "Top-level argument container"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["claim"]
-        }
-      },
-      {
-        name: "mindgraph_inquire",
-        description: "Record things that need investigation or are uncertain. Use 'open_question' when the user asks something worth tracking ('How does X work?'), 'hypothesis' for testable predictions, 'theory' for explanatory frameworks, 'anomaly' for things that don't fit existing understanding, 'assumption' for unstated beliefs worth surfacing. These stay in the graph as open items until resolved. Prefer mindgraph_argue instead when there IS evidence to attach.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            action: {
-              type: "string",
-              enum: [
-                "question",
-                "open_question",
-                "hypothesis",
-                "theory",
-                "paradigm",
-                "anomaly",
-                "assumption"
-              ],
-              description: "Type of epistemic inquiry"
-            },
-            label: {
-              type: "string",
-              description: "The question, hypothesis, or theory statement"
-            },
-            summary: {
-              type: "string",
-              description: "Expanded description or context"
+              description: "Top-level argument container (for action=claim)"
             },
             confidence: {
               type: "number",
               minimum: 0,
               maximum: 1,
-              description: "Confidence level (0-1)"
+              description: "Confidence level (for non-claim actions)"
             },
             salience: {
               type: "number",
               minimum: 0,
               maximum: 1,
-              description: "Importance score (0-1)"
+              description: "Importance score (for non-claim actions)"
             },
             props: {
               type: "object",
@@ -687,31 +727,48 @@ var init_tools = __esm({
               description: "Agent identity"
             }
           },
-          required: ["action", "label"]
+          required: ["action"]
         }
       },
       {
         name: "mindgraph_commit",
-        description: "Track the user's goals, projects, and milestones. Use 'goal' when the user expresses a desired outcome ('I want to learn Rust'), 'project' for organized efforts ('my blog redesign'), 'milestone' for checkpoints ('launch MVP by March'). Link milestones to projects and projects to goals via parent_uid. These appear in daily briefings and active goals queries.",
+        description: "Track goals, projects, milestones, and decisions. Use 'goal' for desired outcomes ('I want to learn Rust'), 'project' for organized efforts, 'milestone' for checkpoints. Link milestones to projects and projects to goals via parent_uid. Use 'open_decision' when facing a choice ('Postgres vs SQLite?'), 'add_option'/'add_constraint' to build out alternatives, 'resolve_decision' to pick one, 'get_open_decisions' to review pending choices.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
-              enum: ["goal", "project", "milestone"],
-              description: "Type of commitment"
+              enum: [
+                "goal",
+                "project",
+                "milestone",
+                "open_decision",
+                "add_option",
+                "add_constraint",
+                "resolve_decision",
+                "get_open_decisions"
+              ],
+              description: "Commitment or decision action"
             },
             label: {
               type: "string",
-              description: "Name of the goal, project, or milestone"
+              description: "Name of the goal, project, milestone, decision, option, or constraint"
             },
             summary: {
               type: "string",
-              description: "Description and success criteria"
+              description: "Description, success criteria, or rationale"
             },
             parent_uid: {
               type: "string",
-              description: "Parent goal/project UID to link under"
+              description: "Parent goal/project UID to link under (for goal/project/milestone)"
+            },
+            decision_uid: {
+              type: "string",
+              description: "Decision UID (for add_option, add_constraint, resolve_decision)"
+            },
+            chosen_option_uid: {
+              type: "string",
+              description: "UID of the chosen option (for resolve_decision)"
             },
             confidence: {
               type: "number",
@@ -732,93 +789,12 @@ var init_tools = __esm({
               description: "Agent identity"
             }
           },
-          required: ["action", "label"]
-        }
-      },
-      {
-        name: "mindgraph_decide",
-        description: "Track decisions through their lifecycle. Use 'open_decision' when the user faces a choice ('Should I use Postgres or SQLite?'), 'add_option' to record each alternative, 'add_constraint' for requirements or dealbreakers, 'resolve' when a choice is made. Use 'get_open' to review pending decisions. This creates a structured decision record that can be referenced later.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            action: {
-              type: "string",
-              enum: ["open_decision", "add_option", "add_constraint", "resolve", "get_open"],
-              description: "Decision lifecycle action"
-            },
-            label: {
-              type: "string",
-              description: "Decision, option, or constraint label"
-            },
-            summary: {
-              type: "string",
-              description: "Description or rationale"
-            },
-            decision_uid: {
-              type: "string",
-              description: "Decision UID (for add_option, add_constraint, resolve)"
-            },
-            chosen_option_uid: {
-              type: "string",
-              description: "UID of the chosen option (for resolve)"
-            },
-            props: {
-              type: "object",
-              description: "Additional properties"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
-          required: ["action"]
-        }
-      },
-      {
-        name: "mindgraph_action",
-        description: "Record procedural knowledge and risk assessments. Use 'create_flow' for workflows/processes, 'add_step' for individual steps in a flow, 'add_affordance' for capabilities ('this API supports batch operations'), 'add_control' for guardrails/constraints. Use 'assess_risk' when the user identifies a risk or potential problem. Less commonly used than capture/argue/commit \u2014 reach for this when the conversation is about HOW to do something.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            action: {
-              type: "string",
-              enum: [
-                "create_flow",
-                "add_step",
-                "add_affordance",
-                "add_control",
-                "assess_risk",
-                "get_assessments"
-              ],
-              description: "Action layer operation"
-            },
-            label: {
-              type: "string",
-              description: "Flow, step, affordance, control, or risk label"
-            },
-            summary: {
-              type: "string",
-              description: "Description"
-            },
-            target_uid: {
-              type: "string",
-              description: "Parent flow/step UID or target node for risk assessment"
-            },
-            props: {
-              type: "object",
-              description: "Type-specific properties (e.g. likelihood, impact, mitigation for risks)"
-            },
-            agent_id: {
-              type: "string",
-              description: "Agent identity"
-            }
-          },
           required: ["action"]
         }
       },
       {
         name: "mindgraph_plan",
-        description: "Agent-level task management and governance. Use 'create_plan'/'create_task'/'add_step' for breaking down work into trackable items, 'update_status' to mark progress, 'start_execution'/'complete_execution'/'fail_execution' for execution tracking. Use 'create_policy' and 'request_approval' for governance workflows. Prefer mindgraph_commit for the user's goals/projects; use mindgraph_plan for agent-managed task breakdowns and execution.",
+        description: "Agent-level task management, governance, and procedural knowledge. Use 'create_plan'/'create_task'/'add_step' for task breakdowns, 'update_status' for progress, 'get_plan' to review. Use 'create_flow'/'add_procedure_step'/'add_affordance'/'add_control' for workflows and procedures. Use 'assess_risk'/'get_assessments' for risk analysis. Use 'create_policy'/'request_approval'/'resolve_approval'/'get_pending' for governance. Prefer mindgraph_commit for user goals/projects; use this for agent-managed execution.",
         inputSchema: {
           type: "object",
           properties: {
@@ -836,13 +812,19 @@ var init_tools = __esm({
                 "create_policy",
                 "request_approval",
                 "resolve_approval",
-                "get_pending"
+                "get_pending",
+                "create_flow",
+                "add_procedure_step",
+                "add_affordance",
+                "add_control",
+                "assess_risk",
+                "get_assessments"
               ],
-              description: "Agent layer operation"
+              description: "Planning, procedure, or governance action"
             },
             label: {
               type: "string",
-              description: "Task, plan, step, or policy label"
+              description: "Task, plan, step, flow, policy, or risk label"
             },
             summary: {
               type: "string",
@@ -854,7 +836,11 @@ var init_tools = __esm({
             },
             task_uid: {
               type: "string",
-              description: "Task/step UID (for update_status, execution actions)"
+              description: "Task/step UID (for update_status, execution actions, resolve_approval)"
+            },
+            target_uid: {
+              type: "string",
+              description: "Parent flow/step UID or target node (for procedure/risk actions)"
             },
             status: {
               type: "string",
@@ -862,7 +848,7 @@ var init_tools = __esm({
             },
             props: {
               type: "object",
-              description: "Additional properties"
+              description: "Additional properties (e.g. likelihood, impact, mitigation for risks)"
             },
             agent_id: {
               type: "string",
@@ -874,7 +860,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_retrieve",
-        description: "Search the knowledge graph using BM25 keyword matching. Primary action: 'context' \u2014 pass 1\u20133 discriminating keywords (proper nouns, technical terms) extracted from the user's question. Drop filler words (what, how, tell me about, implications of). GOOD: 'Kissinger NATO', 'Rust async runtime'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'text' for fast keyword-only lookup. Other actions ('active_goals', 'open_questions', 'weak_claims', 'pending_approvals', 'unresolved_contradictions', 'layer', 'recent') are ONLY for when the user explicitly asks about those topics \u2014 never pre-fetch them.",
+        description: "Search and explore the knowledge graph. Use 'context' (default) for BM25 keyword retrieval \u2014 returns graph nodes only by default (labels, summaries, types, confidence); set include_chunks=true to also get full source text. Pass 1-3 discriminating keywords, not sentences. GOOD: 'Kissinger NATO'. BAD: 'What is Kissinger\\'s view on NATO?'. Use 'document_index' to list all ingested documents (titles, dates, UIDs) for orientation. Use 'semantic' when keywords return nothing \u2014 conceptual/fuzzy queries. Use 'hybrid' for keyword + semantic. Use 'text' for fast keyword-only. Use 'neighborhood'/'chain'/'path'/'subgraph' for graph traversal. Other actions ('active_goals', 'open_questions', etc.) only when the user explicitly asks.",
         inputSchema: {
           type: "object",
           properties: {
@@ -883,19 +869,48 @@ var init_tools = __esm({
               enum: [
                 "text",
                 "context",
+                "semantic",
+                "hybrid",
                 "active_goals",
                 "open_questions",
                 "weak_claims",
                 "pending_approvals",
                 "unresolved_contradictions",
                 "layer",
-                "recent"
+                "recent",
+                "chain",
+                "neighborhood",
+                "path",
+                "subgraph",
+                "document_index"
               ],
-              description: "Retrieval strategy"
+              description: "Retrieval or traversal strategy"
             },
             query: {
               type: "string",
-              description: "BM25 keyword query \u2014 extract 1\u20133 discriminating terms from the user's question, drop filler words. User asks 'What is Kissinger's view on NATO?' \u2192 'Kissinger NATO'. User asks about async in Rust \u2192 'Rust async runtime'. NEVER pass natural language sentences. (for text, context)"
+              description: "Search query \u2014 for 'text'/'context': 1-3 BM25 keywords, drop filler words. For 'semantic'/'hybrid': natural language is OK since it uses vector similarity."
+            },
+            start_uid: {
+              type: "string",
+              description: "Starting node UID (for chain, neighborhood, path, subgraph)"
+            },
+            end_uid: {
+              type: "string",
+              description: "Target node UID (for path)"
+            },
+            max_depth: {
+              type: "number",
+              description: "Maximum traversal depth (for chain, neighborhood, path, subgraph)"
+            },
+            direction: {
+              type: "string",
+              enum: ["outgoing", "incoming", "both"],
+              description: "Traversal direction (for neighborhood, subgraph)"
+            },
+            edge_types: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by edge types (for traversal actions)"
             },
             node_types: {
               type: "array",
@@ -904,15 +919,8 @@ var init_tools = __esm({
             },
             layer: {
               type: "string",
-              enum: [
-                "reality",
-                "epistemic",
-                "intent",
-                "action",
-                "memory",
-                "agent"
-              ],
-              description: "Filter by cognitive layer (for context, text, layer actions)"
+              enum: ["reality", "epistemic", "intent", "action", "memory", "agent"],
+              description: "Filter by cognitive layer"
             },
             limit: {
               type: "number",
@@ -920,7 +928,7 @@ var init_tools = __esm({
             },
             include_chunks: {
               type: "boolean",
-              description: "Include source document chunks in context results (default: true)"
+              description: "Include source document chunks in context results (default: false \u2014 set true to fetch full chunk text for citations or deep reading)"
             },
             include_graph: {
               type: "boolean",
@@ -1014,7 +1022,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.3.2 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v0.5.0 running on stdio (${BASE_URL})`
   );
 }
 var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, client, INSTRUCTIONS, server, PROMPTS;
@@ -1039,72 +1047,83 @@ var init_src = __esm({
       baseUrl: BASE_URL,
       apiKey: API_KEY
     });
-    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph.
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (6 tools).
 
 ## #1 RULE: Go straight to the user's topic
 
 When the user asks about something, your FIRST and ONLY action should be a SINGLE \`mindgraph_retrieve\` call with action "context" and keyword terms from their message. Nothing else first.
 
 **NEVER do any of these before addressing the user's topic:**
-- Do NOT retrieve active_goals
-- Do NOT retrieve open_questions
-- Do NOT retrieve contradictions or weak_claims
+- Do NOT retrieve active_goals, open_questions, contradictions, or weak_claims
 - Do NOT follow a "session lifecycle" or "warm-up" sequence
 - Do NOT make multiple serial retrieve calls when one "context" call covers it
 
 There is no session to open. There is no context to pre-load. Just search for what the user asked about.
 
 **Example:** User says "Tell me about Indian philosophy and Taoism"
-\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\` \u2014 extracted key nouns, dropped "Tell me about"
-\u2717 WRONG: First retrieve active_goals, then open_questions, then search for the topic
-\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language sentence won't match BM25 index
+\u2713 CORRECT: \`mindgraph_retrieve({action: "context", query: "Indian philosophy Taoism"})\`
+\u2717 WRONG: First retrieve active_goals, then open_questions, then search
+\u2717 WRONG: \`mindgraph_retrieve({action: "context", query: "Tell me about Indian philosophy and Taoism"})\` \u2014 natural language won't match BM25
+
+## Two-phase retrieval protocol
+
+**Phase 1 \u2014 Orient (default, fast, lightweight):**
+Use \`action: "context"\` with keywords. By default this returns only graph nodes \u2014 structured knowledge with labels, summaries, types, confidence scores, and edges. This is usually sufficient and keeps results compact.
 
-## Search query style \u2014 BM25 keyword matching
+**Phase 2 \u2014 Fetch source text (only when needed):**
+If you need the original source text behind a node (for verbatim quotes, citations, or when graph summaries lack detail), use \`action: "context"\` with \`include_chunks: true\`. This adds full document chunks (400-800 words each) to the response.
 
-The search index uses BM25 keyword matching against node labels and summaries. It matches individual words, NOT meaning or concepts. Drop filler words like "what", "how", "implications of", "tell me about". Query with 1\u20133 discriminating terms (proper nouns, technical terms, domain-specific words).
+**Orientation shortcut:**
+- \`action: "document_index"\` \u2014 list all ingested documents (titles, dates, UIDs) to see what's in the graph
 
-**Derive keywords from the user's question \u2014 examples:**
-- User asks "What is Kissinger's view on NATO expansion?" \u2192 query: \`"Kissinger NATO"\`
-- User asks "Tell me about async programming in Rust" \u2192 query: \`"Rust async runtime"\`
-- User asks "How does Indian philosophy relate to Taoism?" \u2192 query: \`"Indian philosophy Taoism"\`
-- User asks "What are the implications of carbon tax policy?" \u2192 query: \`"carbon tax"\`
+## Search strategy \u2014 keyword first, semantic as fallback
 
-**GOOD queries:** \`"Rust async runtime"\`, \`"Kissinger NATO"\`, \`"carbon tax emissions"\`
-**BAD queries:** \`"what do I know about async programming in Rust?"\`, \`"how does X relate to Y"\`, \`"implications of climate change"\`
+The default search uses BM25 keyword matching. Query with 1\u20133 discriminating terms (proper nouns, technical terms). Drop filler words.
 
-If the first query returns no results, try synonym or related terms (e.g. \`"global warming"\` instead of \`"climate change"\`).
+**Keyword examples:**
+- "What is Kissinger's view on NATO?" \u2192 query: \`"Kissinger NATO"\`
+- "Tell me about async in Rust" \u2192 query: \`"Rust async runtime"\`
+- "Implications of carbon tax?" \u2192 query: \`"carbon tax"\`
+
+If keyword search returns no results, escalate:
+1. Try synonyms (e.g. \`"global warming"\` instead of \`"climate change"\`)
+2. Use \`action: "semantic"\` \u2014 vector similarity, natural language OK (e.g. \`"ways to manage stress"\` finds "mental health" nodes)
+3. Use \`action: "hybrid"\` \u2014 combines BM25 + semantic for best coverage
 
 ## When to READ
 
 - User asks about topic X \u2192 \`mindgraph_retrieve\` action "context", query "X keywords"
+- User asks "what documents are in my graph?" \u2192 action "document_index"
 - User explicitly asks "what are my goals?" \u2192 action "active_goals"
 - User explicitly asks about open questions \u2192 action "open_questions"
-- Before asserting something the user previously said \u2192 retrieve to check
-- Parallelize independent calls in a single batch
+- Explore around a known node \u2192 action "neighborhood" with start_uid
+- Find connections between nodes \u2192 action "path" with start_uid + end_uid
 
 ## When to WRITE
 
 Capture knowledge when the user shares something worth remembering:
 - People/orgs/places/events \u2192 \`mindgraph_capture\` action "entity"
-- Quick notes, preferences \u2192 \`mindgraph_journal\`
+- Quick notes, preferences \u2192 \`mindgraph_capture\` action "journal"
 - Factual observations \u2192 \`mindgraph_capture\` action "observation"
-- Claims with evidence \u2192 \`mindgraph_argue\`
-- Questions to track \u2192 \`mindgraph_inquire\` action "open_question"
-- Goals or projects \u2192 \`mindgraph_commit\`
-- Decisions \u2192 \`mindgraph_decide\`
+- Claims with evidence \u2192 \`mindgraph_reason\` action "claim"
+- Questions to track \u2192 \`mindgraph_reason\` action "open_question"
+- Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
+- Decisions \u2192 \`mindgraph_commit\` action "open_decision"
 - Long-form content \u2192 \`mindgraph_ingest\`
 
 ## Tool tips
 
-- \`capture\` for structured/factual, \`journal\` for personal/informal
-- \`argue\` when evidence exists, \`inquire\` for open questions
-- \`text\` for fast lookup, \`context\` for rich retrieval with graph traversal
+- \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
+- \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
+- \`retrieve\`: "context" returns graph nodes only by default \u2014 set include_chunks=true for source text
+- \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
+- \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
 - Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
 - Don't narrate tool usage \u2014 capture naturally as part of conversation`;
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.3.4"
+        version: "0.5.0"
       },
       {
         capabilities: {
@@ -1264,14 +1283,12 @@ Capture knowledge when the user shares something worth remembering:
                 content: {
                   type: "text",
                   text: `Analyze the following conversation and capture all important information into my knowledge graph. Extract:
-- Named entities (people, organizations, places, events)
-- Factual claims and observations
-- Decisions made or pending
-- Goals or commitments mentioned
-- Open questions raised
-- Any hypotheses or theories discussed
-
-Use the appropriate MindGraph tools for each type of knowledge.
+- Named entities (people, organizations, places, events) \u2192 mindgraph_capture action "entity"
+- Factual claims and observations \u2192 mindgraph_capture action "observation" or mindgraph_reason action "claim"
+- Decisions made or pending \u2192 mindgraph_commit action "open_decision"
+- Goals or commitments mentioned \u2192 mindgraph_commit action "goal"/"project"
+- Open questions raised \u2192 mindgraph_reason action "open_question"
+- Any hypotheses or theories discussed \u2192 mindgraph_reason action "hypothesis"/"theory"
 
 Conversation:
 ${conversation}`