@kairos-sdk/core 0.4.5 → 0.5.0

package/dist/cli.cjs

@@ -28,7 +28,13 @@ var import_sdk = __toESM(require("@anthropic-ai/sdk"), 1);
 
 // 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/library/null-library.ts
@@ -84,7 +90,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++) {
@@ -109,6 +134,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;
@@ -117,6 +143,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;
@@ -126,7 +163,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),
@@ -181,7 +223,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) {
@@ -195,7 +237,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;
   }
@@ -225,14 +267,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;
   }
@@ -256,6 +298,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,
@@ -303,15 +371,9 @@ var N8nFieldStripper = class {
   }
 };
 
-// src/errors/guard-error.ts
-var GuardError = class extends KairosError {
-  constructor(message) {
-    super(message);
-    this.name = "GuardError";
-  }
-};
-
 // src/providers/n8n/provider.ts
+var SMOKE_TEST_TIMEOUT_MS = 3e4;
+var SMOKE_TEST_POLL_INTERVAL_MS = 1e3;
 var N8nProvider = class {
   constructor(client, stripper) {
     this.client = client;
@@ -373,6 +435,71 @@ var N8nProvider = class {
   async untag(workflowId, tagIds) {
     await this.client.untagWorkflow(workflowId, tagIds);
   }
+  async smokeTest(workflowId, workflow) {
+    const start = Date.now();
+    const trigger = this.detectTrigger(workflow);
+    if (trigger.type === "unsupported") {
+      return { status: "not-applicable", triggerType: "not-applicable" };
+    }
+    if (trigger.type === "manual") {
+      let executionId;
+      try {
+        executionId = await this.client.triggerManual(workflowId);
+      } catch (err) {
+        return { status: "error", triggerType: "manual", durationMs: Date.now() - start, error: String(err) };
+      }
+      try {
+        const execution = await this.pollExecution(executionId);
+        const durationMs = Date.now() - start;
+        if (execution.status === "success") {
+          return { status: "passed", triggerType: "manual", executionId, durationMs };
+        }
+        return {
+          status: "failed",
+          triggerType: "manual",
+          executionId,
+          durationMs,
+          error: `Execution ended with status: ${execution.status}`
+        };
+      } catch (err) {
+        return { status: "error", triggerType: "manual", executionId, durationMs: Date.now() - start, error: String(err) };
+      }
+    }
+    try {
+      const statusCode = await this.client.triggerWebhookTest(trigger.path);
+      const durationMs = Date.now() - start;
+      if (statusCode >= 200 && statusCode < 300) {
+        return { status: "passed", triggerType: "webhook", durationMs };
+      }
+      return { status: "failed", triggerType: "webhook", durationMs, error: `Webhook returned HTTP ${statusCode}` };
+    } catch (err) {
+      return { status: "error", triggerType: "webhook", durationMs: Date.now() - start, error: String(err) };
+    }
+  }
+  detectTrigger(workflow) {
+    for (const node of workflow.nodes) {
+      if (node.type === "n8n-nodes-base.manualTrigger") return { type: "manual" };
+      if (node.type === "n8n-nodes-base.webhook") {
+        const params = node.parameters;
+        const path = typeof params?.["path"] === "string" ? params["path"] : "webhook";
+        return { type: "webhook", path };
+      }
+    }
+    return { type: "unsupported" };
+  }
+  async pollExecution(executionId) {
+    const deadline = Date.now() + SMOKE_TEST_TIMEOUT_MS;
+    for (; ; ) {
+      const execution = await this.client.getExecution(executionId);
+      if (execution.status !== "running" && execution.status !== "waiting") {
+        return execution;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(SMOKE_TEST_POLL_INTERVAL_MS, remaining)));
+    }
+    throw new ProviderError(`Smoke test: execution ${executionId} did not complete within ${SMOKE_TEST_TIMEOUT_MS}ms`);
+  }
 };
 
 // src/validation/registry.ts
@@ -475,6 +602,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 ?? [];
   }
@@ -527,6 +662,14 @@ var N8nValidator = class {
     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) {
@@ -778,19 +921,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
@@ -839,6 +985,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;
@@ -947,23 +1114,162 @@ var N8nValidator = class {
     walk(params);
     return expressions;
   }
-  // Rule 21 (WARN): webhook with responseMode="responseNode" must have respondToWebhook node
-  checkRule21(w, issues) {
+  // Rule 27 (WARN): httpRequest URL is a placeholder
+  checkRule27(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 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
         );
       }
     }
