@mutagent/cli 0.1.16 → 0.1.18

package/dist/bin/cli.js

@@ -235,7 +235,7 @@ function handleError(error, isJson) {
   }
   const message = error instanceof Error ? error.message : "Unknown error";
   if (isJson) {
-    console.log(JSON.stringify({ error: { code: "UNKNOWN_ERROR", message } }, null, 2));
+    console.log(JSON.stringify({ success: false, error: message, code: "UNKNOWN_ERROR" }, null, 2));
   } else {
     console.error(`Error: ${message}`);
   }
@@ -256,11 +256,10 @@ var init_errors = __esm(() => {
     }
     toJSON() {
       return {
-        error: {
-          code: this.code,
-          message: this.message,
-          suggestion: this.suggestion
-        }
+        success: false,
+        error: this.message,
+        code: this.code,
+        suggestedAction: this.suggestion
       };
     }
   };
@@ -300,7 +299,7 @@ var init_errors = __esm(() => {
 `);
   WorkspaceContextError = class WorkspaceContextError extends MutagentError {
     constructor(message) {
-      super("WORKSPACE_CONTEXT_MISSING", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
+      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
     }
   };
   ValidationError = class ValidationError extends MutagentError {
@@ -577,6 +576,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`);
@@ -592,7 +598,7 @@ class SDKClientWrapper {
           datasetId: parseInt(datasetId, 10),
           config: {
             maxIterations: config?.maxIterations ?? 1,
-            targetScore: config?.targetScore,
+            targetScore: config?.targetScore ?? 0.8,
             patience: config?.patience,
             model: config?.model,
             ...config?.evalModel ? { tuningParams: { evaluationModel: config.evalModel } } : {}
@@ -931,8 +937,8 @@ var init_sdk_client = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command14 } from "commander";
-import chalk18 from "chalk";
+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";
@@ -1047,9 +1053,14 @@ ${String(data.length)} result(s)`));
       console.log(chalk.green(`✓ ${message}`));
     }
   }
-  error(message) {
+  error(message, code, suggestedAction) {
     if (this.format === "json") {
-      console.log(JSON.stringify({ success: false, error: message }, null, 2));
+      const result = { success: false, error: message };
+      if (code)
+        result.code = code;
+      if (suggestedAction)
+        result.suggestedAction = suggestedAction;
+      console.log(JSON.stringify(result, null, 2));
     } else {
       console.log(chalk.red(`✗ ${message}`));
     }
@@ -1067,6 +1078,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();
@@ -2563,9 +2592,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([{
@@ -2623,6 +2660,10 @@ async function runGuidedEvalCreator(promptId) {
       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(),
       description: scoringRubric,
@@ -2806,7 +2847,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)")}`;
@@ -2990,7 +3031,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", `
@@ -3068,20 +3109,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)
 
-${chalk7.dim("Note: --data and --file are mutually exclusive. outputSchema is required (include in --data/--file or use --output-schema).")}
+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.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");
@@ -3229,15 +3274,15 @@ Or use interactive mode (TTY) to define variables step by step.`);
   });
   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> --input-schema-file schema.json
+  ${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");
@@ -3378,7 +3423,7 @@ ${chalk7.dim("Tip: Use --force to skip confirmation (required for non-interactiv
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
-      if (!options.force && !isJson) {
+      if (!options.force && !isJson && !process.env.MUTAGENT_NON_INTERACTIVE) {
         const inquirer3 = (await import("inquirer")).default;
         const answers = await inquirer3.prompt([{
           type: "confirm",
@@ -3392,18 +3437,37 @@ ${chalk7.dim("Tip: Use --force to skip confirmation (required for non-interactiv
         }
       }
       const client = getSDKClient();
-      await client.deletePrompt(id);
-      output.success(`Deleted prompt: ${id}`);
+      try {
+        await client.deletePrompt(id);
+      } catch (deleteError) {
+        if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
+          if (isJson) {
+            output.output({ success: true, deletedId: id });
+          } else {
+            output.success(`Prompt ${id} already deleted (idempotent)`);
+          }
+          return;
+        }
+        throw deleteError;
+      }
+      if (isJson) {
+        output.output({ success: true, deletedId: id });
+      } else {
+        output.success(`Deleted prompt: ${id}`);
+      }
     } catch (error) {
       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>
@@ -3433,10 +3497,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": {...}}, ...]
@@ -3447,7 +3510,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");
@@ -3528,27 +3596,61 @@ ${chalk7.dim("Note: --file and -d are mutually exclusive. Provide one or the oth
       handleError(error, isJson);
     }
   });
-  dataset.command("remove").description("Remove dataset from a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").argument("<dataset-id>", "Dataset ID (from: mutagent prompts dataset list <prompt-id>)").addHelpText("after", `
+  dataset.command("remove").description("Remove dataset from a prompt").argument("<prompt-id>", "Prompt ID (from: mutagent prompts list)").argument("<dataset-id>", "Dataset ID (from: mutagent prompts dataset list <prompt-id>)").option("--force", "Skip confirmation").addHelpText("after", `
 Examples:
   ${chalk7.dim("$")} mutagent prompts dataset remove <prompt-id> <dataset-id>
-  ${chalk7.dim("$")} mutagent prompts dataset remove <prompt-id> <dataset-id> --json
-    `).action(async (promptId, datasetId) => {
+  ${chalk7.dim("$")} mutagent prompts dataset remove <prompt-id> <dataset-id> --force
+  ${chalk7.dim("$")} mutagent prompts dataset remove <prompt-id> <dataset-id> --force --json
+    `).action(async (promptId, datasetId, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
+      if (!options.force && !isJson && !process.env.MUTAGENT_NON_INTERACTIVE) {
+        const inquirer3 = (await import("inquirer")).default;
+        const answers = await inquirer3.prompt([{
+          type: "confirm",
+          name: "confirm",
+          message: `Remove dataset ${datasetId} from prompt ${promptId}?`,
+          default: false
+        }]);
+        if (!answers.confirm) {
+          output.info("Cancelled");
+          return;
+        }
+      }
       const client = getSDKClient();
-      await client.removeDataset(promptId, datasetId);
-      output.success(`Removed dataset ${datasetId} from prompt ${promptId}`);
+      try {
+        await client.removeDataset(promptId, datasetId);
+      } catch (deleteError) {
+        if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
+          if (isJson) {
+            output.output({ success: true, deletedId: datasetId });
+          } else {
+            output.success(`Dataset ${datasetId} already removed (idempotent)`);
+          }
+          return;
+        }
+        throw deleteError;
+      }
+      if (isJson) {
+        output.output({ success: true, deletedId: datasetId });
+      } else {
+        output.success(`Removed dataset ${datasetId} from prompt ${promptId}`);
+      }
     } catch (error) {
       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>
@@ -3578,17 +3680,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 format (each criterion needs: name, description, evaluationParameter):
-  ${chalk7.dim('{ "name": "...", "evalConfig": { "criteria": [{ "name": "...", "description": "...", "evaluationParameter": "outputField" }] } }')}
+Expected JSON (--data):
+  ${chalk7.dim('{"evalConfig":{"criteria":[{"name":"<name>","description":"<scoring rubric>","evaluationParameter":"<output field to score>"}]}}')}
 
-${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.red("Each criterion MUST have: name, description, evaluationParameter")}
+  evaluationParameter maps to output schema fields (e.g., "result", "classification")
+
+${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);
@@ -3675,8 +3779,24 @@ ${chalk7.dim("Get prompt IDs: mutagent prompts list | Get dataset IDs: mutagent
         evalData.description = options.description;
       const criteria = evalData.evalConfig?.criteria;
       if (!criteria || !Array.isArray(criteria) || criteria.length === 0) {
-        throw new MutagentError("VALIDATION_ERROR", "Evaluation criteria are required. Provide criteria via --data, --file, or use --guided mode.", `Each criterion needs: name, description, evaluationParameter.
-
+        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"}]}}'
 
@@ -3699,6 +3819,37 @@ Or use --guided for interactive creation: mutagent prompts evaluation create <id
           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)) {
@@ -3746,15 +3897,63 @@ 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>)").option("--force", "Skip confirmation").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id>
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id> --force
+  ${chalk7.dim("$")} mutagent prompts evaluation delete <evaluation-id> --force --json
+    `).action(async (evaluationId, options) => {
+    const isJson = getJsonFlag(prompts);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      if (!options.force && !isJson && !process.env.MUTAGENT_NON_INTERACTIVE) {
+        const inquirer3 = (await import("inquirer")).default;
+        const answers = await inquirer3.prompt([{
+          type: "confirm",
+          name: "confirm",
+          message: `Delete evaluation ${evaluationId}?`,
+          default: false
+        }]);
+        if (!answers.confirm) {
+          output.info("Cancelled");
+          return;
+        }
+      }
+      const client = getSDKClient();
+      try {
+        await client.deleteEvaluation(evaluationId);
+      } catch (deleteError) {
+        if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
+          if (isJson) {
+            output.output({ success: true, deletedId: evaluationId });
+          } else {
+            output.success(`Evaluation ${evaluationId} already deleted (idempotent)`);
+          }
+          return;
+        }
+        throw deleteError;
+      }
+      if (isJson) {
+        output.output({ success: true, deletedId: 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
@@ -3763,6 +3962,8 @@ 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");
@@ -4766,7 +4967,13 @@ It returns INSTRUCTIONS that AI agents execute - it does NOT auto-install packag
         if (options.output) {
           writeFileSync3(options.output, explorationInstructions);
           output.success(`Exploration instructions saved to ${options.output}`);
-        } else if (options.raw === true || isJson) {
+        } else if (isJson) {
+          output.output({
+            type: "exploration",
+            frameworks: Array.from(frameworkRegistry.keys()),
+            instructions: explorationInstructions
+          });
+        } else if (options.raw === true) {
           process.stdout.write(explorationInstructions);
         } else {
           output.info("MutagenT Integration - Framework Detection");
@@ -4814,7 +5021,14 @@ AI AGENT: Execute these steps using Bash for install, Write/Edit for code change
       if (options.output) {
         writeFileSync3(options.output, instructions);
         output.success(`Integration instructions saved to ${options.output}`);
-      } else if (options.raw === true || isJson) {
+      } else if (isJson) {
+        output.output({
+          framework: frameworkArg,
+          displayName: meta?.displayName ?? frameworkArg,
+          mutagentPackage: mutagentPackage ?? null,
+          instructions
+        });
+      } else if (options.raw === true) {
         process.stdout.write(instructions);
       } else {
         const displayName = meta?.displayName ?? frameworkArg;
@@ -4961,19 +5175,47 @@ 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) {
+      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) {
@@ -4987,7 +5229,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);
@@ -4997,17 +5239,45 @@ ${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) {
+      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 {
@@ -5023,7 +5293,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);
@@ -5064,12 +5334,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>
@@ -5218,6 +5491,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:
@@ -5250,21 +5525,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>
@@ -5356,12 +5637,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);
@@ -5693,6 +5975,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:
@@ -5721,6 +6007,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()}`);
@@ -5754,6 +6042,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,
@@ -5783,6 +6073,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);
@@ -5818,7 +6110,7 @@ init_config();
 import { Command as Command11 } from "commander";
 import inquirer3 from "inquirer";
 import chalk15 from "chalk";
