@kairos-sdk/core 0.4.0 → 0.5.0

package/dist/mcp-server.cjs

@@ -13,7 +13,13 @@ var import_node_os = require("os");
 
 // src/utils/uuid.ts
 function generateUUID() {
-  return crypto.randomUUID();
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
 }
 
 // src/utils/thresholds.ts
@@ -26,12 +32,32 @@ function scoreToMode(score) {
 }
 
 // src/library/scorer.ts
-var WEIGHTS = {
-  tfidf: 0.35,
-  nodeFingerprint: 0.3,
-  outcome: 0.2,
-  deploy: 0.15
-};
+function loadWeights() {
+  const raw = {
+    tfidf: parseFloat(process.env["KAIROS_WEIGHT_TFIDF"] ?? ""),
+    nodeFingerprint: parseFloat(process.env["KAIROS_WEIGHT_JACCARD"] ?? ""),
+    outcome: parseFloat(process.env["KAIROS_WEIGHT_OUTCOME"] ?? ""),
+    deploy: parseFloat(process.env["KAIROS_WEIGHT_DEPLOY"] ?? "")
+  };
+  const defaults = { tfidf: 0.35, nodeFingerprint: 0.3, outcome: 0.2, deploy: 0.15 };
+  const anySet = Object.values(raw).some((v) => !isNaN(v) && v >= 0);
+  if (!anySet) return defaults;
+  const w = {
+    tfidf: !isNaN(raw.tfidf) && raw.tfidf >= 0 ? raw.tfidf : defaults.tfidf,
+    nodeFingerprint: !isNaN(raw.nodeFingerprint) && raw.nodeFingerprint >= 0 ? raw.nodeFingerprint : defaults.nodeFingerprint,
+    outcome: !isNaN(raw.outcome) && raw.outcome >= 0 ? raw.outcome : defaults.outcome,
+    deploy: !isNaN(raw.deploy) && raw.deploy >= 0 ? raw.deploy : defaults.deploy
+  };
+  const total = w.tfidf + w.nodeFingerprint + w.outcome + w.deploy;
+  if (total <= 0) return defaults;
+  return {
+    tfidf: w.tfidf / total,
+    nodeFingerprint: w.nodeFingerprint / total,
+    outcome: w.outcome / total,
+    deploy: w.deploy / total
+  };
+}
+var WEIGHTS = loadWeights();
 var NODE_KEYWORDS = {
   slack: ["slack", "slackApi"],
   email: ["gmail", "sendEmail", "emailSend", "emailReadImap"],
@@ -216,6 +242,8 @@ function clusterWorkflows(workflows) {
   }
   return clusters.sort((a, b) => b.members.length - a.members.length);
 }