@@ -1204,6 +1510,14 @@ Cron: { "rule": { "interval": [{ "field": "cronExpression", "expression": "0 9 *
 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://)
 
 ---
 
@@ -1220,7 +1534,7 @@ function scoreToMode(score) {
 }
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 26 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -1247,7 +1561,15 @@ var RULE_PIPELINE_STAGES = {
   23: "node_generation",
   24: "expression_syntax",
   25: "expression_syntax",
-  26: "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: {
@@ -1265,6 +1587,38 @@ var RULE_EXAMPLES = {
   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 = {
@@ -1293,7 +1647,15 @@ var RULE_MITIGATIONS = {
   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'
+  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
@@ -1325,18 +1687,37 @@ var PromptBuilder = class {
   }
   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";
@@ -1344,7 +1725,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(
@@ -1404,7 +1785,7 @@ A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node typ
         });
       }
     }
-    const warnings = this.buildFailureWarnings(matches, globalFailureRates);
+    const warnings = this.buildFailureWarnings(matches, globalFailureRates, description);
     if (warnings) {
       blocks.push({ type: "text", text: warnings });
     }
@@ -1431,15 +1812,34 @@ A loosely similar workflow (score: ${hint.score.toFixed(2)}) used these node typ
     const patterns = this._lastActivePatterns ?? this.getActivePatterns(this.resolveMaxPatterns());
     return patterns.map((p) => p.rule);
   }
-  getActivePatterns(maxCount = 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, maxCount);
-  }
-  buildFailureWarnings(matches, globalFailureRates) {
-    const richPatterns = this.getActivePatterns(this.resolveMaxPatterns());
+    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);
@@ -1619,7 +2019,8 @@ var WorkflowDesigner = class {
         const issueLines = lastErrors.map(
           (i) => `- [Rule ${i.rule}] ${i.message}${i.nodeId ? ` (node: ${i.nodeId})` : ""}`
         );
-        userMessage = this.promptBuilder.buildCorrectionMessage(request, matches, issueLines, attempt - 1);
+        const failingRuleIds = lastErrors.map((i) => i.rule);
+        userMessage = this.promptBuilder.buildCorrectionMessage(request, matches, issueLines, attempt - 1, failingRuleIds);
         this.logger.debug(`WorkflowDesigner: correction attempt ${attempt}`, { issueCount: lastErrors.length });
       }
       const start = Date.now();
@@ -1805,19 +2206,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);
       }
@@ -1859,22 +2261,24 @@ 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;
@@ -2174,6 +2578,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,
@@ -2222,7 +2627,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
         })
       ));
       return {
-        sessionId: bc.sessionId,
+        sessionId: bc.runId ?? bc.sessionId,
         date: bc.fileDate,
         description: data.description ?? "",
         workflowType: data.workflowType ?? null,
@@ -2255,7 +2660,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-26)`
+          message: `Pattern references Rule ${p.rule} which does not exist in the current validator (rules 1-34)`
         });
       }
     }
@@ -2395,7 +2800,7 @@ function inferWorkflowType(description) {
 // src/client.ts
 var import_node_os5 = require("os");
 var import_node_path6 = require("path");
-var DEFAULT_MODEL = "claude-sonnet-4-6";
+var DEFAULT_MODEL = process.env["KAIROS_MODEL"] ?? "claude-sonnet-4-6";
 var Kairos = class {
   provider;
   designer;
@@ -2553,10 +2958,19 @@ var Kairos = class {
     }
     const provider = this.requireProvider();
     const deployed = await provider.deploy(workflow);
-    this.recordDeploy();
+    this.logger.info("Workflow deployed to n8n", { workflowId: deployed.workflowId, name: deployed.name });
+    this.recordDeploy(deployed.workflowId);
     if (options?.activate) {
       await provider.activate(deployed.workflowId);
     }
+    let smokeTestResult;
+    if (options?.smokeTest) {
+      smokeTestResult = await provider.smokeTest(deployed.workflowId, workflow).catch((err) => {
+        this.logger.warn("Smoke test threw unexpectedly", { err: String(err) });
+        return { status: "error", triggerType: "manual", error: String(err) };
+      });
+      this.logger.info("Smoke test complete", { status: smokeTestResult.status, triggerType: smokeTestResult.triggerType });
+    }
     const totalTokensInput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
     const totalTokensOutput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
     await this.telemetry?.emit("build_complete", {
@@ -2581,7 +2995,8 @@ var Kairos = class {
       credentialsNeeded: designResult.credentialsNeeded,
       activationRequired: !options?.activate,
       generationAttempts: designResult.attempts,
-      dryRun: false
+      dryRun: false,
+      ...smokeTestResult !== void 0 ? { smokeTest: smokeTestResult } : {}
     };
   }
   async replace(id, description) {
@@ -2638,7 +3053,8 @@ var Kairos = class {
     await this.emitAttemptTelemetry(description, designResult, workflowType, runId);
     const provider = this.requireProvider();
     const deployed = await provider.update(id, designResult.workflow);
-    this.saveToLibrary(designResult.workflow, description, designResult, matches);
+    this.logger.info("Workflow updated in n8n", { workflowId: deployed.workflowId, name: deployed.name });
+    this.saveToLibrary(designResult.workflow, description, designResult, matches, deployed.workflowId);
     this.recordDeploy();
     const totalTokensInput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
     const totalTokensOutput = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
@@ -2694,10 +3110,10 @@ var Kairos = class {
       }, runId);
     }
   }
-  recordDeploy() {
+  recordDeploy(n8nWorkflowId) {
     this.saveQueue = this.saveQueue.then(async (savedId) => {
       if (savedId) {
-        await this.library.recordDeployment(savedId);
+        await this.library.recordDeployment(savedId, n8nWorkflowId);
       }
       return savedId;
     }).catch((err) => {
@@ -2705,7 +3121,7 @@ var Kairos = class {
       return null;
     });
   }
-  saveToLibrary(workflow, description, designResult, matches) {
+  saveToLibrary(workflow, description, designResult, matches, n8nWorkflowId) {
     const failedAttempts = designResult.attemptMetadata.filter((m) => !m.validationPassed);
     const failurePatterns = failedAttempts.flatMap(
       (m) => m.issues.map((i) => ({ rule: i.rule, message: i.message }))
@@ -2731,6 +3147,7 @@ var Kairos = class {
     if (matches.length > 0) metadata.sourceWorkflowIds = matches.map((m) => m.workflow.id);
     if (topMatch) metadata.topMatchScore = topMatch.score;
     if (designResult.credentialsNeeded.length > 0) metadata.credentialsNeeded = designResult.credentialsNeeded;
+    if (n8nWorkflowId) metadata.n8nWorkflowId = n8nWorkflowId;
     const firstTryPass = designResult.attemptMetadata.length > 0 && designResult.attemptMetadata[0].validationPassed;
     const failedRules = Array.from(new Set(
       designResult.attemptMetadata.filter((m) => !m.validationPassed).flatMap((m) => m.issues.map((i) => i.rule))
@@ -2794,12 +3211,32 @@ var import_node_path7 = require("path");
 var import_node_os6 = require("os");
 
 // 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"],
@@ -2984,6 +3421,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) {
@@ -2991,7 +3430,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) {
@@ -3003,7 +3442,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);
 }
@@ -3020,7 +3477,11 @@ 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);
 }
@@ -3068,6 +3529,7 @@ var FileLibrary = class {
       } catch {
         this.meta = [];
       }
+      await this.scanForOrphansAndCleanup();
     } else {
       try {
         const raw = await (0, import_promises4.readFile)(indexPath, "utf-8");
@@ -3082,6 +3544,31 @@ var FileLibrary = class {
       await (0, import_promises4.mkdir)(this.workflowsDir, { recursive: true });
     }
   }
+  async scanForOrphansAndCleanup() {
+    let entries;
+    try {
+      entries = await (0, import_promises4.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_promises4.unlink)((0, import_node_path7.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
@@ -3152,10 +3639,12 @@ var FileLibrary = class {
     const docTokenSets = docTokenArrays.map((tokens) => new Set(tokens));
     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, shells, docTokenArrays, idf).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
     const clusters = clusterWorkflows(shells);
@@ -3181,6 +3670,27 @@ var FileLibrary = class {
     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);
@@ -3202,25 +3712,27 @@ 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.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 (b.deployCount ?? 0) - (a.deployCount ?? 0);
+        return evictionScore(b) - evictionScore(a);
       });
       this.meta = this.meta.slice(0, MAX_LIBRARY_SIZE);
     }
     await this.persist();
     return id;
   }
-  async recordDeployment(id) {
+  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();
     }
   }
@@ -3283,37 +3795,98 @@ var FileLibrary = class {
     }
     return [...map.values()];
   }
+  // ── 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_path7.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_promises4.open)(this.lockPath, "wx");
+        await fh.writeFile(String(process.pid));
+        await fh.close();
+        return async () => {
+          await (0, import_promises4.unlink)(this.lockPath).catch(() => {
+          });
+        };
+      } catch {
+        try {
+          const content = await (0, import_promises4.readFile)(this.lockPath, "utf-8");
+          const lockPid = parseInt(content.trim(), 10);
+          const fileStat = await (0, import_promises4.stat)(this.lockPath);
+          const ageMs = Date.now() - fileStat.mtimeMs;
+          if (ageMs > 1e4) {
+            await (0, import_promises4.unlink)(this.lockPath).catch(() => {
+            });
+            continue;
+          }
+          if (!isNaN(lockPid)) {
+            try {
+              process.kill(lockPid, 0);
+            } catch {
+              await (0, import_promises4.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 indexPath = (0, import_node_path7.join)(this.dir, "index.json");
-    const tmpPath = `${indexPath}.tmp`;
-    await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(this.meta, null, 2), "utf-8");
-    await (0, import_promises4.rename)(tmpPath, indexPath);
+    const releaseLock = await this.acquireLock();
+    try {
+      const indexPath = (0, import_node_path7.join)(this.dir, "index.json");
+      const tmpPath = `${indexPath}.tmp`;
+      await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(this.meta, null, 2), "utf-8");
+      await (0, import_promises4.rename)(tmpPath, indexPath);
+    } finally {
+      await releaseLock();
+    }
   }
   persist() {
     this.writeQueue = this.writeQueue.then(async () => {
-      const indexPath = (0, import_node_path7.join)(this.dir, "index.json");
-      let onDisk = [];
+      const releaseLock = await this.acquireLock();
       try {
-        const raw = await (0, import_promises4.readFile)(indexPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (Array.isArray(parsed)) {
-          onDisk = parsed.filter(isValidMeta);
+        const indexPath = (0, import_node_path7.join)(this.dir, "index.json");
+        let onDisk = [];
+        try {
+          const raw = await (0, import_promises4.readFile)(indexPath, "utf-8");
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed)) {
+            onDisk = parsed.filter(isValidMeta);
+          }
+        } catch {
         }
-      } 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) => (b.deployCount ?? 0) - (a.deployCount ?? 0));
-        merged = merged.slice(0, MAX_LIBRARY_SIZE);
+        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_promises4.writeFile)(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+        await (0, import_promises4.rename)(tmpPath, indexPath);
+      } finally {
+        await releaseLock();
       }
-      const tmpPath = `${indexPath}.tmp`;
-      await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
-      await (0, import_promises4.rename)(tmpPath, indexPath);
     });
     return this.writeQueue;
   }
@@ -3335,6 +3908,19 @@ var SECRET_PATTERNS = [
   /AIza[a-zA-Z0-9_-]{35}/,
   /AKIA[A-Z0-9]{16}/
 ];
+var SECRET_PREFIXES = ["sk-", "ghp_", "xoxb-", "AIza", "AKIA"];
+function collectExpressionStrings(obj, out = []) {
+  if (typeof obj === "string") {
+    if (obj.includes("={{")) out.push(obj);
+  } else if (Array.isArray(obj)) {
+    for (const item of obj) collectExpressionStrings(item, out);
+  } else if (obj !== null && typeof obj === "object") {
+    for (const val of Object.values(obj)) {
+      collectExpressionStrings(val, out);
+    }
+  }
+  return out;
+}
 function assessTemplateSafety(workflow) {
   const reasons = [];
   let worst = "safe";
@@ -3357,6 +3943,15 @@ function assessTemplateSafety(workflow) {
         break;
       }
     }
+    const expressions = collectExpressionStrings(node.parameters);
+    for (const expr of expressions) {
+      for (const prefix of SECRET_PREFIXES) {
+        if (expr.includes(prefix)) {
+          escalate("review", `Node "${node.name}" has an expression containing credential-like prefix "${prefix}"`);
+          break;
+        }
+      }
+    }
   }
   return { trustLevel: worst, reasons };
 }
@@ -3414,12 +4009,26 @@ var TemplateSyncer = class {
     }
     return progress;
   }
+  async fetchWithBackoff(url, maxRetries = 3) {
+    let delayMs = DELAY_BETWEEN_FETCHES_MS;
+    let lastResponse;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      lastResponse = await fetch(url);
+      if (lastResponse.status !== 429 && lastResponse.status !== 503) return lastResponse;
+      if (attempt === maxRetries) break;
+      const retryAfterHeader = lastResponse.headers.get("Retry-After");
+      const waitMs = retryAfterHeader ? parseInt(retryAfterHeader, 10) * 1e3 : delayMs * Math.pow(2, attempt);
+      this.logger.warn(`HTTP ${lastResponse.status} from template API, retrying in ${waitMs}ms`, { url, attempt });
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    return lastResponse;
+  }
   async fetchTemplateIds(max, progress) {
     const ids = [];
     let page = 1;
     while (ids.length < max) {
       const url = `${N8N_TEMPLATE_API}/search?page=${page}&rows=${PAGE_SIZE}`;
-      const response = await fetch(url);
+      const response = await this.fetchWithBackoff(url);
       if (!response.ok) break;
       const data = await response.json();
       progress.total = Math.min(data.totalWorkflows, max);
@@ -3439,7 +4048,7 @@ var TemplateSyncer = class {
   }
   async processTemplate(id, progress) {
     const url = `${N8N_TEMPLATE_API}/workflows/${id}`;
-    const response = await fetch(url);
+    const response = await this.fetchWithBackoff(url);
     if (!response.ok) return;
     const data = await response.json();
     const templateMeta = data.workflow;
@@ -3501,6 +4110,7 @@ Kairos SDK \u2014 LLM-powered n8n workflow generation
 Usage:
   kairos init                         First-time setup wizard
   kairos build <description> [options]
+  kairos replace <n8n-id> <description>
   kairos patterns [options]
   kairos sessions [options]
   kairos list
@@ -3633,6 +4243,27 @@ async function handleBuild(positional, flags) {
     ...result.dryRun ? { workflow: result.workflow } : {}
   }, null, 2));
 }
+async function handleReplace(positional) {
+  const id = positional[0];
+  const description = positional.slice(1).join(" ");
+  if (!id || !description) {
+    console.error("Usage: kairos replace <n8n-workflow-id> <description>");
+    process.exit(1);
+  }
+  const kairos = createClient();
+  const start = Date.now();
+  console.error(`Replacing workflow ${id}...`);
+  const result = await kairos.replace(id, description);
+  await kairos.drain();
+  const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+  console.error(`Done in ${elapsed}s (${result.generationAttempts} attempt${result.generationAttempts > 1 ? "s" : ""})`);
+  console.error("");
+  console.log(JSON.stringify({
+    workflowId: result.workflowId,
+    name: result.name,
+    generationAttempts: result.generationAttempts
+  }, null, 2));
+}
 async function handleList() {
   const kairos = createClient();
   const workflows = await kairos.list();
@@ -3700,14 +4331,7 @@ async function handleSyncTemplates(flags) {
   const maxRaw = typeof flags["max"] === "string" ? parseInt(flags["max"], 10) : NaN;
   const max = Number.isNaN(maxRaw) ? 500 : maxRaw;
   const library = new FileLibrary();
-  const logger = {
-    debug: () => {
-    },
-    info: (msg, meta) => console.error(meta ? `${msg} ${JSON.stringify(meta)}` : msg),
-    warn: (msg, meta) => console.error(meta ? `[warn] ${msg} ${JSON.stringify(meta)}` : `[warn] ${msg}`),
-    error: (msg, meta) => console.error(meta ? `[error] ${msg} ${JSON.stringify(meta)}` : `[error] ${msg}`)
-  };
-  const syncer = new TemplateSyncer(library, logger);
+  const syncer = new TemplateSyncer(library, CLI_LOGGER);
   console.error(`Syncing up to ${max} templates from n8n community library...`);
   const result = await syncer.sync({
     maxTemplates: max,
@@ -3915,7 +4539,7 @@ async function handleInit() {
 }
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv);
-  if (!command || command === "help" || flags["help"] === true) {
+  if (!command || command === "help" || command === "--help" || flags["help"] === true) {
     console.log(HELP);
     return;
   }
@@ -3926,6 +4550,9 @@ async function main() {
     case "build":
       await handleBuild(positional, flags);
       break;
+    case "replace":
+      await handleReplace(positional);
+      break;
     case "patterns":
       await handlePatterns(flags);
       break;