@mutagent/cli 0.1.15 → 0.1.17

package/dist/bin/cli.js

@@ -464,6 +464,7 @@ class SDKClientWrapper {
         systemPrompt: data.systemPrompt ?? undefined,
         humanPrompt: data.humanPrompt ?? undefined,
         rawPrompt: data.rawPrompt ?? undefined,
+        inputSchema: data.inputSchema,
         outputSchema: data.outputSchema,
         metadata: data.metadata,
         tags: data.tags ?? undefined
@@ -529,11 +530,13 @@ class SDKClientWrapper {
           labels: item.labels,
           metadata: item.metadata
         }));
+        const missingExpectedOutputCount = mappedItems.filter((item) => item.expectedOutput === undefined).length;
         await this.request(`/api/prompts/datasets/${String(dataset.id)}/items/bulk`, {
           method: "POST",
           body: JSON.stringify({ items: mappedItems })
         });
         itemCount = mappedItems.length;
+        return { ...dataset, itemCount, missingExpectedOutputCount };
       }
       return { ...dataset, itemCount };
     } catch (error) {
@@ -574,6 +577,13 @@ class SDKClientWrapper {
       this.handleError(error);
     }
   }
+  async deleteEvaluation(evaluationId) {
+    try {
+      await this.request(`/api/prompts/evaluations/${evaluationId}`, { method: "DELETE" });
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
   async getEvaluationResults(runId) {
     try {
       return await this.request(`/api/prompts/evaluations/${runId}/result`);
@@ -588,8 +598,8 @@ class SDKClientWrapper {
         body: JSON.stringify({
           datasetId: parseInt(datasetId, 10),
           config: {
-            maxIterations: config?.maxIterations ?? 3,
-            targetScore: config?.targetScore,
+            maxIterations: config?.maxIterations ?? 1,
+            targetScore: config?.targetScore ?? 0.8,
             patience: config?.patience,
             model: config?.model,
             ...config?.evalModel ? { tuningParams: { evaluationModel: config.evalModel } } : {}
@@ -849,6 +859,12 @@ class SDKClientWrapper {
       this.handleError(error);
     }
   }
+  getCurrentWorkspaceId() {
+    return this.workspaceId;
+  }
+  getCurrentOrgId() {
+    return this.organizationId;
+  }
   async testProvider(id) {
     try {
       const response = await this.sdk.providerConfigs.testProvider({
@@ -922,9 +938,9 @@ var init_sdk_client = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command14 } from "commander";
-import chalk18 from "chalk";
-import { readFileSync as readFileSync14 } from "fs";
+import { Command as Command15 } from "commander";
+import chalk19 from "chalk";
+import { readFileSync as readFileSync12 } from "fs";
 import { join as join7, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -1058,6 +1074,24 @@ ${String(data.length)} result(s)`));
     }
   }
 }
+function createSpinner(text, isJson) {
+  if (isJson) {
+    const noop = () => {
+      return;
+    };
+    return {
+      start: noop,
+      stop: noop,
+      succeed: noop,
+      fail: noop
+    };
+  }
+  const start = async () => {
+    const { default: ora } = await import("ora");
+    return ora(text).start();
+  };
+  return { start };
+}
 
 // src/commands/auth.ts
 init_errors();
@@ -1779,12 +1813,10 @@ async function runIntegrationPath() {
     name: "framework",
     message: "Which AI framework are you using?",
     choices: [
-      { name: "Mastra", value: "mastra" },
       { name: "LangChain", value: "langchain" },
       { name: "LangGraph", value: "langgraph" },
       { name: "Vercel AI SDK", value: "vercel-ai" },
-      { name: "Claude Code", value: "claude-code" },
-      { name: "Other / Generic", value: "generic" }
+      { name: "OpenAI SDK", value: "openai" }
     ]
   }]);
   console.log("");
@@ -2419,17 +2451,39 @@ function isValidJsonSchema(schema) {
 function buildSchemaFromVariables(variables) {
   const properties = {};
   for (const variable of variables) {
-    const prop = { type: variable.type };
-    if (variable.description) {
-      prop.description = variable.description;
-    }
-    properties[variable.name] = prop;
+    properties[variable.name] = {
+      type: variable.type,
+      description: variable.description
+    };
   }
   return {
     type: "object",
     properties
   };
 }
+function validateSchemaDescriptions(schema) {
+  if (schema === null || schema === undefined)
+    return [];
+  if (typeof schema !== "object" || Array.isArray(schema))
+    return [];
+  const obj = schema;
+  const properties = obj.properties;
+  if (!properties || typeof properties !== "object" || Array.isArray(properties))
+    return [];
+  const missing = [];
+  const props = properties;
+  for (const [key, value] of Object.entries(props)) {
+    if (value === null || value === undefined || typeof value !== "object") {
+      missing.push(key);
+      continue;
+    }
+    const prop = value;
+    if (typeof prop.description !== "string" || prop.description.trim() === "") {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
 function formatSchemaWarning(fieldName) {
   return [
     `${fieldName} doesn't appear to be a valid JSON Schema.`,
@@ -2534,9 +2588,17 @@ async function runGuidedEvalCreator(promptId) {
       }
     }]);
     let targetField;
-    if (allFields.length > 0) {
+    const usedParams = new Set(criteria.map((c) => c.evaluationParameter));
+    const availableFields = allFields.filter((f) => {
+      const param = f.startsWith("output.") ? f.slice("output.".length) : f.startsWith("input.") ? f.slice("input.".length) : f;
+      return !usedParams.has(param);
+    });
+    if (availableFields.length === 0 && allFields.length > 0) {
+      console.log(chalk5.yellow("  All detected schema fields are already used by existing criteria."));
+    }
+    if (availableFields.length > 0) {
       const fieldChoices = [
-        ...allFields.map((f) => ({ name: f, value: f })),
+        ...availableFields.map((f) => ({ name: f, value: f })),
         { name: "(custom field name)", value: "__custom__" }
       ];
       const { field } = await inquirer3.prompt([{
@@ -2593,10 +2655,15 @@ async function runGuidedEvalCreator(promptId) {
     } else {
       scoringRubric = rubric;
     }
+    const evaluationParameter = targetField.startsWith("output.") ? targetField.slice("output.".length) : targetField.startsWith("input.") ? targetField.slice("input.".length) : targetField;
+    if (criteria.some((c) => c.evaluationParameter === evaluationParameter)) {
+      console.log(chalk5.red(`  Error: "${evaluationParameter}" is already used by another criterion. Each criterion must target a unique output field.`));
+      continue;
+    }
     criteria.push({
       name: criterionName.trim(),
-      targetField,
-      scoringRubric,
+      description: scoringRubric,
+      evaluationParameter,
       weight: 1
     });
     const { continueAdding } = await inquirer3.prompt([{
@@ -2618,7 +2685,7 @@ async function runGuidedEvalCreator(promptId) {
   console.log(`    Type: ${evalType}`);
   console.log(`    Criteria: ${String(criteria.length)}`);
   for (const c of criteria) {
-    console.log(`      - ${chalk5.cyan(c.name)} → ${c.targetField}`);
+    console.log(`      - ${chalk5.cyan(c.name)} → ${c.evaluationParameter}`);
   }
   console.log("");
   const { confirmed } = await inquirer3.prompt([{
@@ -2691,6 +2758,38 @@ function renderScorecard(data) {
   console.log(line(`  Prompt: ${chalk6.cyan(truncateText(optimizedText, 38))}`));
   console.log(line(`  Score:  ${formatScore(bestScore)}${formatScoreChange(originalScore, bestScore)}`));
   console.log(separator);
+  if (data.criteriaScores && data.criteriaScores.length > 0) {
+    console.log(line(chalk6.dim("  Criterion         Before    After    Change")));
+    console.log(line(chalk6.dim("  " + "─".repeat(45))));
+    for (const c of data.criteriaScores) {
+      const name = c.name.length > 16 ? c.name.substring(0, 13) + "..." : c.name;
+      const paddedName = name + " ".repeat(18 - name.length);
+      const beforeStr = c.before !== undefined ? c.before.toFixed(2) : "N/A ";
+      const afterStr = c.after !== undefined ? c.after.toFixed(2) : "N/A ";
+      const changeStr = c.before !== undefined && c.after !== undefined && c.before > 0 ? (() => {
+        const pct = Math.round((c.after - c.before) / c.before * 100);
+        if (pct > 0)
+          return chalk6.green(`+${String(pct)}%`);
+        if (pct < 0)
+          return chalk6.red(`${String(pct)}%`);
+        return chalk6.dim("0%");
+      })() : "";
+      console.log(line(`  ${paddedName}${beforeStr}      ${afterStr}     ${changeStr}`));
+    }
+    console.log(line(chalk6.dim("  " + "─".repeat(45))));
+    const overallBefore = originalScore !== undefined ? originalScore.toFixed(2) : "N/A ";
+    const overallAfter = bestScore !== undefined ? bestScore.toFixed(2) : "N/A ";
+    const overallChange = originalScore !== undefined && bestScore !== undefined && originalScore > 0 ? (() => {
+      const pct = Math.round((bestScore - originalScore) / originalScore * 100);
+      if (pct > 0)
+        return chalk6.green(`+${String(pct)}%`);
+      if (pct < 0)
+        return chalk6.red(`${String(pct)}%`);
+      return chalk6.dim("0%");
+    })() : "";
+    console.log(line(`  ${"Overall" + " ".repeat(11)}${overallBefore}      ${overallAfter}     ${overallChange}`));
+    console.log(separator);
+  }
   const statusStr = job.status === "completed" ? chalk6.green("completed") : chalk6.yellow(job.status);
   console.log(line(`Status: ${statusStr}  |  Iterations: ${String(iterations)}`));
   if (job.config?.model) {
@@ -2699,19 +2798,16 @@ function renderScorecard(data) {
   if (data.scoreProgression && data.scoreProgression.length > 0) {
     console.log(line(""));
     console.log(line(chalk6.dim("Score Progression:")));
-    const progression = data.scoreProgression.map((s, i) => `#${String(i + 1)}: ${s.toFixed(2)}`).join("  ");
-    if (progression.length > boxWidth - 4) {
-      const mid = Math.ceil(data.scoreProgression.length / 2);
-      const line1 = data.scoreProgression.slice(0, mid).map((s, i) => `#${String(i + 1)}: ${s.toFixed(2)}`).join("  ");
-      const line2 = data.scoreProgression.slice(mid).map((s, i) => `#${String(i + mid + 1)}: ${s.toFixed(2)}`).join("  ");
-      console.log(line(chalk6.dim(line1)));
-      console.log(line(chalk6.dim(line2)));
-    } else {
-      console.log(line(chalk6.dim(progression)));
+    const barWidth = 10;
+    for (let i = 0;i < data.scoreProgression.length; i++) {
+      const s = data.scoreProgression[i] ?? 0;
+      const filled = Math.round(s * barWidth);
+      const bar = "█".repeat(filled) + "░".repeat(barWidth - filled);
+      console.log(line(chalk6.dim(`  #${String(i + 1)}: ${bar} ${s.toFixed(2)}`)));
     }
   }
   console.log(separator);
-  console.log(line(`Dashboard: ${chalk6.underline(optimizerLink(job.jobId))}`));
+  console.log(line(`Dashboard: ${chalk6.underline(optimizerLink(job.id))}`));
   console.log(bottomBorder);
   console.log("");
 }
@@ -2747,7 +2843,7 @@ function updateMutationContext(updater) {
   } catch {}
 }
 var PREREQUISITES_TEXT = `
-${chalk7.yellow("Prerequisites:")}
+${chalk7.red("Prerequisites (required):")}
   1. Evaluation criteria defined  ${chalk7.dim("(via dashboard or evaluation create)")}
   2. Dataset uploaded             ${chalk7.dim("mutagent prompts dataset list <prompt-id>")}
   ${chalk7.dim("Note: LLM provider config is only required when the server uses external providers (USE_EXT_PROVIDERS=true)")}`;
@@ -2780,18 +2876,6 @@ function isSchemaEmpty(schema) {
     return true;
   return false;
 }
-function warnMissingSchemas(data, output) {
-  if (isSchemaEmpty(data.inputSchema)) {
-    output.warn("No inputSchema provided. Optimization requires inputSchema with defined variables.");
-  } else if (!isValidJsonSchema(data.inputSchema)) {
-    output.warn(formatSchemaWarning("inputSchema"));
-  }
-  if (isSchemaEmpty(data.outputSchema)) {
-    output.warn("No outputSchema provided. This may limit optimization effectiveness.");
-  } else if (!isValidJsonSchema(data.outputSchema)) {
-    output.warn(formatSchemaWarning("outputSchema"));
-  }
-}
 async function collectSchemaInteractively() {
   const inquirer3 = (await import("inquirer")).default;
   const variables = [];
@@ -2820,13 +2904,18 @@ async function collectSchemaInteractively() {
       {
         type: "input",
         name: "description",
-        message: "Description (optional):"
+        message: "Description (required):",
+        validate: (input) => {
+          if (!input.trim())
+            return "Variable description is required";
+          return true;
+        }
       }
     ]);
     variables.push({
       name: answers.name.trim(),
       type: answers.type,
-      description: answers.description.trim() || undefined
+      description: answers.description.trim()
     });
     const continueAnswer = await inquirer3.prompt([{
       type: "confirm",
@@ -2938,7 +3027,7 @@ Examples:
 Subcommands:
   list, get, create, update, delete
   dataset list|add|remove
-  evaluation list|create|results
+  evaluation list|create|delete|results
   optimize start|status|results
     `);
   prompts.command("list").description("List all prompts").option("-l, --limit <n>", "Limit results", "50").addHelpText("after", `
@@ -2963,14 +3052,22 @@ ${chalk7.dim("Tip: Use --json for machine-readable output (AI agents, CI pipelin
         }));
         output.output(withLinks);
       } else {
-        const formatted = limited.map((p) => ({
-          id: p.id,
-          name: p.name,
-          version: p.version,
-          updated: p.updatedAt ? new Date(p.updatedAt).toLocaleDateString() : "N/A",
-          url: promptLink(p.id)
-        }));
-        output.output(formatted);
+        const wsId = client.getCurrentWorkspaceId();
+        if (wsId) {
+          output.info(`Workspace: ${wsId}`);
+        }
+        if (limited.length === 0) {
+          output.info("No prompts found in current workspace. Run 'mutagent config list' to check workspace context.");
+        } else {
+          const formatted = limited.map((p) => ({
+            id: p.id,
+            name: p.name,
+            version: p.version,
+            updated: p.updatedAt ? new Date(p.updatedAt).toLocaleDateString() : "N/A",
+            url: promptLink(p.id)
+          }));
+          output.output(formatted);
+        }
       }
     } catch (error) {
       handleError(error, isJson);
@@ -3008,20 +3105,24 @@ ${chalk7.dim("Tip: Combine --with-datasets and --with-evals to fetch all nested
   });
   prompts.command("create").description("Create a new prompt").option("-d, --data <json>", "Prompt as JSON string (recommended — curl-style inline)").option("-f, --file <path>", "Create from JSON file").option("--raw-file <path>", "Create from plain text file (used as rawPrompt)").option("-n, --name <name>", "Prompt name").option("-c, --content <content>", "Prompt content (rawPrompt) [DEPRECATED: use --raw]").option("-r, --raw <text>", "Raw prompt text (single prompt)").option("--system <text>", "System prompt (use with --human)").option("--human <text>", "Human prompt (use with --system)").option("--messages <json>", `Messages array as JSON (e.g., '[{"role":"system","content":"..."}]')`).option("--output-schema <json>", "Output schema as JSON string (required for optimization)").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize","humanPrompt":"{{text}}","outputSchema":{"type":"object","properties":{"summary":{"type":"string"}}}}'
-  ${chalk7.dim("$")} mutagent prompts create --name "my-prompt" --system "You are helpful" --human "Hello" --output-schema '{"type":"object","properties":{"result":{"type":"string"}}}'
-  ${chalk7.dim("$")} mutagent prompts create --file prompt.json
-  ${chalk7.dim("$")} mutagent prompts create --name "raw-prompt" --raw "Summarize: {{text}}"
+  ${chalk7.dim("$")} mutagent prompts create --name "my-prompt" --system "You are helpful" --human "{{input}}" --output-schema '{"type":"object","properties":{"result":{"type":"string","description":"The result"}}}'
+  ${chalk7.dim("$")} mutagent prompts create --name "raw-prompt" --raw "Summarize: {{text}}" --output-schema '{"type":"object","properties":{"summary":{"type":"string","description":"Summary"}}}'
+  ${chalk7.dim("$")} mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize","humanPrompt":"{{text}}","outputSchema":{"type":"object","properties":{"summary":{"type":"string","description":"Summary"}}}}'
+  ${chalk7.dim("$")} mutagent prompts create --file prompt.json  ${chalk7.dim("# full prompt object as JSON file")}
 
 Prompt Input Methods (pick one, priority order):
-  -d, --data         Inline JSON object (recommended for CI/scripts)
-  --file             Load from JSON file (full prompt object)
-  --raw-file         Load plain text file as raw prompt
-  --system/--human   Structured system + user message pair
+  --system/--human   Structured system + user message pair ${chalk7.green("(recommended)")}
   --raw              Single raw prompt text with {{variables}}
+  -d, --data         Inline JSON object (CI/scripts/agents)
   --messages         Full messages array as JSON
+  --raw-file         Load plain text file as raw prompt
+  --file             Load from JSON file (full prompt object)
+
+Expected JSON (--data):
+  ${chalk7.dim(`'{"name":"my-prompt","systemPrompt":"You are...","humanPrompt":"{{input}}","outputSchema":{"type":"object","properties":{"result":{"type":"string","description":"The result"}}},"inputSchema":{"type":"object","properties":{"input":{"type":"string","description":"User input"}}}}'`)}
 
-${chalk7.dim("Note: --data and --file are mutually exclusive. outputSchema is required (include in --data/--file or use --output-schema).")}
+${chalk7.yellow("Note: Prefer --system/--human or --data over --file to avoid stale files living in your repo.")}
+${chalk7.red("outputSchema is required.")} ${chalk7.dim("--data and --file are mutually exclusive.")}
     `).action(async (options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -3120,17 +3221,32 @@ ${chalk7.dim("Note: --data and --file are mutually exclusive. outputSchema is re
           if (schema) {
             data.inputSchema = schema;
           }
-        } else {
-          output.warn("No inputSchema provided. Optimization requires inputSchema with defined variables.");
         }
       }
-      warnMissingSchemas(data, output);
+      if (isSchemaEmpty(data.inputSchema)) {
+        throw new MutagentError("VALIDATION_ERROR", "inputSchema is required. Optimization cannot run without defined input variables.", `Provide inputSchema via --data, --file, or interactive mode. Example:
+  --data '{"inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"User query"}}}}'
+Or use interactive mode (TTY) to define variables step by step.`);
+      } else if (!isValidJsonSchema(data.inputSchema)) {
+        throw new MutagentError("VALIDATION_ERROR", "inputSchema is not a valid JSON Schema object.", formatSchemaWarning("inputSchema"));
+      } else {
+        const missingDescs = validateSchemaDescriptions(data.inputSchema);
+        if (missingDescs.length > 0) {
+          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
+        }
+      }
+      if (isSchemaEmpty(data.outputSchema)) {
+        output.warn("No outputSchema provided. This may limit optimization effectiveness.");
+      } else if (!isValidJsonSchema(data.outputSchema)) {
+        output.warn(formatSchemaWarning("outputSchema"));
+      }
       const client = getSDKClient();
       const prompt = await client.createPrompt(data);
       if (isJson) {
         output.output({ ...prompt, _links: promptLinks(prompt.id) });
       } else {
         output.success(`Created prompt: ${prompt.name} (id: ${String(prompt.id)})`);
+        output.info(`Workspace: ${client.getCurrentWorkspaceId() ?? "auto-inferred from API key"}`);
         const hints = formatCreationHints({
           resourceType: "Prompt",
           id: prompt.id,
@@ -3152,15 +3268,17 @@ ${chalk7.dim("Note: --data and --file are mutually exclusive. outputSchema is re
       handleError(error, isJson);
     }
   });
-  prompts.command("update").description("Update a prompt").argument("<id>", "Prompt ID (from: mutagent prompts list)").option("-d, --data <json>", "Update fields as JSON string (recommended — curl-style inline)").option("-f, --file <path>", "Update from JSON file").option("--raw-file <path>", "Update from plain text file (used as rawPrompt)").option("-n, --name <name>", "New name").option("-c, --content <content>", "New content (rawPrompt) [DEPRECATED: use --raw]").option("-r, --raw <text>", "Raw prompt text (single prompt)").option("--system <text>", "System prompt (use with --human)").option("--human <text>", "Human prompt (use with --system)").option("--messages <json>", `Messages array as JSON (e.g., '[{"role":"system","content":"..."}]')`).addHelpText("after", `
+  prompts.command("update").description("Update a prompt").argument("<id>", "Prompt ID (from: mutagent prompts list)").option("-d, --data <json>", "Update fields as JSON string (recommended — curl-style inline)").option("-f, --file <path>", "Update from JSON file").option("--raw-file <path>", "Update from plain text file (used as rawPrompt)").option("-n, --name <name>", "New name").option("-c, --content <content>", "New content (rawPrompt) [DEPRECATED: use --raw]").option("-r, --raw <text>", "Raw prompt text (single prompt)").option("--system <text>", "System prompt (use with --human)").option("--human <text>", "Human prompt (use with --system)").option("--messages <json>", `Messages array as JSON (e.g., '[{"role":"system","content":"..."}]')`).option("--input-schema <json>", "Input schema as JSON string").option("--input-schema-file <path>", "Input schema from JSON file").option("--output-schema <json>", "Output schema as JSON string").option("--output-schema-file <path>", "Output schema from JSON file").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated prompt"}'
+  ${chalk7.dim("$")} mutagent prompts update <id> --system "Updated system prompt" --human "{{input}}"
   ${chalk7.dim("$")} mutagent prompts update <id> --name "new-name"
-  ${chalk7.dim("$")} mutagent prompts update <id> --system "Updated system prompt"
-  ${chalk7.dim("$")} mutagent prompts update <id> --raw-file updated-prompt.txt
-  ${chalk7.dim("$")} mutagent prompts update <id> --file updated-prompt.json
+  ${chalk7.dim("$")} mutagent prompts update <id> --raw "Summarize: {{text}}"
+  ${chalk7.dim("$")} mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated prompt"}'
+  ${chalk7.dim("$")} mutagent prompts update <id> --input-schema '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'
+  ${chalk7.dim("$")} mutagent prompts update <id> --file updated-prompt.json  ${chalk7.dim("# full prompt object")}
 
-${chalk7.dim("Note: --data and --file are mutually exclusive. CLI flags (--name) override --data fields.")}
+${chalk7.yellow("Note: Prefer --system/--human or --data over --file to avoid stale files living in your repo.")}
+${chalk7.dim("--data and --file are mutually exclusive. CLI flags (--name) override --data fields.")}
     `).action(async (id, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -3214,8 +3332,52 @@ ${chalk7.dim("Note: --data and --file are mutually exclusive. CLI flags (--name)
           data.rawPrompt = options.content;
         }
       }
+      if (options.inputSchema && options.inputSchemaFile) {
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --input-schema and --input-schema-file together", "Use --input-schema for inline JSON or --input-schema-file for file-based input, not both");
+      }
+      if (options.inputSchema) {
+        try {
+          data.inputSchema = JSON.parse(options.inputSchema);
+        } catch {
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --input-schema flag", `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'`);
+        }
+      } else if (options.inputSchemaFile) {
+        if (!existsSync4(options.inputSchemaFile)) {
+          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.inputSchemaFile}`, "Check the file path and try again");
+        }
+        try {
+          data.inputSchema = JSON.parse(readFileSync4(options.inputSchemaFile, "utf-8"));
+        } catch {
+          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.inputSchemaFile}`, "Ensure the file contains valid JSON Schema");
+        }
+      }
+      if (options.outputSchema && options.outputSchemaFile) {
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --output-schema and --output-schema-file together", "Use --output-schema for inline JSON or --output-schema-file for file-based input, not both");
+      }
+      if (options.outputSchema) {
+        try {
+          data.outputSchema = JSON.parse(options.outputSchema);
+        } catch {
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --output-schema flag", `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"type":"string"}}}'`);
+        }
+      } else if (options.outputSchemaFile) {
+        if (!existsSync4(options.outputSchemaFile)) {
+          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.outputSchemaFile}`, "Check the file path and try again");
+        }
+        try {
+          data.outputSchema = JSON.parse(readFileSync4(options.outputSchemaFile, "utf-8"));
+        } catch {
+          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.outputSchemaFile}`, "Ensure the file contains valid JSON Schema");
+        }
+      }
+      if (data.inputSchema && isValidJsonSchema(data.inputSchema)) {
+        const missingDescs = validateSchemaDescriptions(data.inputSchema);
+        if (missingDescs.length > 0) {
+          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
+        }
+      }
       if (Object.keys(data).length === 0) {
-        throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", "Use --data, --file, --raw-file, --name, --raw, --system/--human, or --messages");
+        throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", "Use --data, --file, --raw-file, --name, --raw, --system/--human, --messages, --input-schema, or --output-schema");
       }
       const promptContent = data.rawPrompt ?? data.systemPrompt ?? data.humanPrompt ?? "";
       if (promptContent && !isJson) {
@@ -3277,12 +3439,15 @@ ${chalk7.dim("Tip: Use --force to skip confirmation (required for non-interactiv
       handleError(error, isJson);
     }
   });
-  const dataset = prompts.command("dataset").description("Manage datasets for prompts").addHelpText("after", `
+  const dataset = new Command3("dataset").description("Manage datasets for prompts").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts dataset list <prompt-id>
   ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> --file dataset.jsonl
   ${chalk7.dim("$")} mutagent prompts dataset remove <prompt-id> <dataset-id>
-    `);
+    `).action(() => {
+    dataset.help();
+  });
+  prompts.addCommand(dataset);
   dataset.command("list").description("List datasets for a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts dataset list <prompt-id>
@@ -3312,10 +3477,9 @@ Examples:
   });
   dataset.command("add").description("Add dataset to a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").option("-f, --file <path>", "Dataset file (JSON array, JSONL, or CSV)").option("-d, --data <json>", "Inline JSON array of dataset items").option("-n, --name <name>", "Dataset name (default: timestamped)").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> --file dataset.json
-  ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> --file dataset.jsonl --name "My Dataset"
-  ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> --file dataset.csv
   ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> -d '[{"input":{"text":"hello"},"expectedOutput":{"result":"world"}}]'
+  ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> -d '[{"input":{"text":"hello"},"expectedOutput":{"result":"world"}}]' --name "My Dataset"
+  ${chalk7.dim("$")} mutagent prompts dataset add <prompt-id> --file dataset.jsonl  ${chalk7.dim("# also supports .json, .csv")}
 
 Supported file formats:
   ${chalk7.dim(".json")}   JSON array of objects: [{"input": {...}, "expectedOutput": {...}}, ...]
@@ -3326,7 +3490,12 @@ Inline data format (-d):
   JSON array of objects, e.g.:
   ${chalk7.dim('[{"input": {"text": "hello"}, "expectedOutput": {"result": "world"}}]')}
 
-${chalk7.dim("Note: --file and -d are mutually exclusive. Provide one or the other.")}
+Expected item format:
+  ${chalk7.dim('{"input": {"<field>": "<value>"}, "expectedOutput": {"<field>": "<value>"}}')}
+
+${chalk7.red("Required: --data or --file must be provided.")}
+${chalk7.yellow("Note: Prefer -d/--data for inline JSON over --file to avoid stale files living in your repo.")}
+${chalk7.dim("--file and -d are mutually exclusive.")}
     `).action(async (promptId, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -3386,6 +3555,9 @@ ${chalk7.dim("Note: --file and -d are mutually exclusive. Provide one or the oth
         if (datasetResult.itemCount !== undefined && datasetResult.itemCount > 0) {
           output.info(`Items uploaded: ${String(datasetResult.itemCount)}`);
         }
+        if (datasetResult.missingExpectedOutputCount !== undefined && datasetResult.missingExpectedOutputCount > 0) {
+          output.warn(`${String(datasetResult.missingExpectedOutputCount)} of ${String(datasetResult.itemCount ?? 0)} items have no expectedOutput. Optimization may fail without expected outputs.`);
+        }
         const hints = formatCreationHints({
           resourceType: "Dataset",
           id: datasetResult.id,
@@ -3419,12 +3591,16 @@ Examples:
       handleError(error, isJson);
     }
   });
-  const evaluation = prompts.command("evaluation").description("Manage evaluations for prompts").addHelpText("after", `
+  const evaluation = new Command3("evaluation").description("Manage evaluations for prompts").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts evaluation list <prompt-id>
   ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --name "My Eval"
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id>
   ${chalk7.dim("$")} mutagent prompts evaluation results <run-id>
-    `);
+    `).action(() => {
+    evaluation.help();
+  });
+  prompts.addCommand(evaluation);
   evaluation.command("list").description("List evaluations for a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts evaluation list <prompt-id>
@@ -3454,17 +3630,19 @@ Examples:
   });
   evaluation.command("create").description("Create an evaluation configuration for a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").option("-d, --data <json>", "Evaluation as JSON string (recommended — curl-style inline)").option("-n, --name <name>", "Evaluation name (required unless --guided)").option("-f, --file <path>", "Load evaluation criteria from JSON file").option("--description <text>", "Evaluation description").option("--dataset <id>", "Dataset ID to associate (from: mutagent prompts dataset list)").option("--guided", "Interactive guided mode — build criteria step by step").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --guided
-  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --data '{"name":"Accuracy","evalConfig":{"criteria":[...]}}' --name "Accuracy"
-  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --name "Accuracy Check"
+  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --guided  ${chalk7.dim("# recommended: interactive walkthrough")}
+  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --name "Accuracy" -d '{"evalConfig":{"criteria":[{"name":"Accuracy","description":"Score 1.0 if output matches expected","evaluationParameter":"result"}]}}'
   ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --name "Full Eval" --file criteria.json --dataset <dataset-id>
-  ${chalk7.dim("$")} mutagent prompts evaluation create <prompt-id> --name "QA" --description "Quality assurance eval" --json
 
-Criteria file format (--file or --data):
-  ${chalk7.dim('{ "name": "...", "evalConfig": { "criteria": [...] }, "llmConfig": { "model": "gpt-4" } }')}
+Expected JSON (--data):
+  ${chalk7.dim('{"evalConfig":{"criteria":[{"name":"<name>","description":"<scoring rubric>","evaluationParameter":"<output field to score>"}]}}')}
+
+  ${chalk7.red("Each criterion MUST have: name, description, evaluationParameter")}
+  evaluationParameter maps to output schema fields (e.g., "result", "classification")
 
-${chalk7.dim("Note: --data and --file are mutually exclusive. CLI flags (--name, --description) override --data fields.")}
-${chalk7.dim("Tip: Use --guided for an interactive walkthrough of criteria creation.")}
+${chalk7.yellow("Note: Prefer --guided or --data over --file to avoid stale files living in your repo.")}
+${chalk7.red("Required: --name (unless --guided). Criteria must include evaluationParameter.")}
+${chalk7.dim("--data and --file are mutually exclusive. CLI flags (--name, --description) override --data fields.")}
 ${chalk7.dim("Get prompt IDs: mutagent prompts list | Get dataset IDs: mutagent prompts dataset list <prompt-id>")}
     `).action(async (promptId, options) => {
     const isJson = getJsonFlag(prompts);
@@ -3549,6 +3727,79 @@ ${chalk7.dim("Get prompt IDs: mutagent prompts list | Get dataset IDs: mutagent
         evalData.name = options.name;
       if (options.description)
         evalData.description = options.description;
+      const criteria = evalData.evalConfig?.criteria;
+      if (!criteria || !Array.isArray(criteria) || criteria.length === 0) {
+        let fieldsHint = "";
+        try {
+          const client2 = getSDKClient();
+          const prompt = await client2.getPrompt(promptId);
+          if (prompt.outputSchema && typeof prompt.outputSchema === "object") {
+            const props = prompt.outputSchema.properties;
+            if (props && typeof props === "object") {
+              const fields = Object.keys(props);
+              if (fields.length > 0) {
+                fieldsHint = `
+Detected output fields from prompt schema: ${fields.join(", ")}
+`;
+              }
+            }
+          }
+        } catch {}
+        throw new MutagentError("VALIDATION_ERROR", "Evaluation criteria are required. Provide criteria via --data, --file, or use --guided mode.", `Each criterion needs: name, description, evaluationParameter (the output field to score).
+` + fieldsHint + `
+Example JSON (--data flag):
+  --data '{"evalConfig":{"criteria":[{"name":"Accuracy","description":"Score 1.0 if output matches expected, 0.0 otherwise","evaluationParameter":"classification"}]}}'
+
+Or use --guided for interactive creation: mutagent prompts evaluation create <id> --guided`);
+      }
+      for (const c of criteria) {
+        const hasDescription = c.description ?? c.scoringRubric;
+        const hasEvalParam = c.evaluationParameter ?? c.targetField;
+        if (!c.name || !hasDescription || !hasEvalParam) {
+          const cName = typeof c.name === "string" ? c.name : "unnamed";
+          throw new MutagentError("VALIDATION_ERROR", `Criterion "${cName}" is missing required fields. Need: name, description (or scoringRubric), evaluationParameter (or targetField).`, 'evaluationParameter maps to the output field to evaluate (e.g., "classification", "riskLevel"). Use --guided for interactive creation.');
+        }
+        if (c.scoringRubric && !c.description) {
+          c.description = c.scoringRubric;
+          delete c.scoringRubric;
+        }
+        if (c.targetField && !c.evaluationParameter) {
+          const tf = c.targetField;
+          c.evaluationParameter = tf.startsWith("output.") ? tf.slice("output.".length) : tf.startsWith("input.") ? tf.slice("input.".length) : tf;
+          delete c.targetField;
+        }
+      }
+      const seenParams = new Set;
+      const duplicateParams = [];
+      for (const c of criteria) {
+        const param = c.evaluationParameter;
+        if (param) {
+          if (seenParams.has(param)) {
+            duplicateParams.push(param);
+          }
+          seenParams.add(param);
+        }
+      }
+      if (duplicateParams.length > 0) {
+        let availableFields = [];
+        try {
+          const client2 = getSDKClient();
+          const prompt = await client2.getPrompt(promptId);
+          if (prompt.outputSchema && typeof prompt.outputSchema === "object") {
+            const props = prompt.outputSchema.properties;
+            if (props && typeof props === "object") {
+              availableFields = Object.keys(props);
+            }
+          }
+        } catch {}
+        const uniqueDupes = [...new Set(duplicateParams)];
+        const fieldsHint = availableFields.length > 0 ? `
+Available output fields: ${availableFields.join(", ")}` : "";
+        throw new MutagentError("VALIDATION_ERROR", `Duplicate evaluationParameter: "${uniqueDupes.join('", "')}". Each criterion must target a unique output field.`, "Each criterion scores a different output field. Fix by changing the evaluationParameter to a unique field." + fieldsHint + `
+
+Example:
+  --data '{"evalConfig":{"criteria":[{"name":"Accuracy","description":"...","evaluationParameter":"classification"},{"name":"Confidence","description":"...","evaluationParameter":"confidence"}]}}'`);
+      }
       if (options.dataset) {
         evalData.datasetId = parseInt(options.dataset, 10);
         if (isNaN(evalData.datasetId)) {
@@ -3596,15 +3847,37 @@ Examples:
       handleError(error, isJson);
     }
   });
-  const optimize = prompts.command("optimize").description("Manage prompt optimization jobs").addHelpText("after", `
+  evaluation.command("delete").description("Delete an evaluation").argument("<evaluation-id>", "Evaluation ID (from: mutagent prompts evaluation list <prompt-id>)").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id>
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id> --json
+    `).action(async (evaluationId) => {
+    const isJson = getJsonFlag(prompts);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const client = getSDKClient();
+      await client.deleteEvaluation(evaluationId);
+      if (isJson) {
+        output.output({ success: true, message: "Evaluation deleted successfully", evaluationId });
+      } else {
+        output.success(`Evaluation ${evaluationId} deleted successfully`);
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+  const optimize = new Command3("optimize").description("Manage prompt optimization jobs").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id>
   ${chalk7.dim("$")} mutagent prompts optimize status <job-id>
   ${chalk7.dim("$")} mutagent prompts optimize results <job-id>
 
 Workflow: start -> status (poll) -> results
-    `);
-  optimize.command("start").description("Start prompt optimization").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").requiredOption("-d, --dataset <id>", "Dataset ID for optimization (from: mutagent prompts dataset list <prompt-id>)").option("--max-iterations <n>", "Max optimization iterations (default: 3)").option("--target-score <n>", "Target accuracy 0-1 (e.g., 0.9)").option("--patience <n>", "Iterations without improvement before stopping").option("--model <model-id>", 'Target LLM model (e.g., "claude-sonnet-4-5-20250929")').option("--eval-model <model-id>", "Evaluation model (defaults to target model)").addHelpText("after", `
+    `).action(() => {
+    optimize.help();
+  });
+  prompts.addCommand(optimize);
+  optimize.command("start").description("Start prompt optimization").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").requiredOption("-d, --dataset <id>", "Dataset ID for optimization (from: mutagent prompts dataset list <prompt-id>)").option("--max-iterations <n>", "Max optimization iterations (default: 1)").option("--target-score <n>", "Target accuracy 0-1 (default: 0.8)").option("--patience <n>", "Iterations without improvement before stopping").option("--model <model-id>", 'Target LLM model (e.g., "claude-sonnet-4-5-20250929")').option("--eval-model <model-id>", "Evaluation model (defaults to target model)").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id>
   ${chalk7.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --max-iterations 5
@@ -3613,11 +3886,45 @@ Examples:
 ${PREREQUISITES_TEXT}
 
 ${chalk7.dim("Monitor progress with: mutagent prompts optimize status <job-id>")}
+
+${chalk7.dim("AI Agent Note: After running commands, present CLI output to the user as a status report. Use --json for structured parsing.")}
     `).action(async (promptId, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       const client = getSDKClient();
+      if (!isJson) {
+        output.info("Running pre-flight checks...");
+        const prompt = await client.getPrompt(promptId);
+        if (isSchemaEmpty(prompt.outputSchema)) {
+          throw new MutagentError("MISSING_OUTPUT_SCHEMA", "Prompt is missing outputSchema — required for optimization", `Update your prompt: mutagent prompts update ${promptId} -d '{"outputSchema":{"type":"object","properties":{"result":{"type":"string"}}}}'`);
+        }
+        if (isSchemaEmpty(prompt.inputSchema)) {
+          output.warn("Prompt has no inputSchema. Optimization works best with defined input variables.");
+        }
+        try {
+          const evals = await client.listEvaluations(promptId);
+          if (evals.length === 0) {
+            throw new MutagentError("MISSING_EVALUATION", "No evaluations found for this prompt — required for optimization", `Create an evaluation: mutagent prompts evaluation create ${promptId} --guided`);
+          }
+          const validEvals = evals.filter((e) => {
+            const config = e.evalConfig;
+            const criteria = config?.criteria;
+            if (!criteria || criteria.length === 0)
+              return false;
+            return criteria.some((c) => c.evaluationParameter ?? c.targetField);
+          });
+          if (validEvals.length === 0) {
+            output.warn(`Evaluations exist but none have evaluationParameter set. Optimization works best with criteria targeting specific output fields. Re-create: mutagent prompts evaluation create ${promptId} --guided`);
+          } else {
+            output.info(`Found ${String(validEvals.length)} evaluation(s) with proper criteria.`);
+          }
+        } catch (e) {
+          if (e instanceof MutagentError)
+            throw e;
+          output.warn("Could not validate evaluations. Optimization will use default evaluation.");
+        }
+      }
       const job = await client.startOptimization(promptId, options.dataset, {
         maxIterations: options.maxIterations ? parseInt(options.maxIterations, 10) : undefined,
         targetScore: options.targetScore ? parseFloat(options.targetScore) : undefined,
@@ -3629,27 +3936,55 @@ ${chalk7.dim("Monitor progress with: mutagent prompts optimize status <job-id>")
         output.output({
           ...job,
           _links: {
-            dashboard: optimizerLink(job.jobId),
-            api: `/api/prompts/${promptId}/optimizations/${job.jobId}`
+            dashboard: optimizerLink(job.id),
+            api: `/api/prompts/${promptId}/optimizations/${job.id}`
           }
         });
       } else {
-        output.success(`Started optimization job: ${job.jobId}`);
+        output.success(`Started optimization job: ${job.id}`);
         const hints = formatCreationHints({
           resourceType: "Optimization",
-          id: job.jobId,
-          dashboardUrl: optimizerLink(job.jobId),
-          apiPath: `/api/prompts/${promptId}/optimizations/${job.jobId}`
+          id: job.id,
+          dashboardUrl: optimizerLink(job.id),
+          apiPath: `/api/prompts/${promptId}/optimizations/${job.id}`
         });
         console.log(hints);
       }
     } catch (error) {
       if (error instanceof ApiError) {
         const messages = parseValidationErrors(error);
+        const errorText = messages.join(" ");
+        const suggestions = [];
+        if (errorText.includes("Output Schema is not present") || errorText.includes("outputSchema")) {
+          suggestions.push(`Update prompt: mutagent prompts update ${promptId} -d '{"outputSchema":{"type":"object","properties":{...}}}'`);
+        }
+        if (errorText.includes("Outputs are not valid") || errorText.includes("Parameters Mismatch")) {
+          suggestions.push("Dataset items may not match the prompt schema. Check expectedOutput fields in your dataset.");
+        }
+        if (errorText.includes("Inputs are not valid")) {
+          suggestions.push("Dataset item inputs don't match the prompt's inputSchema. Verify field names and types.");
+        }
+        if (errorText.includes("has no items") || errorText.includes("Dataset") && errorText.includes("not found")) {
+          suggestions.push(`Upload data: mutagent prompts dataset add ${promptId} --file data.json`);
+        }
+        if (errorText.includes("Evaluations are not present")) {
+          suggestions.push(`Create evaluation: mutagent prompts evaluation create ${promptId} --guided`);
+        }
+        if (errorText.includes("Trial") && errorText.includes("limit")) {
+          suggestions.push("Trial optimization limit reached. Contact support to upgrade.");
+        }
         if (!isJson) {
-          console.error(chalk7.red("Optimization failed. Missing requirements:"));
+          console.error(chalk7.red(`
+Optimization failed:`));
           for (const msg of messages) {
-            console.error(chalk7.red(`  - ${msg}`));
+            console.error(chalk7.red(`  ${msg}`));
+          }
+          if (suggestions.length > 0) {
+            console.error(chalk7.yellow(`
+Suggested fixes:`));
+            for (const s of suggestions) {
+              console.error(chalk7.yellow(`  → ${s}`));
+            }
           }
           console.error("");
           console.error(PREREQUISITES_TEXT);
@@ -3894,235 +4229,179 @@ ${chalk8.dim("Exports to stdout by default. Use --output to save to a file.")}
 init_config();
 import { Command as Command5 } from "commander";
 import chalk9 from "chalk";
-import { writeFileSync as writeFileSync3, existsSync as existsSync11 } from "fs";
+import { writeFileSync as writeFileSync3, existsSync as existsSync9 } from "fs";
 import { execSync } from "child_process";
 init_errors();
 
-// src/lib/integrations/mastra.ts
+// src/lib/integrations/langchain.ts
 import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
-function renderPrerequisites(config) {
-  const keyPreview = config.apiKey.slice(0, 8) + "..." + config.apiKey.slice(-4);
-  return `✓ MUTAGENT_API_KEY: ${keyPreview}
-✓ MUTAGENT_ENDPOINT: ${config.endpoint}
-✓ API Connection: Verified`;
-}
-var mastraIntegration = {
-  name: "mastra",
-  description: "Mastra AI framework",
+var langchainIntegration = {
+  name: "langchain",
+  description: "LangChain framework",
   async detect() {
-    const files = ["mastra.config.ts", "mastra.config.js"];
-    const found = [];
-    for (const file of files) {
-      if (existsSync5(file)) {
-        found.push(file);
-      }
-    }
-    let hasMastraDep = false;
+    let hasLangchain = false;
     if (existsSync5("package.json")) {
       try {
         const pkg = JSON.parse(readFileSync5("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        hasMastraDep = "@mastra/core" in deps;
+        hasLangchain = "langchain" in deps || "@langchain/core" in deps;
       } catch {}
     }
     return {
-      detected: found.length > 0 || hasMastraDep,
-      confidence: found.length > 0 ? 0.95 : hasMastraDep ? 0.7 : 0,
-      files: found
+      detected: hasLangchain,
+      confidence: hasLangchain ? 0.9 : 0,
+      files: hasLangchain ? ["package.json"] : []
     };
   },
   async generate(config) {
     return `---
-name: mutagent-mastra-integration
-description: Integrate MutagenT with Mastra framework for prompt optimization and trace observability
-framework: mastra
+name: mutagent-langchain-integration
+description: Integrate MutagenT with LangChain for prompt optimization and trace observability
+framework: langchain
 version: 1.0.0
 ---
 
-# MutagenT + Mastra Integration
+# MutagenT + LangChain Integration
 
 ## Prerequisites Verification
 
-${renderPrerequisites(config)}
+- MUTAGENT_API_KEY: ${config.apiKey.slice(0, 8)}...${config.apiKey.slice(-4)}
+- MUTAGENT_ENDPOINT: ${config.endpoint}
+- API Connection: Verified
 
 ## Installation
 
 \`\`\`bash
-bun add @mutagent/sdk
+# The @mutagent/langchain package was installed automatically
+# If you need to install manually:
+bun add @mutagent/langchain
 # or
-npm install @mutagent/sdk
+npm install @mutagent/langchain
 \`\`\`
 
 ## Configuration
 
 ### 1. Environment Variables
 
-Add to your \`.env\` file:
-
 \`\`\`env
 MUTAGENT_API_KEY=${config.apiKey}
 MUTAGENT_ENDPOINT=${config.endpoint}
 \`\`\`
 
-### 2. Mastra Config Integration
-
-Update \`mastra.config.ts\`:
+### 2. LangChain Callback Handler
 
 \`\`\`typescript
-import { defineConfig } from '@mastra/core';
-import { MutagentObserver } from '@mutagent/sdk/mastra';
-
-export default defineConfig({
-  observers: [
-    new MutagentObserver({
-      apiKey: process.env.MUTAGENT_API_KEY!,
-      endpoint: process.env.MUTAGENT_ENDPOINT,
-      // Optional: auto-capture all agent traces
-      captureTraces: true,
-    })
-  ],
-});
-\`\`\`
-
-### 3. Per-Agent Configuration
+import { ChatOpenAI } from '@langchain/openai';
+import { MutagentCallbackHandler } from '@mutagent/langchain';
+import { initTracing } from '@mutagent/sdk/tracing';
 
-For specific agents only:
+// Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
+initTracing({
+  apiKey: process.env.MUTAGENT_API_KEY!,
+  endpoint: process.env.MUTAGENT_ENDPOINT,
+});
 
-\`\`\`typescript
-import { Agent } from '@mastra/core';
-import { withMutagent } from '@mutagent/sdk/mastra';
+// Create callback handler (no args needed — uses SDK tracing)
+const handler = new MutagentCallbackHandler();
 
-const agent = new Agent({
-  name: 'support-agent',
-  instructions: '...',
+const llm = new ChatOpenAI({
+  callbacks: [handler],
 });
 
-// Wrap with MutagenT observability
-export default withMutagent(agent, {
-  promptId: 'support-template',
-  autoOptimize: true,
-});
+const result = await llm.invoke('Hello world');
+// Traces automatically captured via LangChain callbacks
 \`\`\`
 
-## Usage
-
-### Trace Collection (Replaces Langfuse)
-
-All agent calls are automatically traced to MutagenT:
+### 3. Chain Integration
 
 \`\`\`typescript
-const result = await agent.generate('How do I reset my password?');
-// Trace automatically captured with latency, tokens, input/output
-\`\`\`
-
-### Prompt Optimization
+import { ChatOpenAI } from '@langchain/openai';
+import { PromptTemplate } from '@langchain/core/prompts';
+import { MutagentCallbackHandler } from '@mutagent/langchain';
 
-\`\`\`typescript
-import { optimizePrompt } from '@mutagent/sdk';
+const handler = new MutagentCallbackHandler();
 
-// Run optimization for a prompt
-const optimized = await optimizePrompt({
-  promptId: 'support-template',
-  datasetId: 'support-tickets',
-  metric: 'response_quality',
+const llm = new ChatOpenAI({
+  callbacks: [handler],
 });
 
-// Update agent with optimized prompt
-agent.instructions = optimized.content;
-\`\`\`
-
-### Manual Tracing
-
-For custom traces:
-
-\`\`\`typescript
-import { trace } from '@mutagent/sdk';
-
-const span = trace.start({
-  name: 'custom-operation',
-  promptId: 'my-prompt',
-});
+const template = PromptTemplate.fromTemplate('Answer the question: {question}');
+const chain = template.pipe(llm);
 
-try {
-  const result = await doSomething();
-  span.end({ output: result });
-} catch (error) {
-  span.error(error);
-}
+const result = await chain.invoke(
+  { question: 'What is TypeScript?' },
+  { callbacks: [handler] },
+);
 \`\`\`
 
 ## Migration from Langfuse
 
-Replace Langfuse imports:
+Replace Langfuse callback:
 
 \`\`\`typescript
 // Before
-import { Langfuse } from 'langfuse';
+import { CallbackHandler } from 'langfuse-langchain';
+const callbacks = [new CallbackHandler()];
 
 // After
-import { MutagentObserver } from '@mutagent/sdk/mastra';
+import { MutagentCallbackHandler } from '@mutagent/langchain';
+const callbacks = [new MutagentCallbackHandler()];
 \`\`\`
 
 ## Verification
 
-Run this to verify your integration:
-
 \`\`\`bash
-mutagent integrate mastra --verify
+mutagent integrate langchain --verify
 \`\`\`
 
-## Next Steps
+## Documentation
 
-1. Create your first prompt: \`mutagent prompts create --interactive\`
-2. Add a dataset: \`mutagent prompts datasets:add <prompt-id> --file data.jsonl\`
-3. Run optimization: \`mutagent prompts optimize <prompt-id> --dataset <dataset-id>\`
-4. View traces: \`mutagent traces list --prompt <prompt-id>\`
+- Full guide: https://docs.mutagent.io/integrations/langchain
+- API Reference: https://docs.mutagent.io/sdk/tracing
+- Dashboard: https://app.mutagent.io
 
-## CLI Commands Reference
+## CLI Reference
 
 \`\`\`bash
-# List prompts
-mutagent prompts list
-
-# Get prompt with traces
-mutagent prompts get <id> --with-datasets
+# View traces
+mutagent traces list --prompt <prompt-id>
 
-# Analyze traces
+# Analyze performance
 mutagent traces analyze <prompt-id>
 \`\`\`
 `;
   }
 };
 
-// src/lib/integrations/langchain.ts
+// src/lib/integrations/langgraph.ts
 import { readFileSync as readFileSync6, existsSync as existsSync6 } from "fs";
-var langchainIntegration = {
-  name: "langchain",
-  description: "LangChain framework",
+var langgraphIntegration = {
+  name: "langgraph",
+  description: "LangGraph agent workflow framework",
   async detect() {
-    let hasLangchain = false;
+    let hasLanggraph = false;
     if (existsSync6("package.json")) {
       try {
         const pkg = JSON.parse(readFileSync6("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        hasLangchain = "langchain" in deps || "@langchain/core" in deps;
+        hasLanggraph = "@langchain/langgraph" in deps;
       } catch {}
     }
     return {
-      detected: hasLangchain,
-      confidence: hasLangchain ? 0.9 : 0,
-      files: hasLangchain ? ["package.json"] : []
+      detected: hasLanggraph,
+      confidence: hasLanggraph ? 0.95 : 0,
+      files: hasLanggraph ? ["package.json"] : []
     };
   },
   async generate(config) {
     return `---
-name: mutagent-langchain-integration
-description: Integrate MutagenT with LangChain for prompt optimization and trace observability
-framework: langchain
-version: 1.0.0
+name: mutagent-langgraph-integration
+description: Integrate MutagenT with LangGraph for agent workflow observability
+framework: langgraph
+version: 2.0.0
 ---
 
-# MutagenT + LangChain Integration
+# MutagenT + LangGraph Integration
 
 ## Prerequisites Verification
 
@@ -4130,173 +4409,51 @@ version: 1.0.0
 - MUTAGENT_ENDPOINT: ${config.endpoint}
 - API Connection: Verified
 
+> **Note**: LangGraph is built on LangChain. The same \`MutagentCallbackHandler\` from
+> \`@mutagent/langchain\` works for both LangChain and LangGraph — no separate package needed.
+
 ## Installation
 
 \`\`\`bash
-# The @mutagent/langchain package was installed automatically
-# If you need to install manually:
-bun add @mutagent/langchain
+bun add @mutagent/langchain @mutagent/sdk
 # or
-npm install @mutagent/langchain
+npm install @mutagent/langchain @mutagent/sdk
 \`\`\`
 
-## Configuration
-
-### 1. Environment Variables
-
-\`\`\`env
-MUTAGENT_API_KEY=${config.apiKey}
-MUTAGENT_ENDPOINT=${config.endpoint}
-\`\`\`
+> **Deprecation Notice**: The \`@mutagent/langgraph\` package is deprecated.
+> Use \`@mutagent/langchain\` instead — it supports both LangChain and LangGraph.
 
-### 2. LangChain Callback Handler
+## Integration
 
 \`\`\`typescript
-import { ChatOpenAI } from '@langchain/openai';
 import { MutagentCallbackHandler } from '@mutagent/langchain';
 import { initTracing } from '@mutagent/sdk/tracing';
 
-// Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: process.env.MUTAGENT_ENDPOINT,
-});
-
-// Create callback handler (no args needed — uses SDK tracing)
-const handler = new MutagentCallbackHandler();
+// Initialize tracing (once at app startup)
+initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
 
-const llm = new ChatOpenAI({
-  callbacks: [handler],
+// Create the handler
+const handler = new MutagentCallbackHandler({
+  sessionId: 'my-session',  // optional
+  userId: 'user-123',       // optional
 });
 
-const result = await llm.invoke('Hello world');
-// Traces automatically captured via LangChain callbacks
+// Pass to any LangGraph invoke/stream call
+const result = await graph.invoke(input, { callbacks: [handler] });
 \`\`\`
 
-### 3. Chain Integration
+## Full Graph Example
 
 \`\`\`typescript
+import { StateGraph, Annotation } from '@langchain/langgraph';
 import { ChatOpenAI } from '@langchain/openai';
-import { PromptTemplate } from '@langchain/core/prompts';
 import { MutagentCallbackHandler } from '@mutagent/langchain';
-
-const handler = new MutagentCallbackHandler();
-
-const llm = new ChatOpenAI({
-  callbacks: [handler],
-});
-
-const template = PromptTemplate.fromTemplate('Answer the question: {question}');
-const chain = template.pipe(llm);
-
-const result = await chain.invoke(
-  { question: 'What is TypeScript?' },
-  { callbacks: [handler] },
-);
-\`\`\`
-
-## Migration from Langfuse
-
-Replace Langfuse callback:
-
-\`\`\`typescript
-// Before
-import { CallbackHandler } from 'langfuse-langchain';
-const callbacks = [new CallbackHandler()];
-
-// After
-import { MutagentCallbackHandler } from '@mutagent/langchain';
-const callbacks = [new MutagentCallbackHandler()];
-\`\`\`
-
-## Verification
-
-\`\`\`bash
-mutagent integrate langchain --verify
-\`\`\`
-
-## Documentation
-
-- Full guide: https://docs.mutagent.io/integrations/langchain
-- API Reference: https://docs.mutagent.io/sdk/tracing
-- Dashboard: https://app.mutagent.io
-
-## CLI Reference
-
-\`\`\`bash
-# View traces
-mutagent traces list --prompt <prompt-id>
-
-# Analyze performance
-mutagent traces analyze <prompt-id>
-\`\`\`
-`;
-  }
-};
-
-// src/lib/integrations/langgraph.ts
-import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
-var langgraphIntegration = {
-  name: "langgraph",
-  description: "LangGraph agent workflow framework",
-  async detect() {
-    let hasLanggraph = false;
-    if (existsSync7("package.json")) {
-      try {
-        const pkg = JSON.parse(readFileSync7("package.json", "utf-8"));
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        hasLanggraph = "@langchain/langgraph" in deps;
-      } catch {}
-    }
-    return {
-      detected: hasLanggraph,
-      confidence: hasLanggraph ? 0.95 : 0,
-      files: hasLanggraph ? ["package.json"] : []
-    };
-  },
-  async generate(config) {
-    return `---
-name: mutagent-langgraph-integration
-description: Integrate MutagenT with LangGraph for agent workflow observability
-framework: langgraph
-version: 1.0.0
----
-
-# MutagenT + LangGraph Integration
-
-## Prerequisites Verification
-
-- MUTAGENT_API_KEY: ${config.apiKey.slice(0, 8)}...${config.apiKey.slice(-4)}
-- MUTAGENT_ENDPOINT: ${config.endpoint}
-- API Connection: Verified
-
-## Installation
-
-\`\`\`bash
-# The @mutagent/langgraph package was installed automatically
-# If you need to install manually:
-bun add @mutagent/langgraph
-# or
-npm install @mutagent/langgraph
-\`\`\`
-
-## Configuration
-
-### Graph with MutagenT Tracer
-
-\`\`\`typescript
-import { StateGraph, Annotation } from '@langchain/langgraph';
-import { MutagentGraphTracer } from '@mutagent/langgraph';
 import { initTracing } from '@mutagent/sdk/tracing';
 
-// Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: process.env.MUTAGENT_ENDPOINT,
-});
+// Initialize tracing (once at app startup)
+initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
 
-// Create tracer (no args needed — uses SDK tracing)
-const tracer = new MutagentGraphTracer();
+const handler = new MutagentCallbackHandler();
 
 // Define your graph as usual
 const StateAnnotation = Annotation.Root({
@@ -4310,29 +4467,24 @@ const graph = new StateGraph(StateAnnotation)
   .addEdge('__start__', 'agent')
   .compile();
 
-// Use lifecycle methods for tracing
-tracer.handleGraphStart('agent-workflow', { input: 'Hello' });
-const result = await graph.invoke({ input: 'Hello' });
-tracer.handleGraphEnd({ output: result.output });
+// All nodes, edges, and LLM calls are automatically traced
+const result = await graph.invoke(
+  { input: 'Hello' },
+  { callbacks: [handler] },
+);
 \`\`\`
 
-### Per-Node and Edge Tracing
+## Streaming
 
 \`\`\`typescript
-// Track individual nodes
-tracer.handleNodeStart('agent', { query: 'Hello' });
-// ... node logic ...
-tracer.handleNodeEnd('agent', { result: 'response' });
-
-// Track edge transitions
-tracer.handleEdgeTransition('agent', 'tools', {
-  isConditional: true,
-  condition: 'needsTools',
-  conditionResult: true,
-});
+const handler = new MutagentCallbackHandler();
 
-tracer.handleNodeStart('tools', { toolName: 'search' });
-tracer.handleNodeEnd('tools', { result: 'found' });
+for await (const event of graph.stream(
+  { input: 'Hello' },
+  { callbacks: [handler] },
+)) {
+  console.log(event);
+}
 \`\`\`
 
 ## Verification
@@ -4346,30 +4498,20 @@ mutagent integrate langgraph --verify
 - Full guide: https://docs.mutagent.io/integrations/langgraph
 - API Reference: https://docs.mutagent.io/sdk/tracing
 - Dashboard: https://app.mutagent.io
-
-## CLI Commands
-
-\`\`\`bash
-# View workflow traces
-mutagent traces list --prompt <graph-id>
-
-# Analyze node performance
-mutagent traces analyze <node-prompt-id>
-\`\`\`
 `;
   }
 };
 
 // src/lib/integrations/vercel-ai.ts
-import { readFileSync as readFileSync8, existsSync as existsSync8 } from "fs";
+import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
 var vercelAiIntegration = {
   name: "vercel-ai",
   description: "Vercel AI SDK",
   async detect() {
     let hasAiSdk = false;
-    if (existsSync8("package.json")) {
+    if (existsSync7("package.json")) {
       try {
-        const pkg = JSON.parse(readFileSync8("package.json", "utf-8"));
+        const pkg = JSON.parse(readFileSync7("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         hasAiSdk = "ai" in deps;
       } catch {}
@@ -4385,7 +4527,7 @@ var vercelAiIntegration = {
 name: mutagent-vercel-ai-integration
 description: Integrate MutagenT with Vercel AI SDK for streaming and edge functions
 framework: vercel-ai
-version: 1.0.0
+version: 2.0.0
 ---
 
 # MutagenT + Vercel AI SDK Integration
@@ -4399,14 +4541,52 @@ version: 1.0.0
 ## Installation
 
 \`\`\`bash
-# The @mutagent/vercel-ai package was installed automatically
-# If you need to install manually:
-bun add @mutagent/vercel-ai
+bun add @mutagent/vercel-ai @mutagent/sdk
 # or
-npm install @mutagent/vercel-ai
+npm install @mutagent/vercel-ai @mutagent/sdk
+
+# For Option A (OTel SpanExporter), also install:
+bun add @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
 \`\`\`
 
-## Integration
+---
+
+## Option A (Recommended): OTel SpanExporter
+
+Uses Vercel AI SDK's built-in \`experimental_telemetry\` with an OpenTelemetry exporter
+that sends spans directly to MutagenT.
+
+\`\`\`typescript
+import { MutagentSpanExporter } from '@mutagent/vercel-ai';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { initTracing } from '@mutagent/sdk/tracing';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+// Initialize MutagenT tracing
+initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
+
+// Set up OTel with MutagenT exporter
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(new MutagentSpanExporter())
+);
+provider.register();
+
+// Use Vercel AI SDK normally with telemetry enabled
+const result = await generateText({
+  model: openai('gpt-4'),
+  prompt: 'Hello!',
+  experimental_telemetry: { isEnabled: true },
+});
+\`\`\`
+
+---
+
+## Option B (Alternative): Middleware
+
+Uses the Vercel AI SDK \`wrapLanguageModel\` middleware pattern.
 
 \`\`\`typescript
 // app/api/chat/route.ts
@@ -4415,13 +4595,10 @@ import { openai } from '@ai-sdk/openai';
 import { createMutagentMiddleware } from '@mutagent/vercel-ai';
 import { initTracing } from '@mutagent/sdk/tracing';
 
-// Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: process.env.MUTAGENT_ENDPOINT,
-});
+// Initialize tracing (once at app startup)
+initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
 
-// Create middleware (no args needed — uses SDK tracing)
+// Create middleware
 const middleware = createMutagentMiddleware();
 
 // Wrap your model with MutagenT middleware
@@ -4467,30 +4644,20 @@ mutagent integrate vercel-ai --verify
 - Full guide: https://docs.mutagent.io/integrations/vercel-ai
 - API Reference: https://docs.mutagent.io/sdk/tracing
 - Dashboard: https://app.mutagent.io
-
-## CLI Commands
-
-\`\`\`bash
-# View streaming traces
-mutagent traces list --prompt <prompt-id>
-
-# Export for analysis
-mutagent traces export --prompt <prompt-id> --format json
-\`\`\`
 `;
   }
 };
 
 // src/lib/integrations/openai.ts
-import { readFileSync as readFileSync9, existsSync as existsSync9 } from "fs";
+import { readFileSync as readFileSync8, existsSync as existsSync8 } from "fs";
 var openaiIntegration = {
   name: "openai",
   description: "OpenAI SDK integration with automatic tracing",
   async detect() {
     let hasOpenAI = false;
-    if (existsSync9("package.json")) {
+    if (existsSync8("package.json")) {
       try {
-        const pkg = JSON.parse(readFileSync9("package.json", "utf-8"));
+        const pkg = JSON.parse(readFileSync8("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         hasOpenAI = "openai" in deps;
       } catch {}
@@ -4506,7 +4673,7 @@ var openaiIntegration = {
 name: mutagent-openai-integration
 description: Integrate MutagenT with OpenAI SDK for automatic tracing
 framework: openai
-version: 1.0.0
+version: 2.0.0
 ---
 
 # MutagenT + OpenAI SDK Integration
@@ -4520,41 +4687,28 @@ version: 1.0.0
 ## Installation
 
 \`\`\`bash
-# The @mutagent/openai package was installed automatically
-# If you need to install manually:
-bun add @mutagent/openai
+bun add @mutagent/openai @mutagent/sdk
 # or
-npm install @mutagent/openai
-\`\`\`
-
-## Configuration
-
-### 1. Environment Variables
-
-\`\`\`env
-MUTAGENT_API_KEY=${config.apiKey}
-MUTAGENT_ENDPOINT=${config.endpoint}
-OPENAI_API_KEY=your-openai-api-key
+npm install @mutagent/openai @mutagent/sdk
 \`\`\`
 
-### 2. Traced OpenAI Client
+## Integration
 
 \`\`\`typescript
-import { MutagentOpenAI } from '@mutagent/openai';
+import OpenAI from 'openai';
+import { observeOpenAI } from '@mutagent/openai';
 import { initTracing } from '@mutagent/sdk/tracing';
 
-// Initialize tracing (or set MUTAGENT_API_KEY env var for auto-init)
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: process.env.MUTAGENT_ENDPOINT,
-});
+// Initialize tracing (once at app startup)
+initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
 
-// Create a traced OpenAI client (drop-in replacement for OpenAI)
-const openai = new MutagentOpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
+// Wrap the OpenAI client — ALL methods are automatically traced
+const openai = observeOpenAI(new OpenAI(), {
+  sessionId: 'my-session',  // optional
+  userId: 'user-123',       // optional
 });
 
-// All calls are automatically traced
+// Use exactly as normal — chat, embeddings, images, audio all work
 const completion = await openai.chat.completions.create({
   model: 'gpt-4o',
   messages: [{ role: 'user', content: 'Hello!' }],
@@ -4563,21 +4717,12 @@ const completion = await openai.chat.completions.create({
 console.log(completion.choices[0].message.content);
 \`\`\`
 
-## Usage Examples
+ALL OpenAI SDK methods are preserved and traced automatically.
+No API changes — just wrap your client and everything is observed.
 
-### Chat Completion
-
-\`\`\`typescript
-const response = await openai.chat.completions.create({
-  model: 'gpt-4o',
-  messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What is TypeScript?' },
-  ],
-});
-\`\`\`
+## Streaming
 
-### Streaming
+Streaming works out of the box with no extra configuration:
 
 \`\`\`typescript
 const stream = await openai.chat.completions.create({
@@ -4591,299 +4736,39 @@ for await (const chunk of stream) {
 }
 \`\`\`
 
-## Verification
-
-\`\`\`bash
-mutagent integrate openai --verify
-\`\`\`
-
-## Documentation
-
-- Full guide: https://docs.mutagent.io/integrations/openai
-- API Reference: https://docs.mutagent.io/sdk/tracing
-- Dashboard: https://app.mutagent.io
-
-## CLI Reference
-
-\`\`\`bash
-# View traces
-mutagent traces list --prompt <prompt-id>
-
-# Analyze performance
-mutagent traces analyze <prompt-id>
-
-# Export traces
-mutagent traces export --format json
-\`\`\`
-`;
-  }
-};
-
-// src/lib/integrations/claude-code.ts
-import { readFileSync as readFileSync10, existsSync as existsSync10 } from "fs";
-var claudeCodeIntegration = {
-  name: "claude-code",
-  description: "Claude Code SDK",
-  async detect() {
-    let hasClaudeCode = false;
-    if (existsSync10("package.json")) {
-      try {
-        const pkg = JSON.parse(readFileSync10("package.json", "utf-8"));
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        hasClaudeCode = "@anthropic-ai/claude-code" in deps || "@anthropic-ai/sdk" in deps;
-      } catch {}
-    }
-    return {
-      detected: hasClaudeCode,
-      confidence: hasClaudeCode ? 0.85 : 0,
-      files: hasClaudeCode ? ["package.json"] : []
-    };
-  },
-  async generate(config) {
-    return `---
-name: mutagent-claude-code-integration
-description: Integrate MutagenT with Claude Code SDK
-framework: claude-code
-version: 1.0.0
----
-
-# MutagenT + Claude Code SDK Integration
-
-## Prerequisites Verification
-
-✓ MUTAGENT_API_KEY: ${config.apiKey.slice(0, 8)}...${config.apiKey.slice(-4)}
-✓ MUTAGENT_ENDPOINT: ${config.endpoint}
-✓ API Connection: Verified
-
-## Installation
-
-\`\`\`bash
-bun add @mutagent/sdk
-\`\`\`
-
-## Basic Integration
+## Embeddings
 
 \`\`\`typescript
-import Anthropic from '@anthropic-ai/sdk';
-import { MutagentTracer } from '@mutagent/sdk/claude';
-
-const tracer = new MutagentTracer({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: process.env.MUTAGENT_ENDPOINT,
-  promptId: 'claude-prompt',
-});
-
-const anthropic = new Anthropic({
-  apiKey: process.env.ANTHROPIC_API_KEY!,
+const embedding = await openai.embeddings.create({
+  model: 'text-embedding-3-small',
+  input: 'Hello world',
 });
-
-// Wrap API calls
-const response = await tracer.wrap(
-  () => anthropic.messages.create({
-    model: 'claude-3-5-sonnet-20241022',
-    max_tokens: 1024,
-    messages: [{ role: 'user', content: 'Hello!' }],
-  })
-);
-\`\`\`
-
-## With Optimized Prompts
-
-\`\`\`typescript
-import { getOptimizedPrompt } from '@mutagent/sdk';
-
-const optimized = await getOptimizedPrompt('my-template');
-
-const response = await tracer.wrap(
-  () => anthropic.messages.create({
-    model: 'claude-3-5-sonnet-20241022',
-    system: optimized,
-    messages,
-  })
-);
-\`\`\`
-
-## MCP Server Integration
-
-For Claude Desktop / MCP:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "mutagent": {
-      "command": "npx",
-      "args": ["-y", "@mutagent/mcp-server"],
-      "env": {
-        "MUTAGENT_API_KEY": "${config.apiKey}"
-      }
-    }
-  }
-}
+// Embedding call is traced automatically
 \`\`\`
 
 ## Verification
 
 \`\`\`bash
-mutagent integrate claude-code --verify
-\`\`\`
-
-## CLI Commands
-
-\`\`\`bash
-# View Claude traces
-mutagent traces list --prompt <prompt-id>
-
-# Optimize Claude prompts
-mutagent prompts optimize <prompt-id> --dataset <dataset-id>
-\`\`\`
-`;
-  }
-};
-
-// src/lib/integrations/generic.ts
-var genericIntegration = {
-  name: "generic",
-  description: "Generic OpenAI-compatible integration",
-  async detect() {
-    return {
-      detected: false,
-      confidence: 0,
-      files: []
-    };
-  },
-  async generate(config) {
-    return `---
-name: mutagent-generic-integration
-description: Generic OpenAI-compatible API integration
-framework: generic
-version: 1.0.0
----
-
-# MutagenT + Generic (OpenAI-compatible) Integration
-
-## Prerequisites Verification
-
-✓ MUTAGENT_API_KEY: ${config.apiKey.slice(0, 8)}...${config.apiKey.slice(-4)}
-✓ MUTAGENT_ENDPOINT: ${config.endpoint}
-✓ API Connection: Verified
-
-## Installation
-
-\`\`\`bash
-bun add @mutagent/sdk
-\`\`\`
-
-## Fetch-based Integration
-
-\`\`\`typescript
-import { trace } from '@mutagent/sdk';
-
-async function callLLM(prompt: string) {
-  const span = trace.start({
-    name: 'llm-call',
-    promptId: 'my-prompt',
-    input: { prompt },
-  });
-
-  const start = Date.now();
-  
-  try {
-    const response = await fetch('https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Authorization': \`Bearer \${process.env.OPENAI_API_KEY}\`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        model: 'gpt-4o',
-        messages: [{ role: 'user', content: prompt }],
-      }),
-    });
-
-    const data = await response.json();
-    const latency = Date.now() - start;
-
-    span.end({
-      output: data,
-      latency,
-      tokens: {
-        input: data.usage?.prompt_tokens || 0,
-        output: data.usage?.completion_tokens || 0,
-      },
-    });
-
-    return data;
-  } catch (error) {
-    span.error(error);
-    throw error;
-  }
-}
-\`\`\`
-
-## With Optimized Prompts
-
-\`\`\`typescript
-import { getOptimizedPrompt } from '@mutagent/sdk';
-
-const optimized = await getOptimizedPrompt('template-id');
-const result = await callLLM(optimized);
-\`\`\`
-
-## OpenAI SDK Wrapper
-
-\`\`\`typescript
-import OpenAI from 'openai';
-import { wrapOpenAI } from '@mutagent/sdk/openai';
-
-const openai = wrapOpenAI(
-  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
-  {
-    mutagentApiKey: process.env.MUTAGENT_API_KEY!,
-    promptId: 'default',
-  }
-);
-
-// All calls are traced
-const completion = await openai.chat.completions.create({...});
-\`\`\`
-
-## Verification
-
-\`\`\`bash
-mutagent integrate generic --verify
+mutagent integrate openai --verify
 \`\`\`
 
-## CLI Commands
-
-\`\`\`bash
-# View traces
-mutagent traces list --prompt <prompt-id>
+## Documentation
 
-# Run evaluation
-mutagent prompts evals:run <prompt-id> --dataset <dataset-id>
-\`\`\`
+- Full guide: https://docs.mutagent.io/integrations/openai
+- API Reference: https://docs.mutagent.io/sdk/tracing
+- Dashboard: https://app.mutagent.io
 `;
   }
 };
 
 // src/lib/integrations/registry.ts
 var frameworkRegistry = new Map([
-  ["mastra", mastraIntegration],
   ["langchain", langchainIntegration],
   ["langgraph", langgraphIntegration],
   ["vercel-ai", vercelAiIntegration],
-  ["openai", openaiIntegration],
-  ["claude-code", claudeCodeIntegration],
-  ["generic", genericIntegration]
+  ["openai", openaiIntegration]
 ]);
 var frameworkMetadata = [
-  {
-    name: "mastra",
-    displayName: "Mastra",
-    description: "Modern AI agent framework with observability built-in",
-    npmPackage: "@mastra/core",
-    website: "https://mastra.ai"
-  },
   {
     name: "langchain",
     displayName: "LangChain",
@@ -4897,7 +4782,7 @@ var frameworkMetadata = [
     displayName: "LangGraph",
     description: "Agent workflow framework built on LangChain",
     npmPackage: "@langchain/langgraph",
-    mutagentPackage: "@mutagent/langgraph",
+    mutagentPackage: "@mutagent/langchain",
     website: "https://langchain-ai.github.io/langgraphjs/"
   },
   {
@@ -4915,20 +4800,6 @@ var frameworkMetadata = [
     npmPackage: "openai",
     mutagentPackage: "@mutagent/openai",
     website: "https://platform.openai.com"
-  },
-  {
-    name: "claude-code",
-    displayName: "Claude Code SDK",
-    description: "Native Anthropic integration for Claude",
-    npmPackage: "@anthropic-ai/claude-code",
-    website: "https://docs.anthropic.com"
-  },
-  {
-    name: "generic",
-    displayName: "Generic (OpenAI-compatible)",
-    description: "Any OpenAI-compatible API endpoint",
-    npmPackage: "openai",
-    website: "https://platform.openai.com"
   }
 ];
 function getFramework(name) {
@@ -4940,16 +4811,16 @@ function getFrameworkMetadata(name) {
 
 // src/commands/integrate.ts
 function detectPackageManager() {
-  if (existsSync11("bun.lockb") || existsSync11("bun.lock")) {
+  if (existsSync9("bun.lockb") || existsSync9("bun.lock")) {
     return "bun";
   }
-  if (existsSync11("pnpm-lock.yaml")) {
+  if (existsSync9("pnpm-lock.yaml")) {
     return "pnpm";
   }
-  if (existsSync11("yarn.lock")) {
+  if (existsSync9("yarn.lock")) {
     return "yarn";
   }
-  if (existsSync11("package-lock.json")) {
+  if (existsSync9("package-lock.json")) {
     return "npm";
   }
   try {
@@ -4978,8 +4849,6 @@ AI AGENT: Please determine the framework by:
 - \`@langchain/langgraph\` -> use \`mutagent integrate langgraph\`
 - \`ai\` (vercel) -> use \`mutagent integrate vercel-ai\`
 - \`openai\` -> use \`mutagent integrate openai\`
-- \`@mastra/core\` -> use \`mutagent integrate mastra\`
-- \`@anthropic-ai/claude-code\` -> use \`mutagent integrate claude-code\`
 
 ### Option 2: Ask the user
 "Which AI framework are you using?"
@@ -4987,9 +4856,6 @@ AI AGENT: Please determine the framework by:
 - LangGraph
 - Vercel AI SDK
 - OpenAI SDK
-- Mastra
-- Claude Code
-- Generic (OpenAI-compatible)
 
 ### Next Steps
 1. Once determined, run: \`mutagent integrate <framework>\`
@@ -5006,12 +4872,12 @@ Examples:
   ${chalk9.dim("$")} mutagent integrate langchain --output ./INTEGRATION.md
   ${chalk9.dim("$")} mutagent integrate --list          # List available frameworks
 
-Frameworks: mastra, langchain, langgraph, vercel-ai, openai, claude-code, generic
+Frameworks: langchain, langgraph, vercel-ai, openai
 
 This is a SKILL LOADER for AI coding agents (Claude Code, Cursor, etc.).
 It returns INSTRUCTIONS that AI agents execute - it does NOT auto-install packages.
     `);
-  integrate.argument("[framework]", "Framework name (mastra, langchain, langgraph, vercel-ai, openai, claude-code, generic)").option("-o, --output <path>", "Save instructions to file").option("--raw", "Output raw markdown (no formatting)").option("--verify", "Verify integration after setup").action(async (frameworkArg, options) => {
+  integrate.argument("[framework]", "Framework name (langchain, langgraph, vercel-ai, openai)").option("-o, --output <path>", "Save instructions to file").option("--raw", "Output raw markdown (no formatting)").option("--verify", "Verify integration after setup").action(async (frameworkArg, options) => {
     const isJson = getJsonFlag(integrate);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
@@ -5109,7 +4975,7 @@ AI AGENT: Execute these steps using Bash for install, Write/Edit for code change
 init_sdk_client();
 import { Command as Command6 } from "commander";
 import chalk10 from "chalk";
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 init_errors();
 function createAgentsCommand() {
   const agents = new Command6("agents").description("Manage AI agents").addHelpText("after", `
@@ -5220,20 +5086,48 @@ System Prompt:`));
       handleError(error, isJson);
     }
   });
-  agents.command("create").description("Create a new agent").option("-f, --file <path>", "Create from JSON file").option("-n, --name <name>", "Agent name").option("-s, --slug <slug>", "Agent slug (URL-friendly identifier)").option("-p, --system-prompt <prompt>", "System prompt").option("-m, --model <model>", "Model (claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5)").option("-d, --description <description>", "Agent description").addHelpText("after", `
+  agents.command("create").description("Create a new agent").option("-d, --data <json>", "Agent as JSON string (recommended for CI/scripts/agents)").option("-f, --file <path>", "Create from JSON file").option("-n, --name <name>", "Agent name").option("-s, --slug <slug>", "Agent slug (URL-friendly identifier)").option("-p, --system-prompt <prompt>", "System prompt").option("-m, --model <model>", "Model (claude-sonnet-4-5, claude-opus-4-5, claude-haiku-4-5)").option("--description <desc>", "Agent description").addHelpText("after", `
 Examples:
-  ${chalk10.dim("$")} mutagent agents create --name "Code Reviewer" --slug code-reviewer --system-prompt "Review code for bugs"
-  ${chalk10.dim("$")} mutagent agents create --file agent.json
-  ${chalk10.dim("$")} mutagent agents create --name "Helper" --slug helper --system-prompt "..." --model claude-sonnet-4-5 --json
+  ${chalk10.dim("$")} mutagent agents create --name "Code Reviewer" --slug code-reviewer --system-prompt "You are a code reviewer..."
+  ${chalk10.dim("$")} mutagent agents create -d '{"name":"Code Reviewer","slug":"code-reviewer","systemPrompt":"You are a code reviewer..."}'
+  ${chalk10.dim("$")} mutagent agents create --file agent.json  ${chalk10.dim("# full agent object as JSON file")}
 
-${chalk10.dim("Required: --name, --slug, and --system-prompt (or --file).")}
+Expected JSON (--data):
+  ${chalk10.dim('{"name":"<name>","slug":"<slug>","systemPrompt":"<system prompt>","model":"<model-id>","description":"<description>"}')}
+
+Input Methods (pick one, priority order):
+  --name/--slug/...  Individual flags ${chalk10.green("(recommended)")}
+  -d, --data         Inline JSON object (CI/scripts/agents)
+  --file             Load from JSON file
+
+${chalk10.yellow("Note: Prefer individual flags or --data over --file to avoid stale files living in your repo.")}
+${chalk10.red("Required: name, slug, systemPrompt.")} ${chalk10.dim("--data and --file are mutually exclusive. CLI flags override --data fields.")}
     `).action(async (options) => {
     const isJson = getJsonFlag(agents);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       let data;
-      if (options.file) {
-        const content = readFileSync11(options.file, "utf-8");
+      if (options.data && options.file) {
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --data and --file together", "Use --data for inline JSON or --file for file-based input, not both");
+      }
+      if (options.data) {
+        try {
+          data = JSON.parse(options.data);
+        } catch {
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Provide a valid JSON object, e.g., '{"name":"my-agent","slug":"my-agent","systemPrompt":"You are..."}'`);
+        }
+        if (options.name)
+          data.name = options.name;
+        if (options.slug)
+          data.slug = options.slug;
+        if (options.systemPrompt)
+          data.systemPrompt = options.systemPrompt;
+        if (options.model)
+          data.model = options.model;
+        if (options.description)
+          data.description = options.description;
+      } else if (options.file) {
+        const content = readFileSync9(options.file, "utf-8");
         data = JSON.parse(content);
       } else if (options.name && options.slug && options.systemPrompt) {
         data = {
@@ -5246,7 +5140,7 @@ ${chalk10.dim("Required: --name, --slug, and --system-prompt (or --file).")}
         if (options.description)
           data.description = options.description;
       } else {
-        throw new MutagentError("MISSING_ARGUMENTS", "Either --file or (--name, --slug, and --system-prompt) are required", "Use --file to load from JSON or provide --name, --slug, and --system-prompt");
+        throw new MutagentError("MISSING_ARGUMENTS", "Either --data, --file, or (--name, --slug, and --system-prompt) are required", "Use --data for inline JSON, --file to load from JSON, or provide --name, --slug, and --system-prompt");
       }
       const client = getSDKClient();
       const agent = await client.createAgent(data);
@@ -5256,18 +5150,46 @@ ${chalk10.dim("Required: --name, --slug, and --system-prompt (or --file).")}
       handleError(error, isJson);
     }
   });
-  agents.command("update").description("Update an agent").argument("<id>", "Agent ID").option("-f, --file <path>", "Update from JSON file").option("-n, --name <name>", "New name").option("-p, --system-prompt <prompt>", "New system prompt").option("-m, --model <model>", "New model").option("-d, --description <description>", "New description").option("-s, --status <status>", "New status (active, paused, archived)").addHelpText("after", `
+  agents.command("update").description("Update an agent").argument("<id>", "Agent ID").option("-d, --data <json>", "Agent updates as JSON string (CI/scripts/agents)").option("-f, --file <path>", "Update from JSON file").option("-n, --name <name>", "New name").option("-p, --system-prompt <prompt>", "New system prompt").option("-m, --model <model>", "New model").option("--description <desc>", "New description").option("-s, --status <status>", "New status (active, paused, archived)").addHelpText("after", `
 Examples:
   ${chalk10.dim("$")} mutagent agents update <id> --name "New Name"
-  ${chalk10.dim("$")} mutagent agents update <id> --status paused
-  ${chalk10.dim("$")} mutagent agents update <id> --file updated-agent.json --json
+  ${chalk10.dim("$")} mutagent agents update <id> --system-prompt "Updated prompt" --status active
+  ${chalk10.dim("$")} mutagent agents update <id> -d '{"name":"New Name","systemPrompt":"Updated prompt"}'
+  ${chalk10.dim("$")} mutagent agents update <id> --file updated-agent.json  ${chalk10.dim("# full agent object")}
+
+Input Methods (pick one, priority order):
+  --name/--system-prompt/...  Individual flags ${chalk10.green("(recommended)")}
+  -d, --data                  Inline JSON object (CI/scripts/agents)
+  --file                      Load from JSON file
+
+${chalk10.yellow("Note: Prefer individual flags or --data over --file to avoid stale files living in your repo.")}
+${chalk10.dim("--data and --file are mutually exclusive. CLI flags override --data fields.")}
     `).action(async (id, options) => {
     const isJson = getJsonFlag(agents);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       let data = {};
-      if (options.file) {
-        const content = readFileSync11(options.file, "utf-8");
+      if (options.data && options.file) {
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --data and --file together", "Use --data for inline JSON or --file for file-based input, not both");
+      }
+      if (options.data) {
+        try {
+          data = JSON.parse(options.data);
+        } catch {
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Provide a valid JSON object, e.g., '{"name":"new-name","systemPrompt":"Updated prompt"}'`);
+        }
+        if (options.name)
+          data.name = options.name;
+        if (options.systemPrompt)
+          data.systemPrompt = options.systemPrompt;
+        if (options.model)
+          data.model = options.model;
+        if (options.description)
+          data.description = options.description;
+        if (options.status)
+          data.status = options.status;
+      } else if (options.file) {
+        const content = readFileSync9(options.file, "utf-8");
         data = JSON.parse(content);
       } else {
         if (options.name)
@@ -5282,7 +5204,7 @@ Examples:
           data.status = options.status;
       }
       if (Object.keys(data).length === 0) {
-        throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", "Use --file, --name, --system-prompt, --model, --description, or --status");
+        throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", "Use --data, --file, --name, --system-prompt, --model, --description, or --status");
       }
       const client = getSDKClient();
       const agent = await client.updateAgent(id, data);
@@ -5323,12 +5245,15 @@ ${chalk10.dim("Tip: Use --force to skip confirmation (required for non-interacti
       handleError(error, isJson);
     }
   });
-  const conversations = agents.command("conversations").description("Manage conversations for agents").addHelpText("after", `
+  const conversations = new Command6("conversations").description("Manage conversations for agents").addHelpText("after", `
 Examples:
   ${chalk10.dim("$")} mutagent agents conversations list <agent-id>
   ${chalk10.dim("$")} mutagent agents conversations create <agent-id>
   ${chalk10.dim("$")} mutagent agents conversations messages <agent-id> <conversation-id>
-    `);
+    `).action(() => {
+    conversations.help();
+  });
+  agents.addCommand(conversations);
   conversations.command("list").description("List conversations for an agent").argument("<agent-id>", "Agent ID").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").addHelpText("after", `
 Examples:
   ${chalk10.dim("$")} mutagent agents conversations list <agent-id>
@@ -5477,6 +5402,8 @@ Examples:
 init_config();
 import { Command as Command7 } from "commander";
 import chalk11 from "chalk";
+init_errors();
+var VALID_CONFIG_KEYS = ["apiKey", "endpoint", "format", "timeout", "defaultWorkspace", "defaultOrganization"];
 function createConfigCommand() {
   const config = new Command7("config").description("Manage CLI configuration").addHelpText("after", `
 Examples:
@@ -5509,21 +5436,27 @@ ${chalk11.dim("Keys: apiKey, endpoint, format, timeout, defaultWorkspace, defaul
     `).action((key) => {
     const isJson = getJsonFlag(config);
     const output = new OutputFormatter(isJson ? "json" : "table");
-    const cfg = loadConfig();
-    if (!(key in cfg)) {
-      output.error(`Unknown config key: ${key}`);
-      process.exit(1);
-    }
-    const value = cfg[key];
-    const stringValue = typeof value === "object" ? JSON.stringify(value) : String(value ?? "");
-    const displayValue = key === "apiKey" && value ? `${stringValue.slice(0, 8)}...` : stringValue;
-    if (isJson) {
-      output.output({ [key]: displayValue });
-    } else {
-      output.info(displayValue);
+    try {
+      const cfg = loadConfig();
+      if (!(key in cfg)) {
+        throw new MutagentError("INVALID_ARGUMENTS", `Unknown config key: "${key}"`, `Valid keys: ${VALID_CONFIG_KEYS.join(", ")}
+` + "Example: mutagent config get endpoint");
+      }
+      const value = cfg[key];
+      const stringValue = typeof value === "object" ? JSON.stringify(value) : String(value ?? "");
+      const displayValue = key === "apiKey" && value ? `${stringValue.slice(0, 8)}...` : stringValue;
+      if (isJson) {
+        output.output({ [key]: displayValue });
+      } else {
+        output.info(displayValue);
+      }
+    } catch (error) {
+      handleError(error, isJson);
     }
   });
-  const set = new Command7("set").description("Set configuration value");
+  const set = new Command7("set").description("Set configuration value").action(() => {
+    set.help();
+  });
   set.command("workspace").description("Set default workspace ID").argument("<id>", "Workspace ID to set as default").addHelpText("after", `
 Examples:
   ${chalk11.dim("$")} mutagent config set workspace <workspace-id>
@@ -5562,7 +5495,7 @@ ${chalk11.dim("Persists organization ID for org-scoped API keys.")}
 init_sdk_client();
 import { Command as Command8 } from "commander";
 import chalk12 from "chalk";
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 init_errors();
 function parseSSELine(line) {
   if (!line || line.startsWith(":")) {
@@ -5615,12 +5548,13 @@ Examples:
   ${chalk12.dim("$")} mutagent playground run <prompt-id> --system "You are helpful" --human "Hello"
   ${chalk12.dim("$")} mutagent playground run <prompt-id> --input '{}' --model gpt-4-turbo --json
 
-Input Methods (pick one):
+Input Methods (pick one, priority order):
+  --system/--human            Quick system + user message ${chalk12.green("(recommended)")}
   --input '{"key":"value"}'   Inline JSON variables
-  --file input.json           Load from JSON file
-  --system/--human            Quick system + user message
   --messages '[...]'          Full messages array
+  --file input.json           Load from JSON file
 
+${chalk12.yellow("Note: Prefer --system/--human or --input over --file to avoid stale files living in your repo.")}
 ${chalk12.dim(`Hint: Test before evaluating: mutagent playground run <id> --input '{"key":"value"}'`)}
     `).action(async (promptId, options) => {
     const isJson = getJsonFlag(playground);
@@ -5724,7 +5658,7 @@ function parsePromptStyleInput(options) {
 function getInputJson(options) {
   if (options.file) {
     try {
-      return readFileSync12(options.file, "utf-8");
+      return readFileSync10(options.file, "utf-8");
     } catch (err) {
       throw new MutagentError("FILE_READ_ERROR", `Failed to read input file: ${options.file}`, err instanceof Error ? err.message : "Check the file path and permissions");
     }
@@ -5952,6 +5886,10 @@ Subcommands:
   list, get, test
 
 Note: Provider management (create, update, delete) is available in the Admin Panel only.
+
+${chalk14.yellow("Note:")} The providers module is not yet active. This is a placeholder
+for future external provider configuration. The server currently uses
+built-in provider settings.
     `);
   providers.command("list").description("List all providers").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").option("-t, --type <type>", "Filter by provider type").addHelpText("after", `
 Examples:
@@ -5980,6 +5918,8 @@ Examples:
         }));
         output.output({ ...result, data: withLinks });
       } else {
+        console.log(chalk14.yellow("Note: The providers module is not yet active. This is a placeholder for future external provider configuration."));
+        console.log("");
         if (result.data.length === 0) {
           output.info("No providers configured.");
           output.info(`Configure at: ${providerSettingsLink()}`);
@@ -6013,6 +5953,8 @@ Examples:
       if (isJson) {
         output.output({ ...provider, _links: providerLinks(provider.id) });
       } else {
+        console.log(chalk14.yellow("Note: The providers module is not yet active. This is a placeholder for future external provider configuration."));
+        console.log("");
         const formatted = {
           id: provider.id,
           name: provider.name,
@@ -6042,6 +5984,8 @@ ${chalk14.dim("Tests connectivity and lists available models for the provider.")
     try {
       const client = getSDKClient();
       if (!isJson) {
+        console.log(chalk14.yellow("Note: The providers module is not yet active. This is a placeholder for future external provider configuration."));
+        console.log("");
         output.info(`Testing provider ${id}...`);
       }
       const result = await client.testProvider(id);
@@ -6077,7 +6021,7 @@ init_config();
 import { Command as Command11 } from "commander";
 import inquirer3 from "inquirer";
 import chalk15 from "chalk";
-import { existsSync as existsSync12, readFileSync as readFileSync13, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync11, writeFileSync as writeFileSync4 } from "fs";
 import { execSync as execSync2 } from "child_process";
 import { join as join5 } from "path";
 init_errors();
@@ -6130,16 +6074,16 @@ var FRAMEWORK_DETECTION_MAP = {
   }
 };
 function detectPackageManager2(cwd = process.cwd()) {
-  if (existsSync12(join5(cwd, "bun.lockb")) || existsSync12(join5(cwd, "bun.lock"))) {
+  if (existsSync10(join5(cwd, "bun.lockb")) || existsSync10(join5(cwd, "bun.lock"))) {
     return "bun";
   }
-  if (existsSync12(join5(cwd, "pnpm-lock.yaml"))) {
+  if (existsSync10(join5(cwd, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (existsSync12(join5(cwd, "yarn.lock"))) {
+  if (existsSync10(join5(cwd, "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync12(join5(cwd, "package-lock.json"))) {
+  if (existsSync10(join5(cwd, "package-lock.json"))) {
     return "npm";
   }
   try {
@@ -6161,12 +6105,12 @@ function getInstallCommand2(pm, packages) {
 }
 function detectFrameworkFromPackageJson(cwd = process.cwd()) {
   const pkgPath = join5(cwd, "package.json");
-  if (!existsSync12(pkgPath)) {
+  if (!existsSync10(pkgPath)) {
     return null;
   }
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
   } catch {
     return null;
   }
@@ -6182,7 +6126,7 @@ function detectFrameworkFromPackageJson(cwd = process.cwd()) {
   return null;
 }
 function hasRcConfig(cwd = process.cwd()) {
-  return existsSync12(join5(cwd, ".mutagentrc.json"));
+  return existsSync10(join5(cwd, ".mutagentrc.json"));
 }
 function writeRcConfig(config, cwd = process.cwd()) {
   const rcPath = join5(cwd, ".mutagentrc.json");
@@ -6350,6 +6294,32 @@ Modes:
           output.info('Ready! Run "mutagent --help" to see available commands.');
         }
       }
+      if (!isNonInteractive) {
+        const skillPath = join5(cwd, ".claude/skills/mutagent-cli/SKILL.md");
+        if (!existsSync10(skillPath)) {
+          const { installSkill } = await inquirer3.prompt([{
+            type: "confirm",
+            name: "installSkill",
+            message: "Install MutagenT skill for Claude Code? (Teaches AI agents how to use the CLI)",
+            default: true
+          }]);
+          if (installSkill) {
+            try {
+              const skillDir = join5(cwd, ".claude/skills/mutagent-cli");
+              if (!existsSync10(skillDir)) {
+                mkdirSync3(skillDir, { recursive: true });
+              }
+              execSync2("node " + join5(cwd, "node_modules/.bin/mutagent") + " skills install", {
+                cwd,
+                stdio: "ignore"
+              });
+              output.success("Installed MutagenT CLI skill for Claude Code");
+            } catch {
+              output.info("Install skill manually: mutagent skills install");
+            }
+          }
+        }
+      }
       if (isJson) {
         output.output({
           success: true,
@@ -6478,7 +6448,7 @@ Scanning ${scanPath}...
 // src/commands/skills.ts
 import { Command as Command13 } from "commander";
 import chalk17 from "chalk";
-import { existsSync as existsSync13, mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
 import { join as join6 } from "path";
 var SKILL_FRONTMATTER = `---
 name: mutagent-cli
@@ -6493,6 +6463,22 @@ var SKILL_BODY = `# MutagenT CLI Skill
 
 ## Quick Reference
 Run \`mutagent --help\` for full command list and examples.
+Run \`mutagent <command> --help\` for on-the-fly instructions before using any command.
+
+Key commands:
+- \`mutagent auth login\` — Authenticate
+- \`mutagent prompts list\` — List prompts
+- \`mutagent usage\` — Check plan limits and remaining optimization runs
+- \`mutagent explore\` — Discover prompts in codebase
+- \`mutagent integrate <framework>\` — Framework integration instructions
+
+## Agent Usage Guidelines
+
+- **ALWAYS** run \`mutagent prompts list --json\` and \`mutagent usage --json\` BEFORE creating or modifying resources
+- **ALWAYS** use the \`--json\` flag for machine-readable output
+- **ALWAYS** confirm with the user before write operations (create, update, delete, optimize)
+- **CHECK** \`mutagent usage\` before running \`optimize start\` to verify remaining optimization runs
+- Format dashboard links as markdown: \`[View on Dashboard](url)\`
 
 ## Post-Onboarding Decision Tree
 
@@ -6511,8 +6497,9 @@ After \`mutagent auth login\`, the user lands in one of 3 paths:
 3. \`mutagent prompts create --data '{...}'\` — Upload with REQUIRED outputSchema
 4. Guided eval creator OR \`mutagent prompts evaluation create\`
 5. \`mutagent prompts dataset add\` — Upload/curate datasets (named)
-6. \`mutagent prompts optimize start\` — Run optimization
-7. Review scorecard → Apply/Reject optimized prompt
+6. \`mutagent usage --json\` — Verify remaining optimization runs
+7. \`mutagent prompts optimize start\` — Run optimization
+8. Review scorecard → Apply/Reject optimized prompt
 
 ### Path C: Manual
 User uses CLI commands directly. Run \`mutagent --help\`.
@@ -6585,8 +6572,8 @@ that teaches coding agents how to use the MutagenT CLI effectively.
     const output = new OutputFormatter(isJson ? "json" : "table");
     const skillDir = join6(process.cwd(), SKILL_DIR);
     const skillPath = join6(skillDir, SKILL_FILE);
-    if (!existsSync13(skillDir)) {
-      mkdirSync3(skillDir, { recursive: true });
+    if (!existsSync11(skillDir)) {
+      mkdirSync4(skillDir, { recursive: true });
     }
     const content = `${SKILL_FRONTMATTER}
 
@@ -6610,16 +6597,120 @@ ${SKILL_BODY}
   return skills;
 }
 
+// src/commands/usage.ts
+init_config();
+import { Command as Command14 } from "commander";
+import chalk18 from "chalk";
+init_errors();
+init_sdk_client();
+var TRIAL_OPTIMIZATION_LIMIT = 5;
+var BILLING_URL = "https://app.mutagent.io/settings/billing";
+function renderProgressBar(used, limit, width = 30) {
+  const ratio = Math.min(used / limit, 1);
+  const filled = Math.round(ratio * width);
+  const empty = width - filled;
+  const bar = "█".repeat(filled) + "░".repeat(empty);
+  const percent = Math.round(ratio * 100);
+  return `${bar} ${String(percent)}%`;
+}
+function createUsageCommand() {
+  const usage = new Command14("usage").description("Show resource counts and optimization run limits").addHelpText("after", `
+Examples:
+  ${chalk18.dim("$")} mutagent usage
+  ${chalk18.dim("$")} mutagent usage --json
+    `);
+  usage.action(async () => {
+    const isJson = getJsonFlag(usage);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const apiKey = getApiKey();
+      if (!apiKey) {
+        throw new AuthenticationError;
+      }
+      const spinner = await createSpinner("Fetching usage data...", isJson).start();
+      const client = getSDKClient();
+      const prompts = await client.listPrompts();
+      const promptCount = prompts.length;
+      let datasetCount = 0;
+      let evaluationCount = 0;
+      if (promptCount > 0) {
+        const results = await Promise.all(prompts.map(async (prompt) => {
+          const id = String(prompt.id);
+          const [datasets, evaluations] = await Promise.all([
+            client.listDatasets(id).catch(() => []),
+            client.listEvaluations(id).catch(() => [])
+          ]);
+          return { datasets: datasets.length, evaluations: evaluations.length };
+        }));
+        for (const r of results) {
+          datasetCount += r.datasets;
+          evaluationCount += r.evaluations;
+        }
+      }
+      const optimizationLimit = TRIAL_OPTIMIZATION_LIMIT;
+      const optimizationUsed = 0;
+      const optimizationRemaining = optimizationLimit - optimizationUsed;
+      if (spinner && typeof spinner.stop === "function") {
+        spinner.stop();
+      }
+      if (isJson) {
+        output.output({
+          resources: {
+            prompts: promptCount,
+            datasets: datasetCount,
+            evaluations: evaluationCount
+          },
+          optimizationRuns: {
+            used: optimizationUsed,
+            limit: optimizationLimit,
+            remaining: optimizationRemaining,
+            plan: "trial"
+          },
+          _links: {
+            billing: BILLING_URL
+          }
+        });
+      } else {
+        console.log("");
+        console.log(chalk18.bold("\uD83D\uDCCA MutagenT Usage"));
+        console.log(chalk18.dim("─".repeat(45)));
+        console.log("");
+        console.log(chalk18.bold("Resources:"));
+        console.log(`  Prompts:       ${chalk18.cyan(String(promptCount))}`);
+        console.log(`  Datasets:      ${chalk18.cyan(String(datasetCount))}`);
+        console.log(`  Evaluations:   ${chalk18.cyan(String(evaluationCount))}`);
+        console.log("");
+        console.log(chalk18.bold(`Optimization Runs (${chalk18.yellow("trial")} plan):`));
+        console.log(`  Remaining:  ${chalk18.cyan(String(optimizationRemaining))} / ${String(optimizationLimit)}`);
+        console.log(`  ${renderProgressBar(optimizationUsed, optimizationLimit)}`);
+        console.log("");
+        console.log(chalk18.yellow(`  ⚠ ${String(optimizationRemaining)} optimization runs remaining`));
+        console.log(chalk18.dim(`  ℹ Optimization run counts are approximate`));
+        console.log(`  Upgrade: ${chalk18.underline(BILLING_URL)}`);
+        console.log("");
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+  return usage;
+}
+
 // src/bin/cli.ts
 init_config();
+import { existsSync as existsSync12 } from "fs";
 var cliVersion = "0.1.1";
-try {
-  const __dirname2 = dirname(fileURLToPath(import.meta.url));
-  const pkgPath = join7(__dirname2, "..", "..", "package.json");
-  const pkg = JSON.parse(readFileSync14(pkgPath, "utf-8"));
-  cliVersion = pkg.version ?? cliVersion;
-} catch {}
-var program = new Command14;
+if (process.env.CLI_VERSION) {
+  cliVersion = process.env.CLI_VERSION;
+} else {
+  try {
+    const __dirname2 = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join7(__dirname2, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    cliVersion = pkg.version ?? cliVersion;
+  } catch {}
+}
+var program = new Command15;
 program.name("mutagent").description(`MutagenT CLI - AI-native prompt optimization platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -6628,45 +6719,47 @@ program.name("mutagent").description(`MutagenT CLI - AI-native prompt optimizati
   showGlobalOptions: true
 });
 program.addHelpText("after", `
-${chalk18.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  Export your API key:     ${chalk18.green("export MUTAGENT_API_KEY=mt_your_key_here")}
-  Or pass inline:          ${chalk18.green("mutagent prompts list --api-key mt_your_key")}
-  Machine-readable output: ${chalk18.green("mutagent prompts list --json")}
-  Disable prompts:         ${chalk18.green("mutagent prompts list --non-interactive")}
-  Set default workspace:   ${chalk18.green("mutagent config set workspace <workspace-id>")}
-  Set default org:         ${chalk18.green("mutagent config set org <org-id>")}
+${chalk19.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
+  Export your API key:     ${chalk19.green("export MUTAGENT_API_KEY=mt_your_key_here")}
+  Or pass inline:          ${chalk19.green("mutagent prompts list --api-key mt_your_key")}
+  Machine-readable output: ${chalk19.green("mutagent prompts list --json")}
+  Disable prompts:         ${chalk19.green("mutagent prompts list --non-interactive")}
+  Set default workspace:   ${chalk19.green("mutagent config set workspace <workspace-id>")}
+  Set default org:         ${chalk19.green("mutagent config set org <org-id>")}
 `);
 program.addHelpText("after", `
-${chalk18.yellow("Workflows:")}
-  ${chalk18.bold("Evaluate → Optimize Loop:")}
+${chalk19.yellow("Workflows:")}
+  ${chalk19.bold("Evaluate → Optimize Loop:")}
     1. mutagent prompts create --name "..." --raw-file prompt.txt
     2. mutagent prompts dataset add <prompt-id> --name "..." --file data.json
     3. mutagent prompts evaluation create <prompt-id> --name "..." --file criteria.json
     4. mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 3
 
-  ${chalk18.bold("Quick Test:")}
+  ${chalk19.bold("Quick Test:")}
     mutagent playground run <prompt-id> --input '{"key":"value"}'
 
-  ${chalk18.bold("Prerequisites for Optimization:")}
-    ${chalk18.green("✓")} Prompt with input/output parameters
-    ${chalk18.green("✓")} Dataset with items (input + expectedOutput pairs)
-    ${chalk18.green("✓")} Evaluation with criteria (field-level, input/output focused)
-    ${chalk18.dim("•")} LLM provider ${chalk18.dim("(only when server uses external providers)")}
+  ${chalk19.bold("Prerequisites for Optimization:")}
+    ${chalk19.green("✓")} Prompt with input/output parameters
+    ${chalk19.green("✓")} Dataset with items (input + expectedOutput pairs)
+    ${chalk19.green("✓")} Evaluation with criteria (field-level, input/output focused)
+    ${chalk19.dim("•")} LLM provider ${chalk19.dim("(only when server uses external providers)")}
 `);
 program.addHelpText("after", `
-${chalk18.cyan("┌─ AI AGENT INTEGRATION HINT ────────────────────────────────────────────────┐")}
-${chalk18.cyan("│")}                                                                            ${chalk18.cyan("│")}
-${chalk18.cyan("│")} Frameworks: mastra, langchain, langgraph, vercel-ai, claude-code, generic  ${chalk18.cyan("│")}
-${chalk18.cyan("│")}                                                                            ${chalk18.cyan("│")}
-${chalk18.cyan("│")} Get integration guide:  mutagent integrate <framework>                     ${chalk18.cyan("│")}
-${chalk18.cyan("│")} Verify setup:           mutagent integrate <framework> --verify            ${chalk18.cyan("│")}
-${chalk18.cyan("│")} Use --json for AI parsing:  mutagent <command> --json                      ${chalk18.cyan("│")}
-${chalk18.cyan("│")}                                                                            ${chalk18.cyan("│")}
-${chalk18.cyan("└────────────────────────────────────────────────────────────────────────────┘")}
-${!hasCredentials() ? chalk18.yellow(`
+${chalk19.cyan("┌─ AI AGENT INTEGRATION HINT ────────────────────────────────────────────────┐")}
+${chalk19.cyan("│")}                                                                            ${chalk19.cyan("│")}
+${chalk19.cyan("│")} Frameworks: langchain, langgraph, vercel-ai, openai                        ${chalk19.cyan("│")}
+${chalk19.cyan("│")}                                                                            ${chalk19.cyan("│")}
+${chalk19.cyan("│")} Get integration guide:  mutagent integrate <framework>                     ${chalk19.cyan("│")}
+${chalk19.cyan("│")} Verify setup:           mutagent integrate <framework> --verify            ${chalk19.cyan("│")}
+${chalk19.cyan("│")} Use --json for AI parsing:  mutagent <command> --json                      ${chalk19.cyan("│")}
+${chalk19.cyan("│")}                                                                            ${chalk19.cyan("│")}
+${chalk19.cyan("└────────────────────────────────────────────────────────────────────────────┘")}
+${!hasCredentials() ? chalk19.yellow(`
   Warning: Not authenticated. Run: mutagent auth login --browser
-`) : ""}${!hasRcConfig() ? chalk18.green(`
+`) : ""}${!hasRcConfig() ? chalk19.green(`
   Get started: mutagent init
+`) : ""}${!existsSync12(join7(process.cwd(), ".claude/skills/mutagent-cli/SKILL.md")) ? chalk19.magenta(`
+  Using Claude Code? Install the MutagenT skill: mutagent skills install
 `) : ""}`);
 program.hook("preAction", (thisCommand) => {
   const globalOpts = thisCommand.optsWithGlobals();
@@ -6693,7 +6786,8 @@ program.addCommand(createWorkspacesCommand());
 program.addCommand(createProvidersCommand());
 program.addCommand(createExploreCommand());
 program.addCommand(createSkillsCommand());
+program.addCommand(createUsageCommand());
 program.parse();
 
-//# debugId=A683D38662CECE3C64756E2164756E21
+//# debugId=88B4F3961CA6D43E64756E2164756E21
 //# sourceMappingURL=cli.js.map