+var NOVELTY_BOOST = 0.05;
+var NOVELTY_PENALTY = 0.03;
 function rerank(candidates, clusters) {
   const clusterMap = /* @__PURE__ */ new Map();
   for (const cluster of clusters) {
@@ -223,7 +251,7 @@ function rerank(candidates, clusters) {
       clusterMap.set(member.id, cluster);
     }
   }
-  return candidates.map((c) => {
+  const pass1 = candidates.map((c) => {
     const cluster = clusterMap.get(c.workflow.id);
     let boost = 0;
     if (cluster && cluster.avgFirstTryPassRate > 0) {
@@ -235,7 +263,25 @@ function rerank(candidates, clusters) {
     return {
       workflow: c.workflow,
       score: Math.max(0, Math.min(1, c.score + boost)),
-      ...cluster ? { clusterPattern: cluster.pattern } : {}
+      cluster
+    };
+  }).sort((a, b) => b.score - a.score);
+  const seenFingerprints = /* @__PURE__ */ new Set();
+  return pass1.map((c) => {
+    const fpKey = c.cluster ? fingerprintKey(c.cluster.fingerprint) : null;
+    let noveltyAdjust = 0;
+    if (fpKey !== null) {
+      if (!seenFingerprints.has(fpKey)) {
+        seenFingerprints.add(fpKey);
+        noveltyAdjust = NOVELTY_BOOST;
+      } else {
+        noveltyAdjust = -NOVELTY_PENALTY;
+      }
+    }
+    return {
+      workflow: c.workflow,
+      score: Math.max(0, Math.min(1, c.score + noveltyAdjust)),
+      ...c.cluster ? { clusterPattern: c.cluster.pattern } : {}
     };
   }).sort((a, b) => b.score - a.score);
 }
@@ -252,15 +298,33 @@ function buildSearchCorpus(w) {
   });
   return `${w.description} ${w.workflow.name} ${w.tags.join(" ")} ${nodeTokens.join(" ")}`;
 }
-var MAX_LIBRARY_SIZE = 500;
+var _rawSize = parseInt(process.env["KAIROS_LIBRARY_SIZE"] ?? "500", 10);
+var MAX_LIBRARY_SIZE = Number.isFinite(_rawSize) && _rawSize >= 10 ? _rawSize : 500;
+function evictionScore(m) {
+  return (m.deployCount ?? 0) * 3 + (m.timesRetrieved ?? 0) + (m.outcomeStats?.totalUses ?? 0);
+}
+function isValidMeta(item) {
+  return typeof item === "object" && item !== null && typeof item.id === "string" && typeof item.description === "string" && typeof item.workflowName === "string" && Array.isArray(item.cachedNodeTypes);
+}
+function isValidOldEntry(item) {
+  return typeof item === "object" && item !== null && typeof item.id === "string" && typeof item.description === "string" && typeof item.workflow === "object" && item.workflow !== null && Array.isArray(
+    item.workflow.nodes
+  );
+}
 var FileLibrary = class {
   dir;
-  workflows = [];
+  meta = [];
   initPromise = null;
   writeQueue = Promise.resolve();
   constructor(dir) {
     this.dir = dir ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".kairos", "library");
   }
+  get workflowsDir() {
+    return (0, import_node_path.join)(this.dir, "workflows");
+  }
+  workflowFilePath(id) {
+    return (0, import_node_path.join)(this.workflowsDir, `${id}.json`);
+  }
   async initialize() {
     if (!this.initPromise) {
       this.initPromise = this.doInitialize();
@@ -270,60 +334,196 @@ var FileLibrary = class {
   async doInitialize() {
     await (0, import_promises.mkdir)(this.dir, { recursive: true });
     const indexPath = (0, import_node_path.join)(this.dir, "index.json");
+    let workflowsDirExists = false;
     try {
-      const raw = await (0, import_promises.readFile)(indexPath, "utf-8");
-      const parsed = JSON.parse(raw);
-      if (!Array.isArray(parsed)) {
-        this.workflows = [];
-      } else {
-        this.workflows = parsed.filter(
-          (item) => typeof item === "object" && item !== null && typeof item.id === "string" && typeof item.description === "string" && typeof item.workflow === "object" && item.workflow !== null && Array.isArray(item.workflow.nodes)
-        );
+      await (0, import_promises.stat)(this.workflowsDir);
+      workflowsDirExists = true;
+    } catch {
+    }
+    if (workflowsDirExists) {
+      try {
+        const raw = await (0, import_promises.readFile)(indexPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+          this.meta = parsed.filter(isValidMeta);
+        }
+      } catch {
+        this.meta = [];
+      }
+      await this.scanForOrphansAndCleanup();
+    } else {
+      try {
+        const raw = await (0, import_promises.readFile)(indexPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed) && parsed.length > 0 && isValidOldEntry(parsed[0])) {
+          await this.migrateFromMonolithic(parsed.filter(isValidOldEntry));
+          return;
+        }
+      } catch {
+      }
+      this.meta = [];
+      await (0, import_promises.mkdir)(this.workflowsDir, { recursive: true });
+    }
+  }
+  async scanForOrphansAndCleanup() {
+    let entries;
+    try {
+      entries = await (0, import_promises.readdir)(this.workflowsDir);
+    } catch {
+      return;
+    }
+    const indexedIds = new Set(this.meta.map((m) => m.id));
+    const orphanIds = [];
+    for (const filename of entries) {
+      if (filename.endsWith(".tmp")) {
+        await (0, import_promises.unlink)((0, import_node_path.join)(this.workflowsDir, filename)).catch(() => {
+        });
+        continue;
       }
+      if (!filename.endsWith(".json")) continue;
+      const id = filename.slice(0, -5);
+      if (!indexedIds.has(id)) {
+        orphanIds.push(id);
+      }
+    }
+    if (orphanIds.length > 0) {
+      console.warn(`[FileLibrary] Found ${orphanIds.length} orphaned workflow file(s) not in index: ${orphanIds.join(", ")}`);
+    }
+  }
+  /**
+   * One-time transparent migration from v0.4.x monolithic index.json.
+   * Splits each stored workflow into a per-file workflow JSON and a lightweight
+   * meta entry. Rewrites index.json in the new format.
+   */
+  async migrateFromMonolithic(oldEntries) {
+    await (0, import_promises.mkdir)(this.workflowsDir, { recursive: true });
+    const newMeta = [];
+    for (const entry of oldEntries) {
+      const wfPath = this.workflowFilePath(entry.id);
+      const tmpPath = `${wfPath}.tmp`;
+      await (0, import_promises.writeFile)(tmpPath, JSON.stringify(entry.workflow), "utf-8");
+      await (0, import_promises.rename)(tmpPath, wfPath);
+      const { workflow, ...metaFields } = entry;
+      newMeta.push({
+        ...metaFields,
+        workflowName: workflow.name,
+        cachedNodeTypes: workflow.nodes.map((n) => n.type)
+      });
+    }
+    this.meta = newMeta;
+    await this.persistNow();
+  }
+  async loadWorkflowFile(id) {
+    try {
+      const raw = await (0, import_promises.readFile)(this.workflowFilePath(id), "utf-8");
+      return JSON.parse(raw);
     } catch {
-      this.workflows = [];
+      return null;
     }
   }
+  async writeWorkflowFile(id, workflow) {
+    const wfPath = this.workflowFilePath(id);
+    const tmpPath = `${wfPath}.tmp`;
+    await (0, import_promises.writeFile)(tmpPath, JSON.stringify(workflow), "utf-8");
+    await (0, import_promises.rename)(tmpPath, wfPath);
+  }
+  /**
+   * Build a lightweight StoredWorkflow shell from a meta entry for use in
+   * scoring / clustering. Only node.type is populated in each node — no other
+   * node fields are used by hybridScore or clusterWorkflows.
+   */
+  makeSearchShell(m) {
+    return {
+      ...m,
+      workflow: {
+        name: m.workflowName,
+        nodes: m.cachedNodeTypes.map((type) => ({
+          id: "",
+          name: "",
+          type,
+          typeVersion: 1,
+          position: [0, 0],
+          parameters: {}
+        })),
+        connections: {}
+      }
+    };
+  }
   async search(description, options) {
-    const searchable = this.workflows.filter((w) => w.trustLevel !== "blocked");
-    if (searchable.length === 0) return [];
+    const filteredMeta = this.meta.filter((m) => m.trustLevel !== "blocked");
+    if (filteredMeta.length === 0) return [];
     const limit = options?.limit ?? 3;
     const queryTokens = tokenize(description);
     if (queryTokens.length === 0) return [];
-    const docTokenArrays = searchable.map((w) => tokenize(buildSearchCorpus(w)));
+    const shells = filteredMeta.map((m) => this.makeSearchShell(m));
+    const docTokenArrays = shells.map((w) => tokenize(buildSearchCorpus(w)));
     const docTokenSets = docTokenArrays.map((tokens) => new Set(tokens));
-    const docCount = searchable.length;
+    const docCount = shells.length;
     const idf = /* @__PURE__ */ new Map();
+    const idfCeiling = Math.log(docCount + 1) + 1;
     const allTokens = new Set(queryTokens);
     for (const token of allTokens) {
       const docsWithToken = docTokenSets.filter((d) => d.has(token)).length;
-      idf.set(token, Math.log((docCount + 1) / (docsWithToken + 1)) + 1);
+      const rawIdf = Math.log((docCount + 1) / (docsWithToken + 1)) + 1;
+      idf.set(token, rawIdf / idfCeiling);
     }
-    const scored = hybridScore(queryTokens, description, searchable, docTokenArrays, idf).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
-    const clusters = clusterWorkflows(searchable);
+    const scored = hybridScore(queryTokens, description, shells, docTokenArrays, idf).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
+    const clusters = clusterWorkflows(shells);
     const reranked = rerank(scored, clusters).slice(0, limit);
-    const results = reranked.map((m) => {
-      return { workflow: m.workflow, score: m.score, mode: scoreToMode(m.score) };
-    });
-    if (results.length > 0) {
-      for (const r of results) {
-        r.workflow.timesRetrieved = (r.workflow.timesRetrieved ?? 0) + 1;
-      }
-      this.persist();
-    }
-    return results;
+    if (reranked.length === 0) return [];
+    for (const r of reranked) {
+      const m = this.meta.find((m2) => m2.id === r.workflow.id);
+      if (m) m.timesRetrieved = (m.timesRetrieved ?? 0) + 1;
+    }
+    this.persist();
+    const results = await Promise.all(
+      reranked.map(async (r) => {
+        const m = this.meta.find((meta) => meta.id === r.workflow.id);
+        const workflow = await this.loadWorkflowFile(r.workflow.id);
+        if (!workflow) return null;
+        return {
+          workflow: { ...m, workflow },
+          score: r.score,
+          mode: scoreToMode(r.score)
+        };
+      })
+    );
+    return results.filter((r) => r !== null);
   }
   async save(workflow, metadata) {
+    const existingByN8nId = metadata.n8nWorkflowId ? this.meta.find((m) => m.n8nWorkflowId === metadata.n8nWorkflowId) : void 0;
+    const normalizedDesc = metadata.description.trim().toLowerCase();
+    const existing = existingByN8nId ?? this.meta.find((m) => m.description.trim().toLowerCase() === normalizedDesc);
+    if (existing) {
+      existing.description = metadata.description;
+      existing.workflowName = workflow.name;
+      existing.cachedNodeTypes = workflow.nodes.map((n) => n.type);
+      if (metadata.n8nWorkflowId) existing.n8nWorkflowId = metadata.n8nWorkflowId;
+      if (metadata.generationAttempts != null) {
+        existing.generationAttempts = metadata.generationAttempts;
+      }
+      if (metadata.failurePatterns?.length) {
+        existing.failurePatterns = this.deduplicateFailurePatterns(metadata.failurePatterns);
+      }
+      if (metadata.tags?.length) {
+        existing.tags = [.../* @__PURE__ */ new Set([...existing.tags, ...metadata.tags])];
+      }
+      await this.writeWorkflowFile(existing.id, workflow);
+      await this.persist();
+      return existing.id;
+    }
     const id = generateUUID();
+    await this.writeWorkflowFile(id, workflow);
     const failurePatterns = this.deduplicateFailurePatterns(metadata.failurePatterns);
-    const stored = {
+    const meta = {
       id,
-      workflow,
       description: metadata.description,
       tags: metadata.tags ?? [],
       platform: metadata.platform ?? "n8n",
       deployCount: 0,
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      workflowName: workflow.name,
+      cachedNodeTypes: workflow.nodes.map((n) => n.type),
       ...failurePatterns?.length ? { failurePatterns } : {},
       ...metadata.sourceWorkflowIds?.length ? { sourceWorkflowIds: metadata.sourceWorkflowIds } : {},
       ...metadata.generationMode ? { generationMode: metadata.generationMode } : {},
@@ -333,33 +533,39 @@ var FileLibrary = class {
       ...metadata.sourceKind ? { sourceKind: metadata.sourceKind } : {},
       ...metadata.sourceId ? { sourceId: metadata.sourceId } : {},
       ...metadata.sourceUrl ? { sourceUrl: metadata.sourceUrl } : {},
-      ...metadata.trustLevel ? { trustLevel: metadata.trustLevel } : {}
+      ...metadata.trustLevel ? { trustLevel: metadata.trustLevel } : {},
+      ...metadata.n8nWorkflowId ? { n8nWorkflowId: metadata.n8nWorkflowId } : {}
     };
-    this.workflows.push(stored);
-    if (this.workflows.length > MAX_LIBRARY_SIZE) {
-      this.workflows.sort((a, b) => (b.deployCount ?? 1) - (a.deployCount ?? 1));
-      this.workflows = this.workflows.slice(0, MAX_LIBRARY_SIZE);
+    this.meta.push(meta);
+    if (this.meta.length > MAX_LIBRARY_SIZE) {
+      this.meta.sort((a, b) => {
+        if (a.id === id) return -1;
+        if (b.id === id) return 1;
+        return evictionScore(b) - evictionScore(a);
+      });
+      this.meta = this.meta.slice(0, MAX_LIBRARY_SIZE);
     }
     await this.persist();
     return id;
   }
-  async recordDeployment(id) {
-    const w = this.workflows.find((w2) => w2.id === id);
-    if (w) {
-      w.deployCount++;
-      w.lastDeployedAt = (/* @__PURE__ */ new Date()).toISOString();
+  async recordDeployment(id, n8nWorkflowId) {
+    const m = this.meta.find((m2) => m2.id === id);
+    if (m) {
+      m.deployCount++;
+      m.lastDeployedAt = (/* @__PURE__ */ new Date()).toISOString();
+      if (n8nWorkflowId) m.n8nWorkflowId = n8nWorkflowId;
       await this.persist();
     }
   }
   async recordOutcome(id, outcome) {
-    const w = this.workflows.find((w2) => w2.id === id);
-    if (!w) return;
+    const m = this.meta.find((m2) => m2.id === id);
+    if (!m) return;
     if (outcome.mode === "direct") {
-      w.timesUsedAsDirect = (w.timesUsedAsDirect ?? 0) + 1;
+      m.timesUsedAsDirect = (m.timesUsedAsDirect ?? 0) + 1;
     } else {
-      w.timesUsedAsReference = (w.timesUsedAsReference ?? 0) + 1;
+      m.timesUsedAsReference = (m.timesUsedAsReference ?? 0) + 1;
     }
-    const stats = w.outcomeStats ?? { totalUses: 0, totalAttempts: 0, firstTryPasses: 0, failedRules: {} };
+    const stats = m.outcomeStats ?? { totalUses: 0, totalAttempts: 0, firstTryPasses: 0, failedRules: {} };
     stats.totalUses++;
     stats.totalAttempts += outcome.attempts;
     if (outcome.firstTryPass) stats.firstTryPasses++;
@@ -367,24 +573,35 @@ var FileLibrary = class {
       const key = String(rule);
       stats.failedRules[key] = (stats.failedRules[key] ?? 0) + 1;
     }
-    w.outcomeStats = stats;
+    m.outcomeStats = stats;
     await this.persist();
   }
   async drain() {
     await this.writeQueue;
   }
   async get(id) {
-    return this.workflows.find((w) => w.id === id) ?? null;
+    const m = this.meta.find((m2) => m2.id === id);
+    if (!m) return null;
+    const workflow = await this.loadWorkflowFile(id);
+    if (!workflow) return null;
+    return { ...m, workflow };
   }
   async list(filters) {
-    let result = this.workflows;
+    let filtered = this.meta;
     if (filters?.platform) {
-      result = result.filter((w) => w.platform === filters.platform);
+      filtered = filtered.filter((m) => m.platform === filters.platform);
     }
     if (filters?.tags && filters.tags.length > 0) {
-      result = result.filter((w) => filters.tags.some((t) => w.tags.includes(t)));
-    }
-    return result;
+      filtered = filtered.filter((m) => filters.tags.some((t) => m.tags.includes(t)));
+    }
+    const results = await Promise.all(
+      filtered.map(async (m) => {
+        const workflow = await this.loadWorkflowFile(m.id);
+        if (!workflow) return null;
+        return { ...m, workflow };
+      })
+    );
+    return results.filter((r) => r !== null);
   }
   deduplicateFailurePatterns(patterns) {
     if (!patterns?.length) return void 0;
@@ -399,12 +616,98 @@ var FileLibrary = class {
     }
     return [...map.values()];
   }
-  persist() {
-    this.writeQueue = this.writeQueue.then(async () => {
+  // ── Cross-process file locking ────────────────────────────────────────────
+  // Uses O_EXCL (exclusive create) which is atomic on POSIX and Windows NTFS.
+  // Protects the read-modify-write cycle in persist() from concurrent writers
+  // in separate OS processes (e.g. MCP server + CLI running simultaneously).
+  get lockPath() {
+    return (0, import_node_path.join)(this.dir, ".index.lock");
+  }
+  async acquireLock(timeoutMs = 3e3) {
+    const deadline = Date.now() + timeoutMs;
+    let delayMs = 10;
+    while (true) {
+      try {
+        const fh = await (0, import_promises.open)(this.lockPath, "wx");
+        await fh.writeFile(String(process.pid));
+        await fh.close();
+        return async () => {
+          await (0, import_promises.unlink)(this.lockPath).catch(() => {
+          });
+        };
+      } catch {
+        try {
+          const content = await (0, import_promises.readFile)(this.lockPath, "utf-8");
+          const lockPid = parseInt(content.trim(), 10);
+          const fileStat = await (0, import_promises.stat)(this.lockPath);
+          const ageMs = Date.now() - fileStat.mtimeMs;
+          if (ageMs > 1e4) {
+            await (0, import_promises.unlink)(this.lockPath).catch(() => {
+            });
+            continue;
+          }
+          if (!isNaN(lockPid)) {
+            try {
+              process.kill(lockPid, 0);
+            } catch {
+              await (0, import_promises.unlink)(this.lockPath).catch(() => {
+              });
+              continue;
+            }
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() > deadline) {
+          return async () => {
+          };
+        }
+        await new Promise((r) => setTimeout(r, delayMs));
+        delayMs = Math.min(delayMs * 1.5, 200);
+      }
+    }
+  }
+  /**
+   * Direct write used only during migration (before writeQueue is needed).
+   */
+  async persistNow() {
+    const releaseLock = await this.acquireLock();
+    try {
       const indexPath = (0, import_node_path.join)(this.dir, "index.json");
       const tmpPath = `${indexPath}.tmp`;
-      await (0, import_promises.writeFile)(tmpPath, JSON.stringify(this.workflows, null, 2), "utf-8");
+      await (0, import_promises.writeFile)(tmpPath, JSON.stringify(this.meta, null, 2), "utf-8");
       await (0, import_promises.rename)(tmpPath, indexPath);
+    } finally {
+      await releaseLock();
+    }
+  }
+  persist() {
+    this.writeQueue = this.writeQueue.then(async () => {
+      const releaseLock = await this.acquireLock();
+      try {
+        const indexPath = (0, import_node_path.join)(this.dir, "index.json");
+        let onDisk = [];
+        try {
+          const raw = await (0, import_promises.readFile)(indexPath, "utf-8");
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed)) {
+            onDisk = parsed.filter(isValidMeta);
+          }
+        } catch {
+        }
+        const ourIds = new Set(this.meta.map((m) => m.id));
+        const external = onDisk.filter((m) => !ourIds.has(m.id));
+        let merged = [...this.meta, ...external];
+        if (merged.length > MAX_LIBRARY_SIZE) {
+          merged.sort((a, b) => evictionScore(b) - evictionScore(a));
+          merged = merged.slice(0, MAX_LIBRARY_SIZE);
+        }
+        const tmpPath = `${indexPath}.tmp`;
+        await (0, import_promises.writeFile)(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+        await (0, import_promises.rename)(tmpPath, indexPath);
+      } finally {
+        await releaseLock();
+      }
     });
     return this.writeQueue;
   }
@@ -510,6 +813,14 @@ var NodeRegistry = class {
     if (!def) return true;
     return def.safeTypeVersions.includes(version);
   }
+  // Returns true when the version is a positive integer greater than the highest
+  // known safe version — indicates a newer release rather than a bad value.
+  isVersionNewer(type, version) {
+    const def = this.byType.get(type);
+    if (!def || def.safeTypeVersions.length === 0) return false;
+    const max = Math.max(...def.safeTypeVersions);
+    return Number.isInteger(version) && version > max;
+  }
   getRequiredParams(type) {
     return this.byType.get(type)?.requiredParams ?? [];
   }
@@ -577,6 +888,17 @@ var N8nValidator = class {
     this.checkRule21(workflow, issues);
     this.checkRule22(workflow, issues);
     this.checkRule23(workflow, issues);
+    this.checkRule24(workflow, issues);
+    this.checkRule25(workflow, issues);
+    this.checkRule26(workflow, issues);
+    this.checkRule27(workflow, issues);
+    this.checkRule28(workflow, issues);
+    this.checkRule29(workflow, issues);
+    this.checkRule30(workflow, issues);
+    this.checkRule31(workflow, issues);
+    this.checkRule32(workflow, issues);
+    this.checkRule33(workflow, issues);
+    this.checkRule34(workflow, issues);
     if (Array.isArray(workflow.nodes)) {
       const nodeById = new Map(workflow.nodes.map((n) => [n.id, n.type]));
       for (const issue of issues) {
@@ -709,10 +1031,14 @@ var N8nValidator = class {
   checkRule11(w, issues) {
     if (!Array.isArray(w.nodes) || typeof w.connections !== "object" || w.connections === null) return;
     const reachable = /* @__PURE__ */ new Set();
-    for (const [, outputs] of Object.entries(w.connections)) {
+    const aiSubNodeSources = /* @__PURE__ */ new Set();
+    for (const [sourceName, outputs] of Object.entries(w.connections)) {
       if (typeof outputs !== "object" || outputs === null) continue;
-      for (const portGroup of Object.values(outputs)) {
+      let hasAiPort = false;
+      for (const [portName, portGroup] of Object.entries(outputs)) {
         if (!Array.isArray(portGroup)) continue;
+        const isAiPort = portName.startsWith("ai_");
+        if (isAiPort) hasAiPort = true;
         for (const targets of portGroup) {
           if (!Array.isArray(targets)) continue;
           for (const target of targets) {
@@ -721,10 +1047,13 @@ var N8nValidator = class {
           }
         }
       }
+      if (hasAiPort) aiSubNodeSources.add(sourceName);
     }
     for (const node of w.nodes) {
       if (node.type.includes("stickyNote")) continue;
-      if (!this.isTriggerNode(node) && !reachable.has(node.name)) {
+      if (this.isTriggerNode(node)) continue;
+      if (aiSubNodeSources.has(node.name)) continue;
+      if (!reachable.has(node.name)) {
         this.warn(issues, 11, `Node "${node.name}" has no incoming connections and may never execute`, node.id);
       }
     }
@@ -821,19 +1150,22 @@ var N8nValidator = class {
       }
     }
   }
-  // Rule 19 (WARN): typeVersion is within known safe range for registered node types
+  // Rule 19 (WARN): typeVersion is within known safe range for registered node types.
+  // In lenient mode (KAIROS_REGISTRY_STRICT != 'true'), versions higher than the known
+  // max are allowed — they likely represent newer n8n releases Kairos hasn't catalogued yet.
   checkRule19(w, issues) {
     if (!Array.isArray(w.nodes)) return;
+    const strict = process.env["KAIROS_REGISTRY_STRICT"] === "true";
     for (const node of w.nodes) {
       if (typeof node.type !== "string" || typeof node.typeVersion !== "number") continue;
-      if (!this.registry.isVersionSafe(node.type, node.typeVersion)) {
-        this.warn(
-          issues,
-          19,
-          `Node "${node.name}" uses typeVersion ${node.typeVersion} for type "${node.type}" which is not in the known safe list`,
-          node.id
-        );
-      }
+      if (this.registry.isVersionSafe(node.type, node.typeVersion)) continue;
+      if (!strict && this.registry.isVersionNewer(node.type, node.typeVersion)) continue;
+      this.warn(
+        issues,
+        19,
+        `Node "${node.name}" uses typeVersion ${node.typeVersion} for type "${node.type}" which is not in the known safe list`,
+        node.id
+      );
     }
   }
   // Rule 20 (WARN): cycle detection — no node should be reachable from itself
@@ -882,6 +1214,27 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 21 (WARN): webhook with responseMode="responseNode" must have respondToWebhook node
+  checkRule21(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const webhooksNeedingResponse = w.nodes.filter((n) => {
+      if (!n.type.includes("webhook")) return false;
+      const params = n.parameters;
+      return params?.responseMode === "responseNode";
+    });
+    if (webhooksNeedingResponse.length === 0) return;
+    const hasRespondNode = w.nodes.some((n) => n.type.includes("respondToWebhook"));
+    if (!hasRespondNode) {
+      for (const wh of webhooksNeedingResponse) {
+        this.warn(
+          issues,
+          21,
+          `Webhook "${wh.name}" uses responseMode "responseNode" but no respondToWebhook node exists in the workflow`,
+          wh.id
+        );
+      }
+    }
+  }
   // Rule 22 (WARN): check requiredParams from registry
   checkRule22(w, issues) {
     if (!Array.isArray(w.nodes)) return;
@@ -920,23 +1273,232 @@ var N8nValidator = class {
       }
     }
   }
-  // Rule 21 (WARN): webhook with responseMode="responseNode" must have respondToWebhook node
-  checkRule21(w, issues) {
+  // Rule 24 (WARN): deprecated accessor syntax in expressions
+  checkRule24(w, issues) {
     if (!Array.isArray(w.nodes)) return;
-    const webhooksNeedingResponse = w.nodes.filter((n) => {
-      if (!n.type.includes("webhook")) return false;
-      const params = n.parameters;
-      return params?.responseMode === "responseNode";
-    });
-    if (webhooksNeedingResponse.length === 0) return;
-    const hasRespondNode = w.nodes.some((n) => n.type.includes("respondToWebhook"));
-    if (!hasRespondNode) {
-      for (const wh of webhooksNeedingResponse) {
+    const deprecated = /\$node\s*\[/;
+    for (const node of w.nodes) {
+      for (const expr of this.extractExpressions(node.parameters)) {
+        if (deprecated.test(expr)) {
+          this.warn(
+            issues,
+            24,
+            `Node "${node.name}" uses deprecated accessor $node["..."] \u2014 use $('NodeName').item.json.field instead`,
+            node.id
+          );
+          break;
+        }
+      }
+    }
+  }
+  // Rule 25 (WARN): wrong item index assumptions in expressions
+  checkRule25(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const itemIndex = /\$json\s*\.\s*items\s*\[/;
+    for (const node of w.nodes) {
+      for (const expr of this.extractExpressions(node.parameters)) {
+        if (itemIndex.test(expr)) {
+          this.warn(
+            issues,
+            25,
+            `Node "${node.name}" accesses $json.items[n] \u2014 n8n flattens items automatically, use $json.field directly`,
+            node.id
+          );
+          break;
+        }
+      }
+    }
+  }
+  // Rule 26 (WARN): missing .first() or .all() on node references
+  checkRule26(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const bareRef = /\$\(\s*'[^']+'\s*\)\s*\.json/;
+    for (const node of w.nodes) {
+      for (const expr of this.extractExpressions(node.parameters)) {
+        if (bareRef.test(expr)) {
+          this.warn(
+            issues,
+            26,
+            `Node "${node.name}" references $('NodeName').json without .first() or .all() \u2014 use $('NodeName').first().json.field`,
+            node.id
+          );
+          break;
+        }
+      }
+    }
+  }
+  extractExpressions(params) {
+    const expressions = [];
+    const walk = (val) => {
+      if (typeof val === "string") {
+        if (val.includes("={{") || val.includes("$node") || val.includes("$('")) {
+          expressions.push(val);
+        }
+      } else if (Array.isArray(val)) {
+        for (const item of val) walk(item);
+      } else if (val !== null && typeof val === "object") {
+        for (const v of Object.values(val)) walk(v);
+      }
+    };
+    walk(params);
+    return expressions;
+  }
+  // Rule 27 (WARN): httpRequest URL is a placeholder
+  checkRule27(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const PLACEHOLDER_RE = [
+      /^https?:\/\/example\.com/i,
+      /your[-_]?(api[-_]?)?url/i,
+      /^https?:\/\/$/,
+      /^<.+>$/,
+      /placeholder/i
+    ];
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.httpRequest") continue;
+      const params = node.parameters;
+      const url = params?.["url"];
+      if (typeof url !== "string" || url.trim() === "") continue;
+      if (PLACEHOLDER_RE.some((re) => re.test(url.trim()))) {
         this.warn(
           issues,
-          21,
-          `Webhook "${wh.name}" uses responseMode "responseNode" but no respondToWebhook node exists in the workflow`,
-          wh.id
+          27,
+          `Node "${node.name}" httpRequest URL appears to be a placeholder: "${url}" \u2014 replace with your actual endpoint`,
+          node.id
+        );
+      }
+    }
+  }
+  // Rule 28 (WARN): code node with empty or comment-only code
+  checkRule28(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.code") continue;
+      const params = node.parameters;
+      const jsCode = typeof params?.["jsCode"] === "string" ? params["jsCode"] : "";
+      const pythonCode = typeof params?.["pythonCode"] === "string" ? params["pythonCode"] : "";
+      const code = jsCode || pythonCode;
+      const stripped = code.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "").replace(/#[^\n]*/g, "").trim();
+      if (!stripped) {
+        this.warn(issues, 28, `Node "${node.name}" code node has no executable code`, node.id);
+      }
+    }
+  }
+  // Rule 29 (WARN): slack node message operation missing channel
+  checkRule29(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.slack") continue;
+      const params = node.parameters;
+      const resource = params?.["resource"];
+      const operation = params?.["operation"];
+      const isMessageOp = resource === "message" || operation === "sendMessage" || operation === "post";
+      if (!isMessageOp) continue;
+      const channel = params?.["channel"] ?? params?.["channelId"];
+      const rlValue = typeof channel === "object" && channel !== null ? channel["value"] : void 0;
+      const isEmpty = channel === void 0 || channel === null || typeof channel === "string" && channel.trim() === "" || typeof channel === "object" && (!rlValue || typeof rlValue === "string" && rlValue.trim() === "");
+      if (isEmpty) {
+        this.warn(issues, 29, `Node "${node.name}" Slack message has no channel specified`, node.id);
+      }
+    }
+  }
+  // Rule 30 (WARN): gmail node send operation missing recipient
+  checkRule30(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.gmail") continue;
+      const params = node.parameters;
+      const operation = params?.["operation"];
+      if (operation !== "send") continue;
+      const to = params?.["to"] ?? params?.["toList"];
+      const isEmpty = to === void 0 || to === null || typeof to === "string" && to.trim() === "" || Array.isArray(to) && to.length === 0;
+      if (isEmpty) {
+        this.warn(issues, 30, `Node "${node.name}" gmail send has no recipient (to) specified`, node.id);
+      }
+    }
+  }
+  // Rule 31 (WARN): if node with empty conditions
+  checkRule31(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.if") continue;
+      const params = node.parameters;
+      const conditions = params?.["conditions"];
+      if (conditions === void 0 || conditions === null) {
+        this.warn(issues, 31, `Node "${node.name}" if node has no conditions defined`, node.id);
+        continue;
+      }
+      if (typeof conditions === "object" && !Array.isArray(conditions)) {
+        const conds = conditions["conditions"];
+        if (!Array.isArray(conds) || conds.length === 0) {
+          this.warn(issues, 31, `Node "${node.name}" if node conditions array is empty`, node.id);
+        }
+      } else if (Array.isArray(conditions) && conditions.length === 0) {
+        this.warn(issues, 31, `Node "${node.name}" if node conditions array is empty`, node.id);
+      }
+    }
+  }
+  // Rule 32 (WARN): set node with no assignments
+  checkRule32(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.set") continue;
+      const params = node.parameters;
+      const assignmentsObj = params?.["assignments"];
+      const assignmentsArr = assignmentsObj?.["assignments"];
+      const valuesObj = params?.["values"];
+      const hasV1 = valuesObj && Object.values(valuesObj).some((v) => Array.isArray(v) && v.length > 0);
+      const hasV3 = Array.isArray(assignmentsArr) && assignmentsArr.length > 0;
+      if (!hasV1 && !hasV3) {
+        this.warn(
+          issues,
+          32,
+          `Node "${node.name}" set node has no fields defined \u2014 it will pass data through unchanged`,
+          node.id
+        );
+      }
+    }
+  }
+  // Rule 33 (WARN): scheduleTrigger with no schedule rules
+  checkRule33(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.scheduleTrigger") continue;
+      const params = node.parameters;
+      const rule = params?.["rule"];
+      const intervals = rule?.["interval"];
+      if (!Array.isArray(intervals) || intervals.length === 0) {
+        this.warn(issues, 33, `Node "${node.name}" scheduleTrigger has no schedule rules defined`, node.id);
+      }
+    }
+  }
+  // Rule 34 (WARN): webhook path contains spaces, starts with slash, or looks like a full URL
+  checkRule34(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    for (const node of w.nodes) {
+      if (node.type !== "n8n-nodes-base.webhook") continue;
+      const params = node.parameters;
+      const path = params?.["path"];
+      if (typeof path !== "string") continue;
+      if (/\s/.test(path)) {
+        this.warn(
+          issues,
+          34,
+          `Node "${node.name}" webhook path contains spaces: "${path}" \u2014 use hyphens or underscores instead`,
+          node.id
+        );
+      } else if (/^https?:\/\//i.test(path)) {
+        this.warn(
+          issues,
+          34,
+          `Node "${node.name}" webhook path looks like a full URL \u2014 it should be a relative path (e.g. "my-hook")`,
+          node.id
+        );
+      } else if (path.startsWith("/")) {
+        this.warn(
+          issues,
+          34,
+          `Node "${node.name}" webhook path starts with "/" \u2014 n8n adds the leading slash automatically`,
+          node.id
         );
       }
     }
@@ -991,7 +1553,26 @@ var ProviderError = class extends KairosError {
   }
 };
 
+// src/errors/guard-error.ts
+var GuardError = class extends KairosError {
+  constructor(message) {
+    super(message);
+    this.name = "GuardError";
+  }
+};
+
 // src/utils/retry.ts
+function isTransientNetworkError(err) {
+  const TRANSIENT_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "ENOTFOUND", "ECONNABORTED"]);
+  let current = err;
+  for (let i = 0; i < 4; i++) {
+    if (current === null || typeof current !== "object") break;
+    const code = current.code;
+    if (typeof code === "string" && TRANSIENT_CODES.has(code)) return true;
+    current = current.cause;
+  }
+  return false;
+}
 async function withRetry(fn, maxAttempts, delayMs, shouldRetry) {
   let lastError;
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
@@ -1016,6 +1597,7 @@ function fetchWithTimeout(url, init, timeoutMs) {
 
 // src/providers/n8n/api-client.ts
 var EXECUTION_LIMIT_CAP = 100;
+var N8N_API_PAGE_SIZE = 250;
 var REQUEST_TIMEOUT_MS = 3e4;
 var RETRY_ATTEMPTS = 3;
 var RETRY_DELAY_MS = 1e3;
@@ -1024,6 +1606,17 @@ var N8nApiClient = class {
     this.baseUrl = baseUrl;
     this.apiKey = apiKey;
     this.logger = logger;
+    if (!baseUrl || typeof baseUrl !== "string") {
+      throw new GuardError("N8nApiClient: baseUrl must be a non-empty string");
+    }
+    try {
+      new URL(baseUrl);
+    } catch {
+      throw new GuardError(`N8nApiClient: baseUrl is not a valid URL: "${baseUrl}"`);
+    }
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new GuardError("N8nApiClient: apiKey must be a non-empty string");
+    }
   }
   baseUrl;
   apiKey;
@@ -1033,7 +1626,12 @@ var N8nApiClient = class {
     this.logger.debug(`n8n ${method} ${path}`);
     const isSafe = method === "GET";
     if (!isSafe) {
-      return this.singleRequest(url, method, path, body);
+      return withRetry(
+        () => this.singleRequest(url, method, path, body),
+        2,
+        RETRY_DELAY_MS,
+        isTransientNetworkError
+      );
     }
     return withRetry(
       () => this.singleRequest(url, method, path, body),
@@ -1088,7 +1686,7 @@ var N8nApiClient = class {
   }
   async listWorkflows() {
     const all = [];
-    let path = "/workflows?limit=250";
+    let path = `/workflows?limit=${N8N_API_PAGE_SIZE}`;
     for (; ; ) {
       const response = await this.request("GET", path);
       for (const w of response.data) {
@@ -1102,7 +1700,7 @@ var N8nApiClient = class {
         });
       }
       if (!response.nextCursor) break;
-      path = `/workflows?limit=250&cursor=${response.nextCursor}`;
+      path = `/workflows?limit=${N8N_API_PAGE_SIZE}&cursor=${response.nextCursor}`;
     }
     return all;
   }
@@ -1132,14 +1730,14 @@ var N8nApiClient = class {
   }
   async listTags() {
     const all = [];
-    let path = "/tags?limit=250";
+    let path = `/tags?limit=${N8N_API_PAGE_SIZE}`;
     for (; ; ) {
       const response = await this.request("GET", path);
       for (const t of response.data) {
         all.push({ id: t.id, name: t.name });
       }
       if (!response.nextCursor) break;
-      path = `/tags?limit=250&cursor=${response.nextCursor}`;
+      path = `/tags?limit=${N8N_API_PAGE_SIZE}&cursor=${response.nextCursor}`;
     }
     return all;
   }
@@ -1163,6 +1761,32 @@ var N8nApiClient = class {
       return [];
     }
   }
+  async triggerManual(workflowId) {
+    const raw = await this.request("POST", `/workflows/${workflowId}/run`);
+    const inner = raw["data"];
+    const execId = inner?.["executionId"] ?? raw["executionId"];
+    if (execId === void 0 || execId === null) {
+      throw new ProviderError(
+        `n8n trigger response missing executionId \u2014 got: ${JSON.stringify(raw)}`
+      );
+    }
+    return String(execId);
+  }
+  async triggerWebhookTest(path) {
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const url = `${this.baseUrl.replace(/\/$/, "")}/webhook-test${cleanPath}`;
+    this.logger.debug(`n8n POST webhook-test ${cleanPath}`);
+    try {
+      const response = await fetchWithTimeout(
+        url,
+        { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) },
+        REQUEST_TIMEOUT_MS
+      );
+      return response.status;
+    } catch (err) {
+      throw new ProviderError(`Webhook test request failed for path "${path}"`, err);
+    }
+  }
   mapExecution(e) {
     return {
       id: e.id,
@@ -1209,9 +1833,11 @@ id, active, createdAt, updatedAt, versionId, meta, isArchived, activeVersionId,
 - Never reuse IDs, never use sequential fake IDs like "node-1"
 
 ### Credentials:
-- Only reference credentials with exact type names (see catalog below)
-- If credential ID is unknown, OMIT the credentials block entirely \u2014 never invent credential IDs
-- Never put API keys or tokens in parameters when a credential type exists
+- Each credential is keyed by its type string, with an object value containing id and name:
+  "credentials": { "slackOAuth2Api": { "id": "placeholder-id", "name": "My Slack Credential" } }
+- Use "placeholder-id" as the id \u2014 users replace this with their real credential ID from n8n after deployment
+- The credentialsNeeded field in your response declares what credentials the user must configure
+- Never put API keys or tokens directly in node parameters when a credential type exists
 
 ### Node names:
 - All node names must be unique within the workflow
@@ -1258,6 +1884,23 @@ Node parameters like conditions, assignments, and rule intervals MUST include al
 
 ---
 
+## EXPRESSION SYNTAX \u2014 how to reference upstream node data
+
+### Accessing a field from an upstream node:
+- CORRECT:   $('NodeName').item.json.field
+- WRONG:     $node["NodeName"].json.field   \u2190 deprecated accessor, fails at runtime (Rule 24)
+
+### Accessing array items from $json:
+- CORRECT:   $json.field                    \u2190 n8n auto-flattens items; each item is already a flat object
+- WRONG:     $json.items[0].field           \u2190 do not index into items[] (Rule 25)
+
+### Calling node data \u2014 always qualify with .first() or .all():
+- CORRECT:   $('NodeName').first().json.field   \u2190 single item
+- CORRECT:   $('NodeName').all()                \u2190 array of all items
+- WRONG:     $('NodeName').json                 \u2190 throws at runtime without .first() or .all() (Rule 26)
+
+---
+
 ## NODE CATALOG \u2014 exact type strings and safe typeVersions
 
 ### Triggers (always at least one required):
@@ -1357,6 +2000,17 @@ Cron: { "rule": { "interval": [{ "field": "cronExpression", "expression": "0 9 *
 5. At least one trigger node present
 6. Every AI Agent has an ai_languageModel sub-node
 7. settings block is complete with executionOrder: "v1"
+8. No deprecated $node["NodeName"].json \u2014 use $('NodeName').item.json.field
+9. No $json.items[0] array indexing \u2014 access fields directly as $json.field
+10. No bare $('NodeName').json \u2014 always use .first().json.field or .all()
+11. httpRequest URL is a real endpoint (not "example.com" or "YOUR_URL")
+12. code nodes contain actual logic \u2014 not empty or comment-only
+13. Slack message nodes have a channel specified (channelId or channel)
+14. Gmail send nodes have a recipient (to field non-empty)
+15. if nodes have at least one condition in conditions.conditions[]
+16. set nodes have at least one entry in assignments.assignments[]
+17. scheduleTrigger has at least one rule in rule.interval[]
+18. webhook path is relative (no spaces, no leading slash, no http://)
 
 ---
 
@@ -1364,7 +2018,7 @@ Respond ONLY with a generate_workflow tool call. No prose. No markdown outside t
 If the request is impossible or unclear, set the error field instead of generating a workflow.`;
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 23 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -1388,7 +2042,68 @@ var RULE_PIPELINE_STAGES = {
   20: "connection_wiring",
   21: "workflow_structure",
   22: "workflow_structure",
-  23: "node_generation"
+  23: "node_generation",
+  24: "expression_syntax",
+  25: "expression_syntax",
+  26: "expression_syntax",
+  27: "node_generation",
+  28: "node_generation",
+  29: "node_generation",
+  30: "node_generation",
+  31: "node_generation",
+  32: "node_generation",
+  33: "node_generation",
+  34: "node_generation"
+};
+var RULE_EXAMPLES = {
+  17: {
+    bad: '"credentials": { "slackOAuth2Api": "my-token" }',
+    good: '"credentials": { "slackOAuth2Api": { "id": "placeholder-id", "name": "My Slack OAuth" } }'
+  },
+  24: {
+    bad: '$node["Fetch Data"].json.email',
+    good: "$('Fetch Data').item.json.email"
+  },
+  25: {
+    bad: "$json.items[0].email",
+    good: "$json.email"
+  },
+  26: {
+    bad: "$('Fetch Data').json.email",
+    good: "$('Fetch Data').first().json.email"
+  },
+  27: {
+    bad: '"url": "https://example.com/api/data"',
+    good: '"url": "https://api.yourservice.com/v1/endpoint"'
+  },
+  28: {
+    bad: '"jsCode": "// TODO: implement this"',
+    good: '"jsCode": "return items.map(item => ({ json: { result: item.json.value * 2 } }))"'
+  },
+  29: {
+    bad: '"channelId": ""',
+    good: '"channelId": { "__rl": true, "value": "C0123456789", "mode": "id" }'
+  },
+  30: {
+    bad: '"operation": "send", "to": ""',
+    good: '"operation": "send", "to": "recipient@example.com"'
+  },
+  31: {
+    bad: '"conditions": { "combinator": "and", "conditions": [] }',
+    good: '"conditions": { "combinator": "and", "conditions": [{ "leftValue": "={{ $json.status }}", "rightValue": "active", "operator": { "type": "string", "operation": "equals" } }] }'
+  },
+  32: {
+    bad: '"assignments": { "assignments": [] }',
+    good: '"assignments": { "assignments": [{ "id": "f1", "name": "status", "value": "processed", "type": "string" }] }'
+  },
+  33: {
+    bad: '"rule": { "interval": [] }',
+    good: '"rule": { "interval": [{ "field": "cronExpression", "expression": "0 9 * * 1-5" }] }'
+  },
+  34: {
+    bad: '"path": "/my webhook"',
+    good: '"path": "my-webhook"'
+  }
 };
 var RULE_MITIGATIONS = {
   1: "Provide a non-empty workflow name string",
@@ -1407,36 +2122,86 @@ var RULE_MITIGATIONS = {
   14: "Include at least one trigger node (e.g. scheduleTrigger, webhookTrigger, manualTrigger, or service-specific)",
   15: 'Node type strings must be fully qualified: "n8n-nodes-base.httpRequest" not just "httpRequest"',
   16: "All node names must be unique within the workflow",
-  17: 'Credentials must be an object with non-empty string id and name fields: { id: "placeholder-id", name: "My Credential" }',
+  17: 'Each credential entry must be keyed by credential type with an object value: { "slackOAuth2Api": { "id": "placeholder-id", "name": "My Credential" } } \u2014 the key is the credential type, the value has id and name strings',
   18: "AI sub-nodes (languageModel, memory, tool) must be the CONNECTION SOURCE pointing TO the agent \u2014 not the reverse",
   19: "Use known safe typeVersion values for each node type",
   20: "Remove connection cycles \u2014 ensure no node can reach itself through the connection graph",
   21: 'When using webhook with responseMode "responseNode", include a respondToWebhook node in the flow',
   22: "Ensure all required parameters are set for each node type (e.g. webhook needs httpMethod and path)",
-  23: "Use node types that exist in the n8n registry \u2014 check with kairos_sync"
+  23: "Use node types that exist in the n8n registry \u2014 check with kairos_sync",
+  24: 'Use modern accessor syntax: $("NodeName").item.json.field instead of deprecated $node["NodeName"].json.field',
+  25: "Access item fields directly with $json.field \u2014 n8n flattens items automatically, do not use $json.items[0]",
+  26: 'Use $("NodeName").first().json.field or $("NodeName").all() \u2014 bare $("NodeName").json without .first() or .all() throws at runtime',
+  27: 'Replace placeholder URLs with your actual API endpoint \u2014 do not use "example.com" or "YOUR_URL" patterns',
+  28: "Add executable code to the code node \u2014 empty or comment-only code nodes do nothing at runtime",
+  29: "Set the channel parameter for Slack message operations (channelId with __rl object, or channel as string)",
+  30: "Set the to parameter for Gmail send operations with at least one recipient email address",
+  31: "Add at least one condition to the if node \u2014 conditions.conditions array must be non-empty",
+  32: "Add field assignments to the set node \u2014 assignments.assignments array must be non-empty for typeVersion 3.x",
+  33: "Add at least one schedule rule to scheduleTrigger \u2014 rule.interval array must have at least one entry",
+  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")'
 };
 
 // src/generation/prompt-builder.ts
 var CRITICAL_SCORE_THRESHOLD = 0.15;
+function resolveProfile() {
+  const env = process.env["KAIROS_PROMPT_PROFILE"];
+  if (env === "minimal" || env === "standard" || env === "rich") return env;
+  return "standard";
+}
+var PROACTIVE_EXPRESSION_GUIDANCE = `## Expression Syntax Quick Reference
+
+Always use these patterns in expressions:
+- Access node data:  $('NodeName').item.json.field  (not $node["NodeName"].json)
+- Access JSON field: $json.field  (not $json.items[0].field)
+- Single item:       $('NodeName').first().json.field
+- All items:         $('NodeName').all()`;
 var PromptBuilder = class {
   patternsPath;
-  constructor(patternsPath) {
+  profile;
+  _lastActivePatterns = null;
+  constructor(patternsPath, profile) {
     this.patternsPath = patternsPath ?? (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".kairos", "patterns.json");
+    this.profile = profile ?? resolveProfile();
+  }
+  resolveMaxPatterns() {
+    if (this.profile === "minimal") return 3;
+    if (this.profile === "rich") return 15;
+    return 10;
   }
   build(request, matches, globalFailureRates = [], dynamicCatalog) {
     const mode = this.resolveMode(matches);
-    const system = this.buildSystem(matches, mode, globalFailureRates, dynamicCatalog);
+    const system = this.buildSystem(matches, mode, globalFailureRates, dynamicCatalog, request.description);
     const userMessage = this.buildUserMessage(request, matches, mode);
     return { system, userMessage, mode, matches };
   }
-  buildCorrectionMessage(request, matches, allIssues, attempt) {
+  buildCorrectionMessage(request, matches, allIssues, attempt, failingRuleIds) {
     const base = this.buildUserMessage(request, matches, this.resolveMode(matches));
+    let examplesSection = "";
+    if (failingRuleIds && failingRuleIds.length > 0) {
+      const uniqueRules = [...new Set(failingRuleIds)];
+      const exampleLines = [];
+      for (const rule of uniqueRules) {
+        const ex = RULE_EXAMPLES[rule];
+        if (ex) {
+          exampleLines.push(`Rule ${rule}:
+  Bad:  ${ex.bad}
+  Good: ${ex.good}`);
+        }
+      }
+      if (exampleLines.length > 0) {
+        examplesSection = `
+
+## Concrete Fix Examples
+${exampleLines.join("\n\n")}`;
+      }
+    }
     return `${base}
 
 IMPORTANT: A previous generation attempt (attempt ${attempt}) failed validation with these issues:
 ${allIssues.join("\n")}
 
-Fix ALL of the above issues in your new response. Do not repeat any of these mistakes.`;
+Fix ALL of the above issues in your new response. Do not repeat any of these mistakes.${examplesSection}`;
   }
   resolveMode(matches) {
     if (matches.length === 0) return "scratch";
@@ -1444,7 +2209,7 @@ Fix ALL of the above issues in your new response. Do not repeat any of these mis
     if (!top) return "scratch";
     return scoreToMode(top.score);
   }
-  buildSystem(matches, mode, globalFailureRates = [], dynamicCatalog) {
+  buildSystem(matches, mode, globalFailureRates = [], dynamicCatalog, description) {
     let basePrompt = SYSTEM_PROMPT_V1;
     if (dynamicCatalog) {
       basePrompt = basePrompt.replace(
@@ -1459,53 +2224,62 @@ Fix ALL of the above issues in your new response. Do not repeat any of these mis
         cache_control: { type: "ephemeral" }
       }
     ];
-    if (mode === "reference" && matches.length > 0) {
-      const refText = matches.slice(0, 3).map((m) => {
-        const nodes = m.workflow.workflow.nodes.map((n) => `  - ${n.name} (${n.type} v${n.typeVersion})`).join("\n");
-        return `Reference workflow: "${m.workflow.description}" (similarity: ${m.score.toFixed(2)})
+    if (this.profile !== "minimal") {
+      if (mode === "reference" && matches.length > 0) {
+        const refText = matches.slice(0, 3).map((m) => {
+          const nodes = m.workflow.workflow.nodes.map((n) => `  - ${n.name} (${n.type} v${n.typeVersion})`).join("\n");
+          return `Reference workflow: "${m.workflow.description}" (similarity: ${m.score.toFixed(2)})
 Nodes:
 ${nodes}`;
-      }).join("\n\n");
-      blocks.push({
-        type: "text",
-        text: `## Similar Workflows From Library (for reference only \u2014 adapt, do not copy verbatim)
-
-${refText}`
-      });
-    }
-    if (mode === "direct" && matches[0]) {
-      const match = matches[0];
-      const json = JSON.stringify(match.workflow.workflow, null, 2);
-      if (json.length > 3e4) {
-        const nodes = match.workflow.workflow.nodes.map((n) => `  - ${n.name} (${n.type} v${n.typeVersion})`).join("\n");
+        }).join("\n\n");
         blocks.push({
           type: "text",
-          text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 too large for full JSON, using reference:
+          text: `## Similar Workflows From Library (for reference only \u2014 adapt, do not copy verbatim)
+
+${refText}`
+        });
+      }
+      if (mode === "direct" && matches[0]) {
+        const match = matches[0];
+        const json = JSON.stringify(match.workflow.workflow, null, 2);
+        if (json.length > 3e4) {
+          const nodes = match.workflow.workflow.nodes.map((n) => `  - ${n.name} (${n.type} v${n.typeVersion})`).join("\n");
+          blocks.push({
+            type: "text",
+            text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 too large for full JSON, using reference:
 Nodes:
 ${nodes}`
-        });
-      } else {
-        blocks.push({
-          type: "text",
-          text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 adapt this structure:
+          });
+        } else {
+          blocks.push({
+            type: "text",
+            text: `## Closely Matched Workflow (score: ${match.score.toFixed(2)}) \u2014 adapt this structure:
 
 ${json}`
-        });
+          });
+        }
       }
-    }
-    if (mode === "scratch" && matches.length > 0 && matches[0].score >= 0.4) {
-      const hint = matches[0];
-      const nodeTypes = hint.workflow.workflow.nodes.map((n) => n.type.split(".").pop()).join(", ");
-      blocks.push({
-        type: "text",
-        text: `## Weak Structural Hint
+      if (mode === "scratch" && matches.length > 0 && matches[0].score >= 0.4) {
+        const hint = matches[0];
+        const nodeTypes = hint.workflow.workflow.nodes.map((n) => n.type.split(".").pop()).join(", ");
+        blocks.push({
+          type: "text",
+          text: `## Weak Structural Hint
 A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node types: ${nodeTypes}`
-      });
+        });
+      }
     }
-    const warnings = this.buildFailureWarnings(matches, globalFailureRates);
+    const warnings = this.buildFailureWarnings(matches, globalFailureRates, description);
     if (warnings) {
       blocks.push({ type: "text", text: warnings });
     }
+    if (this.profile === "rich") {
+      const expressionRules = /* @__PURE__ */ new Set([24, 25, 26]);
+      const expressionAlreadyCovered = (this._lastActivePatterns ?? []).some((p) => expressionRules.has(p.rule));
+      if (!expressionAlreadyCovered) {
+        blocks.push({ type: "text", text: PROACTIVE_EXPRESSION_GUIDANCE });
+      }
+    }
     return blocks;
   }
   loadPatterns() {
@@ -1519,18 +2293,38 @@ A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node typ
     }
   }
   getWarnedRules() {
-    return this.getActivePatterns().map((p) => p.rule);
+    const patterns = this._lastActivePatterns ?? this.getActivePatterns(this.resolveMaxPatterns());
+    return patterns.map((p) => p.rule);
   }
-  getActivePatterns() {
-    const MAX_WARNED = 10;
+  getActivePatterns(maxCount = 10, description) {
     const all = this.loadPatterns().filter((p) => p.state !== "resolved" && p.confidence > 0);
     const regressed = all.filter((p) => p.regressed).sort((a, b) => b.compositeScore - a.compositeScore);
     const confirmed = all.filter((p) => !p.regressed && p.state === "confirmed").sort((a, b) => b.compositeScore - a.compositeScore);
     const drafts = all.filter((p) => !p.regressed && p.state !== "confirmed").sort((a, b) => b.compositeScore - a.compositeScore);
-    return [...regressed, ...confirmed, ...drafts].slice(0, MAX_WARNED);
-  }
-  buildFailureWarnings(matches, globalFailureRates) {
-    const richPatterns = this.getActivePatterns();
+    const ordered = [...regressed, ...confirmed, ...drafts];
+    if (this.profile === "minimal" && description) {
+      return this.rankByRelevance(ordered, description).slice(0, maxCount);
+    }
+    return ordered.slice(0, maxCount);
+  }
+  rankByRelevance(patterns, description) {
+    const lower = description.toLowerCase();
+    const STAGE_KEYWORDS = {
+      credential_injection: ["credential", "auth", "api key", "token", "oauth", "smtp", "imap", "password", "secret"],
+      connection_wiring: ["connect", "link", "wire", "chain", "merge", "branch", "join"],
+      expression_syntax: ["expression", "variable", "json", "field", "data", "$json", "item"],
+      workflow_structure: ["trigger", "webhook", "schedule", "structure", "workflow"],
+      node_generation: ["node", "generate", "create", "build", "send", "fetch", "email", "slack", "http"]
+    };
+    return patterns.map((p) => {
+      const keywords = STAGE_KEYWORDS[p.pipelineStage] ?? [];
+      const relevanceBoost = keywords.some((kw) => lower.includes(kw)) ? 1 : 0;
+      return { pattern: p, sort: relevanceBoost * 10 + p.compositeScore };
+    }).sort((a, b) => b.sort - a.sort).map((x) => x.pattern);
+  }
+  buildFailureWarnings(matches, globalFailureRates, description) {
+    const richPatterns = this.getActivePatterns(this.resolveMaxPatterns(), description);
+    this._lastActivePatterns = richPatterns;
     if (richPatterns.length > 0) {
       return this.buildStageGroupedWarnings(richPatterns, matches);
     }
@@ -1541,7 +2335,8 @@ A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node typ
       credential_injection: "CREDENTIAL FORMATTING",
       connection_wiring: "CONNECTION WIRING",
       node_generation: "NODE GENERATION",
-      workflow_structure: "WORKFLOW STRUCTURE"
+      workflow_structure: "WORKFLOW STRUCTURE",
+      expression_syntax: "EXPRESSION SYNTAX"
     };
     const byStage = /* @__PURE__ */ new Map();
     for (const p of patterns) {
@@ -1569,7 +2364,11 @@ A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node typ
           const remedy = p.mitigation ?? RULE_MITIGATIONS[p.rule];
           const remedyStr = remedy ? `
   Fix: ${remedy}` : "";
-          lines.push(`- ${urgency}${statePrefix}Rule ${p.rule}${trendSuffix}: ${p.exampleMessages[0] ?? "No example"}${remedyStr}`);
+          const ex = RULE_EXAMPLES[p.rule];
+          const exampleStr = ex ? `
+  Bad:  ${ex.bad}
+  Good: ${ex.good}` : "";
+          lines.push(`- ${urgency}${statePrefix}Rule ${p.rule}${trendSuffix}: ${p.exampleMessages[0] ?? "No example"}${remedyStr}${exampleStr}`);
         } else {
           const ruleNums = group.map((p) => p.rule).join(", ");
           const totalFailures = group.reduce((s, p) => s + p.failureCount, 0);
@@ -1691,19 +2490,20 @@ var TelemetryReader = class {
     }
     const events = await this.readRecentEvents(days);
     const buildSessions = new Set(
-      events.filter((e) => e.eventType === "build_complete").map((e) => e.sessionId)
+      events.filter((e) => e.eventType === "build_complete").map((e) => e.runId ?? e.sessionId)
     );
     const MIN_BUILDS_FOR_RATES = 3;
     if (buildSessions.size < MIN_BUILDS_FOR_RATES) return [];
     const ruleSessions = /* @__PURE__ */ new Map();
     for (const event of events) {
       if (event.eventType !== "generation_attempt") continue;
-      if (!buildSessions.has(event.sessionId)) continue;
+      const eventKey = event.runId ?? event.sessionId;
+      if (!buildSessions.has(eventKey)) continue;
       const data = event.data;
       if (data.validationPassed || !data.issues) continue;
       for (const issue of data.issues) {
         const entry = ruleSessions.get(issue.rule) ?? { sessions: /* @__PURE__ */ new Set(), messages: /* @__PURE__ */ new Map() };
-        entry.sessions.add(event.sessionId);
+        entry.sessions.add(eventKey);
         entry.messages.set(issue.message, (entry.messages.get(issue.message) ?? 0) + 1);
         ruleSessions.set(issue.rule, entry);
       }
@@ -1744,22 +2544,25 @@ var PATTERN_SCHEMA_VERSION = 2;
 var PatternAnalyzer = class _PatternAnalyzer {
   telemetryDir;
   outputDir;
+  _cachedEvents = null;
+  _cachedPreviousPatterns = null;
   constructor(telemetryDir) {
     const defaultDir = (0, import_node_path5.join)((0, import_node_os4.homedir)(), ".kairos", "telemetry");
     this.telemetryDir = telemetryDir ?? defaultDir;
     this.outputDir = telemetryDir ? (0, import_node_path5.join)(telemetryDir, "..") : (0, import_node_path5.join)((0, import_node_os4.homedir)(), ".kairos");
   }
   async loadPreviousPatterns() {
+    if (this._cachedPreviousPatterns !== null) return this._cachedPreviousPatterns;
     try {
       const raw = await (0, import_promises3.readFile)((0, import_node_path5.join)(this.outputDir, "patterns.json"), "utf-8");
       const prev = JSON.parse(raw);
       const version = prev.schemaVersion ?? 0;
       const patterns = prev.topFailureRules ?? [];
-      if (version === PATTERN_SCHEMA_VERSION) return patterns;
-      return this.migratePatterns(patterns, version);
+      this._cachedPreviousPatterns = version === PATTERN_SCHEMA_VERSION ? patterns : this.migratePatterns(patterns, version);
     } catch {
-      return [];
+      this._cachedPreviousPatterns = [];
     }
+    return this._cachedPreviousPatterns;
   }
   migratePatterns(patterns, fromVersion) {
     let migrated = patterns;
@@ -1772,19 +2575,23 @@ var PatternAnalyzer = class _PatternAnalyzer {
       }));
     }
     if (fromVersion < 2) {
-      migrated = migrated.map((p) => ({
-        ...p,
-        scoringFactors: {
-          ...p.scoringFactors,
-          stickinessBoost: p.scoringFactors.stickinessBoost ?? p.scoringFactors["validationBoost"] ?? 0
-        }
-      }));
+      migrated = migrated.map((p) => {
+        const sf = p.scoringFactors ?? { rawConfidence: 0, impact: 0, recency: 0, stickinessBoost: 0 };
+        return {
+          ...p,
+          scoringFactors: {
+            ...sf,
+            stickinessBoost: sf.stickinessBoost ?? sf["validationBoost"] ?? 0
+          }
+        };
+      });
     }
     return migrated;
   }
   async analyze(days = 30) {
     const previousPatterns = await this.loadPreviousPatterns();
     const events = await this.readAllEvents(days);
+    this._cachedEvents = events;
     const starts = events.filter((e) => e.eventType === "build_start");
     const attempts = events.filter((e) => e.eventType === "generation_attempt");
     const passed = attempts.filter(
@@ -1797,13 +2604,18 @@ var PatternAnalyzer = class _PatternAnalyzer {
     const credentialFailures = /* @__PURE__ */ new Map();
     for (const a of failed) {
       const weight = this.recencyWeight(a.fileDate);
+      const buildId = a.runId ?? a.sessionId;
       const data = a.data;
       for (const issue of data.issues ?? []) {
-        const entry = ruleFailures.get(issue.rule) ?? { count: 0, sessions: /* @__PURE__ */ new Set(), recencyWeights: [], allMessages: [] };
+        if (issue.severity === "warn") continue;
+        const entry = ruleFailures.get(issue.rule) ?? { count: 0, sessions: /* @__PURE__ */ new Set(), recencyWeights: [], allMessages: [], workflowTypes: /* @__PURE__ */ new Map() };
         entry.count++;
-        entry.sessions.add(a.sessionId);
+        entry.sessions.add(buildId);
         entry.recencyWeights.push(weight);
         entry.allMessages.push(issue.message);
+        if (data.workflowType) {
+          entry.workflowTypes.set(data.workflowType, (entry.workflowTypes.get(data.workflowType) ?? 0) + 1);
+        }
         ruleFailures.set(issue.rule, entry);
         if (issue.rule === 17) {
           const credPatterns = [
@@ -1856,9 +2668,10 @@ var PatternAnalyzer = class _PatternAnalyzer {
     }
     const sessions = /* @__PURE__ */ new Map();
     for (const a of attempts) {
-      const list = sessions.get(a.sessionId) ?? [];
+      const buildId = a.runId ?? a.sessionId;
+      const list = sessions.get(buildId) ?? [];
       list.push(a);
-      sessions.set(a.sessionId, list);
+      sessions.set(buildId, list);
     }
     let firstTryPass = 0;
     let correctionNeeded = 0;
@@ -1905,7 +2718,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
       const avgRecency = entry.recencyWeights.length > 0 ? entry.recencyWeights.reduce((s, w) => s + w, 0) / entry.recencyWeights.length : 1;
       const stickiness = stickinessCount.get(rule) ?? 0;
       const { compositeScore, factors } = this.computeCompositeScore(rawConfidence, entry.count, state, avgRecency, stickiness);
-      return {
+      const pattern = {
         rule,
         failureCount: entry.count,
         confidence: Math.round(rawConfidence * 1e3) / 1e3,
@@ -1917,6 +2730,10 @@ var PatternAnalyzer = class _PatternAnalyzer {
         exampleMessages: this.deduplicateMessages(entry.allMessages),
         mitigation: RULE_MITIGATIONS[rule] ?? null
       };
+      if (entry.workflowTypes.size > 0) {
+        pattern.workflowTypeBreakdown = Object.fromEntries(entry.workflowTypes);
+      }
+      return pattern;
     }).sort((a, b) => b.compositeScore - a.compositeScore);
     const activeRules = new Set(activePatterns.map((p) => p.rule));
     for (const p of activePatterns) {
@@ -1973,7 +2790,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
       const warned = bcData.warnedRules ?? [];
       if (warned.length === 0) continue;
       const sessionFailedRules = /* @__PURE__ */ new Set();
-      const sessionAttempts = sessions.get(bc.sessionId) ?? [];
+      const sessionAttempts = sessions.get(bc.runId ?? bc.sessionId) ?? [];
       for (const a of sessionAttempts) {
         const ad = a.data;
         if (ad.validationPassed === false) {
@@ -2045,6 +2862,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
     const tmpPath = `${outputPath}.tmp`;
     await (0, import_promises3.writeFile)(tmpPath, JSON.stringify(analysis, null, 2), "utf-8");
     await (0, import_promises3.rename)(tmpPath, outputPath);
+    this._cachedPreviousPatterns = null;
     const historySummary = {
       timestamp: analysis.generatedAt,
       totalBuilds: analysis.summary.totalBuilds,
@@ -2056,8 +2874,55 @@ var PatternAnalyzer = class _PatternAnalyzer {
     };
     const historyPath = (0, import_node_path5.join)(this.outputDir, "pattern-history.jsonl");
     await (0, import_promises3.appendFile)(historyPath, JSON.stringify(historySummary) + "\n", "utf-8");
+    const sessions = await this.buildSessionSummaries(days);
+    const sessionHistoryPath = (0, import_node_path5.join)(this.outputDir, "session-history.json");
+    const sessionHistoryTmp = `${sessionHistoryPath}.tmp`;
+    await (0, import_promises3.writeFile)(sessionHistoryTmp, JSON.stringify(sessions, null, 2), "utf-8");
+    await (0, import_promises3.rename)(sessionHistoryTmp, sessionHistoryPath);
     return analysis;
   }
+  async getSessions(limit = 20) {
+    try {
+      const raw = await (0, import_promises3.readFile)((0, import_node_path5.join)(this.outputDir, "session-history.json"), "utf-8");
+      const all = JSON.parse(raw);
+      return all.slice(-limit);
+    } catch {
+      return [];
+    }
+  }
+  async buildSessionSummaries(days = 30) {
+    const events = this._cachedEvents ?? await this.readAllEvents(days);
+    const buildCompletes = events.filter((e) => e.eventType === "build_complete");
+    const attemptsByBuild = /* @__PURE__ */ new Map();
+    for (const e of events.filter((e2) => e2.eventType === "generation_attempt")) {
+      const buildId = e.runId ?? e.sessionId;
+      const list = attemptsByBuild.get(buildId) ?? [];
+      list.push(e);
+      attemptsByBuild.set(buildId, list);
+    }
+    const summaries = buildCompletes.map((bc) => {
+      const data = bc.data;
+      const sessionAttempts = attemptsByBuild.get(bc.runId ?? bc.sessionId) ?? [];
+      const failedRules = Array.from(new Set(
+        sessionAttempts.flatMap((a) => {
+          const ad = a.data;
+          if (ad.validationPassed !== false) return [];
+          return (ad.issues ?? []).map((i) => i.rule);
+        })
+      ));
+      return {
+        sessionId: bc.runId ?? bc.sessionId,
+        date: bc.fileDate,
+        description: data.description ?? "",
+        workflowType: data.workflowType ?? null,
+        attempts: data.totalAttempts ?? 1,
+        success: data.success ?? false,
+        failedRules,
+        workflowName: data.workflowName ?? null
+      };
+    });
+    return summaries.sort((a, b) => a.date.localeCompare(b.date));
+  }
   async getHistory(limit = 20) {
     try {
       const raw = await (0, import_promises3.readFile)((0, import_node_path5.join)(this.outputDir, "pattern-history.jsonl"), "utf-8");
@@ -2079,7 +2944,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
         alerts.push({
           type: "stale_pattern",
           rule: p.rule,
-          message: `Pattern references Rule ${p.rule} which does not exist in the current validator (rules 1-23)`
+          message: `Pattern references Rule ${p.rule} which does not exist in the current validator (rules 1-34)`
         });
       }
     }
@@ -2211,6 +3076,43 @@ ${regularLines}`;
   }
 };
 
+// src/telemetry/collector.ts
+var import_promises4 = require("fs/promises");
+var import_node_path6 = require("path");
+var import_node_os5 = require("os");
+
+// src/telemetry/types.ts
+var TELEMETRY_SCHEMA_VERSION = 2;
+
+// src/telemetry/collector.ts
+var TelemetryCollector = class {
+  dir;
+  sessionId;
+  dirReady = null;
+  constructor(dir) {
+    this.dir = dir ?? (0, import_node_path6.join)((0, import_node_os5.homedir)(), ".kairos", "telemetry");
+    this.sessionId = generateUUID();
+  }
+  async emit(eventType, data, runId) {
+    const event = {
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: this.sessionId,
+      ...runId ? { runId } : {},
+      eventType,
+      data
+    };
+    if (!this.dirReady) {
+      this.dirReady = (0, import_promises4.mkdir)(this.dir, { recursive: true }).then(() => {
+      });
+    }
+    await this.dirReady;
+    const filename = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) + ".jsonl";
+    const filepath = (0, import_node_path6.join)(this.dir, filename);
+    await (0, import_promises4.appendFile)(filepath, JSON.stringify(event) + "\n", "utf-8");
+  }
+};
+
 // src/utils/logger.ts
 var nullLogger = {
   debug() {
@@ -2223,19 +3125,95 @@ var nullLogger = {
   }
 };
 
+// src/utils/workflow-type.ts
+var TYPE_KEYWORDS = [
+  ["gmail", "email"],
+  ["imap", "email"],
+  ["smtp", "email"],
+  [" email", "email"],
+  ["slack", "slack"],
+  ["telegram", "messaging"],
+  ["discord", "messaging"],
+  [" sms", "messaging"],
+  ["twilio", "messaging"],
+  ["webhook", "webhook"],
+  ["google sheets", "data"],
+  ["spreadsheet", "data"],
+  ["airtable", "data"],
+  ["notion", "data"],
+  ["github", "devops"],
+  ["gitlab", "devops"],
+  ["schedule", "schedule"],
+  [" cron", "schedule"],
+  ["daily", "schedule"],
+  ["weekly", "schedule"],
+  ["hourly", "schedule"],
+  ["every day", "schedule"],
+  ["every hour", "schedule"],
+  ["every morning", "schedule"],
+  ["postgres", "database"],
+  ["mysql", "database"],
+  ["supabase", "database"],
+  ["redis", "database"],
+  [" database", "database"],
+  [" llm", "ai"],
+  [" gpt", "ai"],
+  ["claude", "ai"],
+  [" agent", "ai"],
+  ["langchain", "ai"],
+  [" ai ", "ai"],
+  [" ai", "ai"],
+  ["http request", "api"],
+  ["rest api", "api"],
+  [" api", "api"]
+];
+function inferWorkflowType(description) {
+  const lower = " " + description.toLowerCase();
+  for (const [keyword, type] of TYPE_KEYWORDS) {
+    if (lower.includes(keyword)) return type;
+  }
+  return null;
+}
+
 // src/mcp-server.ts
 var import_node_fs3 = require("fs");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
+var import_node_os6 = require("os");
 var import_node_url = require("url");
 var import_meta = {};
-var __dirname = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
-var pkg = JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path6.join)(__dirname, "..", "package.json"), "utf-8"));
+var __dirname = (0, import_node_path7.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+var pkg = JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path7.join)(__dirname, "..", "package.json"), "utf-8"));
 var library = new FileLibrary();
-var validator = new N8nValidator();
+var _validator = new N8nValidator();
+function getValidator() {
+  return _validator;
+}
 var nodeSyncer = new NodeSyncer();
 var lastSync = null;
+var AUTO_SYNC_TIMEOUT_MS = 5e3;
 var stripper = new N8nFieldStripper();
-var promptBuilder = new PromptBuilder();
+var promptBuilder = new PromptBuilder(getMcpPatternsPath());
+function getMcpTelemetry() {
+  const val = process.env["KAIROS_TELEMETRY"];
+  if (!val || val === "false") return null;
+  return val === "true" ? new TelemetryCollector() : new TelemetryCollector(val);
+}
+function getMcpPatternsPath() {
+  const val = process.env["KAIROS_TELEMETRY"];
+  if (val && val !== "false" && val !== "true") {
+    return (0, import_node_path7.join)(val, "..", "patterns.json");
+  }
+  return (0, import_node_path7.join)((0, import_node_os6.homedir)(), ".kairos", "patterns.json");
+}
+var mcpTelemetry = getMcpTelemetry();
+var mcpSessions = /* @__PURE__ */ new Map();
+var SESSION_TTL_MS = 60 * 60 * 1e3;
+function evictStaleSessions() {
+  const cutoff = Date.now() - SESSION_TTL_MS;
+  for (const [id, session] of mcpSessions) {
+    if (session.startTime < cutoff) mcpSessions.delete(id);
+  }
+}
 function getTelemetryReader() {
   try {
     return new TelemetryReader();
@@ -2247,11 +3225,23 @@ function isAllowed(action) {
   const key = `KAIROS_MCP_ALLOW_${action.toUpperCase()}`;
   return process.env[key] === "true";
 }
+function mcpText(text) {
+  return { content: [{ type: "text", text }] };
+}
+function mcpError(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function checkMcpAuth(provided) {
+  const expected = process.env["KAIROS_MCP_SECRET"];
+  if (!expected) return null;
+  if (provided === expected) return null;
+  return mcpError(JSON.stringify({ error: "Unauthorized: missing or incorrect kairos_secret" }));
+}
 function getApiClient() {
   const baseUrl = process.env["N8N_BASE_URL"];
   const apiKey = process.env["N8N_API_KEY"];
   if (!baseUrl || !apiKey) {
-    throw new Error("N8N_BASE_URL and N8N_API_KEY environment variables are required for n8n operations");
+    throw new GuardError("N8N_BASE_URL and N8N_API_KEY environment variables are required for n8n operations");
   }
   return new N8nApiClient(baseUrl, apiKey, nullLogger);
 }
@@ -2265,7 +3255,7 @@ async function autoSync() {
     const nodeTypes = await client.getNodeTypes();
     if (nodeTypes.length === 0) return null;
     lastSync = nodeSyncer.sync(nodeTypes);
-    validator = new N8nValidator(lastSync.registry);
+    _validator = new N8nValidator(lastSync.registry);
     return lastSync;
   } catch {
     return null;
@@ -2283,103 +3273,110 @@ server.tool(
     name: import_zod.z.string().optional().describe("Optional workflow name override")
   },
   async ({ description, name }) => {
+    evictStaleSessions();
     const baseUrl = process.env["N8N_BASE_URL"];
     const apiKey = process.env["N8N_API_KEY"];
     if (!baseUrl || !apiKey) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required. Kairos needs to sync your n8n instance's node types to generate accurate workflows." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required. Kairos needs to sync your n8n instance's node types to generate accurate workflows." }));
     }
+    const runId = generateUUID();
+    const workflowType = inferWorkflowType(description);
+    const syncPromise = autoSync();
+    const syncTimeout = new Promise((resolve) => setTimeout(() => resolve(null), AUTO_SYNC_TIMEOUT_MS));
     await library.initialize();
-    const syncResult = await autoSync();
-    const matches = await library.search(description);
-    const telemetryReader = getTelemetryReader();
-    const failureRates = await telemetryReader?.getFailureRates() ?? [];
+    const [syncResult, matches, failureRates] = await Promise.all([
+      Promise.race([syncPromise, syncTimeout]),
+      library.search(description),
+      (async () => {
+        const reader = getTelemetryReader();
+        return reader ? reader.getFailureRates() : [];
+      })()
+    ]);
     const request = { description, ...name ? { name } : {} };
     const built = promptBuilder.build(request, matches, failureRates, syncResult?.catalogText);
+    if (mcpTelemetry) {
+      mcpSessions.set(runId, {
+        description,
+        startTime: Date.now(),
+        validateAttempts: 0,
+        warnedRules: promptBuilder.getWarnedRules(),
+        workflowType
+      });
+      await mcpTelemetry.emit("build_start", { description, model: "mcp-decomposed", dryRun: false }, runId);
+    }
     const systemText = built.system.map((block) => block.text).join("\n\n---\n\n");
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          mode: built.mode,
-          matchCount: matches.length,
-          topMatchScore: matches[0]?.score ?? null,
-          nodeCatalog: syncResult ? "synced" : "static",
-          nodeCount: syncResult?.nodeCount ?? null,
-          ...syncResult ? {} : { syncWarning: "Could not sync node types from your n8n instance. Using static fallback catalog \u2014 generated workflows may not match your exact n8n setup." },
-          systemPrompt: systemText,
-          userMessage: built.userMessage,
-          outputFormat: {
-            description: "Generate a JSON object with this exact structure. The workflow field contains the n8n workflow. credentialsNeeded lists services requiring credentials.",
-            schema: {
-              workflow: {
-                name: "string \u2014 descriptive workflow name",
-                nodes: "array \u2014 n8n node objects with id (UUID v4), type, typeVersion, name, position, parameters",
-                connections: "object \u2014 keyed by source node NAME, maps to target nodes",
-                settings: 'object \u2014 include executionOrder: "v1"'
-              },
-              credentialsNeeded: [{
-                service: 'string \u2014 e.g. "Slack"',
-                credentialType: 'string \u2014 e.g. "slackOAuth2Api"',
-                description: "string \u2014 what the user needs to set up"
-              }]
-            }
-          }
-        }, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify({
+      kairos_run_id: runId,
+      mode: built.mode,
+      matchCount: matches.length,
+      topMatchScore: matches[0]?.score ?? null,
+      nodeCatalog: syncResult ? "synced" : "static",
+      nodeCount: syncResult?.nodeCount ?? null,
+      ...syncResult ? {} : { syncWarning: "Could not sync node types from your n8n instance. Using static fallback catalog \u2014 generated workflows may not match your exact n8n setup." },
+      systemPrompt: systemText,
+      userMessage: built.userMessage,
+      outputFormat: {
+        description: "Generate a JSON object with this exact structure. The workflow field contains the n8n workflow. credentialsNeeded lists services requiring credentials.",
+        schema: {
+          workflow: {
+            name: "string \u2014 descriptive workflow name",
+            nodes: "array \u2014 n8n node objects with id (UUID v4), type, typeVersion, name, position, parameters",
+            connections: "object \u2014 keyed by source node NAME, maps to target nodes",
+            settings: 'object \u2014 include executionOrder: "v1"'
+          },
+          credentialsNeeded: [{
+            service: 'string \u2014 e.g. "Slack"',
+            credentialType: 'string \u2014 e.g. "slackOAuth2Api"',
+            description: "string \u2014 what the user needs to set up"
+          }]
+        }
+      }
+    }, null, 2));
   }
 );
 server.tool(
   "kairos_validate",
-  "Validate n8n workflow JSON against 23 structural rules. Returns pass/fail with specific issues. If validation fails, fix the issues and call this again. Errors block deployment; warnings are advisory.",
+  "Validate n8n workflow JSON against 34 structural rules. Returns pass/fail with specific issues. If validation fails, fix the issues and call this again. Errors block deployment; warnings are advisory.",
   {
-    workflow: import_zod.z.string().describe("The workflow JSON string to validate")
+    workflow: import_zod.z.string().describe("The workflow JSON string to validate"),
+    kairos_run_id: import_zod.z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation")
   },
-  async ({ workflow: workflowStr }) => {
+  async ({ workflow: workflowStr, kairos_run_id }) => {
     let parsed;
     try {
       parsed = JSON.parse(workflowStr);
     } catch (e) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            valid: false,
-            error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`
-          }, null, 2)
-        }]
-      };
+      return mcpText(JSON.stringify({ valid: false, error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }, null, 2));
     }
-    const result = validator.validate(parsed);
+    const result = getValidator().validate(parsed);
     const errors = result.issues.filter((i) => i.severity === "error");
     const warnings = result.issues.filter((i) => i.severity === "warn");
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          valid: result.valid,
-          errorCount: errors.length,
-          warningCount: warnings.length,
-          errors: errors.map((i) => ({
-            rule: i.rule,
-            message: i.message,
-            nodeId: i.nodeId ?? null
-          })),
-          warnings: warnings.map((i) => ({
-            rule: i.rule,
-            message: i.message,
-            nodeId: i.nodeId ?? null
-          })),
-          deployable: errors.length === 0
-        }, null, 2)
-      }]
-    };
+    if (mcpTelemetry && kairos_run_id) {
+      const session = mcpSessions.get(kairos_run_id);
+      if (session) {
+        session.validateAttempts++;
+        await mcpTelemetry.emit("generation_attempt", {
+          description: session.description,
+          attempt: session.validateAttempts,
+          temperature: 0,
+          durationMs: 0,
+          tokensInput: 0,
+          tokensOutput: 0,
+          validationPassed: result.valid,
+          issueCount: result.issues.length,
+          issues: result.issues.map((i) => ({ rule: i.rule, severity: i.severity, message: i.message, nodeId: i.nodeId ?? null })),
+          workflowType: session.workflowType
+        }, kairos_run_id);
+      }
+    }
+    return mcpText(JSON.stringify({
+      valid: result.valid,
+      errorCount: errors.length,
+      warningCount: warnings.length,
+      errors: errors.map((i) => ({ rule: i.rule, message: i.message, nodeId: i.nodeId ?? null })),
+      warnings: warnings.map((i) => ({ rule: i.rule, message: i.message, nodeId: i.nodeId ?? null })),
+      deployable: errors.length === 0
+    }, null, 2));
   }
 );
 server.tool(
@@ -2387,79 +3384,147 @@ server.tool(
   "Deploy a validated workflow to n8n. Pass the workflow JSON that passed kairos_validate. Strips server-assigned fields automatically. Requires N8N_BASE_URL and N8N_API_KEY.",
   {
     workflow: import_zod.z.string().describe("The validated workflow JSON string to deploy"),
-    activate: import_zod.z.boolean().default(false).describe("Activate the workflow immediately after deployment")
+    activate: import_zod.z.boolean().default(false).describe("Activate the workflow immediately after deployment"),
+    kairos_run_id: import_zod.z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
+    kairos_secret: import_zod.z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow: workflowStr, activate }) => {
+  async ({ workflow: workflowStr, activate, kairos_run_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
     if (!isAllowed("deploy")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Deploy is disabled. Set KAIROS_MCP_ALLOW_DEPLOY=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Deploy is disabled. Set KAIROS_MCP_ALLOW_DEPLOY=true to enable." }));
     }
     let parsed;
     try {
       parsed = JSON.parse(workflowStr);
     } catch (e) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` })
-        }]
-      };
+      return mcpError(JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }));
     }
-    const validation = validator.validate(parsed);
+    const validation = getValidator().validate(parsed);
     const errors = validation.issues.filter((i) => i.severity === "error");
     if (errors.length > 0) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            error: "Workflow has validation errors \u2014 fix them before deploying",
-            errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
-          }, null, 2)
-        }]
-      };
+      return mcpError(JSON.stringify({
+        error: "Workflow has validation errors \u2014 fix them before deploying",
+        errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
+      }, null, 2));
     }
     const client = getApiClient();
     const stripped = stripper.stripForCreate(parsed);
     const response = await client.createWorkflow(stripped);
     if (activate) {
       if (!isAllowed("activate")) {
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              workflowId: response.id,
-              name: response.name,
-              activated: false,
-              warning: "Workflow deployed but activation is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable.",
-              url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
-            }, null, 2)
-          }]
-        };
+        return mcpText(JSON.stringify({
+          workflowId: response.id,
+          name: response.name,
+          activated: false,
+          warning: "Workflow deployed but activation is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable.",
+          url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+        }, null, 2));
       }
       await client.activateWorkflow(response.id);
     }
