@mutagent/cli 0.1.41 → 0.1.43

package/dist/bin/cli.js

@@ -1063,7 +1063,7 @@ var init_sdk_client = __esm(() => {
 // src/bin/cli.ts
 import { Command as Command19 } from "commander";
 import chalk24 from "chalk";
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 import { join as join9, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -2505,7 +2505,7 @@ Environment Variables:
 init_errors();
 import { Command as Command6 } from "commander";
 import chalk11 from "chalk";
-import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
+import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
 
 // src/lib/ui-links.ts
 function getAppBaseUrl() {
@@ -3019,7 +3019,6 @@ function buildScorecardDetailsText(data) {
 // src/commands/prompts/prompts-crud.ts
 init_sdk_client();
 import chalk6 from "chalk";
-import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
 init_errors();
 
 // src/lib/schema-helpers.ts
@@ -3162,21 +3161,16 @@ ${chalk6.dim("Tip: Combine --with-datasets and --with-evals to fetch all nested
       handleError(error, isJson);
     }
   });
-  prompts.command("create").description("Create a new prompt").option("-d, --data <json>", "Prompt as JSON string (recommended — curl-style inline)").option("--raw-file <path>", "Create from plain text file (used as rawPrompt)").option("-n, --name <name>", "Prompt name").option("--description <text>", "Prompt description (shown in dashboard)").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", `
+  prompts.command("create").description("Create a new prompt").option("-n, --name <name>", "Prompt name").option("--description <text>", "Prompt description (shown in dashboard)").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:
   ${chalk6.dim("$")} mutagent prompts create --name "my-prompt" --description "Greeting prompt for customers" --system "You are helpful" --human "{input}" --output-schema '{"type":"object","properties":{"result":{"type":"string","description":"The result"}}}'
   ${chalk6.dim("$")} mutagent prompts create --name "raw-prompt" --raw "Summarize: {text}" --output-schema '{"type":"object","properties":{"summary":{"type":"string","description":"Summary"}}}'
-  ${chalk6.dim("$")} mutagent prompts create -d '{"name":"summarizer","systemPrompt":"Summarize","humanPrompt":"{text}","outputSchema":{"type":"object","properties":{"summary":{"type":"string","description":"Summary"}}}}'
+  ${chalk6.dim("$")} mutagent prompts create --name "multi-turn" --messages '[{"role":"system","content":"You are helpful"},{"role":"user","content":"{input}"}]' --output-schema '{"type":"object","properties":{"result":{"type":"string","description":"The result"}}}'
 
 Prompt Input Methods (pick one, priority order):
   --system/--human   Structured system + user message pair ${chalk6.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
-
-Expected JSON (--data):
-  ${chalk6.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"}}}}'`)}
 
 ${chalk6.yellow("Variable Syntax:")}
   MutagenT uses {single_braces} for template variables.
@@ -3186,6 +3180,23 @@ ${chalk6.yellow("Variable Syntax:")}
   Variables in humanPrompt MUST also appear in inputSchema.properties.
   Static prompts (no variables) cannot substitute inputs during optimization.
 
+${chalk6.yellow("AI Agent: Format Selection Rules")}
+  Examine the SOURCE CODE structure of the prompt being uploaded:
+
+  1. If the code uses SystemMessagePromptTemplate + HumanMessagePromptTemplate
+     (or equivalent system/human split in any framework):
+     → Use --system "..." --human "..."
+
+  2. If the code is a single string template with {variables}, no role split:
+     → Use --raw "..."
+
+  3. If the code uses a messages array (ChatPromptTemplate.fromMessages,
+     multi-turn, or >2 roles):
+     → Use --messages '[{"role":"system","content":"..."},{"role":"user","content":"..."}]'
+
+  The decision is about SOURCE CODE STRUCTURE, not prompt content.
+  A persona description in a system prompt still uses --system/--human.
+
 ${chalk6.red("outputSchema is required.")}
 
 ${chalk6.yellow("AI Agent: ALWAYS append --json to this command.")}
@@ -3194,29 +3205,7 @@ ${chalk6.yellow("AI Agent: ALWAYS append --json to this command.")}
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       let data;
-      if (options.data) {
-        try {
-          data = JSON.parse(options.data);
-        } catch {
-          throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Run: mutagent prompts create --help
-Provide a valid JSON object, e.g., '{"name":"my-prompt","systemPrompt":"You are helpful"}'`);
-        }
-        if (options.name)
-          data.name = options.name;
-        if (options.description)
-          data.description = options.description;
-      } else if (options.rawFile) {
-        if (!existsSync4(options.rawFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.rawFile}`, `Run: mutagent prompts create --help
-Check the file path and try again`);
-        }
-        const textContent = readFileSync4(options.rawFile, "utf-8");
-        data = {
-          name: options.name ?? options.rawFile.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, ""),
-          description: options.description,
-          rawPrompt: textContent
-        };
-      } else if (options.name) {
+      if (options.name) {
         data = { name: options.name, description: options.description };
         if (options.messages) {
           try {
@@ -3242,11 +3231,11 @@ Provide a valid JSON array, e.g., '[{"role":"system","content":"..."}]'`);
           data.rawPrompt = options.content;
         } else {
           throw new MutagentError("MISSING_ARGUMENTS", "Prompt content required", `Run: mutagent prompts create --help
-Use --data, --raw-file, --raw, --system/--human, or --messages to specify prompt content`);
+Use --raw, --system/--human, or --messages to specify prompt content`);
         }
       } else {
-        throw new MutagentError("MISSING_ARGUMENTS", "Either --data, --raw-file, or --name with prompt content is required", `Run: mutagent prompts create --help
-Use --data for inline JSON, --raw-file for plain text, or provide --name with --raw, --system/--human, or --messages`);
+        throw new MutagentError("MISSING_ARGUMENTS", "--name is required. Use --name with --system/--human, --raw, or --messages", `Run: mutagent prompts create --help
+Provide --name with --system/--human, --raw, or --messages to specify prompt content`);
       }
       if (options.outputSchema) {
         try {
@@ -3258,12 +3247,11 @@ Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"ty
       }
       if (isSchemaEmpty(data.outputSchema)) {
         throw new MutagentError("MISSING_ARGUMENTS", "outputSchema is required for prompt creation", `Run: mutagent prompts create --help
-Use --output-schema '{"type":"object","properties":{...}}' or include outputSchema in --data`);
+Use --output-schema '{"type":"object","properties":{...}}'`);
       }
       if (isSchemaEmpty(data.inputSchema)) {
         throw new MutagentError("VALIDATION_ERROR", "inputSchema is required. Optimization cannot run without defined input variables.", `Run: mutagent prompts create --help
-Provide inputSchema via --data. Example:
-` + `  --data '{"inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"User query"}}}}'`);
+inputSchema must be provided. Pass it via the API or dashboard.`);
       } else if (!isValidJsonSchema(data.inputSchema)) {
         throw new MutagentError("VALIDATION_ERROR", "inputSchema is not a valid JSON Schema object.", `Run: mutagent prompts create --help
 ` + formatSchemaWarning("inputSchema"));
@@ -3297,82 +3285,48 @@ Add a 'description' field to each property in your inputSchema. Example: { "prop
         });
         console.log(hints);
       }
-      if (options.rawFile) {
-        const rawFilePath = options.rawFile;
-        updateMutationContext((ctx) => {
-          const preview = (data.rawPrompt ?? data.systemPrompt ?? data.name ?? "").slice(0, 50);
-          ctx.addDiscoveredPrompt(rawFilePath, 1, preview);
-          ctx.markPromptUploaded(rawFilePath, String(prompt.id), prompt.version);
-        });
-      }
     } catch (error) {
       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("--raw-file <path>", "Update from plain text file (used as rawPrompt)").option("-n, --name <name>", "New name").option("--description <text>", "New description (shown in dashboard)").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", `
+  prompts.command("update").description("Update a prompt").argument("<id>", "Prompt ID (from: mutagent prompts list)").option("-n, --name <name>", "New name").option("--description <text>", "New description (shown in dashboard)").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:
   ${chalk6.dim("$")} mutagent prompts update <id> --system "Updated system prompt" --human "{input}"
   ${chalk6.dim("$")} mutagent prompts update <id> --name "new-name" --description "Updated description"
   ${chalk6.dim("$")} mutagent prompts update <id> --raw "Summarize: {text}"
-  ${chalk6.dim("$")} mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated prompt"}'
+  ${chalk6.dim("$")} mutagent prompts update <id> --messages '[{"role":"system","content":"Updated"},{"role":"user","content":"{input}"}]'
   ${chalk6.dim("$")} mutagent prompts update <id> --input-schema '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'
-
-${chalk6.dim("CLI flags (--name) override --data fields.")}
     `).action(async (id, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       let data = {};
-      if (options.data) {
+      if (options.name)
+        data.name = options.name;
+      if (options.description)
+        data.description = options.description;
+      if (options.messages) {
         try {
-          data = JSON.parse(options.data);
+          const messages = JSON.parse(options.messages);
+          const systemMsg = messages.find((m) => m.role === "system");
+          const humanMsg = messages.find((m) => m.role === "user" || m.role === "human");
+          if (systemMsg)
+            data.systemPrompt = systemMsg.content;
+          if (humanMsg)
+            data.humanPrompt = humanMsg.content;
         } catch {
-          throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Run: mutagent prompts update --help
-` + `Provide a valid JSON object, e.g., '{"name":"new-name","systemPrompt":"Updated prompt"}'`);
-        }
-        if (options.name)
-          data.name = options.name;
-        if (options.description)
-          data.description = options.description;
-      } else if (options.rawFile) {
-        if (!existsSync4(options.rawFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.rawFile}`, `Run: mutagent prompts update --help
-` + "Check the file path and try again");
-        }
-        const textContent = readFileSync4(options.rawFile, "utf-8");
-        data.rawPrompt = textContent;
-        if (options.name)
-          data.name = options.name;
-        if (options.description)
-          data.description = options.description;
-      } else {
-        if (options.name)
-          data.name = options.name;
-        if (options.description)
-          data.description = options.description;
-        if (options.messages) {
-          try {
-            const messages = JSON.parse(options.messages);
-            const systemMsg = messages.find((m) => m.role === "system");
-            const humanMsg = messages.find((m) => m.role === "user" || m.role === "human");
-            if (systemMsg)
-              data.systemPrompt = systemMsg.content;
-            if (humanMsg)
-              data.humanPrompt = humanMsg.content;
-          } catch {
-            throw new MutagentError("INVALID_JSON", "Invalid JSON in --messages flag", `Run: mutagent prompts update --help
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --messages flag", `Run: mutagent prompts update --help
 ` + `Provide a valid JSON array, e.g., '[{"role":"system","content":"..."}]'`);
-          }
-        } else if (options.system ?? options.human) {
-          if (options.system)
-            data.systemPrompt = options.system;
-          if (options.human)
-            data.humanPrompt = options.human;
-        } else if (options.raw) {
-          data.rawPrompt = options.raw;
-        } else if (options.content) {
-          data.rawPrompt = options.content;
         }
+      } else if (options.system ?? options.human) {
+        if (options.system)
+          data.systemPrompt = options.system;
+        if (options.human)
+          data.humanPrompt = options.human;
+      } else if (options.raw) {
+        data.rawPrompt = options.raw;
+      } else if (options.content) {
+        data.rawPrompt = options.content;
       }
       const parsedInputSchema = parseSchemaOption(options.inputSchema, options.inputSchemaFile, "input-schema", "mutagent prompts update --help");
       if (parsedInputSchema)
@@ -3389,7 +3343,7 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
       }
       if (Object.keys(data).length === 0) {
         throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", `Run: mutagent prompts update --help
-` + "Use --data, --raw-file, --name, --raw, --system/--human, --messages, --input-schema, or --output-schema");
+` + "Use --name, --raw, --system/--human, --messages, --input-schema, or --output-schema");
       }
       const client = getSDKClient();
       const prompt = await client.updatePrompt(id, data);
@@ -3408,12 +3362,6 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
         });
         console.log(hints);
       }