-import { existsSync as existsSync10, readFileSync as readFileSync11, 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();
@@ -6091,6 +6383,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,
@@ -6219,7 +6537,7 @@ Scanning ${scanPath}...
 // src/commands/skills.ts
 import { Command as Command13 } from "commander";
 import chalk17 from "chalk";
-import { existsSync as existsSync11, 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
@@ -6234,6 +6552,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
 
@@ -6252,8 +6586,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\`.
@@ -6327,7 +6662,7 @@ that teaches coding agents how to use the MutagenT CLI effectively.
     const skillDir = join6(process.cwd(), SKILL_DIR);
     const skillPath = join6(skillDir, SKILL_FILE);
     if (!existsSync11(skillDir)) {
-      mkdirSync3(skillDir, { recursive: true });
+      mkdirSync4(skillDir, { recursive: true });
     }
     const content = `${SKILL_FRONTMATTER}
 
@@ -6351,8 +6686,108 @@ ${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";
 if (process.env.CLI_VERSION) {
   cliVersion = process.env.CLI_VERSION;
@@ -6364,7 +6799,7 @@ if (process.env.CLI_VERSION) {
     cliVersion = pkg.version ?? cliVersion;
   } catch {}
 }
-var program = new Command14;
+var program = new Command15;
 program.name("mutagent").description(`MutagenT CLI - AI-native prompt optimization platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -6373,45 +6808,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: langchain, langgraph, vercel-ai, openai                        ${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();
@@ -6438,7 +6875,8 @@ program.addCommand(createWorkspacesCommand());
 program.addCommand(createProvidersCommand());
 program.addCommand(createExploreCommand());
 program.addCommand(createSkillsCommand());
+program.addCommand(createUsageCommand());
 program.parse();
 
-//# debugId=8F5D422F7273E03E64756E2164756E21
+//# debugId=F0BA27BEF939892164756E2164756E21
 //# sourceMappingURL=cli.js.map