+    const session = kairos_run_id ? mcpSessions.get(kairos_run_id) : void 0;
+    const missingSessionWarning = kairos_run_id && !session ? `
+
+Note: kairos_run_id "${kairos_run_id}" was provided but no active session was found. This usually means kairos_deploy was called without a prior kairos_prompt call, or the session expired. Telemetry and pattern learning for this build were skipped.` : "";
     await library.initialize();
     await library.save(parsed, {
-      description: parsed.name,
+      description: session?.description ?? parsed.name,
       generationMode: "scratch",
-      generationAttempts: 1
+      generationAttempts: session?.validateAttempts ?? 1,
+      n8nWorkflowId: response.id
     });
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          workflowId: response.id,
-          name: response.name,
-          activated: activate,
-          url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
-        }, null, 2)
-      }]
-    };
+    if (mcpTelemetry && kairos_run_id && session) {
+      await mcpTelemetry.emit("build_complete", {
+        description: session.description,
+        success: true,
+        totalAttempts: session.validateAttempts,
+        totalDurationMs: Date.now() - session.startTime,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+        workflowName: response.name,
+        workflowId: response.id,
+        dryRun: false,
+        credentialsNeeded: 0,
+        warnedRules: session.warnedRules,
+        workflowType: session.workflowType
+      }, kairos_run_id);
+      mcpSessions.delete(kairos_run_id);
+      PatternAnalyzer.fromEnv().analyzeAndSave().catch(() => {
+      });
+    }
+    return mcpText(JSON.stringify({
+      workflowId: response.id,
+      name: response.name,
+      activated: activate,
+      url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+    }, null, 2) + missingSessionWarning);
+  }
+);
+server.tool(
+  "kairos_replace",
+  "Replace an existing n8n workflow with a new version. Validates before updating. Use kairos_prompt \u2192 kairos_validate \u2192 kairos_replace for iteration on existing workflows.",
+  {
+    workflow_id: import_zod.z.string().describe("The n8n workflow ID to replace"),
+    workflow: import_zod.z.string().describe("The validated workflow JSON string"),
+    kairos_run_id: import_zod.z.string().optional().describe("Run ID from kairos_prompt \u2014 enables telemetry correlation"),
+    kairos_secret: import_zod.z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
+  },
+  async ({ workflow_id, workflow: workflowStr, kairos_run_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
+    let parsed;
+    try {
+      parsed = JSON.parse(workflowStr);
+    } catch (e) {
+      return mcpError(JSON.stringify({ error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` }));
+    }
+    const validation = getValidator().validate(parsed);
+    const errors = validation.issues.filter((i) => i.severity === "error");
+    if (errors.length > 0) {
+      return mcpError(JSON.stringify({
+        error: "Workflow has validation errors \u2014 fix them before replacing",
+        errors: errors.map((i) => ({ rule: i.rule, message: i.message }))
+      }, null, 2));
+    }
+    const client = getApiClient();
+    const stripped = stripper.stripForUpdate(parsed);
+    const response = await client.updateWorkflow(workflow_id, stripped);
+    const session = kairos_run_id ? mcpSessions.get(kairos_run_id) : void 0;
+    const missingSessionWarning = kairos_run_id && !session ? `
+
+Note: kairos_run_id "${kairos_run_id}" was provided but no active session was found.` : "";
+    await library.initialize();
+    await library.save(parsed, {
+      description: session?.description ?? parsed.name,
+      generationMode: "scratch",
+      generationAttempts: session?.validateAttempts ?? 1,
+      n8nWorkflowId: workflow_id
+    });
+    if (mcpTelemetry && kairos_run_id && session) {
+      await mcpTelemetry.emit("build_complete", {
+        description: session.description,
+        success: true,
+        totalAttempts: session.validateAttempts,
+        totalDurationMs: Date.now() - session.startTime,
+        totalTokensInput: 0,
+        totalTokensOutput: 0,
+        workflowName: response.name,
+        workflowId: response.id,
+        dryRun: false,
+        credentialsNeeded: 0,
+        warnedRules: session.warnedRules,
+        workflowType: session.workflowType
+      }, kairos_run_id);
+      mcpSessions.delete(kairos_run_id);
+      PatternAnalyzer.fromEnv().analyzeAndSave().catch(() => {
+      });
+    }
+    return mcpText(JSON.stringify({
+      workflowId: response.id,
+      name: response.name,
+      url: `${process.env["N8N_BASE_URL"]}/workflow/${response.id}`
+    }, null, 2) + missingSessionWarning);
   }
 );
 server.tool(
@@ -2472,23 +3537,20 @@ server.tool(
   async ({ query, limit }) => {
     await library.initialize();
     const matches = await library.search(query);
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(
-          matches.slice(0, limit).map((m) => ({
-            score: Number(m.score.toFixed(3)),
-            mode: m.mode,
-            description: m.workflow.description,
-            nodeCount: m.workflow.workflow.nodes.length,
-            nodes: m.workflow.workflow.nodes.map((n) => n.name),
-            failurePatterns: m.workflow.failurePatterns ?? []
-          })),
-          null,
-          2
-        )
-      }]
-    };
+    return mcpText(JSON.stringify(
+      matches.slice(0, limit).map((m) => ({
+        id: m.workflow.id,
+        score: Number(m.score.toFixed(3)),
+        mode: m.mode,
+        description: m.workflow.description,
+        nodeCount: m.workflow.workflow.nodes.length,
+        nodes: m.workflow.workflow.nodes.map((n) => n.name),
+        n8nWorkflowId: m.workflow.n8nWorkflowId ?? null,
+        failurePatterns: m.workflow.failurePatterns ?? []
+      })),
+      null,
+      2
+    ));
   }
 );
 server.tool(
@@ -2499,36 +3561,19 @@ server.tool(
     const baseUrl = process.env["N8N_BASE_URL"];
     const apiKey = process.env["N8N_API_KEY"];
     if (!baseUrl || !apiKey) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required for sync." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "N8N_BASE_URL and N8N_API_KEY are required for sync." }));
     }
     lastSync = null;
     const result = await autoSync();
     if (!result) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Failed to fetch node types from n8n. Check your credentials and that your instance is running." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Failed to fetch node types from n8n. Check your credentials and that your instance is running." }));
     }
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          synced: true,
-          nodeCount: result.nodeCount,
-          newNodes: result.newNodes,
-          message: `Synced ${result.nodeCount} node types from your n8n instance (${result.newNodes} not in default catalog).`
-        }, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify({
+      synced: true,
+      nodeCount: result.nodeCount,
+      newNodes: result.newNodes,
+      message: `Synced ${result.nodeCount} node types from your n8n instance (${result.newNodes} not in default catalog).`
+    }, null, 2));
   }
 );
 server.tool(
@@ -2544,12 +3589,72 @@ server.tool(
     if (limit !== void 0 && limit > 0) {
       analysis.topFailureRules = analysis.topFailureRules.slice(0, limit);
     }
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(analysis, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(analysis, null, 2));
+  }
+);
+server.tool(
+  "kairos_library",
+  "Browse the local Kairos workflow library. Returns saved workflow metadata. Use the optional query to search, or omit it to list all entries.",
+  {
+    query: import_zod.z.string().optional().describe("Optional search query \u2014 omit to list all entries"),
+    limit: import_zod.z.number().default(20).describe("Maximum entries to return")
+  },
+  async ({ query, limit }) => {
+    await library.initialize();
+    if (query) {
+      const matches = await library.search(query);
+      return mcpText(JSON.stringify(
+        matches.slice(0, limit).map((m) => ({
+          id: m.workflow.id,
+          description: m.workflow.description,
+          score: Number(m.score.toFixed(3)),
+          mode: m.mode,
+          nodeCount: m.workflow.workflow.nodes.length,
+          nodes: m.workflow.workflow.nodes.map((n) => n.name),
+          deployCount: m.workflow.deployCount,
+          n8nWorkflowId: m.workflow.n8nWorkflowId ?? null,
+          createdAt: m.workflow.createdAt
+        })),
+        null,
+        2
+      ));
+    }
+    const all = await library.list();
+    return mcpText(JSON.stringify(
+      all.slice(0, limit).map((w) => ({
+        id: w.id,
+        description: w.description,
+        nodeCount: w.workflow.nodes.length,
+        nodes: w.workflow.nodes.map((n) => n.name),
+        deployCount: w.deployCount,
+        n8nWorkflowId: w.n8nWorkflowId ?? null,
+        timesRetrieved: w.timesRetrieved ?? 0,
+        createdAt: w.createdAt
+      })),
+      null,
+      2
+    ));
+  }
+);
+server.tool(
+  "kairos_outcome",
+  "Record the outcome of a workflow build against a library entry. Trains the pattern learning system to know what works and what fails over time.",
+  {
+    library_id: import_zod.z.string().describe("The Kairos library entry ID (returned by kairos_deploy, kairos_replace, or kairos_library)"),
+    attempts: import_zod.z.number().describe("Number of generation+validation attempts before success"),
+    first_try_pass: import_zod.z.boolean().describe("Whether the first attempt passed validation"),
+    failed_rules: import_zod.z.array(import_zod.z.number()).describe("Validation rule IDs that failed during generation"),
+    mode: import_zod.z.enum(["direct", "reference"]).describe("How the library entry was used during generation")
+  },
+  async ({ library_id, attempts, first_try_pass, failed_rules, mode }) => {
+    await library.initialize();
+    await library.recordOutcome(library_id, {
+      attempts,
+      firstTryPass: first_try_pass,
+      failedRules: failed_rules,
+      mode
+    });
+    return mcpText(JSON.stringify({ recorded: true, libraryId: library_id }));
   }
 );
 server.tool(
@@ -2559,12 +3664,7 @@ server.tool(
   async () => {
     const client = getApiClient();
     const workflows = await client.listWorkflows();
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(workflows, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(workflows, null, 2));
   }
 );
 server.tool(
@@ -2576,12 +3676,7 @@ server.tool(
   async ({ workflow_id }) => {
     const client = getApiClient();
     const workflow = await client.getWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(workflow, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(workflow, null, 2));
   }
 );
 server.tool(
@@ -2592,22 +3687,11 @@ server.tool(
   },
   async ({ workflow_id }) => {
     if (!isAllowed("activate")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Activate is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Activate is disabled. Set KAIROS_MCP_ALLOW_ACTIVATE=true to enable." }));
     }
     const client = getApiClient();
     await client.activateWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Activated workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Activated workflow ${workflow_id}`);
   }
 );
 server.tool(
@@ -2619,38 +3703,25 @@ server.tool(
   async ({ workflow_id }) => {
     const client = getApiClient();
     await client.deactivateWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Deactivated workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Deactivated workflow ${workflow_id}`);
   }
 );
 server.tool(
   "kairos_delete",
   "Delete a workflow from n8n. This is irreversible.",
   {
-    workflow_id: import_zod.z.string().describe("The n8n workflow ID to delete")
+    workflow_id: import_zod.z.string().describe("The n8n workflow ID to delete"),
+    kairos_secret: import_zod.z.string().optional().describe("Required when KAIROS_MCP_SECRET env var is set")
   },
-  async ({ workflow_id }) => {
+  async ({ workflow_id, kairos_secret }) => {
+    const authError = checkMcpAuth(kairos_secret);
+    if (authError) return authError;
     if (!isAllowed("delete")) {
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ error: "Delete is disabled. Set KAIROS_MCP_ALLOW_DELETE=true to enable." })
-        }],
-        isError: true
-      };
+      return mcpError(JSON.stringify({ error: "Delete is disabled. Set KAIROS_MCP_ALLOW_DELETE=true to enable." }));
     }
     const client = getApiClient();
     await client.deleteWorkflow(workflow_id);
-    return {
-      content: [{
-        type: "text",
-        text: `Deleted workflow ${workflow_id}`
-      }]
-    };
+    return mcpText(`Deleted workflow ${workflow_id}`);
   }
 );
 server.tool(
@@ -2663,15 +3734,15 @@ server.tool(
   async ({ workflow_id, limit }) => {
     const client = getApiClient();
     const executions = await client.getExecutions(workflow_id, { limit });
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify(executions, null, 2)
-      }]
-    };
+    return mcpText(JSON.stringify(executions, null, 2));
   }
 );
 async function main() {
+  if (!process.env["ANTHROPIC_API_KEY"]) {
+    process.stderr.write(
+      "[kairos-mcp] WARNING: ANTHROPIC_API_KEY is not set \u2014 kairos_prompt will fail. Set it before using workflow generation tools.\n"
+    );
+  }
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
 }