-      if (options.rawFile) {
-        const rawFilePath = options.rawFile;
-        updateMutationContext((ctx) => {
-          ctx.markPromptUploaded(rawFilePath, String(prompt.id), prompt.version);
-        });
-      }
     } catch (error) {
       handleError(error, isJson);
     }
@@ -4859,12 +4807,12 @@ Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"field":{"typ
     }
   }
   if (filePath) {
-    if (!existsSync5(filePath)) {
+    if (!existsSync4(filePath)) {
       throw new MutagentError("FILE_NOT_FOUND", `File not found: ${filePath}`, `Run: ${helpCommand}
 Check the file path and try again`);
     }
     try {
-      return JSON.parse(readFileSync5(filePath, "utf-8"));
+      return JSON.parse(readFileSync4(filePath, "utf-8"));
     } catch {
       throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${filePath}`, `Run: ${helpCommand}
 Ensure the file contains valid JSON Schema`);
@@ -5104,20 +5052,20 @@ ${chalk12.dim("Exports to stdout by default. Use --output to save to a file.")}
 init_config();
 import { Command as Command8 } from "commander";
 import chalk13 from "chalk";
-import { writeFileSync as writeFileSync3, existsSync as existsSync10 } from "fs";
+import { writeFileSync as writeFileSync3, existsSync as existsSync9 } from "fs";
 import { execSync } from "child_process";
 init_errors();
 
 // src/lib/integrations/langchain.ts
-import { readFileSync as readFileSync6, existsSync as existsSync6 } from "fs";
+import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
 var langchainIntegration = {
   name: "langchain",
   description: "LangChain framework",
   detect() {
     let hasLangchain = false;
-    if (existsSync6("package.json")) {
+    if (existsSync5("package.json")) {
       try {
-        const pkg = JSON.parse(readFileSync6("package.json", "utf-8"));
+        const pkg = JSON.parse(readFileSync5("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         hasLangchain = "langchain" in deps || "@langchain/core" in deps;
       } catch {}
@@ -5249,15 +5197,15 @@ mutagent traces analyze <prompt-id>
 };
 
 // src/lib/integrations/langgraph.ts
-import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
+import { readFileSync as readFileSync6, existsSync as existsSync6 } from "fs";
 var langgraphIntegration = {
   name: "langgraph",
   description: "LangGraph agent workflow framework",
   detect() {
     let hasLanggraph = false;
-    if (existsSync7("package.json")) {
+    if (existsSync6("package.json")) {
       try {
-        const pkg = JSON.parse(readFileSync7("package.json", "utf-8"));
+        const pkg = JSON.parse(readFileSync6("package.json", "utf-8"));
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         hasLanggraph = "@langchain/langgraph" in deps;
       } catch {}
@@ -5378,15 +5326,15 @@ mutagent integrate langgraph --verify
 };
 
 // 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",
   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 {}
@@ -5524,15 +5472,15 @@ mutagent integrate vercel-ai --verify
 };
 
 // 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",
   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 {}
@@ -5686,16 +5634,16 @@ function getFrameworkMetadata(name) {
 
 // src/commands/integrate.ts
 function detectPackageManager() {
-  if (existsSync10("bun.lockb") || existsSync10("bun.lock")) {
+  if (existsSync9("bun.lockb") || existsSync9("bun.lock")) {
     return "bun";
   }
-  if (existsSync10("pnpm-lock.yaml")) {
+  if (existsSync9("pnpm-lock.yaml")) {
     return "pnpm";
   }
-  if (existsSync10("yarn.lock")) {
+  if (existsSync9("yarn.lock")) {
     return "yarn";
   }
-  if (existsSync10("package-lock.json")) {
+  if (existsSync9("package-lock.json")) {
     return "npm";
   }
   try {
@@ -6740,13 +6688,13 @@ init_config();
 import { Command as Command14 } from "commander";
 import inquirer3 from "inquirer";
 import chalk20 from "chalk";
-import { existsSync as existsSync12, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
 import { execSync as execSync3 } from "child_process";
 import { join as join6 } from "path";
 init_errors();
 
 // src/lib/framework-detection.ts
-import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 import { execSync as execSync2 } from "child_process";
 import { join as join5 } from "path";
 var FRAMEWORK_DETECTION_MAP = {
@@ -6798,16 +6746,16 @@ var FRAMEWORK_DETECTION_MAP = {
   }
 };
 function detectPackageManager2(cwd = process.cwd()) {
-  if (existsSync11(join5(cwd, "bun.lockb")) || existsSync11(join5(cwd, "bun.lock"))) {
+  if (existsSync10(join5(cwd, "bun.lockb")) || existsSync10(join5(cwd, "bun.lock"))) {
     return "bun";
   }
-  if (existsSync11(join5(cwd, "pnpm-lock.yaml"))) {
+  if (existsSync10(join5(cwd, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (existsSync11(join5(cwd, "yarn.lock"))) {
+  if (existsSync10(join5(cwd, "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync11(join5(cwd, "package-lock.json"))) {
+  if (existsSync10(join5(cwd, "package-lock.json"))) {
     return "npm";
   }
   try {
@@ -6829,12 +6777,12 @@ function getInstallCommand2(pm, packages) {
 }
 function detectFrameworkFromPackageJson(cwd = process.cwd()) {
   const pkgPath = join5(cwd, "package.json");
-  if (!existsSync11(pkgPath)) {
+  if (!existsSync10(pkgPath)) {
     return null;
   }
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+    pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
   } catch {
     return null;
   }
@@ -6850,7 +6798,7 @@ function detectFrameworkFromPackageJson(cwd = process.cwd()) {
   return null;
 }
 function hasRcConfig(cwd = process.cwd()) {
-  return existsSync11(join5(cwd, ".mutagentrc.json"));
+  return existsSync10(join5(cwd, ".mutagentrc.json"));
 }
 
 // src/commands/init.ts
@@ -7069,7 +7017,7 @@ Modes:
         }
       }
       const skillPath = join6(cwd, ".claude/skills/mutagent-cli/SKILL.md");
-      const skillInstalled = existsSync12(skillPath);
+      const skillInstalled = existsSync11(skillPath);
       if (!isNonInteractive && !skillInstalled) {
         const { installSkill } = await inquirer3.prompt([{
           type: "confirm",
@@ -7080,7 +7028,7 @@ Modes:
         if (installSkill) {
           try {
             const skillDir = join6(cwd, ".claude/skills/mutagent-cli");
-            if (!existsSync12(skillDir)) {
+            if (!existsSync11(skillDir)) {
               mkdirSync3(skillDir, { recursive: true });
             }
             execSync3("node " + join6(cwd, "node_modules/.bin/mutagent") + " skills install", {
@@ -7101,7 +7049,7 @@ Modes:
         framework: confirmedFramework?.name ?? null,
         authenticated,
         workspaceValidation: workspaceValidation ?? null,
-        skillInstalled: skillInstalled || existsSync12(skillPath),
+        skillInstalled: skillInstalled || existsSync11(skillPath),
         _directive: {
           instruction: "Verify workspace. Run: mutagent workspaces list --json",
           next: ["mutagent workspaces list --json", "mutagent prompts list --json"],
@@ -7247,7 +7195,7 @@ Scanning ${scanPath}...
 // src/commands/skills.ts
 import { Command as Command16 } from "commander";
 import chalk22 from "chalk";
-import { existsSync as existsSync13, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
 import { join as join7 } from "path";
 import { execSync as execSync4 } from "child_process";
 function findRepoRoot() {
@@ -7268,24 +7216,27 @@ description: |
 ---`;
 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.
+## First Things First
+Run \`mutagent --help\` — this is the CENTRAL navigation hub containing ALL commands, workflows, and rules.
+Run \`mutagent <command> --help\` BEFORE using ANY command for the first time.
 
-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 Protocol (4 Rules)
+1. EVERY command MUST include \`--json\`
+2. Run \`<command> --help\` BEFORE first use
+3. **MANDATORY**: Parse \`_directive.renderedCard\` and copy it into your CHAT RESPONSE verbatim. The card appears in bash output but that is NOT sufficient — the user cannot read collapsed bash blocks. HARD STOP: do NOT run any further commands until the card text is rendered in your chat message.
+4. ALL user interaction via AskUserQuestion — CLI is non-interactive
 
-## Agent Usage Guidelines
+## Directive System
+Every JSON response may include:
+- \`_directive.renderedCard\` — Pre-formatted card that MUST be shown to the user verbatim
+- \`_directive.instruction\` — Next step for the agent
+- \`_directive.next\` — Array of suggested commands
+- \`_links\` — Dashboard/API URLs (format as markdown)
 
-- **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)\`
+The agent MUST parse and act on directives. Cards in collapsed bash output are invisible to the user — always render them in chat.
+
+## Prompt Variables
+Use \`{single_braces}\`: \`"Analyze: {document}"\`
 
 ## Post-Onboarding Decision Tree
 
@@ -7311,58 +7262,56 @@ After \`mutagent auth login\`, the user lands in one of 3 paths:
 ### Path C: Manual
 User uses CLI commands directly. Run \`mutagent --help\`.
 
-## State Tracking
-- \`.mutagent/mutation-context.md\` — Local context file tracking all uploads
-- \`mutagent auth status\` — Shows onboarding completion + integration state
-- Comment markers (\`// MutagenT:START ... // MutagenT:END\`) in source files
+## Guided Evaluation Creation
+Use \`--guided --json\` when creating evaluations (NEVER \`--guided\` alone — it launches interactive prompts that agents can't use):
+\\\`\\\`\\\`
+mutagent prompts evaluation create <id> --guided --json
+\\\`\\\`\\\`
 
-## Wireframe Templates
+**When to use guided mode:**
+The optimizer requires each criterion to have \`name\`, \`description\` (scoring rubric), and \`evaluationParameter\` (a field from the prompt's inputSchema or outputSchema). If the user's existing evaluation format doesn't match this shape — e.g. they have generic rubrics without per-field targeting, or criteria that don't map 1:1 to schema fields — use \`--guided\` to:
+1. Fetch the prompt's inputSchema + outputSchema fields
+2. Show which fields need coverage
+3. Return a criteria template with the exact JSON shape
 
-### Active Operation Status Card
-\`\`\`
-┌─────────────────────────────────────────┐
-│ ⚡ MutagenT: Optimizing                │
-│ ─────────────────────────────────────── │
-│ Prompt:  "email-summarizer" (ID: 42)    │
-│ Dataset: "customer-emails" (150 items)  │
-│ Status:  Running — Iteration 3/10       │
-│ Score:   0.72 → 0.85 (+18%)            │
-│ ████████████░░░░░░░░ 60%               │
-│                                         │
-│ \uD83D\uDD17 View: https://app.mutagent.io/...   │
-└─────────────────────────────────────────┘
-\`\`\`
+**Validation rules the CLI enforces:**
+- Every criterion MUST have \`name\`, \`description\`, and \`evaluationParameter\`
+- \`evaluationParameter\` MUST match an actual schema field name
+- No duplicate \`evaluationParameter\` values — each criterion targets a unique field
+- ALL schema fields must be covered (missing fields = error)
 
-### Optimization Scorecard
-\`\`\`
-┌─────────────────────────────────────────┐
-│ \uD83D\uDCCA Optimization Results                │
-│ ─────────────────────────────────────── │
-│ BEFORE                                  │
-│   System: "You are a helpful..."        │
-│   Score:  0.62                          │
-│                                         │
-│ AFTER                                   │
-│   System: "You are an expert..."        │
-│   Score:  0.91 (+47%)                   │
-│                                         │
-│ Iterations: 5 | Best: #4               │
-│ ─────────────────────────────────────── │
-│ Score Progression:                      │
-│ #1: 0.62  #2: 0.71  #3: 0.78          │
-│ #4: 0.91  #5: 0.89                     │
-│                                         │
-│ [Apply] [Reject] [View Details]         │
-│                                         │
-│ \uD83D\uDD17 Dashboard: https://app.mutagent...  │
-│ \uD83D\uDD17 Optimizer: https://app.mutagent...  │
-└─────────────────────────────────────────┘
-\`\`\`
+## State Tracking
+- \`.mutagent/mutation-context.md\` — Codebase index of discovered/uploaded prompts
+- Check and update this file after explore, create, and dataset operations
+- \`mutagent auth status\` — Auth + workspace state
+- Comment markers (\`// MutagenT:START ... // MutagenT:END\`) in source files
+
+## Post-Optimization
+After \`optimize results\`: ALWAYS show the before/after diff to the user first. Then offer choices via AskUserQuestion: Apply / Reject.
 
 ## Evaluation Criteria Reminder
 Every evaluation MUST specify criteria targeting either:
 - Input variable fields (from inputSchema)
-- Output fields (from outputSchema / structured output)`;
+- Output fields (from outputSchema / structured output)
+
+## Optimization Cost Control
+- Default max-iterations is 1. NEVER increase without explicit user request.
+- Each iteration incurs LLM costs. Starting >1 iterations without consent = protocol violation.
+- If user wants more, confirm the number via AskUserQuestion first.
+
+## Claude Code Hooks (Session Telemetry)
+Optional — sends session activity to MutagenT traces API for observability.
+
+Install via \`.claude/settings.local.json\`:
+\\\`\\\`\\\`json
+{"hooks": {
+  "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
+  "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
+  "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
+  "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}]
+}}
+\\\`\\\`\\\`
+Or run: \`mutagent init\` (option 1 installs skill + hooks together)`;
 var SKILL_DIR = ".claude/skills/mutagent-cli";
 var SKILL_FILE = "SKILL.md";
 function createSkillsCommand() {
@@ -7380,7 +7329,7 @@ that teaches coding agents how to use the MutagenT CLI effectively.
     const repoRoot = findRepoRoot();
     const skillDir = join7(repoRoot, SKILL_DIR);
     const skillPath = join7(skillDir, SKILL_FILE);
-    if (!existsSync13(skillDir)) {
+    if (!existsSync12(skillDir)) {
       mkdirSync4(skillDir, { recursive: true });
     }
     const content = `${SKILL_FRONTMATTER}
@@ -7510,7 +7459,7 @@ import { Command as Command18 } from "commander";
 import { randomUUID } from "crypto";
 import { join as join8 } from "path";
 import { tmpdir } from "os";
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, unlinkSync, existsSync as existsSync14 } from "fs";
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync6, unlinkSync, existsSync as existsSync13 } from "fs";
 async function safeExecute(fn) {
   try {
     await fn();
@@ -7531,10 +7480,10 @@ function stateFilePath(sessionId) {
 }
 function readState(sessionId) {
   const path = stateFilePath(sessionId);
-  if (!existsSync14(path))
+  if (!existsSync13(path))
     return null;
   try {
-    return JSON.parse(readFileSync11(path, "utf-8"));
+    return JSON.parse(readFileSync10(path, "utf-8"));
   } catch {
     return null;
   }
@@ -7544,7 +7493,7 @@ function writeState(sessionId, state) {
 }
 function deleteState(sessionId) {
   const path = stateFilePath(sessionId);
-  if (existsSync14(path)) {
+  if (existsSync13(path)) {
     try {
       unlinkSync(path);
     } catch {}
@@ -7738,7 +7687,23 @@ async function handlePostToolUse() {
   ]);
 }
 function createHooksCommand() {
-  const hooks = new Command18("hooks").description("Hook handlers for AI coding assistants");
+  const hooks = new Command18("hooks").description("Hook handlers for AI coding assistants").addHelpText("after", `
+Claude Code Session Telemetry:
+  Sends lightweight session activity to the MutagenT traces API for observability.
+
+  Install by adding to .claude/settings.local.json:
+
+  {
+    "hooks": {
+      "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
+      "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
+      "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
+      "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}]
+    }
+  }
+
+  Or run: mutagent init (option 1 installs skill + hooks together)
+    `);
   const claudeCode = hooks.command("claude-code").description("Claude Code session telemetry");
   claudeCode.command("session-start").description("Handle session start event").action(async () => {
     await safeExecute(handleSessionStart);
@@ -7764,7 +7729,7 @@ if (process.env.CLI_VERSION) {
   try {
     const __dirname2 = dirname(fileURLToPath(import.meta.url));
     const pkgPath = join9(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
     cliVersion = pkg.version ?? cliVersion;
   } catch {}
 }
@@ -7806,10 +7771,16 @@ ${chalk24.yellow("Command Navigation:")}
   mutagent prompts optimize results <job-id>  ${chalk24.dim("View scorecard")}
 
   mutagent integrate <framework>        ${chalk24.dim("Framework integration guide")}
-  mutagent hooks claude-code <event>   ${chalk24.dim("Hook handler for Claude Code telemetry")}
+  mutagent hooks --help                 ${chalk24.dim("Hook setup for Claude Code telemetry")}
   mutagent playground run <id> --input '{...}'  ${chalk24.dim("Quick test")}
 
-${chalk24.yellow("Workflow: Evaluate → Optimize:")}
+${chalk24.yellow("★ Workflow: Framework Integration (Tracing):")}
+  1. mutagent explore                                    ${chalk24.dim("← discover prompts/agents in codebase")}
+  2. mutagent integrate <framework>                      ${chalk24.dim("← get integration instructions")}
+  3. Apply tracing code to your codebase                 ${chalk24.dim("← follow the guide output")}
+  4. mutagent traces list --json                         ${chalk24.dim("← verify traces are arriving")}
+
+${chalk24.yellow("★ Workflow: Evaluate → Optimize:")}
   1. mutagent prompts create --help               ${chalk24.dim("← read help")}
   2. mutagent prompts create ... --json            ${chalk24.dim("← upload prompt with {variables} + inputSchema")}
   3. mutagent prompts dataset add --help           ${chalk24.dim("← read help")}
@@ -7817,14 +7788,50 @@ ${chalk24.yellow("Workflow: Evaluate → Optimize:")}
   5. mutagent prompts evaluation create <id> --guided --json  ${chalk24.dim("← guided eval")}
   6. mutagent prompts optimize start <id> --dataset <d> --evaluation <e> --json
 
+${chalk24.yellow("Post-Onboarding Decision Tree:")}
+  After ${chalk24.bold("mutagent auth login")}, users land in one of 3 paths:
+  ${chalk24.bold("Path A")} (Tracing):      explore → integrate <framework> → apply tracing → verify
+  ${chalk24.bold("Path B")} (Optimization): explore → prompts create → dataset add → eval create → optimize
+  ${chalk24.bold("Path C")} (Manual):       Use CLI commands directly — run mutagent <command> --help
+
+${chalk24.yellow("Directive System:")}
+  Every --json response may include:
+  ${chalk24.bold("_directive.renderedCard")}  Pre-formatted card for the user ${chalk24.red("(MUST be shown in chat)")}
+  ${chalk24.bold("_directive.instruction")}   Next step for the agent
+  ${chalk24.bold("_directive.next")}          Array of suggested follow-up commands
+  ${chalk24.bold("_links")}                   Dashboard/API URLs (format as markdown links)
+
+${chalk24.yellow("Evaluation Criteria Format:")}
+  Each criterion MUST have: ${chalk24.bold("name")}, ${chalk24.bold("description")} (scoring rubric), ${chalk24.bold("evaluationParameter")}
+  evaluationParameter MUST match an inputSchema or outputSchema field name
+  No duplicate evaluationParameter values — each criterion targets a unique field
+  ALL schema fields must be covered (missing fields = error)
+  Use ${chalk24.bold("--guided --json")} to generate criteria templates from prompt schemas
+
+${chalk24.yellow("Optimization Cost Control:")}
+  Default max-iterations is 1. ${chalk24.red("NEVER increase without explicit user request.")}
+  Each iteration incurs LLM costs — confirm with user before starting >1.
+
+${chalk24.yellow("Post-Optimization:")}
+  After ${chalk24.bold("optimize results")}: ALWAYS show the before/after diff to the user first.
+  Then offer choices: ${chalk24.bold("Apply")} / ${chalk24.bold("Reject")}.
+
+${chalk24.yellow("State Tracking:")}
+  .mutagent/mutation-context.md — Codebase index of discovered/uploaded prompts
+  Update after explore, create, and dataset operations
+  mutagent auth status — Auth + workspace state
+  Comment markers (// MutagenT:START ... // MutagenT:END) in source files
+
 ${chalk24.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   1. EVERY command MUST include --json (no exceptions)
   2. Run <command> --help BEFORE first use of any command
   3. Use --guided --json for evaluation creation (NEVER --guided alone)
-  4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim — bash output is NOT sufficient
+  4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim
+     ${chalk24.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
   5. After mutagent init, verify workspace: mutagent workspaces list --json
   6. Use {single_braces} for template variables in prompts
-  7. Collect evaluation rubrics from the user — NEVER auto-generate
+  7. Collect evaluation criteria from the user — NEVER auto-generate
+  8. ALL user interaction via AskUserQuestion — CLI is non-interactive
 ${!hasCredentials() ? `
 ` + chalk24.yellow("  Warning: Not authenticated. Run: mutagent auth login --browser") + `
 ` : ""}${!hasRcConfig() ? `
@@ -7859,5 +7866,5 @@ program.addCommand(createUsageCommand());
 program.addCommand(createHooksCommand());
 program.parse();
 
-//# debugId=C82411F79C0AD74464756E2164756E21
+//# debugId=3B726C6C3EEAEFBE64756E2164756E21
 //# sourceMappingURL=cli.js.map