@kairos-sdk/core 0.5.0 → 0.6.0

package/dist/cli.cjs

@@ -6,6 +6,13 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -23,6 +30,364 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/pack/pack-builder.ts
+var pack_builder_exports = {};
+__export(pack_builder_exports, {
+  PackBuilder: () => PackBuilder,
+  derivePackStatus: () => derivePackStatus
+});
+function derivePackStatus(pack) {
+  const hasBlocking = pack.assumptions.some((a) => a.type === "blocking");
+  const hasFailures = pack.workflows.some((w) => w.error);
+  const allDeployed = pack.workflows.length > 0 && pack.workflows.every((w) => w.deployed);
+  const hasNeedsConfirmation = pack.assumptions.some((a) => a.type === "needs_confirmation");
+  if (pack.status === "active" && !hasBlocking && !hasFailures && allDeployed) return "active";
+  if (pack.workflows.length === 0 || !allDeployed && !hasFailures) return "draft";
+  if (hasBlocking) return "blocked";
+  if (hasFailures) return "needs_attention";
+  if (hasNeedsConfirmation) return "ready_for_test";
+  return "ready_for_activation";
+}
+function normalizeAssumptions(raw) {
+  const validTypes = /* @__PURE__ */ new Set(["safe", "needs_confirmation", "blocking"]);
+  return raw.map((a) => {
+    if (typeof a === "string") {
+      return { type: "needs_confirmation", text: a };
+    }
+    if (typeof a === "object" && a !== null) {
+      const obj = a;
+      const type = typeof obj["type"] === "string" && validTypes.has(obj["type"]) ? obj["type"] : "needs_confirmation";
+      const text = typeof obj["text"] === "string" ? obj["text"] : JSON.stringify(obj);
+      return { type, text };
+    }
+    return { type: "needs_confirmation", text: String(a) };
+  });
+}
+var import_sdk2, PLAN_PROMPT, PackBuilder;
+var init_pack_builder = __esm({
+  "src/pack/pack-builder.ts"() {
+    "use strict";
+    import_sdk2 = __toESM(require("@anthropic-ai/sdk"), 1);
+    PLAN_PROMPT = `You are planning an n8n workflow automation pack for a business.
+
+Business context: {CONTEXT}
+
+Generate a list of 4-8 n8n workflows that would meaningfully automate this business's operations. Focus on workflows that save time on repetitive tasks, improve customer communication, prevent things falling through the cracks, and are realistic to implement with n8n nodes.
+
+For each workflow, write a detailed build description (2-4 sentences) suitable for passing directly to an n8n workflow generator. Be specific: name the trigger type, data sources (Google Sheets columns if applicable), actions, and outputs.
+
+For assumptions, classify each one:
+- "safe": a clearly reasonable default the business likely expects (e.g. "Schedule runs Monday 9 AM")
+- "needs_confirmation": should be confirmed before going live but won't break things immediately (e.g. "Assumed professional email tone \u2014 confirm brand voice")
+- "blocking": MUST be resolved before activation or the workflow will fail, send duplicates, or surprise customers (e.g. "Google Sheet ID not provided", "emails auto-send without approval gate \u2014 add confirmation step")
+
+Treat any open question that would block safe deployment as a blocking assumption.
+
+Return ONLY valid JSON with no markdown or extra text:
+{
+  "workflows": [
+    {
+      "name": "Short descriptive name",
+      "description": "Detailed generator-ready description specifying trigger, data sources, actions, outputs",
+      "purpose": "One sentence explaining the business value"
+    }
+  ],
+  "assumptions": [
+    { "type": "safe" | "needs_confirmation" | "blocking", "text": "Description of the assumption" }
+  ],
+  "sheetsColumns": [
+    { "sheet": "Sheet name", "columns": ["col1", "col2"] }
+  ],
+  "testChecklist": [
+    { "workflow": "Workflow name", "steps": ["How to manually test this workflow"] }
+  ]
+}`;
+    PackBuilder = class {
+      client;
+      kairos;
+      model;
+      constructor(options) {
+        this.client = new import_sdk2.default({ apiKey: options.anthropicApiKey });
+        this.kairos = options.kairos;
+        this.model = options.model ?? "claude-sonnet-4-6";
+      }
+      async plan(businessContext) {
+        const prompt = PLAN_PROMPT.replace("{CONTEXT}", businessContext);
+        const response = await this.client.messages.create({
+          model: this.model,
+          max_tokens: 4096,
+          messages: [{ role: "user", content: prompt }]
+        });
+        const text = response.content[0]?.type === "text" ? response.content[0].text.trim() : "";
+        const cleaned = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+        const parsed = JSON.parse(cleaned);
+        const rawAssumptions = Array.isArray(parsed["assumptions"]) ? parsed["assumptions"] : [];
+        const rawOpenQuestions = Array.isArray(parsed["openQuestions"]) ? parsed["openQuestions"] : [];
+        const assumptions = normalizeAssumptions([...rawAssumptions, ...rawOpenQuestions.map(
+          (q) => typeof q === "string" ? { type: "needs_confirmation", text: q } : q
+        )]);
+        return {
+          businessContext,
+          workflows: Array.isArray(parsed["workflows"]) ? parsed["workflows"] : [],
+          assumptions,
+          sheetsColumns: Array.isArray(parsed["sheetsColumns"]) ? parsed["sheetsColumns"] : [],
+          testChecklist: Array.isArray(parsed["testChecklist"]) ? parsed["testChecklist"] : []
+        };
+      }
+      async build(plan, options = {}) {
+        const hasBlockingAssumptions = plan.assumptions.some((a) => a.type === "blocking");
+        const effectiveActivate = hasBlockingAssumptions ? false : options.activate ?? false;
+        const results = [];
+        const credentialMap = /* @__PURE__ */ new Map();
+        for (let i = 0; i < plan.workflows.length; i++) {
+          const wf = plan.workflows[i];
+          options.onProgress?.(wf, i, plan.workflows.length);
+          try {
+            const result = await this.kairos.build(wf.description, {
+              name: wf.name,
+              dryRun: options.dryRun ?? false,
+              activate: effectiveActivate
+            });
+            for (const cred of result.credentialsNeeded) {
+              credentialMap.set(cred.service, { service: cred.service, credentialType: cred.credentialType });
+            }
+            results.push({
+              name: wf.name,
+              purpose: wf.purpose,
+              workflowId: result.workflowId,
+              deployed: !result.dryRun,
+              generationAttempts: result.generationAttempts,
+              credentialsNeeded: result.credentialsNeeded
+            });
+          } catch (err) {
+            results.push({
+              name: wf.name,
+              purpose: wf.purpose,
+              workflowId: null,
+              deployed: false,
+              generationAttempts: 0,
+              credentialsNeeded: [],
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
+        const packName = plan.businessContext.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const partial = {
+          businessContext: plan.businessContext,
+          packName,
+          status: "draft",
+          workflows: results,
+          allCredentials: Array.from(credentialMap.values()),
+          sheetsColumns: plan.sheetsColumns,
+          assumptions: plan.assumptions,
+          testChecklist: plan.testChecklist,
+          builtAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        return { ...partial, status: derivePackStatus(partial) };
+      }
+    };
+  }
+});
+
+// src/pack/pack-exporter.ts
+var pack_exporter_exports = {};
+__export(pack_exporter_exports, {
+  generateHandoff: () => generateHandoff
+});
+function generateHandoff(pack) {
+  const lines = [];
+  const line = () => lines.push("");
+  lines.push(`# ${pack.businessContext} \u2014 Workflow Pack`);
+  line();
+  lines.push(`**Status:** ${STATUS_LABELS[pack.status] ?? pack.status}`);
+  lines.push(`**Generated:** ${new Date(pack.builtAt).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" })}`);
+  lines.push(`**Workflows:** ${pack.workflows.length} (${pack.workflows.filter((w) => w.deployed).length} deployed)`);
+  line();
+  lines.push(`## Overview`);
+  line();
+  lines.push(
+    `This workflow pack automates operations for **${pack.businessContext}**. It was built with Kairos and requires credential setup before workflows can be activated in n8n.`
+  );
+  line();
+  const blocking = pack.assumptions.filter((a) => a.type === "blocking");
+  if (blocking.length > 0) {
+    lines.push(`## Blocking Issues`);
+    line();
+    lines.push(`> These must be resolved before any workflows are activated.`);
+    line();
+    for (const a of blocking) {
+      lines.push(`- [ ] ${a.text}`);
+    }
+    line();
+  }
+  lines.push(`## Workflows`);
+  line();
+  for (const wf of pack.workflows) {
+    const icon = wf.error ? "\u2717" : "\u2713";
+    lines.push(`### ${icon} ${wf.name}`);
+    line();
+    lines.push(`**Purpose:** ${wf.purpose}`);
+    if (wf.workflowId) lines.push(`**n8n ID:** \`${wf.workflowId}\``);
+    if (!wf.deployed && !wf.error) lines.push(`**Status:** Not deployed (dry run)`);
+    if (wf.error) lines.push(`**Error:** ${wf.error}`);
+    line();
+  }
+  if (pack.allCredentials.length > 0) {
+    lines.push(`## Required Credentials`);
+    line();
+    lines.push(`Connect these in n8n before activating workflows:`);
+    line();
+    for (const cred of pack.allCredentials) {
+      lines.push(`- [ ] **${cred.service}** (${cred.credentialType})`);
+    }
+    line();
+  }
+  if (pack.sheetsColumns.length > 0) {
+    lines.push(`## Required Google Sheets`);
+    line();
+    for (const sheet of pack.sheetsColumns) {
+      lines.push(`### ${sheet.sheet}`);
+      line();
+      lines.push(`Columns: ${sheet.columns.map((c) => `\`${c}\``).join(", ")}`);
+      line();
+    }
+  }
+  const needsConfirmation = pack.assumptions.filter((a) => a.type === "needs_confirmation");
+  if (needsConfirmation.length > 0) {
+    lines.push(`## Needs Confirmation`);
+    line();
+    lines.push(`Verify these with the client before going live:`);
+    line();
+    for (const a of needsConfirmation) {
+      lines.push(`- [ ] ${a.text}`);
+    }
+    line();
+  }
+  const safe = pack.assumptions.filter((a) => a.type === "safe");
+  if (safe.length > 0) {
+    lines.push(`## Safe Assumptions`);
+    line();
+    lines.push(`These defaults were used during generation \u2014 no action needed:`);
+    line();
+    for (const a of safe) {
+      lines.push(`- ${a.text}`);
+    }
+    line();
+  }
+  lines.push(`## Setup Checklist`);
+  line();
+  lines.push(`Complete before testing:`);
+  line();
+  for (const cred of pack.allCredentials) {
+    lines.push(`- [ ] Connect **${cred.service}** credential in n8n Settings \u2192 Credentials`);
+  }
+  for (const sheet of pack.sheetsColumns) {
+    lines.push(`- [ ] Create Google Sheet: "${sheet.sheet}" with columns: ${sheet.columns.join(", ")}`);
+  }
+  for (const a of blocking) {
+    lines.push(`- [ ] Resolve: ${a.text}`);
+  }
+  for (const a of needsConfirmation) {
+    lines.push(`- [ ] Confirm: ${a.text}`);
+  }
+  line();
+  if (pack.testChecklist.length > 0) {
+    lines.push(`## Testing Checklist`);
+    line();
+    for (const item of pack.testChecklist) {
+      lines.push(`### ${item.workflow}`);
+      line();
+      for (const step of item.steps) {
+        lines.push(`- [ ] ${step}`);
+      }
+      line();
+    }
+  }
+  const deployedWorkflows = pack.workflows.filter((w) => w.deployed && !w.error);
+  if (deployedWorkflows.length > 0) {
+    lines.push(`## Activation Checklist`);
+    line();
+    lines.push(`Activate in n8n after testing is complete:`);
+    line();
+    for (const wf of deployedWorkflows) {
+      const idSuffix = wf.workflowId ? ` (n8n ID: \`${wf.workflowId}\`)` : "";
+      lines.push(`- [ ] Activate: **${wf.name}**${idSuffix}`);
+    }
+    line();
+  }
+  lines.push(`## Maintenance Notes`);
+  line();
+  lines.push(`- Monitor n8n executions weekly \u2014 check the Executions tab for failures`);
+  lines.push(`- Re-run \`kairos build-pack\` to regenerate workflows if business needs change`);
+  lines.push(`- Update Google Sheets data as business information changes`);
+  lines.push(`- Rotate API credentials before expiration (n8n Settings \u2192 Credentials)`);
+  lines.push(`- Run \`kairos validate-pack <name>\` before activating after any changes`);
+  return lines.join("\n");
+}
+var STATUS_LABELS;
+var init_pack_exporter = __esm({
+  "src/pack/pack-exporter.ts"() {
+    "use strict";
+    STATUS_LABELS = {
+      draft: "Draft",
+      blocked: "Blocked \u2014 resolve issues before activation",
+      ready_for_test: "Ready for Testing",
+      ready_for_activation: "Ready for Activation",
+      active: "Active",
+      needs_attention: "Needs Attention"
+    };
+  }
+});
+
+// src/pack/pack-validator.ts
+var pack_validator_exports = {};
+__export(pack_validator_exports, {
+  validatePack: () => validatePack
+});
+function validatePack(pack) {
+  const issues = [];
+  const names = pack.workflows.map((w) => w.name);
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (seen.has(name)) duplicates.add(name);
+    seen.add(name);
+  }
+  if (duplicates.size > 0) {
+    issues.push({
+      type: "duplicate_name",
+      severity: "error",
+      message: `Duplicate workflow names: ${[...duplicates].join(", ")} \u2014 n8n may overwrite existing workflows on deploy`,
+      workflows: [...duplicates]
+    });
+  }
+  const blocking = pack.assumptions.filter((a) => a.type === "blocking");
+  if (blocking.length > 0) {
+    const plural = blocking.length === 1 ? "assumption" : "assumptions";
+    issues.push({
+      type: "blocking_assumption",
+      severity: "error",
+      message: `${blocking.length} blocking ${plural} must be resolved before activation:
+  ${blocking.map((a) => `\u2022 ${a.text}`).join("\n  ")}`
+    });
+  }
+  const failed = pack.workflows.filter((w) => w.error);
+  for (const wf of failed) {
+    issues.push({
+      type: "unsafe_activation",
+      severity: "error",
+      message: `Workflow "${wf.name}" failed to deploy: ${wf.error ?? "unknown error"}`,
+      workflows: [wf.name]
+    });
+  }
+  return issues;
+}
+var init_pack_validator = __esm({
+  "src/pack/pack-validator.ts"() {
+    "use strict";
+  }
+});
+
 // src/client.ts
 var import_sdk = __toESM(require("@anthropic-ai/sdk"), 1);
 
@@ -502,6 +867,36 @@ var N8nProvider = class {
   }
 };
 
+// src/errors/generation-error.ts
+var GenerationError = class extends KairosError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "GenerationError";
+  }
+};
+
+// src/errors/response-parse-error.ts
+var ResponseParseError = class extends KairosError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "ResponseParseError";
+  }
+};
+
+// src/errors/validation-error.ts
+var ValidationError = class extends KairosError {
+  constructor(message, issues, attemptMetadata, warnedRules) {
+    super(message);
+    this.issues = issues;
+    this.attemptMetadata = attemptMetadata;
+    this.warnedRules = warnedRules;
+    this.name = "ValidationError";
+  }
+  issues;
+  attemptMetadata;
+  warnedRules;
+};
+
 // src/validation/registry.ts
 var DEFAULT_REGISTRY = [
   // Trigger nodes
@@ -670,6 +1065,7 @@ var N8nValidator = class {
     this.checkRule32(workflow, issues);
     this.checkRule33(workflow, issues);
     this.checkRule34(workflow, issues);
+    this.checkRule35(workflow, issues);
     if (Array.isArray(workflow.nodes)) {
       const nodeById = new Map(workflow.nodes.map((n) => [n.id, n.type]));
       for (const issue of issues) {
@@ -1242,6 +1638,43 @@ var N8nValidator = class {
       }
     }
   }
+  // Rule 35 (WARN): email-sending node with no duplicate-prevention signal
+  checkRule35(w, issues) {
+    if (!Array.isArray(w.nodes)) return;
+    const sendNodes = w.nodes.filter((node) => {
+      if (node.type === "n8n-nodes-base.gmail") {
+        const op = node.parameters?.["operation"];
+        return !op || op === "send" || op === "sendEmail" || op === "reply";
+      }
+      return node.type === "n8n-nodes-base.emailSend" || node.type === "n8n-nodes-base.sendEmail";
+    });
+    if (sendNodes.length === 0) return;
+    const workflowText = JSON.stringify(w).toLowerCase();
+    const IDEMPOTENCY_SIGNALS = [
+      "sent_at",
+      "last_sent",
+      "last_reminder",
+      "processed_at",
+      "already_sent",
+      "email_sent",
+      "notified_at",
+      "reminder_sent",
+      "contacted_at",
+      "dedupe",
+      "idempotent"
+    ];
+    const hasIdempotencySignal = IDEMPOTENCY_SIGNALS.some((s) => workflowText.includes(s));
+    if (!hasIdempotencySignal) {
+      for (const node of sendNodes) {
+        this.warn(
+          issues,
+          35,
+          `Node "${node.name}" sends email but no duplicate-prevention signal detected \u2014 add a sent_at timestamp field, a prior-send IF check, or a deduplication key to avoid repeat sends`,
+          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;
@@ -1276,36 +1709,6 @@ var N8nValidator = class {
   }
 };
 
-// src/errors/generation-error.ts
-var GenerationError = class extends KairosError {
-  constructor(message, cause) {
-    super(message, cause);
-    this.name = "GenerationError";
-  }
-};
-
-// src/errors/response-parse-error.ts
-var ResponseParseError = class extends KairosError {
-  constructor(message, cause) {
-    super(message, cause);
-    this.name = "ResponseParseError";
-  }
-};
-
-// src/errors/validation-error.ts
-var ValidationError = class extends KairosError {
-  constructor(message, issues, attemptMetadata, warnedRules) {
-    super(message);
-    this.issues = issues;
-    this.attemptMetadata = attemptMetadata;
-    this.warnedRules = warnedRules;
-    this.name = "ValidationError";
-  }
-  issues;
-  attemptMetadata;
-  warnedRules;
-};
-
 // src/generation/prompt-builder.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
@@ -1534,7 +1937,7 @@ function scoreToMode(score) {
 }
 
 // src/validation/rule-metadata.ts
-var VALIDATOR_RULE_IDS = Array.from({ length: 34 }, (_, i) => i + 1);
+var VALIDATOR_RULE_IDS = Array.from({ length: 35 }, (_, i) => i + 1);
 var RULE_PIPELINE_STAGES = {
   1: "node_generation",
   2: "node_generation",
@@ -1569,7 +1972,8 @@ var RULE_PIPELINE_STAGES = {
   31: "node_generation",
   32: "node_generation",
   33: "node_generation",
-  34: "node_generation"
+  34: "node_generation",
+  35: "node_generation"
 };
 var RULE_EXAMPLES = {
   17: {
@@ -1619,6 +2023,10 @@ var RULE_EXAMPLES = {
   34: {
     bad: '"path": "/my webhook"',
     good: '"path": "my-webhook"'
+  },
+  35: {
+    bad: '"type": "n8n-nodes-base.gmail", "parameters": { "operation": "send" }  // no sent_at tracking',
+    good: 'Add a Set node after send that writes "sent_at": "={{ $now }}" back to the sheet, or an IF node that checks sent_at before sending'
   }
 };
 var RULE_MITIGATIONS = {
@@ -1655,7 +2063,8 @@ var RULE_MITIGATIONS = {
   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")'
+  34: 'Webhook path must be a relative path without spaces, leading slashes, or protocol prefixes (e.g. "my-hook")',
+  35: "Add duplicate-prevention to email-sending workflows: a sent_at timestamp field updated after each send, or an IF node that checks prior-send status before sending"
 };
 
 // src/generation/prompt-builder.ts
@@ -2310,7 +2719,7 @@ var PatternAnalyzer = class _PatternAnalyzer {
     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(
+    const _passed = attempts.filter(
       (a) => a.data.validationPassed === true
     );
     const failed = attempts.filter(
@@ -2804,7 +3213,6 @@ var DEFAULT_MODEL = process.env["KAIROS_MODEL"] ?? "claude-sonnet-4-6";
 var Kairos = class {
   provider;
   designer;
-  validator;
   library;
   logger;
   telemetry;
@@ -2830,7 +3238,6 @@ var Kairos = class {
     const anthropic = new import_sdk.default({ apiKey: options.anthropicApiKey });
     const patternsPath = typeof options.telemetry === "string" ? (0, import_node_path6.join)(options.telemetry, "..", "patterns.json") : (0, import_node_path6.join)((0, import_node_os5.homedir)(), ".kairos", "patterns.json");
     this.designer = new WorkflowDesigner(anthropic, this.model, logger, patternsPath);
-    this.validator = new N8nValidator();
     this.library = options.library ?? new NullLibrary();
     this.logger = logger;
     if (options.telemetry === true) {
@@ -2927,7 +3334,6 @@ var Kairos = class {
     }
     await this.emitAttemptTelemetry(description, designResult, workflowType, runId);
     const workflow = options?.name ? { ...designResult.workflow, name: options.name } : designResult.workflow;
-    this.saveToLibrary(workflow, description, designResult, matches);
     if (options?.dryRun) {
       const totalTokensInput2 = designResult.attemptMetadata.reduce((s, m) => s + m.tokensInput, 0);
       const totalTokensOutput2 = designResult.attemptMetadata.reduce((s, m) => s + m.tokensOutput, 0);
@@ -2963,6 +3369,7 @@ var Kairos = class {
     if (options?.activate) {
       await provider.activate(deployed.workflowId);
     }
+    this.saveToLibrary(workflow, description, designResult, matches, deployed.workflowId);
     let smokeTestResult;
     if (options?.smokeTest) {
       smokeTestResult = await provider.smokeTest(deployed.workflowId, workflow).catch((err) => {
@@ -4110,6 +4517,9 @@ Kairos SDK \u2014 LLM-powered n8n workflow generation
 Usage:
   kairos init                         First-time setup wizard
   kairos build <description> [options]
+  kairos build-pack <business context> [options]
+  kairos pack export <name> [--handoff]
+  kairos validate-pack <name>
   kairos replace <n8n-id> <description>
   kairos patterns [options]
   kairos sessions [options]
@@ -4124,6 +4534,17 @@ Build options:
   --dry-run       Generate and validate without deploying
   --name <name>   Override the generated workflow name
   --activate      Activate the workflow after deployment
+  --smoke-test    After deploy, trigger the workflow and verify it runs without error
+
+Build-pack options:
+  --dry-run       Plan and validate without deploying
+  --activate      Activate each workflow after deployment (blocked if blocking assumptions exist)
+  --yes           Skip confirmation prompt and build immediately
+
+Pack options:
+  pack export <name>          Print the saved pack as JSON
+  pack export <name> --handoff  Generate a client-ready Markdown handoff document
+  validate-pack <name>        Cross-workflow safety check before activation
 
 Patterns options:
   --days <days>   Analysis window (default: 30)
@@ -4217,7 +4638,7 @@ function createDryRunClient() {
 async function handleBuild(positional, flags) {
   const description = positional.join(" ");
   if (!description) {
-    console.error("Usage: kairos build <description> [--dry-run] [--name <name>] [--activate]");
+    console.error("Usage: kairos build <description> [--dry-run] [--name <name>] [--activate] [--smoke-test]");
     process.exit(1);
   }
   const isDryRun = flags["dry-run"] === true;
@@ -4227,7 +4648,8 @@ async function handleBuild(positional, flags) {
   const result = await kairos.build(description, {
     dryRun: isDryRun,
     ...typeof flags["name"] === "string" ? { name: flags["name"] } : {},
-    activate: flags["activate"] === true
+    activate: flags["activate"] === true || flags["smoke-test"] === true,
+    smokeTest: flags["smoke-test"] === true
   });
   await kairos.drain();
   const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
@@ -4240,7 +4662,8 @@ async function handleBuild(positional, flags) {
     activationRequired: result.activationRequired,
     dryRun: result.dryRun,
     credentialsNeeded: result.credentialsNeeded,
-    ...result.dryRun ? { workflow: result.workflow } : {}
+    ...result.dryRun ? { workflow: result.workflow } : {},
+    ...result.smokeTest ? { smokeTest: result.smokeTest } : {}
   }, null, 2));
 }
 async function handleReplace(positional) {
@@ -4454,6 +4877,210 @@ Recent Sessions (last ${sessions.length})`);
     console.log(`${s.date}  ${status}${nameStr}${attemptsStr}${typeTag}${rulesStr}`);
   }
 }
+function printPackResult(result) {
+  const line = "\u2500".repeat(50);
+  const deployed = result.workflows.filter((w) => w.deployed).length;
+  const total = result.workflows.length;
+  console.error(`
+${result.businessContext} \u2014 Workflow Pack`);
+  console.error("\u2550".repeat(Math.min(result.businessContext.length + 18, 60)));
+  console.error(`Status: ${result.status}`);
+  const blocking = result.assumptions.filter((a) => a.type === "blocking");
+  if (blocking.length > 0) {
+    console.error(`
+\u26A0 Blocking Issues (${blocking.length}) \u2014 resolve before activating`);
+    console.error(line);
+    for (const a of blocking) {
+      console.error(`  \u2717 ${a.text}`);
+    }
+  }
+  console.error(`
+Workflows Built (${deployed}/${total})`);
+  console.error(line);
+  for (const wf of result.workflows) {
+    const icon = wf.error ? "\u2717" : "\u2713";
+    const idStr = wf.workflowId ? `  [${wf.workflowId}]` : "";
+    const attStr = wf.generationAttempts > 1 ? `  ${wf.generationAttempts} attempts` : "";
+    console.error(`  ${icon} ${wf.name}${idStr}${attStr}`);
+    console.error(`    ${wf.purpose}`);
+    if (wf.error) console.error(`    Error: ${wf.error}`);
+  }
+  if (result.allCredentials.length > 0) {
+    console.error(`
+Credentials Needed (connect once in n8n)`);
+    console.error(line);
+    for (const cred of result.allCredentials) {
+      console.error(`  \u25A1 ${cred.service}`);
+    }
+  }
+  if (result.sheetsColumns.length > 0) {
+    console.error(`
+Google Sheets Required`);
+    console.error(line);
+    for (const sheet of result.sheetsColumns) {
+      console.error(`  \u25A1 ${sheet.sheet}: ${sheet.columns.join(", ")}`);
+    }
+  }
+  const needsConfirmation = result.assumptions.filter((a) => a.type === "needs_confirmation");
+  if (needsConfirmation.length > 0) {
+    console.error(`
+Needs Confirmation Before Going Live`);
+    console.error(line);
+    for (const a of needsConfirmation) {
+      console.error(`  ? ${a.text}`);
+    }
+  }
+  const safe = result.assumptions.filter((a) => a.type === "safe");
+  if (safe.length > 0) {
+    console.error(`
+Safe Assumptions`);
+    console.error(line);
+    for (const a of safe) {
+      console.error(`  - ${a.text}`);
+    }
+  }
+  if (result.testChecklist.length > 0) {
+    console.error(`
+Test Checklist`);
+    console.error(line);
+    for (const item of result.testChecklist) {
+      console.error(`  ${item.workflow}`);
+      for (const step of item.steps) {
+        console.error(`    \u25A1 ${step}`);
+      }
+    }
+  }
+}
+async function handleBuildPack(positional, flags) {
+  const businessContext = positional.join(" ");
+  if (!businessContext) {
+    console.error("Usage: kairos build-pack <business context description> [--dry-run] [--activate] [--yes]");
+    process.exit(1);
+  }
+  const anthropicKey = getEnvOrExit("ANTHROPIC_API_KEY");
+  const { PackBuilder: PackBuilder2 } = await Promise.resolve().then(() => (init_pack_builder(), pack_builder_exports));
+  const isDryRun = flags["dry-run"] === true;
+  const kairos = isDryRun ? createDryRunClient() : createClient();
+  const builder = new PackBuilder2({ anthropicApiKey: anthropicKey, kairos });
+  console.error("\nPlanning workflow pack...");
+  const plan = await builder.plan(businessContext);
+  console.error(`
+${businessContext} \u2014 Planned Workflows (${plan.workflows.length})
+`);
+  for (let i = 0; i < plan.workflows.length; i++) {
+    const wf = plan.workflows[i];
+    console.error(`  ${i + 1}. ${wf.name}`);
+    console.error(`     ${wf.purpose}`);
+  }
+  const planBlocking = plan.assumptions.filter((a) => a.type === "blocking");
+  const planNeedsConfirmation = plan.assumptions.filter((a) => a.type === "needs_confirmation");
+  if (planBlocking.length > 0) {
+    console.error(`
+Blocking Issues (resolve before activation)`);
+    for (const a of planBlocking) console.error(`  \u2717 ${a.text}`);
+  }
+  if (planNeedsConfirmation.length > 0) {
+    console.error(`
+Needs Confirmation`);
+    for (const a of planNeedsConfirmation) console.error(`  ? ${a.text}`);
+  }
+  if (flags["yes"] !== true) {
+    const readline = await import("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((resolve) => rl.question("\nBuild all of these? [y/N] ", resolve));
+    rl.close();
+    if (!answer.toLowerCase().startsWith("y")) {
+      console.error("Aborted.");
+      process.exit(0);
+    }
+  }
+  console.error("\nBuilding...\n");
+  const result = await builder.build(plan, {
+    dryRun: isDryRun,
+    activate: flags["activate"] === true,
+    onProgress: (wf, i, total) => {
+      console.error(`  [${i + 1}/${total}] ${wf.name}...`);
+    }
+  });
+  printPackResult(result);
+  const { writeFile: writeFile3, mkdir: mkdir4 } = await import("fs/promises");
+  const { join: join8 } = await import("path");
+  const { homedir: homedir7 } = await import("os");
+  const packsDir = join8(homedir7(), ".kairos", "packs");
+  await mkdir4(packsDir, { recursive: true });
+  const packPath = join8(packsDir, `${result.packName}.json`);
+  await writeFile3(packPath, JSON.stringify(result, null, 2), "utf-8");
+  console.error(`
+Pack saved to: ${packPath}`);
+}
+async function handlePackExport(positional, flags) {
+  const packName = positional[0];
+  if (!packName) {
+    console.error("Usage: kairos pack export <pack-name> [--handoff]");
+    process.exit(1);
+  }
+  const { readFile: readFile2 } = await import("fs/promises");
+  const { join: join8 } = await import("path");
+  const { homedir: homedir7 } = await import("os");
+  const packPath = join8(homedir7(), ".kairos", "packs", `${packName}.json`);
+  let pack;
+  try {
+    const content = await readFile2(packPath, "utf-8");
+    pack = JSON.parse(content);
+  } catch {
+    console.error(`Pack not found: ${packPath}`);
+    console.error('Run "kairos build-pack <context>" to create one.');
+    process.exit(1);
+  }
+  if (flags["handoff"] === true) {
+    const { generateHandoff: generateHandoff2 } = await Promise.resolve().then(() => (init_pack_exporter(), pack_exporter_exports));
+    console.log(generateHandoff2(pack));
+  } else {
+    console.log(JSON.stringify(pack, null, 2));
+  }
+}
+async function handleValidatePack(positional) {
+  const packName = positional[0];
+  if (!packName) {
+    console.error("Usage: kairos validate-pack <pack-name>");
+    process.exit(1);
+  }
+  const { readFile: readFile2 } = await import("fs/promises");
+  const { join: join8 } = await import("path");
+  const { homedir: homedir7 } = await import("os");
+  const packPath = join8(homedir7(), ".kairos", "packs", `${packName}.json`);
+  let pack;
+  try {
+    const content = await readFile2(packPath, "utf-8");
+    pack = JSON.parse(content);
+  } catch {
+    console.error(`Pack not found: ${packPath}`);
+    console.error('Run "kairos build-pack <context>" to create one.');
+    process.exit(1);
+  }
+  const { validatePack: validatePack2 } = await Promise.resolve().then(() => (init_pack_validator(), pack_validator_exports));
+  const issues = validatePack2(pack);
+  const packLabel = `"${packName}" (status: ${pack.status})`;
+  if (issues.length === 0) {
+    console.log(`\u2713 Pack ${packLabel} passed all cross-workflow checks`);
+    return;
+  }
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  console.log(`
+${packName} \u2014 Pack Validation`);
+  console.log("\u2500".repeat(50));
+  console.log(`Status: ${pack.status}`);
+  console.log(`Issues: ${errors.length} error(s), ${warnings.length} warning(s)`);
+  console.log("");
+  for (const issue of errors) {
+    console.log(`  \u2717 [error]   ${issue.message}`);
+  }
+  for (const issue of warnings) {
+    console.log(`  \u26A0 [warning] ${issue.message}`);
+  }
+  if (errors.length > 0) process.exit(1);
+}
 async function handleInit() {
   const { writeFile: writeFile3, readFile: readFile2, mkdir: mkdir4 } = await import("fs/promises");
   const { join: join8 } = await import("path");
@@ -4531,11 +5158,28 @@ async function handleInit() {
   }
   const kairosDir = join8(homedir7(), ".kairos");
   await mkdir4(join8(kairosDir, "telemetry"), { recursive: true });
+  const kairosPath = process.execPath ? `${process.execPath.replace(/node$/, "kairos-mcp")}` : "kairos-mcp";
   console.error("");
   console.error("  Setup complete! Try:");
   console.error("");
   console.error('    kairos build "Send a Slack message when a webhook fires" --dry-run');
   console.error("");
+  console.error("  \u2500\u2500\u2500 Claude Desktop MCP config \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.error("  Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:");
+  console.error("");
+  console.error("  {");
+  console.error('    "mcpServers": {');
+  console.error('      "kairos": {');
+  console.error(`        "command": "${kairosPath}",`);
+  console.error('        "env": {');
+  console.error(`          "ANTHROPIC_API_KEY": "${process.env["ANTHROPIC_API_KEY"] ? "<set>" : "your-key-here"}",`);
+  console.error(`          "N8N_BASE_URL": "${process.env["N8N_BASE_URL"] ?? "https://your-n8n-instance"}",`);
+  console.error(`          "N8N_API_KEY": "${process.env["N8N_API_KEY"] ? "<set>" : "your-n8n-api-key"}"`);
+  console.error("        }");
+  console.error("      }");
+  console.error("    }");
+  console.error("  }");
+  console.error("");
 }
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv);
@@ -4550,6 +5194,9 @@ async function main() {
     case "build":
       await handleBuild(positional, flags);
       break;
+    case "build-pack":
+      await handleBuildPack(positional, flags);
+      break;
     case "replace":
       await handleReplace(positional);
       break;
@@ -4577,6 +5224,21 @@ async function main() {
     case "sync-templates":
       await handleSyncTemplates(flags);
       break;
+    case "pack": {
+      const subcommand = positional[0];
+      const subPositional = positional.slice(1);
+      if (subcommand === "export") {
+        await handlePackExport(subPositional, flags);
+      } else {
+        console.error(`Unknown pack subcommand: ${subcommand ?? "(none)"}`);
+        console.error("Available: kairos pack export <name> [--handoff]");
+        process.exit(1);
+      }
+      break;
+    }
+    case "validate-pack":
+      await handleValidatePack(positional);
+      break;
     default:
       console.error(`Unknown command: ${command}`);
       console.log(HELP);