@a-company/paradigm 3.20.2 → 3.22.0

package/dist/mcp.js

@@ -2026,7 +2026,7 @@ function registerResources(server, getContext2) {
 
 // ../paradigm-mcp/src/tools/index.ts
 import * as os3 from "os";
-import * as path25 from "path";
+import * as path26 from "path";
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema
@@ -2790,7 +2790,7 @@ function navigateExplore(config, target, rootDir) {
   }
   if (result.paths.length === 0) {
     const areaSymbols = Object.entries(config.symbols).filter(
-      ([sym, path26]) => sym.toLowerCase().includes(targetLower) || path26.toLowerCase().includes(targetLower)
+      ([sym, path27]) => sym.toLowerCase().includes(targetLower) || path27.toLowerCase().includes(targetLower)
     ).slice(0, 10);
     result.paths = [...new Set(areaSymbols.map(([, p]) => p))];
     result.symbols = areaSymbols.map(([s]) => s);
@@ -7543,8 +7543,16 @@ function loadHabitsFresh(rootDir) {
   const home = process.env.HOME || process.env.USERPROFILE || "~";
   const globalConfig = loadHabitsYaml(path18.join(home, ".paradigm", "habits.yaml"));
   if (globalConfig) mergeHabits(habitsById, globalConfig);
+  const globalHabitFiles = loadHabitFiles(path18.join(home, ".paradigm", "habits"));
+  for (const habit of globalHabitFiles) {
+    habitsById.set(habit.id, habit);
+  }
   const projectConfig = loadHabitsYaml(path18.join(rootDir, ".paradigm", "habits.yaml"));
   if (projectConfig) mergeHabits(habitsById, projectConfig);
+  const projectHabitFiles = loadHabitFiles(path18.join(rootDir, ".paradigm", "habits"));
+  for (const habit of projectHabitFiles) {
+    habitsById.set(habit.id, habit);
+  }
   return Array.from(habitsById.values());
 }
 function loadHabitsYaml(filePath) {
@@ -7575,6 +7583,141 @@ function mergeHabits(habitsById, config) {
 function getHabitsByTrigger(habits, trigger) {
   return habits.filter((h) => h.enabled && h.trigger === trigger);
 }
+function invalidateHabitsCache(rootDir) {
+  habitsCache.delete(path18.resolve(rootDir));
+}
+function loadHabitFiles(dir) {
+  if (!fs17.existsSync(dir)) return [];
+  try {
+    const files = fs17.readdirSync(dir).filter((f) => f.endsWith(".habit")).sort();
+    const habits = [];
+    for (const file of files) {
+      try {
+        const content = fs17.readFileSync(path18.join(dir, file), "utf8");
+        const habit = yaml11.load(content);
+        if (habit?.id && habit?.name) {
+          habits.push(habit);
+        }
+      } catch {
+      }
+    }
+    return habits;
+  } catch {
+    return [];
+  }
+}
+var VALID_CATEGORIES = [
+  "discovery",
+  "verification",
+  "testing",
+  "documentation",
+  "collaboration",
+  "security"
+];
+var VALID_TRIGGERS = [
+  "preflight",
+  "postflight",
+  "on-commit",
+  "on-stop"
+];
+var VALID_SEVERITIES = ["advisory", "warn", "block"];
+var VALID_CHECK_TYPES = [
+  "tool-called",
+  "file-exists",
+  "file-modified",
+  "lore-recorded",
+  "symbols-registered",
+  "gates-declared",
+  "tests-exist",
+  "git-clean",
+  "commit-message-format",
+  "flow-coverage",
+  "context-checked",
+  "aspect-anchored"
+];
+var KEBAB_CASE_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function validateHabitDefinition(habit) {
+  const errors = [];
+  if (!habit.id) errors.push("Missing required field: id");
+  if (!habit.name) errors.push("Missing required field: name");
+  if (!habit.description) errors.push("Missing required field: description");
+  if (!habit.category) errors.push("Missing required field: category");
+  if (!habit.trigger) errors.push("Missing required field: trigger");
+  if (!habit.severity) errors.push("Missing required field: severity");
+  if (!habit.check) errors.push("Missing required field: check");
+  if (habit.enabled === void 0 || habit.enabled === null) errors.push("Missing required field: enabled");
+  if (habit.id && !KEBAB_CASE_RE.test(habit.id)) {
+    errors.push(`Invalid id format: "${habit.id}" \u2014 must be kebab-case (lowercase, hyphens only)`);
+  }
+  if (habit.category && !VALID_CATEGORIES.includes(habit.category)) {
+    errors.push(`Invalid category: "${habit.category}" \u2014 must be one of: ${VALID_CATEGORIES.join(", ")}`);
+  }
+  if (habit.trigger && !VALID_TRIGGERS.includes(habit.trigger)) {
+    errors.push(`Invalid trigger: "${habit.trigger}" \u2014 must be one of: ${VALID_TRIGGERS.join(", ")}`);
+  }
+  if (habit.severity && !VALID_SEVERITIES.includes(habit.severity)) {
+    errors.push(`Invalid severity: "${habit.severity}" \u2014 must be one of: ${VALID_SEVERITIES.join(", ")}`);
+  }
+  if (habit.check) {
+    if (!VALID_CHECK_TYPES.includes(habit.check.type)) {
+      errors.push(`Invalid check.type: "${habit.check.type}" \u2014 must be one of: ${VALID_CHECK_TYPES.join(", ")}`);
+    }
+    const params = habit.check.params || {};
+    switch (habit.check.type) {
+      case "tool-called":
+        if (!params.tools || !Array.isArray(params.tools) || params.tools.length === 0) {
+          errors.push('check.type "tool-called" requires check.params.tools[] (non-empty array)');
+        }
+        break;
+      case "file-exists":
+      case "file-modified":
+        if (!params.patterns || !Array.isArray(params.patterns) || params.patterns.length === 0) {
+          errors.push(`check.type "${habit.check.type}" requires check.params.patterns[] (non-empty array)`);
+        }
+        break;
+      case "commit-message-format":
+        if (!params.messagePatterns || !Array.isArray(params.messagePatterns) || params.messagePatterns.length === 0) {
+          errors.push('check.type "commit-message-format" requires check.params.messagePatterns[] (non-empty array)');
+        }
+        break;
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+var SEED_HABIT_IDS = new Set(SEED_HABITS.map((h) => h.id));
+function isSeedHabit(id) {
+  return SEED_HABIT_IDS.has(id);
+}
+function saveHabit(rootDir, habit, scope = "project") {
+  const baseDir = scope === "global" ? path18.join(process.env.HOME || process.env.USERPROFILE || "~", ".paradigm", "habits") : path18.join(rootDir, ".paradigm", "habits");
+  if (!fs17.existsSync(baseDir)) {
+    fs17.mkdirSync(baseDir, { recursive: true });
+  }
+  const filePath = path18.join(baseDir, `${habit.id}.habit`);
+  const content = yaml11.dump(habit, { lineWidth: 120, noRefs: true });
+  fs17.writeFileSync(filePath, content, "utf8");
+  invalidateHabitsCache(rootDir);
+  return filePath;
+}
+function removeHabit(rootDir, id) {
+  if (isSeedHabit(id)) {
+    return { removed: false, reason: `"${id}" is a seed habit and cannot be removed. Use overrides in habits.yaml to disable it.` };
+  }
+  const projectPath = path18.join(rootDir, ".paradigm", "habits", `${id}.habit`);
+  if (fs17.existsSync(projectPath)) {
+    fs17.unlinkSync(projectPath);
+    invalidateHabitsCache(rootDir);
+    return { removed: true };
+  }
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  const globalPath = path18.join(home, ".paradigm", "habits", `${id}.habit`);
+  if (fs17.existsSync(globalPath)) {
+    fs17.unlinkSync(globalPath);
+    invalidateHabitsCache(rootDir);
+    return { removed: true };
+  }
+  return { removed: false, reason: `No .habit file found for "${id}". It may be defined in habits.yaml \u2014 edit that file directly.` };
+}
 function evaluateHabits(habits, trigger, context2, platform2) {
   let activeHabits = getHabitsByTrigger(habits, trigger);
   if (platform2) {
@@ -8786,6 +8929,7 @@ function summarizeEntry(entry) {
 // ../paradigm-mcp/src/tools/habits.ts
 import * as fs19 from "fs";
 import * as path21 from "path";
+import * as yaml12 from "js-yaml";
 import { execSync as execSync3 } from "child_process";
 function getHabitsToolsList() {
   return [
@@ -8897,6 +9041,128 @@ function getHabitsToolsList() {
         readOnlyHint: true,
         destructiveHint: false
       }
+    },
+    {
+      name: "paradigm_habits_add",
+      description: 'Create a new custom habit as an individual .habit file. Validates all fields and checks for ID collisions with seed habits. Use scope "global" for ~/.paradigm/habits/ or "project" (default) for .paradigm/habits/. ~150 tokens.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: 'Unique habit ID in kebab-case (e.g. "check-changelog")' },
+          name: { type: "string", description: "Human-readable habit name" },
+          description: { type: "string", description: "What this habit checks and why" },
+          category: {
+            type: "string",
+            enum: ["discovery", "verification", "testing", "documentation", "collaboration", "security"],
+            description: "Habit category"
+          },
+          trigger: {
+            type: "string",
+            enum: ["preflight", "postflight", "on-commit", "on-stop"],
+            description: "When the habit is evaluated"
+          },
+          severity: {
+            type: "string",
+            enum: ["advisory", "warn", "block"],
+            description: "How strictly to enforce (block prevents session completion)"
+          },
+          check: {
+            type: "object",
+            description: "Check definition with type and params",
+            properties: {
+              type: {
+                type: "string",
+                enum: [
+                  "tool-called",
+                  "file-exists",
+                  "file-modified",
+                  "lore-recorded",
+                  "symbols-registered",
+                  "gates-declared",
+                  "tests-exist",
+                  "git-clean",
+                  "commit-message-format",
+                  "flow-coverage",
+                  "context-checked",
+                  "aspect-anchored"
+                ]
+              },
+              params: { type: "object", description: "Check-specific parameters (tools[], patterns[], etc.)" }
+            },
+            required: ["type", "params"]
+          },
+          enabled: { type: "boolean", description: "Whether the habit is active (default: true)" },
+          platforms: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Platforms this habit applies to (e.g. ["claude", "cursor"]). Omit for all.'
+          },
+          scope: {
+            type: "string",
+            enum: ["project", "global"],
+            description: 'Where to save: "project" (default) or "global" (~/.paradigm/habits/)'
+          }
+        },
+        required: ["id", "name", "description", "category", "trigger", "severity", "check"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_habits_edit",
+      description: "Update fields on an existing custom .habit file. Cannot edit seed habits \u2014 use overrides in habits.yaml instead. Merges provided fields with existing definition and re-validates. ~150 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "ID of the habit to edit" },
+          name: { type: "string", description: "Updated name" },
+          description: { type: "string", description: "Updated description" },
+          category: {
+            type: "string",
+            enum: ["discovery", "verification", "testing", "documentation", "collaboration", "security"]
+          },
+          trigger: {
+            type: "string",
+            enum: ["preflight", "postflight", "on-commit", "on-stop"]
+          },
+          severity: {
+            type: "string",
+            enum: ["advisory", "warn", "block"]
+          },
+          check: {
+            type: "object",
+            properties: {
+              type: { type: "string" },
+              params: { type: "object" }
+            },
+            required: ["type", "params"]
+          },
+          enabled: { type: "boolean" },
+          platforms: { type: "array", items: { type: "string" } }
+        },
+        required: ["id"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_habits_remove",
+      description: "Delete a custom .habit file. Cannot remove seed habits \u2014 use overrides to disable them instead. Searches both project and global habit directories. ~100 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "ID of the habit to remove" }
+        },
+        required: ["id"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true
+      }
     }
   ];
 }
@@ -8922,6 +9188,21 @@ async function handleHabitsTool(name, args, ctx) {
       trackToolCall(result.length, name);
       return { text: result, handled: true };
     }
+    case "paradigm_habits_add": {
+      const result = handleHabitsAdd(args, ctx);
+      trackToolCall(result.length, name);
+      return { text: result, handled: true };
+    }
+    case "paradigm_habits_edit": {
+      const result = handleHabitsEdit(args, ctx);
+      trackToolCall(result.length, name);
+      return { text: result, handled: true };
+    }
+    case "paradigm_habits_remove": {
+      const result = handleHabitsRemove(args, ctx);
+      trackToolCall(result.length, name);
+      return { text: result, handled: true };
+    }
     default:
       return { text: "", handled: false };
   }
@@ -9111,6 +9392,127 @@ function buildRecommendations(evaluation) {
   }
   return [...new Set(recs)];
 }
+function handleHabitsAdd(args, ctx) {
+  const id = args.id;
+  const scope = args.scope || "project";
+  if (isSeedHabit(id)) {
+    return JSON.stringify({
+      error: true,
+      message: `Cannot create habit "${id}" \u2014 it collides with a seed habit. Choose a different ID or use overrides in habits.yaml to customize the seed habit.`
+    }, null, 2);
+  }
+  const existingHabits = loadHabits(ctx.rootDir);
+  const existing = existingHabits.find((h) => h.id === id);
+  if (existing) {
+    return JSON.stringify({
+      error: true,
+      message: `Habit "${id}" already exists. Use paradigm_habits_edit to update it, or choose a different ID.`
+    }, null, 2);
+  }
+  const habit = {
+    id,
+    name: args.name,
+    description: args.description,
+    category: args.category,
+    trigger: args.trigger,
+    severity: args.severity,
+    check: args.check,
+    enabled: args.enabled !== void 0 ? args.enabled : true
+  };
+  if (args.platforms) habit.platforms = args.platforms;
+  const validation = validateHabitDefinition(habit);
+  if (!validation.valid) {
+    return JSON.stringify({
+      error: true,
+      message: "Validation failed",
+      errors: validation.errors
+    }, null, 2);
+  }
+  const filePath = saveHabit(ctx.rootDir, habit, scope);
+  return JSON.stringify({
+    created: true,
+    id: habit.id,
+    filePath,
+    scope,
+    message: `Habit "${habit.name}" created at ${filePath}`
+  }, null, 2);
+}
+function handleHabitsEdit(args, ctx) {
+  const id = args.id;
+  if (isSeedHabit(id)) {
+    return JSON.stringify({
+      error: true,
+      message: `Cannot edit "${id}" \u2014 it is a seed habit. To customize it, add an override in .paradigm/habits.yaml under the "overrides:" key.`
+    }, null, 2);
+  }
+  const projectPath = path21.join(ctx.rootDir, ".paradigm", "habits", `${id}.habit`);
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  const globalPath = path21.join(home, ".paradigm", "habits", `${id}.habit`);
+  let filePath = null;
+  let scope = "project";
+  if (fs19.existsSync(projectPath)) {
+    filePath = projectPath;
+    scope = "project";
+  } else if (fs19.existsSync(globalPath)) {
+    filePath = globalPath;
+    scope = "global";
+  }
+  if (!filePath) {
+    return JSON.stringify({
+      error: true,
+      message: `No .habit file found for "${id}". It may be defined in habits.yaml \u2014 edit that file directly.`
+    }, null, 2);
+  }
+  let existing;
+  try {
+    const content = fs19.readFileSync(filePath, "utf8");
+    existing = yaml12.load(content);
+  } catch {
+    return JSON.stringify({
+      error: true,
+      message: `Failed to read ${filePath}`
+    }, null, 2);
+  }
+  const updated = { ...existing };
+  if (args.name !== void 0) updated.name = args.name;
+  if (args.description !== void 0) updated.description = args.description;
+  if (args.category !== void 0) updated.category = args.category;
+  if (args.trigger !== void 0) updated.trigger = args.trigger;
+  if (args.severity !== void 0) updated.severity = args.severity;
+  if (args.check !== void 0) updated.check = args.check;
+  if (args.enabled !== void 0) updated.enabled = args.enabled;
+  if (args.platforms !== void 0) updated.platforms = args.platforms;
+  const validation = validateHabitDefinition(updated);
+  if (!validation.valid) {
+    return JSON.stringify({
+      error: true,
+      message: "Validation failed after merge",
+      errors: validation.errors
+    }, null, 2);
+  }
+  saveHabit(ctx.rootDir, updated, scope);
+  return JSON.stringify({
+    updated: true,
+    id: updated.id,
+    filePath,
+    message: `Habit "${updated.name}" updated`
+  }, null, 2);
+}
+function handleHabitsRemove(args, ctx) {
+  const id = args.id;
+  const result = removeHabit(ctx.rootDir, id);
+  if (result.removed) {
+    return JSON.stringify({
+      removed: true,
+      id,
+      message: `Habit "${id}" removed`
+    }, null, 2);
+  }
+  return JSON.stringify({
+    error: true,
+    message: result.reason
+  }, null, 2);
+}
 async function handleHabitsStatus(args, ctx) {
   const engineer = args.engineer;
   const period = args.period || "30d";
@@ -10366,7 +10768,7 @@ async function handleTasksTool(name, args, ctx) {
 // ../paradigm-mcp/src/utils/assessment-loader.ts
 import * as fs21 from "fs";
 import * as path23 from "path";
-import * as yaml12 from "js-yaml";
+import * as yaml13 from "js-yaml";
 var ASSESSMENTS_DIR = ".paradigm/assessments";
 var ARCS_DIR = "arcs";
 var INDEX_FILE = "index.yaml";
@@ -10379,7 +10781,7 @@ function computeArcStats(rootDir, arc) {
     const files = fs21.readdirSync(entriesPath).filter((f) => f.endsWith(".yaml"));
     for (const file of files) {
       try {
-        const entry = yaml12.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
+        const entry = yaml13.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
         entryCount++;
         if (entry.symbols) entry.symbols.forEach((s) => symbolSet.add(s));
         if (!latestDate || entry.date > latestDate) latestDate = entry.date;
@@ -10404,7 +10806,7 @@ async function loadArcs(rootDir, status) {
     const arcFile = path23.join(arcsPath, arcDir, "arc.yaml");
     if (!fs21.existsSync(arcFile)) continue;
     try {
-      const arc = yaml12.load(fs21.readFileSync(arcFile, "utf8"));
+      const arc = yaml13.load(fs21.readFileSync(arcFile, "utf8"));
       if (status && status !== "all" && arc.status !== status) continue;
       arcs.push(computeArcStats(rootDir, arc));
     } catch {
@@ -10421,7 +10823,7 @@ async function loadArc(rootDir, arcId) {
   const arcFile = path23.join(rootDir, ASSESSMENTS_DIR, ARCS_DIR, arcId, "arc.yaml");
   if (!fs21.existsSync(arcFile)) return null;
   try {
-    const arc = yaml12.load(fs21.readFileSync(arcFile, "utf8"));
+    const arc = yaml13.load(fs21.readFileSync(arcFile, "utf8"));
     return computeArcStats(rootDir, arc);
   } catch {
     return null;
@@ -10431,9 +10833,9 @@ async function closeArc(rootDir, arcId, status) {
   const arcFile = path23.join(rootDir, ASSESSMENTS_DIR, ARCS_DIR, arcId, "arc.yaml");
   if (!fs21.existsSync(arcFile)) return false;
   try {
-    const arc = yaml12.load(fs21.readFileSync(arcFile, "utf8"));
+    const arc = yaml13.load(fs21.readFileSync(arcFile, "utf8"));
     arc.status = status;
-    fs21.writeFileSync(arcFile, yaml12.dump(arc, { lineWidth: -1, noRefs: true }));
+    fs21.writeFileSync(arcFile, yaml13.dump(arc, { lineWidth: -1, noRefs: true }));
     await rebuildAssessmentIndex(rootDir);
     return true;
   } catch {
@@ -10447,7 +10849,7 @@ async function loadEntries(rootDir, arcId) {
   const files = fs21.readdirSync(entriesPath).filter((f) => f.endsWith(".yaml")).sort();
   for (const file of files) {
     try {
-      const entry = yaml12.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
+      const entry = yaml13.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
       entries.push(entry);
     } catch {
     }
@@ -10469,9 +10871,9 @@ async function loadEntry(rootDir, entryId) {
     const entryFile = path23.join(arcsPath, arcDir, "entries", `${entryId}.yaml`);
     if (fs21.existsSync(entryFile)) {
       try {
-        const entry = yaml12.load(fs21.readFileSync(entryFile, "utf8"));
+        const entry = yaml13.load(fs21.readFileSync(entryFile, "utf8"));
         const arcFile = path23.join(arcsPath, arcDir, "arc.yaml");
-        const arc = yaml12.load(fs21.readFileSync(arcFile, "utf8"));
+        const arc = yaml13.load(fs21.readFileSync(arcFile, "utf8"));
         return { entry, arc };
       } catch {
         return null;
@@ -10498,7 +10900,7 @@ async function searchEntries(rootDir, filter) {
     const files = fs21.readdirSync(entriesPath).filter((f) => f.endsWith(".yaml"));
     for (const file of files) {
       try {
-        const entry = yaml12.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
+        const entry = yaml13.load(fs21.readFileSync(path23.join(entriesPath, file), "utf8"));
         if (filter.symbol && !(entry.symbols || []).includes(filter.symbol)) continue;
         if (filter.tag && !(entry.tags || []).includes(filter.tag)) continue;
         if (filter.type && entry.type !== filter.type) continue;
@@ -10529,7 +10931,7 @@ async function rebuildAssessmentIndex(rootDir) {
       const arcFile = path23.join(arcsPath, arcDir, "arc.yaml");
       if (!fs21.existsSync(arcFile)) continue;
       try {
-        const arc = yaml12.load(fs21.readFileSync(arcFile, "utf8"));
+        const arc = yaml13.load(fs21.readFileSync(arcFile, "utf8"));
         const entriesPath = path23.join(arcsPath, arcDir, "entries");
         const entryCount = fs21.existsSync(entriesPath) ? fs21.readdirSync(entriesPath).filter((f) => f.endsWith(".yaml")).length : 0;
         totalArcs++;
@@ -10549,7 +10951,7 @@ async function rebuildAssessmentIndex(rootDir) {
     arcs: arcSummaries
   };
   fs21.mkdirSync(assessmentsPath, { recursive: true });
-  fs21.writeFileSync(path23.join(assessmentsPath, INDEX_FILE), yaml12.dump(index, { lineWidth: -1, noRefs: true }));
+  fs21.writeFileSync(path23.join(assessmentsPath, INDEX_FILE), yaml13.dump(index, { lineWidth: -1, noRefs: true }));
   return index;
 }
 
@@ -10886,8 +11288,8 @@ function generateRunId() {
 var TEMPLATE_REGEX = /\{\{([^}]+)\}\}/g;
 function interpolate(value, scope) {
   if (typeof value === "string") {
-    return value.replace(TEMPLATE_REGEX, (_match, path26) => {
-      const resolved = resolvePath(path26.trim(), scope);
+    return value.replace(TEMPLATE_REGEX, (_match, path27) => {
+      const resolved = resolvePath(path27.trim(), scope);
       return resolved !== void 0 ? String(resolved) : _match;
     });
   }
@@ -10920,8 +11322,8 @@ function resolvePath(dotPath, scope) {
       return void 0;
   }
 }
-function deepGet(obj, path26) {
-  const parts = path26.split(/[.\[\]]+/).filter(Boolean);
+function deepGet(obj, path27) {
+  const parts = path27.split(/[.\[\]]+/).filter(Boolean);
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") return void 0;
@@ -11157,11 +11559,11 @@ async function runPersonaObject(rootDir, persona, options) {
 }
 async function runChain(rootDir, chainId, options) {
   const start = Date.now();
-  const fs22 = await import("fs");
-  const path26 = await import("path");
-  const yaml13 = await import("js-yaml");
-  const chainPath = path26.join(rootDir, ".paradigm", "personas", "chains", `${chainId}.yaml`);
-  if (!fs22.existsSync(chainPath)) {
+  const fs23 = await import("fs");
+  const path27 = await import("path");
+  const yaml14 = await import("js-yaml");
+  const chainPath = path27.join(rootDir, ".paradigm", "personas", "chains", `${chainId}.yaml`);
+  if (!fs23.existsSync(chainPath)) {
     return {
       chain_id: chainId,
       status: "error",
@@ -11170,7 +11572,7 @@ async function runChain(rootDir, chainId, options) {
       duration_ms: Date.now() - start
     };
   }
-  const chain = yaml13.load(fs22.readFileSync(chainPath, "utf8"));
+  const chain = yaml14.load(fs23.readFileSync(chainPath, "utf8"));
   let permutation;
   if (options.permutation && chain.permutations) {
     permutation = chain.permutations.find((p) => p.id === options.permutation);
@@ -11274,8 +11676,8 @@ function validateInterpolation(persona) {
     const serialized = JSON.stringify(step);
     const templates = serialized.match(TEMPLATE_REGEX) || [];
     for (const template of templates) {
-      const path26 = template.replace("{{", "").replace("}}", "").trim();
-      const [namespace, ...rest] = path26.split(".");
+      const path27 = template.replace("{{", "").replace("}}", "").trim();
+      const [namespace, ...rest] = path27.split(".");
       const key = rest.join(".");
       switch (namespace) {
         case "fixtures":
@@ -12287,8 +12689,241 @@ function summarizeStep(step) {
   return result;
 }
 
-// ../paradigm-mcp/src/tools/fallback-grep.ts
+// ../paradigm-mcp/src/tools/graph.ts
+import * as fs22 from "fs";
 import * as path24 from "path";
+var CATEGORY_PREFIXES = {
+  component: "#",
+  flow: "$",
+  gate: "^",
+  signal: "!",
+  aspect: "~"
+};
+var NODE_WIDTH = 200;
+var NODE_HEIGHT = 60;
+var NODE_GAP = 20;
+var GROUP_PADDING = 40;
+var GROUP_HEADER = 50;
+var GROUP_GAP = 60;
+function getGraphToolsList() {
+  return [
+    {
+      name: "paradigm_graph_generate",
+      description: "Generate a GraphState JSON document for the Paradigm Symbol Graph UI. Accepts optional symbols (filter), groups (clustering), and links (edges between groups). Returns valid GraphState ready to load. ~200 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          symbols: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Symbol names to include (e.g. ["#auth-middleware", "^authenticated"]). Omit to include all from scan-index.'
+          },
+          groups: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                label: { type: "string", description: "Group display label" },
+                symbols: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Symbol names belonging to this group"
+                }
+              },
+              required: ["label", "symbols"]
+            },
+            description: "Optional groupings of symbols."
+          },
+          links: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                source: { type: "string", description: "Source group label" },
+                target: { type: "string", description: "Target group label" },
+                label: { type: "string", description: "Edge label" }
+              },
+              required: ["source", "target"]
+            },
+            description: "Edges between groups (by label name)."
+          },
+          name: {
+            type: "string",
+            description: 'Graph name (default: "Generated Graph").'
+          }
+        }
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false
+      }
+    }
+  ];
+}
+async function handleGraphTool(name, args, ctx) {
+  if (name !== "paradigm_graph_generate") {
+    return { handled: false, text: "" };
+  }
+  try {
+    const result = buildGraphState(
+      ctx.rootDir,
+      args.symbols,
+      args.groups,
+      args.links,
+      args.name || "Generated Graph"
+    );
+    const text = JSON.stringify(result, null, 2);
+    trackToolCall(text.length, name);
+    return { handled: true, text };
+  } catch (err2) {
+    const text = JSON.stringify({ error: err2.message }, null, 2);
+    trackToolCall(text.length, name);
+    return { handled: true, text };
+  }
+}
+var SCAN_CATEGORY_MAP = {
+  components: "component",
+  flows: "flow",
+  gates: "gate",
+  signals: "signal",
+  aspects: "aspect"
+};
+function loadScanIndex(rootDir) {
+  const indexPath = path24.join(rootDir, ".paradigm", "scan-index.json");
+  if (!fs22.existsSync(indexPath)) return [];
+  const raw = JSON.parse(fs22.readFileSync(indexPath, "utf8"));
+  const symbols = [];
+  for (const [sectionKey, categoryName] of Object.entries(SCAN_CATEGORY_MAP)) {
+    const section = raw[sectionKey];
+    if (!section || typeof section !== "object") continue;
+    for (const [id, sym] of Object.entries(section)) {
+      const s = sym;
+      symbols.push({
+        id,
+        name: id,
+        category: categoryName,
+        prefix: CATEGORY_PREFIXES[categoryName] || "#",
+        description: s.description,
+        path: s.path,
+        tags: s.tags
+      });
+    }
+  }
+  return symbols;
+}
+function resolveSymbol(name, allSymbols) {
+  const stripped = name.replace(/^[#$^!~]/, "");
+  return allSymbols.find(
+    (s) => s.id === stripped || s.name === stripped || s.id === name || s.name === name
+  );
+}
+function buildGraphState(rootDir, symbolFilter, groups, links, graphName = "Generated Graph") {
+  const allSymbols = loadScanIndex(rootDir);
+  let included;
+  if (symbolFilter && symbolFilter.length > 0) {
+    included = symbolFilter.map((name) => resolveSymbol(name, allSymbols)).filter(Boolean);
+  } else {
+    included = allSymbols;
+  }
+  const nodes = [];
+  const edges = [];
+  const groupIdMap = /* @__PURE__ */ new Map();
+  const assignedSymbols = /* @__PURE__ */ new Set();
+  let nextGroupX = 0;
+  if (groups && groups.length > 0) {
+    for (const group of groups) {
+      const groupId = `group-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+      groupIdMap.set(group.label, groupId);
+      const memberSymbols = group.symbols.map((name) => resolveSymbol(name, included)).filter(Boolean);
+      const cols = Math.ceil(Math.sqrt(memberSymbols.length));
+      const rows = Math.ceil(memberSymbols.length / cols);
+      for (let i = 0; i < memberSymbols.length; i++) {
+        const sym = memberSymbols[i];
+        const col = i % cols;
+        const row = Math.floor(i / cols);
+        const prefix = CATEGORY_PREFIXES[sym.category] || "#";
+        nodes.push({
+          id: `sym-${sym.id}`,
+          type: "symbolNode",
+          position: {
+            x: GROUP_PADDING + col * (NODE_WIDTH + NODE_GAP),
+            y: GROUP_HEADER + GROUP_PADDING + row * (NODE_HEIGHT + NODE_GAP)
+          },
+          parentId: groupId,
+          data: {
+            type: "symbol",
+            symbol: sym,
+            label: `${prefix}${sym.name}`
+          }
+        });
+        assignedSymbols.add(sym.id);
+      }
+      const cols2 = Math.max(cols, 1);
+      const rows2 = Math.max(rows, 1);
+      const groupWidth = GROUP_PADDING * 2 + cols2 * NODE_WIDTH + (cols2 - 1) * NODE_GAP;
+      const groupHeight = GROUP_HEADER + GROUP_PADDING * 2 + rows2 * NODE_HEIGHT + (rows2 - 1) * NODE_GAP;
+      nodes.unshift({
+        id: groupId,
+        type: "groupNode",
+        position: { x: nextGroupX, y: 0 },
+        style: { width: groupWidth, height: groupHeight },
+        data: { type: "group", label: group.label }
+      });
+      nextGroupX += groupWidth + GROUP_GAP;
+    }
+  }
+  const ungrouped = included.filter((s) => !assignedSymbols.has(s.id));
+  if (ungrouped.length > 0) {
+    const startY = groups && groups.length > 0 ? 400 : 0;
+    const cols = Math.ceil(Math.sqrt(ungrouped.length));
+    for (let i = 0; i < ungrouped.length; i++) {
+      const sym = ungrouped[i];
+      const col = i % cols;
+      const row = Math.floor(i / cols);
+      const prefix = CATEGORY_PREFIXES[sym.category] || "#";
+      nodes.push({
+        id: `sym-${sym.id}`,
+        type: "symbolNode",
+        position: {
+          x: col * (NODE_WIDTH + NODE_GAP),
+          y: startY + row * (NODE_HEIGHT + NODE_GAP)
+        },
+        data: {
+          type: "symbol",
+          symbol: sym,
+          label: `${prefix}${sym.name}`
+        }
+      });
+    }
+  }
+  if (links && links.length > 0) {
+    for (const link of links) {
+      const sourceId = groupIdMap.get(link.source);
+      const targetId = groupIdMap.get(link.target);
+      if (sourceId && targetId) {
+        edges.push({
+          id: `e-${sourceId}-${targetId}`,
+          source: sourceId,
+          target: targetId,
+          type: "default",
+          label: link.label,
+          data: { label: link.label }
+        });
+      }
+    }
+  }
+  return {
+    version: "1.0",
+    name: graphName,
+    projectId: path24.basename(rootDir),
+    lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+    nodes,
+    edges
+  };
+}
+
+// ../paradigm-mcp/src/tools/fallback-grep.ts
+import * as path25 from "path";
 import { execSync as execSync5 } from "child_process";
 function grepForReferences(rootDir, symbol, options = {}) {
   const { maxResults = 20 } = options;
@@ -12317,7 +12952,7 @@ function grepForReferences(rootDir, symbol, options = {}) {
     const match = line.match(/^(.+?):(\d+):(.*)$/);
     if (match) {
       const [, filePath, lineNum, content] = match;
-      const relativePath = path24.relative(rootDir, filePath);
+      const relativePath = path25.relative(rootDir, filePath);
       let context2 = "unknown";
       if (relativePath.includes(".purpose") || relativePath.includes("portal.yaml")) {
         context2 = "purpose";
@@ -12580,6 +13215,8 @@ function registerTools(server, getContext2, reloadContext2) {
           ...getPersonaToolsList(),
           // Protocol tools
           ...getProtocolsToolsList(),
+          // Graph generation tool
+          ...getGraphToolsList(),
           // Plugin update check
           {
             name: "paradigm_plugin_check",
@@ -13213,7 +13850,7 @@ Update command:
             const { rebuildStaticFiles: rebuildStaticFiles2 } = await import("./reindex-CMZARW5K.js");
             const memberResults = [];
             for (const member of ctx.workspace.config.members) {
-              const memberAbsPath = path25.resolve(path25.dirname(ctx.workspace.workspacePath), member.path);
+              const memberAbsPath = path26.resolve(path26.dirname(ctx.workspace.workspacePath), member.path);
               try {
                 const result = await rebuildStaticFiles2(memberAbsPath);
                 memberResults.push({
@@ -13402,6 +14039,15 @@ Update command:
                 };
               }
             }
+            if (name === "paradigm_graph_generate") {
+              const result = await handleGraphTool(name, args, ctx);
+              if (result.handled) {
+                trackToolCall(result.text.length, name);
+                return {
+                  content: [{ type: "text", text: result.text }]
+                };
+              }
+            }
             if (name === "paradigm_reindex") {
               const reload = reloadContext2 || (async () => {
               });