@mutagent/cli 0.1.23 → 0.1.25

package/dist/bin/cli.js

@@ -16,46 +16,24 @@ var __toESM = (mod, isNodeMode, target) => {
       });
   return to;
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
-// src/bin/cli.ts
-import { Command as Command15 } from "commander";
-import chalk18 from "chalk";
-import { readFileSync as readFileSync10 } from "fs";
-import { join as join7, dirname } from "path";
-import { fileURLToPath } from "url";
-
-// src/commands/auth.ts
-import { Command } from "commander";
-import inquirer from "inquirer";
-import chalk3 from "chalk";
-import ora from "ora";
-import { existsSync as existsSync3 } from "fs";
-import { join as join4 } from "path";
-
 // src/lib/config.ts
 import { cosmiconfigSync } from "cosmiconfig";
 import { z } from "zod";
 import { homedir } from "os";
 import { join } from "path";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-var configSchema = z.object({
-  apiKey: z.string().optional(),
-  endpoint: z.string().default("https://api.mutagent.io"),
-  format: z.enum(["table", "json"]).default("table"),
-  timeout: z.number().default(30000),
-  defaultWorkspace: z.string().optional(),
-  defaultOrganization: z.string().optional()
-});
-var credentialsSchema = z.object({
-  apiKey: z.string().optional(),
-  endpoint: z.string().optional(),
-  defaultWorkspace: z.string().optional(),
-  defaultOrganization: z.string().optional(),
-  expiresAt: z.string().optional()
-}).loose();
-var CREDENTIALS_DIR = join(homedir(), ".config", "mutagent");
-var CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
 function parseJsonSafe(content, schema) {
   try {
     const parsed = JSON.parse(content);
@@ -163,79 +141,28 @@ function setDefaultOrganization(organizationId) {
   };
   writeFileSync(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
 }
-
-// src/lib/sdk-client.ts
-import { Mutagent, HTTPClient } from "@mutagent/sdk";
+var configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
+var init_config = __esm(() => {
+  configSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().default("https://api.mutagent.io"),
+    format: z.enum(["table", "json"]).default("table"),
+    timeout: z.number().default(30000),
+    defaultWorkspace: z.string().optional(),
+    defaultOrganization: z.string().optional()
+  });
+  credentialsSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().optional(),
+    defaultWorkspace: z.string().optional(),
+    defaultOrganization: z.string().optional(),
+    expiresAt: z.string().optional()
+  }).loose();
+  CREDENTIALS_DIR = join(homedir(), ".config", "mutagent");
+  CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+});
 
 // src/lib/errors.ts
-class MutagentError extends Error {
-  code;
-  suggestion;
-  exitCode;
-  constructor(code, message, suggestion, exitCode = 1) {
-    super(message);
-    this.code = code;
-    this.suggestion = suggestion;
-    this.exitCode = exitCode;
-    this.name = "MutagentError";
-  }
-  toJSON() {
-    return {
-      success: false,
-      error: this.message,
-      code: this.code,
-      suggestedAction: this.suggestion
-    };
-  }
-}
-var AUTH_REMEDIATION_MESSAGE = [
-  "Authentication required. Options:",
-  "  Interactive:     mutagent auth login --browser",
-  "  Non-interactive: export MUTAGENT_API_KEY=<your-key>",
-  "  CI/CD:           mutagent auth login --api-key <key>"
-].join(`
-`);
-
-class AuthenticationError extends MutagentError {
-  suggestions;
-  cause;
-  constructor(message, options = {}) {
-    super("AUTH_REQUIRED", message ?? 'Authentication required. Please run "mutagent auth login"', options.suggestions ? options.suggestions[0] : "Run: mutagent auth login --browser", 2);
-    this.suggestions = options.suggestions ?? [
-      "mutagent auth login --browser",
-      "export MUTAGENT_API_KEY=<your-key>",
-      "mutagent auth login --api-key <key>"
-    ];
-    this.suggestion = options.suggestions ? options.suggestions[0] : "Run: mutagent auth login --browser";
-    this.cause = options.cause;
-  }
-}
-
-class ApiError extends MutagentError {
-  statusCode;
-  constructor(status, message) {
-    super(`API_${String(status)}`, message, status === 401 ? "Check your API key with: mutagent auth status" : undefined, 1);
-    this.statusCode = status;
-  }
-}
-var WORKSPACE_REMEDIATION_MESSAGE = [
-  "Workspace context missing. To fix:",
-  "  mutagent config set workspace <workspace-id>   # Set default workspace",
-  "  mutagent workspaces list                        # List available workspaces"
-].join(`
-`);
-
-class WorkspaceContextError extends MutagentError {
-  constructor(message) {
-    super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
-  }
-}
-
-class ValidationError extends MutagentError {
-  constructor(message) {
-    super("VALIDATION_ERROR", message, "Check the command syntax with: mutagent <command> --help", 1);
-  }
-}
 function handleError(error, isJson) {
   if (error instanceof MutagentError) {
     if (isJson) {
@@ -260,6 +187,14 @@ function handleError(error, isJson) {
           checkPermissions: "Verify your API key has the required permissions"
         };
       }
+      if (error.suggestion) {
+        const helpMatch = /^Run:\s+(mutagent\s+[^\n]+--help)/.exec(error.suggestion);
+        const helpCommand = helpMatch ? helpMatch[1] : "mutagent --help";
+        jsonOutput._agentGuidance = {
+          helpCommand,
+          suggestion: error.suggestion
+        };
+      }
       console.log(JSON.stringify(jsonOutput, null, 2));
     } else {
       console.error(`Error: ${error.message}`);
@@ -314,8 +249,86 @@ function handleError(error, isJson) {
   }
   process.exit(1);
 }
+var MutagentError, AUTH_REMEDIATION_MESSAGE, AuthenticationError, ApiError, WORKSPACE_REMEDIATION_MESSAGE, WorkspaceContextError, ValidationError;
+var init_errors = __esm(() => {
+  MutagentError = class MutagentError extends Error {
+    code;
+    suggestion;
+    exitCode;
+    constructor(code, message, suggestion, exitCode = 1) {
+      super(message);
+      this.code = code;
+      this.suggestion = suggestion;
+      this.exitCode = exitCode;
+      this.name = "MutagentError";
+    }
+    toJSON() {
+      return {
+        success: false,
+        error: this.message,
+        code: this.code,
+        suggestedAction: this.suggestion
+      };
+    }
+  };
+  AUTH_REMEDIATION_MESSAGE = [
+    "Authentication required. Options:",
+    "  Interactive:     mutagent auth login --browser",
+    "  Non-interactive: export MUTAGENT_API_KEY=<your-key>",
+    "  CI/CD:           mutagent auth login --api-key <key>"
+  ].join(`
+`);
+  AuthenticationError = class AuthenticationError extends MutagentError {
+    suggestions;
+    cause;
+    constructor(message, options = {}) {
+      super("AUTH_REQUIRED", message ?? 'Authentication required. Please run "mutagent auth login"', options.suggestions ? options.suggestions[0] : "Run: mutagent auth login --browser", 2);
+      this.suggestions = options.suggestions ?? [
+        "mutagent auth login --browser",
+        "export MUTAGENT_API_KEY=<your-key>",
+        "mutagent auth login --api-key <key>"
+      ];
+      this.suggestion = options.suggestions ? options.suggestions[0] : "Run: mutagent auth login --browser";
+      this.cause = options.cause;
+    }
+  };
+  ApiError = class ApiError extends MutagentError {
+    statusCode;
+    constructor(status, message) {
+      super(`API_${String(status)}`, message, status === 401 ? "Check your API key with: mutagent auth status" : undefined, 1);
+      this.statusCode = status;
+    }
+  };
+  WORKSPACE_REMEDIATION_MESSAGE = [
+    "Workspace context missing. To fix:",
+    "  mutagent config set workspace <workspace-id>   # Set default workspace",
+    "  mutagent workspaces list                        # List available workspaces"
+  ].join(`
+`);
+  WorkspaceContextError = class WorkspaceContextError extends MutagentError {
+    constructor(message) {
+      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
+    }
+  };
+  ValidationError = class ValidationError extends MutagentError {
+    constructor(message) {
+      super("VALIDATION_ERROR", message, "Check the command syntax with: mutagent <command> --help", 1);
+    }
+  };
+});
 
 // src/lib/sdk-client.ts
+var exports_sdk_client = {};
+__export(exports_sdk_client, {
+  validateApiKey: () => validateApiKey,
+  resetSDKClient: () => resetSDKClient,
+  getSDKClient: () => getSDKClient,
+  fetchWorkspaces: () => fetchWorkspaces,
+  fetchOrganizations: () => fetchOrganizations,
+  MutagentSDK: () => SDKClientWrapper
+});
+import { Mutagent, HTTPClient } from "@mutagent/sdk";
+
 class SDKClientWrapper {
   sdk;
   apiKey;
@@ -870,7 +883,6 @@ class SDKClientWrapper {
     }
   }
 }
-var sdkClient = null;
 function getSDKClient() {
   if (!sdkClient) {
     const apiKey = getApiKey();
@@ -887,6 +899,9 @@ function getSDKClient() {
   }
   return sdkClient;
 }
+function resetSDKClient() {
+  sdkClient = null;
+}
 async function validateApiKey(apiKey, endpoint) {
   try {
     const response = await fetch(`${endpoint}/api/organizations`, {
@@ -923,6 +938,28 @@ async function fetchWorkspaces(apiKey, endpoint, orgId) {
     return [];
   }
 }
+var sdkClient = null;
+var init_sdk_client = __esm(() => {
+  init_errors();
+  init_config();
+});
+
+// src/bin/cli.ts
+import { Command as Command15 } from "commander";
+import chalk18 from "chalk";
+import { readFileSync as readFileSync10 } from "fs";
+import { join as join7, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// src/commands/auth.ts
+init_config();
+init_sdk_client();
+import { Command } from "commander";
+import inquirer from "inquirer";
+import chalk3 from "chalk";
+import ora from "ora";
+import { existsSync as existsSync3 } from "fs";
+import { join as join4 } from "path";
 
 // src/lib/output.ts
 import chalk from "chalk";
@@ -1068,6 +1105,9 @@ function createSpinner(text, isJson) {
   return { start };
 }
 
+// src/commands/auth.ts
+init_errors();
+
 // src/lib/browser-auth.ts
 import { hostname, platform } from "os";
 function generateCliToken() {
@@ -1868,6 +1908,8 @@ Environment Variables:
       let endpoint = process.env.MUTAGENT_ENDPOINT ?? options.endpoint;
       let workspaceName;
       let organizationName;
+      let loginWorkspaceId;
+      let loginOrgId;
       if (apiKey) {
         output.info("Validating API key...");
         const isValid = await validateApiKey(apiKey, endpoint);
@@ -1890,8 +1932,21 @@ Environment Variables:
           organizationId: orgId
         });
         output.success("Authenticated successfully");
-        if (!isJson) {
+        if (isJson) {
+          output.output({
+            success: true,
+            authenticated: true,
+            endpoint,
+            workspace: wsId ? { id: wsId } : null,
+            organization: orgId ? { id: orgId } : null,
+            _directive: {
+              instruction: "Verify workspace. Run: mutagent workspaces list --json",
+              next: ["mutagent workspaces list --json", "mutagent prompts list --json"]
+            }
+          });
+        } else {
           output.info(`Endpoint: ${endpoint}`);
+          output.info("Next: mutagent workspaces list --json");
         }
         return;
       }
@@ -1956,6 +2011,8 @@ Environment Variables:
           apiKey = result.apiKey;
           workspaceName = result.workspaceName;
           organizationName = result.organizationName;
+          loginWorkspaceId = result.workspaceId;
+          loginOrgId = result.organizationId;
           console.log("");
           output.info("Workspace: " + workspaceName);
           output.info("Organization: " + organizationName);
@@ -2034,6 +2091,10 @@ Environment Variables:
           workspaceId: selectedWsId,
           organizationId: selectedOrgId
         });
+        workspaceName = selectedWsName;
+        organizationName = selectedOrgName;
+        loginWorkspaceId = selectedWsId;
+        loginOrgId = selectedOrgId;
         output.success("Authenticated successfully");
         if (selectedOrgName)
           output.info("Organization: " + selectedOrgName);
@@ -2041,6 +2102,21 @@ Environment Variables:
           output.info("Workspace: " + selectedWsName);
         output.info("Endpoint: " + endpoint);
       }
+      if (isJson) {
+        output.output({
+          success: true,
+          authenticated: true,
+          endpoint,
+          workspace: loginWorkspaceId ? { id: loginWorkspaceId, name: workspaceName } : null,
+          organization: loginOrgId ? { id: loginOrgId, name: organizationName } : null,
+          _directive: {
+            instruction: "Verify workspace. Run: mutagent workspaces list --json",
+            next: ["mutagent workspaces list --json", "mutagent prompts list --json"]
+          }
+        });
+      } else {
+        output.info("Next: mutagent workspaces list --json");
+      }
       if (wasFirstLogin && process.stdin.isTTY && !isJson) {
         await runPostOnboarding();
       }
@@ -2156,10 +2232,13 @@ Examples:
 }
 
 // src/commands/login.ts
+init_config();
+init_sdk_client();
 import { Command as Command2 } from "commander";
 import inquirer2 from "inquirer";
 import chalk4 from "chalk";
 import ora2 from "ora";
+init_errors();
 function createLoginCommand() {
   const login = new Command2("login").description("Login to MutagenT platform").option("--browser", "Force browser-based authentication").option("--non-interactive", "Disable interactive prompts (auto-selects browser auth)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
 Examples:
@@ -2302,9 +2381,11 @@ Environment Variables:
 }
 
 // src/commands/prompts.ts
+init_sdk_client();
 import { Command as Command3 } from "commander";
 import chalk6 from "chalk";
 import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+init_errors();
 
 // src/lib/ui-links.ts
 function getAppBaseUrl() {
@@ -2390,6 +2471,13 @@ function evaluationLinks(promptId, evalId) {
 }
 var AI_DIRECTIVE = `
 [AI Agent: STOP. Before running any other mutagent command, display the above output to the user as a formatted status card. Do not summarize or omit details. Show all links and suggested next steps.]`;
+function echoDirectiveToStderr(directive) {
+  if (directive?.instruction) {
+    console.error(`
+⚠️  AI AGENT: ${directive.instruction}
+`);
+  }
+}
 function formatCreationHints(hint) {
   const lines = [
     "",
@@ -2839,22 +2927,12 @@ function isSchemaEmpty(schema) {
     return true;
   return false;
 }
-function warnSingleBraceVariables(content, output) {
-  const singleBracePattern = /(?<!\{)\{([a-zA-Z_][a-zA-Z0-9_]*)\}(?!\})/g;
-  const matches = [...content.matchAll(singleBracePattern)];
-  if (matches.length > 0) {
-    const variables = [...new Set(matches.map((m) => m[1] ?? ""))];
-    for (const variable of variables) {
-      output.warn(`Found {${variable}} -- MutagenT uses {{${variable}}} syntax. Did you mean {{${variable}}}?`);
-    }
-  }
-}
 function createPromptsCommand() {
   const prompts = new Command3("prompts").description("Manage prompts, datasets, evaluations, and optimizations").addHelpText("after", `
 Examples:
   ${chalk6.dim("$")} mutagent prompts list
   ${chalk6.dim("$")} mutagent prompts get <prompt-id>
-  ${chalk6.dim("$")} mutagent prompts create --name "my-prompt" --system "You are helpful" --human "{{input}}"
+  ${chalk6.dim("$")} mutagent prompts create --name "my-prompt" --system "You are helpful" --human "{input}"
   ${chalk6.dim("$")} mutagent prompts dataset list <prompt-id>
   ${chalk6.dim("$")} mutagent prompts evaluation create <prompt-id> --name "My Eval"
   ${chalk6.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --evaluation <eval-id>
@@ -2947,19 +3025,27 @@ ${chalk6.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("--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", `
 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 "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"}}}}'
 
 Prompt Input Methods (pick one, priority order):
   --system/--human   Structured system + user message pair ${chalk6.green("(recommended)")}
-  --raw              Single raw prompt text with {{variables}}
+  --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.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.
+  humanPrompt: "Analyze this: {document}"    ${chalk6.green("✓ correct")}
+  humanPrompt: "Analyze this: {{document}}"  ${chalk6.red("✗ wrong")}
+
+  Variables in humanPrompt MUST also appear in inputSchema.properties.
+  Static prompts (no variables) cannot substitute inputs during optimization.
 
 ${chalk6.red("outputSchema is required.")}
     `).action(async (options) => {
@@ -2971,7 +3057,8 @@ ${chalk6.red("outputSchema is required.")}
         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-prompt","systemPrompt":"You are helpful"}'`);
+          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;
@@ -2979,7 +3066,8 @@ ${chalk6.red("outputSchema is required.")}
           data.description = options.description;
       } else if (options.rawFile) {
         if (!existsSync4(options.rawFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.rawFile}`, "Check the file path and try again");
+          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 = {
@@ -2999,7 +3087,8 @@ ${chalk6.red("outputSchema is required.")}
             if (humanMsg)
               data.humanPrompt = humanMsg.content;
           } catch {
-            throw new MutagentError("INVALID_JSON", "Invalid JSON in --messages flag", `Provide a valid JSON array, e.g., '[{"role":"system","content":"..."}]'`);
+            throw new MutagentError("INVALID_JSON", "Invalid JSON in --messages flag", `Run: mutagent prompts create --help
+Provide a valid JSON array, e.g., '[{"role":"system","content":"..."}]'`);
           }
         } else if (options.system ?? options.human) {
           if (options.system)
@@ -3011,34 +3100,37 @@ ${chalk6.red("outputSchema is required.")}
         } else if (options.content) {
           data.rawPrompt = options.content;
         } else {
-          throw new MutagentError("MISSING_ARGUMENTS", "Prompt content required", "Use --data, --raw-file, --raw, --system/--human, or --messages to specify prompt content");
+          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`);
         }
       } else {
-        throw new MutagentError("MISSING_ARGUMENTS", "Either --data, --raw-file, or --name with prompt content is required", "Use --data for inline JSON, --raw-file for plain text, or provide --name with --raw, --system/--human, or --messages");
-      }
-      const promptContent = data.rawPrompt ?? data.systemPrompt ?? data.humanPrompt ?? "";
-      if (promptContent && !isJson) {
-        warnSingleBraceVariables(promptContent, output);
+        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`);
       }
       if (options.outputSchema) {
         try {
           data.outputSchema = JSON.parse(options.outputSchema);
         } catch {
-          throw new MutagentError("INVALID_JSON", "Invalid JSON in --output-schema flag", `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"type":"string"}}}'`);
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --output-schema flag", `Run: mutagent prompts create --help
+Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"type":"string"}}}'`);
         }
       }
       if (isSchemaEmpty(data.outputSchema)) {
-        throw new MutagentError("MISSING_ARGUMENTS", "outputSchema is required for prompt creation", `Use --output-schema '{"type":"object","properties":{...}}' or include outputSchema in --data`);
+        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`);
       }
       if (isSchemaEmpty(data.inputSchema)) {
-        throw new MutagentError("VALIDATION_ERROR", "inputSchema is required. Optimization cannot run without defined input variables.", `Provide inputSchema via --data. Example:
+        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"}}}}'`);
       } else if (!isValidJsonSchema(data.inputSchema)) {
-        throw new MutagentError("VALIDATION_ERROR", "inputSchema is not a valid JSON Schema object.", formatSchemaWarning("inputSchema"));
+        throw new MutagentError("VALIDATION_ERROR", "inputSchema is not a valid JSON Schema object.", `Run: mutagent prompts create --help
+` + formatSchemaWarning("inputSchema"));
       } else {
         const missingDescs = validateSchemaDescriptions(data.inputSchema);
         if (missingDescs.length > 0) {
-          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
+          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Run: mutagent prompts create --help
+Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
         }
       }
       if (isSchemaEmpty(data.outputSchema)) {
@@ -3049,7 +3141,9 @@ ${chalk6.red("outputSchema is required.")}
       const client = getSDKClient();
       const prompt = await client.createPrompt(data);
       if (isJson) {
-        output.output({ ...prompt, _links: promptLinks(prompt.id), _directive: promptCreatedDirective(prompt.id, prompt.name) });
+        const directive = promptCreatedDirective(prompt.id, prompt.name);
+        output.output({ ...prompt, _links: promptLinks(prompt.id), _directive: directive });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Created prompt: ${prompt.name} (id: ${String(prompt.id)})`);
         output.info(`Workspace: ${client.getCurrentWorkspaceId() ?? "auto-inferred from API key"}`);
@@ -3076,9 +3170,9 @@ ${chalk6.red("outputSchema is required.")}
   });
   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", `
 Examples:
-  ${chalk6.dim("$")} mutagent prompts update <id> --system "Updated system prompt" --human "{{input}}"
+  ${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> --raw "Summarize: {text}"
   ${chalk6.dim("$")} mutagent prompts update <id> -d '{"name":"new-name","systemPrompt":"Updated prompt"}'
   ${chalk6.dim("$")} mutagent prompts update <id> --input-schema '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'
 
@@ -3092,7 +3186,8 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
         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"}'`);
+          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;
@@ -3100,7 +3195,8 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
           data.description = options.description;
       } else if (options.rawFile) {
         if (!existsSync4(options.rawFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.rawFile}`, "Check the file path and try again");
+          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;
@@ -3123,7 +3219,8 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
             if (humanMsg)
               data.humanPrompt = humanMsg.content;
           } catch {
-            throw new MutagentError("INVALID_JSON", "Invalid JSON in --messages flag", `Provide a valid JSON array, e.g., '[{"role":"system","content":"..."}]'`);
+            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)
@@ -3137,60 +3234,68 @@ ${chalk6.dim("CLI flags (--name) override --data fields.")}
         }
       }
       if (options.inputSchema && options.inputSchemaFile) {
-        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --input-schema and --input-schema-file together", "Use --input-schema for inline JSON or --input-schema-file for file-based input, not both");
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --input-schema and --input-schema-file together", `Run: mutagent prompts update --help
+` + "Use --input-schema for inline JSON or --input-schema-file for file-based input, not both");
       }
       if (options.inputSchema) {
         try {
           data.inputSchema = JSON.parse(options.inputSchema);
         } catch {
-          throw new MutagentError("INVALID_JSON", "Invalid JSON in --input-schema flag", `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'`);
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --input-schema flag", `Run: mutagent prompts update --help
+` + `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"text":{"type":"string","description":"Input text"}}}'`);
         }
       } else if (options.inputSchemaFile) {
         if (!existsSync4(options.inputSchemaFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.inputSchemaFile}`, "Check the file path and try again");
+          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.inputSchemaFile}`, `Run: mutagent prompts update --help
+` + "Check the file path and try again");
         }
         try {
           data.inputSchema = JSON.parse(readFileSync4(options.inputSchemaFile, "utf-8"));
         } catch {
-          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.inputSchemaFile}`, "Ensure the file contains valid JSON Schema");
+          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.inputSchemaFile}`, `Run: mutagent prompts update --help
+` + "Ensure the file contains valid JSON Schema");
         }
       }
       if (options.outputSchema && options.outputSchemaFile) {
-        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --output-schema and --output-schema-file together", "Use --output-schema for inline JSON or --output-schema-file for file-based input, not both");
+        throw new MutagentError("INVALID_ARGUMENTS", "Cannot use --output-schema and --output-schema-file together", `Run: mutagent prompts update --help
+` + "Use --output-schema for inline JSON or --output-schema-file for file-based input, not both");
       }
       if (options.outputSchema) {
         try {
           data.outputSchema = JSON.parse(options.outputSchema);
         } catch {
-          throw new MutagentError("INVALID_JSON", "Invalid JSON in --output-schema flag", `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"type":"string"}}}'`);
+          throw new MutagentError("INVALID_JSON", "Invalid JSON in --output-schema flag", `Run: mutagent prompts update --help
+` + `Provide a valid JSON Schema, e.g., '{"type":"object","properties":{"result":{"type":"string"}}}'`);
         }
       } else if (options.outputSchemaFile) {
         if (!existsSync4(options.outputSchemaFile)) {
-          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.outputSchemaFile}`, "Check the file path and try again");
+          throw new MutagentError("FILE_NOT_FOUND", `File not found: ${options.outputSchemaFile}`, `Run: mutagent prompts update --help
+` + "Check the file path and try again");
         }
         try {
           data.outputSchema = JSON.parse(readFileSync4(options.outputSchemaFile, "utf-8"));
         } catch {
-          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.outputSchemaFile}`, "Ensure the file contains valid JSON Schema");
+          throw new MutagentError("INVALID_JSON", `Failed to parse JSON from ${options.outputSchemaFile}`, `Run: mutagent prompts update --help
+` + "Ensure the file contains valid JSON Schema");
         }
       }
       if (data.inputSchema && isValidJsonSchema(data.inputSchema)) {
         const missingDescs = validateSchemaDescriptions(data.inputSchema);
         if (missingDescs.length > 0) {
-          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
+          throw new MutagentError("VALIDATION_ERROR", `inputSchema properties missing descriptions: ${missingDescs.join(", ")}`, `Run: mutagent prompts update --help
+` + `Add a 'description' field to each property in your inputSchema. Example: { "properties": { "field": { "type": "string", "description": "What this field contains" } } }`);
         }
       }
       if (Object.keys(data).length === 0) {
-        throw new MutagentError("MISSING_ARGUMENTS", "No update data provided", "Use --data, --raw-file, --name, --raw, --system/--human, --messages, --input-schema, or --output-schema");
-      }
-      const promptContent = data.rawPrompt ?? data.systemPrompt ?? data.humanPrompt ?? "";
-      if (promptContent && !isJson) {
-        warnSingleBraceVariables(promptContent, output);
+        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");
       }
       const client = getSDKClient();
       const prompt = await client.updatePrompt(id, data);
       if (isJson) {
-        output.output({ ...prompt, _links: promptLinks(prompt.id), _directive: promptUpdatedDirective(prompt.id, prompt.name) });
+        const directive = promptUpdatedDirective(prompt.id, prompt.name);
+        output.output({ ...prompt, _links: promptLinks(prompt.id), _directive: directive });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Updated prompt: ${prompt.name} (id: ${String(prompt.id)})`);
         const hints = formatCreationHints({
@@ -3224,7 +3329,8 @@ ${chalk6.dim("Note: --force is required. The CLI is non-interactive — confirm
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       if (!options.force && !isJson) {
-        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting prompt ${id} requires confirmation`, `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
+        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting prompt ${id} requires confirmation`, `Run: mutagent prompts delete --help
+` + `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
 ` + `Use --force to confirm: mutagent prompts delete ${id} --force`);
       }
       const client = getSDKClient();
@@ -3233,7 +3339,9 @@ ${chalk6.dim("Note: --force is required. The CLI is non-interactive — confirm
       } catch (deleteError) {
         if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
           if (isJson) {
-            output.output({ success: true, deletedId: id, _links: { prompts: promptsDashboardLink() }, _directive: promptDeletedDirective(id) });
+            const directive = promptDeletedDirective(id);
+            output.output({ success: true, deletedId: id, _links: { prompts: promptsDashboardLink() }, _directive: directive });
+            echoDirectiveToStderr(directive);
           } else {
             output.success(`Prompt ${id} already deleted (idempotent)`);
           }
@@ -3242,7 +3350,9 @@ ${chalk6.dim("Note: --force is required. The CLI is non-interactive — confirm
         throw deleteError;
       }
       if (isJson) {
-        output.output({ success: true, deletedId: id, _links: { prompts: promptsDashboardLink() }, _directive: promptDeletedDirective(id) });
+        const directive = promptDeletedDirective(id);
+        output.output({ success: true, deletedId: id, _links: { prompts: promptsDashboardLink() }, _directive: directive });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Deleted prompt: ${id}`);
         output.info(`View prompts: ${promptsDashboardLink()}`);
@@ -3305,39 +3415,51 @@ Inline data format (-d):
 Expected item format:
   ${chalk6.dim('{"input": {"<field>": "<value>"}, "expectedOutput": {"<field>": "<value>"}}')}
 
+${chalk6.yellow("AI Agent Note:")}
+  Items MUST have BOTH input AND expectedOutput.
+  Keys must match prompt's inputSchema.properties (input) and outputSchema.properties (expectedOutput).
+  expectedOutput is REQUIRED for evaluation scoring.
+  Check schemas: mutagent prompts get <prompt-id> --json
+
 ${chalk6.red("Required: --data must be provided.")}
     `).action(async (promptId, options) => {
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       if (!options.data) {
-        throw new MutagentError("MISSING_ARGUMENTS", "-d/--data is required", "Use -d '[{...}]' to provide inline JSON data");
+        throw new MutagentError("MISSING_ARGUMENTS", "-d/--data is required", `Run: mutagent prompts dataset add --help
+` + "Use -d '[{...}]' to provide inline JSON data");
       }
       let content;
       try {
         const parsed = JSON.parse(options.data);
         if (!Array.isArray(parsed)) {
-          throw new MutagentError("INVALID_JSON", "Inline data must be a JSON array", `Provide a JSON array, e.g., '[{"input": {...}, "expectedOutput": {...}}]'`);
+          throw new MutagentError("INVALID_JSON", "Inline data must be a JSON array", `Run: mutagent prompts dataset add --help
+` + `Provide a JSON array, e.g., '[{"input": {...}, "expectedOutput": {...}}]'`);
         }
         content = options.data;
       } catch (e) {
         if (e instanceof MutagentError)
           throw e;
-        throw new MutagentError("INVALID_JSON", "Invalid JSON in -d/--data flag", `Provide a valid JSON array, e.g., '[{"input": {...}, "expectedOutput": {...}}]'`);
+        throw new MutagentError("INVALID_JSON", "Invalid JSON in -d/--data flag", `Run: mutagent prompts dataset add --help
+` + `Provide a valid JSON array, e.g., '[{"input": {...}, "expectedOutput": {...}}]'`);
       }
       const datasetName = options.name;
       if (!datasetName) {
-        throw new MutagentError("MISSING_ARGUMENTS", "Dataset name is required", `[Agent: Ask the user for a dataset name via AskUserQuestion, then pass --name]
+        throw new MutagentError("MISSING_ARGUMENTS", "Dataset name is required", `Run: mutagent prompts dataset add --help
+` + `[Agent: Ask the user for a dataset name via AskUserQuestion, then pass --name]
 ` + `Use --name <name>, e.g., mutagent prompts dataset add ${promptId} --name "my-dataset" -d '[...]'`);
       }
       const client = getSDKClient();
       const datasetResult = await client.addDataset(promptId, content, datasetName);
       if (isJson) {
+        const directive = datasetAddedDirective(promptId, datasetResult.id, datasetResult.name, datasetResult.itemCount);
         output.output({
           ...datasetResult,
           _links: datasetLinks(promptId, datasetResult.id),
-          _directive: datasetAddedDirective(promptId, datasetResult.id, datasetResult.name, datasetResult.itemCount)
+          _directive: directive
         });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Added dataset "${datasetResult.name}" to prompt: ${promptId} (id: ${String(datasetResult.id)})`);
         if (datasetResult.itemCount !== undefined && datasetResult.itemCount > 0) {
@@ -3373,7 +3495,8 @@ Examples:
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       if (!options.force && !isJson) {
-        throw new MutagentError("CONFIRMATION_REQUIRED", `Removing dataset ${datasetId} from prompt ${promptId} requires confirmation`, `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
+        throw new MutagentError("CONFIRMATION_REQUIRED", `Removing dataset ${datasetId} from prompt ${promptId} requires confirmation`, `Run: mutagent prompts dataset remove --help
+` + `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
 ` + `Use --force to confirm: mutagent prompts dataset remove ${promptId} ${datasetId} --force`);
       }
       const client = getSDKClient();
@@ -3382,7 +3505,9 @@ Examples:
       } catch (deleteError) {
         if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
           if (isJson) {
-            output.output({ success: true, deletedId: datasetId, _links: { datasets: promptDatasetsLink(promptId) }, _directive: datasetRemovedDirective(promptId, datasetId) });
+            const directive = datasetRemovedDirective(promptId, datasetId);
+            output.output({ success: true, deletedId: datasetId, _links: { datasets: promptDatasetsLink(promptId) }, _directive: directive });
+            echoDirectiveToStderr(directive);
           } else {
             output.success(`Dataset ${datasetId} already removed (idempotent)`);
           }
@@ -3391,7 +3516,9 @@ Examples:
         throw deleteError;
       }
       if (isJson) {
-        output.output({ success: true, deletedId: datasetId, _links: { datasets: promptDatasetsLink(promptId) }, _directive: datasetRemovedDirective(promptId, datasetId) });
+        const directive = datasetRemovedDirective(promptId, datasetId);
+        output.output({ success: true, deletedId: datasetId, _links: { datasets: promptDatasetsLink(promptId) }, _directive: directive });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Removed dataset ${datasetId} from prompt ${promptId}`);
         output.info(`View datasets: ${promptDatasetsLink(promptId)}`);
@@ -3500,7 +3627,7 @@ Examples:
       handleError(error, isJson);
     }
   });
-  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 (for pre-validated criteria only)").option("-n, --name <name>", "Evaluation name (required unless --guided)").option("--description <text>", "Evaluation description").option("--guided", "Show evaluation workflow guide with prompt schema fields and criteria template (recommended)").addHelpText("after", `
+  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 (for pre-validated criteria only)").option("-n, --name <name>", "Evaluation name (required unless --guided)").option("--description <text>", "Evaluation description").option("--guided", "Interactive guided mode — build criteria step by step (ALWAYS pair with --json for AI agents)").addHelpText("after", `
 Examples:
   ${chalk6.dim("$")} mutagent prompts evaluation create <prompt-id> --guided          ${chalk6.dim("# recommended: shows workflow guide + schema fields")}
   ${chalk6.dim("$")} mutagent prompts evaluation create <prompt-id> --guided --json  ${chalk6.dim("# structured workflow for AI agents")}
@@ -3516,9 +3643,11 @@ Guided Workflow (recommended):
   Works in all modes (TTY, non-TTY, --json).
 
 AI Agent Directive:
-  Before creating an eval, CHECK if criteria already exist in the user's code:
-    - If criteria match expected shape (name + description + evaluationParameter targeting schema fields) → use --data
-    - If criteria are missing or malformed → use --guided
+  CRITICAL: Run mutagent prompts evaluation create --help FIRST.
+  Then: mutagent prompts evaluation create <id> --guided --json
+  NEVER --guided alone. ALWAYS --guided --json.
+  NEVER construct criteria JSON manually.
+  Parse askUserQuestions from --guided --json output, use AskUserQuestion to collect from user.
 
 Expected Criteria Shape (--data):
   ${chalk6.dim('{"evalConfig":{"criteria":[{"name":"<name>","description":"<scoring rubric>","evaluationParameter":"<schema field>"}]}}')}
@@ -3531,7 +3660,7 @@ ${chalk6.dim("Get prompt IDs: mutagent prompts list")}
     const isJson = getJsonFlag(prompts);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
-      if (options.guided) {
+      const buildGuidedWorkflow = async () => {
         const client2 = getSDKClient();
         const prompt = await client2.getPrompt(promptId);
         const inputFields = prompt.inputSchema && typeof prompt.inputSchema === "object" ? Object.keys(prompt.inputSchema.properties ?? {}) : [];
@@ -3559,48 +3688,26 @@ ${chalk6.dim("Get prompt IDs: mutagent prompts list")}
           ],
           multiSelect: false
         }));
-        const workflow = {
+        return {
           prompt: { id: promptId, name: prompt.name },
           inputSchema: { fields: inputFields },
           outputSchema: { fields: outputFields },
           workflow: {
             description: "Follow these steps to create an evaluation for this prompt:",
             steps: [
-              {
-                step: 1,
-                action: "Review the prompt schemas above",
-                detail: "Each criterion must target a field from outputSchema (preferred) or inputSchema"
-              },
-              {
-                step: 2,
-                action: "Ask the user about each schema field using AskUserQuestion",
-                detail: "For EACH field listed in askUserQuestions below, present the question to the user. Collect their scoring rubric choice or custom description."
-              },
-              {
-                step: 3,
-                action: "Build criteria JSON from user answers",
-                detail: `Map each user answer to a criterion: { name: "<field> <rubric>", description: "<user's rubric>", evaluationParameter: "<field>" }`
-              },
-              {
-                step: 4,
-                action: "Ask for evaluation name",
-                detail: 'Ask the user what to name this evaluation (e.g., "Accuracy Check", "Quality Eval")'
-              },
-              {
-                step: 5,
-                action: "Create the evaluation",
-                detail: `Run: mutagent prompts evaluation create <prompt-id> --name "<name>" -d '{"evalConfig":{"criteria":[...]}}'`
-              }
+              { step: 1, action: "Review the prompt schemas above", detail: "Each criterion must target a field from outputSchema (preferred) or inputSchema" },
+              { step: 2, action: "Ask the user about each schema field using AskUserQuestion", detail: "For EACH field listed in askUserQuestions below, present the question to the user. Collect their scoring rubric choice or custom description." },
+              { step: 3, action: "Build criteria JSON from user answers", detail: `Map each user answer to a criterion: { name: "<field> <rubric>", description: "<user's rubric>", evaluationParameter: "<field>" }` },
+              { step: 4, action: "Ask for evaluation name", detail: 'Ask the user what to name this evaluation (e.g., "Accuracy Check", "Quality Eval")' },
+              { step: 5, action: "Create the evaluation", detail: `Run: mutagent prompts evaluation create <prompt-id> --name "<name>" -d '{"evalConfig":{"criteria":[...]}}'` }
             ],
             criteriaTemplate: {
               evalConfig: {
-                criteria: [
-                  {
-                    name: "<criterion_name>",
-                    description: "<scoring rubric - describe what 1.0 vs 0.0 means>",
-                    evaluationParameter: `<one of: ${allFields.length > 0 ? allFields.map((f) => f.field).join(", ") : "no fields detected - check prompt schemas"}>`
-                  }
-                ]
+                criteria: [{
+                  name: "<criterion_name>",
+                  description: "<scoring rubric - describe what 1.0 vs 0.0 means>",
+                  evaluationParameter: `<one of: ${allFields.length > 0 ? allFields.map((f) => f.field).join(", ") : "no fields detected - check prompt schemas"}>`
+                }]
               }
             },
             exampleCommand: `mutagent prompts evaluation create ${promptId} --name "My Evaluation" -d '${JSON.stringify({
@@ -3622,12 +3729,18 @@ ${chalk6.dim("Get prompt IDs: mutagent prompts list")}
               step2: "If criteria are missing or malformed, use the askUserQuestions payloads to collect them via AskUserQuestion.",
               step3: `After collecting all criteria, construct the --data JSON and run: mutagent prompts evaluation create <prompt-id> --name "<name>" -d '<json>'`
             }
-          }
+          },
+          _meta: { inputFields, outputFields, allFields }
         };
+      };
+      const renderGuidedWorkflow = (wf) => {
+        const { inputFields, outputFields, allFields } = wf._meta;
         if (isJson) {
-          output.output(workflow);
+          const { _meta: _discarded, ...cleanWorkflow } = wf;
+          output.output(cleanWorkflow);
+          echoDirectiveToStderr(wf._directive);
         } else {
-          output.success(`Guided Evaluation Workflow for prompt: ${prompt.name} (ID: ${promptId})`);
+          output.success(`Guided Evaluation Workflow for prompt: ${wf.prompt.name} (ID: ${promptId})`);
           console.log("");
           if (outputFields.length > 0) {
             console.log(`  Output Schema Fields: ${outputFields.join(", ")}`);
@@ -3647,15 +3760,24 @@ ${chalk6.dim("Get prompt IDs: mutagent prompts list")}
           console.log(`      -d '{"evalConfig":{"criteria":[{"name":"accuracy","description":"Score 1.0 if correct","evaluationParameter":"${outputFields[0] ?? "<field>"}"}]}}'`);
           console.log("");
         }
+      };
+      if (options.guided) {
+        const workflow = await buildGuidedWorkflow();
+        renderGuidedWorkflow(workflow);
         return;
       }
       if (!options.data) {
-        throw new MutagentError("MISSING_ARGUMENTS", "No criteria source provided", `[Agent: Run --guided first to see available schema fields, then ask the user to define criteria via AskUserQuestion]
-` + `Use --guided to see the evaluation workflow and available schema fields, or provide criteria via --data.
-` + "Example: mutagent prompts evaluation create " + promptId + " --guided");
+        if (isJson || process.stdout.isTTY) {
+          const workflow = await buildGuidedWorkflow();
+          renderGuidedWorkflow(workflow);
+          return;
+        }
+        throw new MutagentError("MISSING_ARGUMENTS", "No criteria source provided", `Run: mutagent prompts evaluation create --help
+` + "Then: mutagent prompts evaluation create " + promptId + " --guided --json");
       }
       if (!options.name) {
-        throw new MutagentError("MISSING_ARGUMENTS", "Evaluation name is required", `[Agent: Ask the user for an evaluation name via AskUserQuestion, then pass --name]
+        throw new MutagentError("MISSING_ARGUMENTS", "Evaluation name is required", `Run: mutagent prompts evaluation create --help
+` + `[Agent: Ask the user for an evaluation name via AskUserQuestion, then pass --name]
 ` + "Use --name <name>, e.g., mutagent prompts evaluation create " + promptId + ` --name "My Eval" --data '...'`);
       }
       const evalData = {
@@ -3673,7 +3795,8 @@ ${chalk6.dim("Get prompt IDs: mutagent prompts list")}
         if (parsed.metadata)
           evalData.metadata = parsed.metadata;
       } catch {
-        throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Provide a valid JSON object, e.g., '{"evalConfig":{"criteria":[...]},"llmConfig":{"model":"gpt-4"}}'`);
+        throw new MutagentError("INVALID_JSON", "Invalid JSON in --data flag", `Run: mutagent prompts evaluation create --help
+` + `Provide a valid JSON object, e.g., '{"evalConfig":{"criteria":[...]},"llmConfig":{"model":"gpt-4"}}'`);
       }
       if (options.name)
         evalData.name = options.name;
@@ -3697,7 +3820,8 @@ Detected output fields from prompt schema: ${fields.join(", ")}
             }
           }
         } catch {}
-        throw new MutagentError("VALIDATION_ERROR", "Evaluation criteria are required. Provide criteria via --data.", `Run with --guided to see available schema fields and criteria template.
+        throw new MutagentError("VALIDATION_ERROR", "Evaluation criteria are required. Provide criteria via --data.", `Run: mutagent prompts evaluation create --help
+` + "Then: mutagent prompts evaluation create " + promptId + ` --guided --json
 ` + fieldsHint + `
 Example JSON (--data flag):
 ` + `  --data '{"evalConfig":{"criteria":[{"name":"Accuracy","description":"...","evaluationParameter":"classification"}]}}'
@@ -3717,7 +3841,8 @@ Example JSON (--data flag):
         const hasEvalParam = c.evaluationParameter;
         if (!c.name || !hasDescription || !hasEvalParam) {
           const cName = typeof c.name === "string" ? c.name : "unnamed";
-          throw new MutagentError("VALIDATION_ERROR", `Criterion "${cName}" is missing required fields. Need: name, description, evaluationParameter.`, "Run with --guided to see available schema fields and criteria template. Use --data to pass well-formed criteria.");
+          throw new MutagentError("VALIDATION_ERROR", `Criterion "${cName}" is missing required fields. Need: name, description, evaluationParameter.`, `Run: mutagent prompts evaluation create --help
+` + "Then: mutagent prompts evaluation create " + promptId + " --guided --json");
         }
       }
       const seenParams = new Set;
@@ -3746,7 +3871,8 @@ Example JSON (--data flag):
         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 + `
+        throw new MutagentError("VALIDATION_ERROR", `Duplicate evaluationParameter: "${uniqueDupes.join('", "')}". Each criterion must target a unique output field.`, `Run: mutagent prompts evaluation create --help
+` + "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"}' + "]}}'");
@@ -3755,11 +3881,13 @@ Example:
       const evalResult = await client.createEvaluation(promptId, evalData);
       if (isJson) {
         const criteriaLen = evalData.evalConfig?.criteria?.length ?? 0;
+        const directive = evaluationCreatedDirective(promptId, evalResult.id, evalResult.name, criteriaLen);
         output.output({
           ...evalResult,
           _links: evaluationLinks(promptId, evalResult.id),
-          _directive: evaluationCreatedDirective(promptId, evalResult.id, evalResult.name, criteriaLen)
+          _directive: directive
         });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Created evaluation: ${evalResult.name} (id: ${String(evalResult.id)})`);
         const hints = formatCreationHints({
@@ -3789,7 +3917,8 @@ Examples:
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
       if (!options.force && !isJson) {
-        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting evaluation ${evaluationId} requires confirmation`, `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
+        throw new MutagentError("CONFIRMATION_REQUIRED", `Deleting evaluation ${evaluationId} requires confirmation`, `Run: mutagent prompts evaluation delete --help
+` + `[Agent: Ask the user to confirm via MultiChoice, then pass --force]
 ` + `Use --force to confirm: mutagent prompts evaluation delete ${evaluationId} --force`);
       }
       const client = getSDKClient();
@@ -3798,7 +3927,9 @@ Examples:
       } catch (deleteError) {
         if (deleteError instanceof ApiError && deleteError.statusCode === 404) {
           if (isJson) {
-            output.output({ success: true, deletedId: evaluationId, _links: { dashboard: promptsDashboardLink() }, _directive: evaluationDeletedDirective(evaluationId) });
+            const directive = evaluationDeletedDirective(evaluationId);
+            output.output({ success: true, deletedId: evaluationId, _links: { dashboard: promptsDashboardLink() }, _directive: directive });
+            echoDirectiveToStderr(directive);
           } else {
             output.success(`Evaluation ${evaluationId} already deleted (idempotent)`);
           }
@@ -3807,7 +3938,9 @@ Examples:
         throw deleteError;
       }
       if (isJson) {
-        output.output({ success: true, deletedId: evaluationId, _links: { dashboard: promptsDashboardLink() }, _directive: evaluationDeletedDirective(evaluationId) });
+        const directive = evaluationDeletedDirective(evaluationId);
+        output.output({ success: true, deletedId: evaluationId, _links: { dashboard: promptsDashboardLink() }, _directive: directive });
+        echoDirectiveToStderr(directive);
       } else {
         output.success(`Evaluation ${evaluationId} deleted successfully`);
         output.info(`View evaluations: ${promptsDashboardLink()}`);
@@ -3833,11 +3966,15 @@ Examples:
   ${chalk6.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --evaluation <eval-id> --max-iterations 5
   ${chalk6.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --evaluation <eval-id> --target-score 0.95 --model claude-sonnet-4-5-20250929
   ${chalk6.dim("$")} mutagent prompts optimize start <prompt-id> --dataset <dataset-id> --evaluation <eval-id> --json
+${chalk6.yellow("Pre-Optimization Checklist:")}
+  □ mutagent prompts get <id> --json       ${chalk6.dim("(has inputSchema + outputSchema)")}
+  □ mutagent prompts evaluation list <id> --json  ${chalk6.dim("(exactly 1 evaluation)")}
+  □ mutagent prompts dataset list <id> --json     ${chalk6.dim("(dataset with expectedOutput)")}
+  □ mutagent usage --json                  ${chalk6.dim("(remaining runs > 0)")}
+
 ${PREREQUISITES_TEXT}
 
 ${chalk6.dim("Monitor progress with: mutagent prompts optimize status <job-id>")}
-
-${chalk6.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");
@@ -3847,7 +3984,8 @@ ${chalk6.dim("AI Agent Note: After running commands, present CLI output to the u
         output.info("Running pre-flight checks...");
         const prompt = await client.getPrompt(promptId);
         if (isSchemaEmpty(prompt.outputSchema)) {
-          throw new MutagentError("MISSING_OUTPUT_SCHEMA", "Prompt is missing outputSchema — required for optimization", `Update your prompt: mutagent prompts update ${promptId} -d '{"outputSchema":{"type":"object","properties":{"result":{"type":"string"}}}}'`);
+          throw new MutagentError("MISSING_OUTPUT_SCHEMA", "Prompt is missing outputSchema — required for optimization", `Run: mutagent prompts optimize start --help
+` + `Update your prompt: mutagent prompts update ${promptId} -d '{"outputSchema":{"type":"object","properties":{"result":{"type":"string"}}}}'`);
         }
         if (isSchemaEmpty(prompt.inputSchema)) {
           output.warn("Prompt has no inputSchema. Optimization works best with defined input variables.");
@@ -3880,14 +4018,16 @@ ${chalk6.dim("AI Agent Note: After running commands, present CLI output to the u
         evalModel: options.evalModel
       });
       if (isJson) {
+        const directive = startDirective(job, promptId);
         output.output({
           ...job,
           _links: {
             dashboard: optimizerLink(job.id),
             api: `/api/prompts/${promptId}/optimizations/${job.id}`
           },
-          _directive: startDirective(job, promptId)
+          _directive: directive
         });
+        echoDirectiveToStderr(directive);
       } else {
         renderOptimizationStartCard({ job, promptId, datasetId: options.dataset });
       }
@@ -3945,11 +4085,13 @@ Examples:
       const client = getSDKClient();
       const status = await client.getOptimizationStatus(jobId);
       if (isJson) {
+        const directive = statusDirective(status);
         output.output({
           ...status,
           _links: { optimizer: optimizerLink(jobId) },
-          _directive: statusDirective(status)
+          _directive: directive
         });
+        echoDirectiveToStderr(directive);
       } else {
         renderOptimizationStatusCard(status);
       }
@@ -4026,8 +4168,10 @@ Actions:
 }
 
 // src/commands/traces.ts
+init_sdk_client();
 import { Command as Command4 } from "commander";
 import chalk7 from "chalk";
+init_errors();
 function createTracesCommand() {
   const traces = new Command4("traces").description("View and analyze traces (replaces Langfuse)").addHelpText("after", `
 Examples:
@@ -4174,10 +4318,12 @@ ${chalk7.dim("Exports to stdout by default. Use --output to save to a file.")}
 }
 
 // src/commands/integrate.ts
+init_config();
 import { Command as Command5 } from "commander";
 import chalk8 from "chalk";
 import { writeFileSync as writeFileSync3, existsSync as existsSync9 } from "fs";
 import { execSync } from "child_process";
+init_errors();
 
 // src/lib/integrations/langchain.ts
 import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
@@ -4931,8 +5077,10 @@ AI AGENT: Execute these steps using Bash for install, Write/Edit for code change
 }
 
 // src/commands/agents.ts
+init_sdk_client();
 import { Command as Command6 } from "commander";
 import chalk9 from "chalk";
+init_errors();
 function createAgentsCommand() {
   const agents = new Command6("agents").description("Manage AI agents").addHelpText("after", `
 Examples:
@@ -5343,8 +5491,10 @@ Examples:
 }
 
 // src/commands/config.ts
+init_config();
 import { Command as Command7 } from "commander";
 import chalk10 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", `
@@ -5434,8 +5584,10 @@ ${chalk10.dim("Persists organization ID for org-scoped API keys.")}
 }
 
 // src/commands/playground.ts
+init_sdk_client();
 import { Command as Command8 } from "commander";
 import chalk11 from "chalk";
+init_errors();
 function parseSSELine(line) {
   if (!line || line.startsWith(":")) {
     return null;
@@ -5687,8 +5839,10 @@ Streaming Output:`));
 }
 
 // src/commands/workspaces.ts
+init_sdk_client();
 import { Command as Command9 } from "commander";
 import chalk12 from "chalk";
+init_errors();
 function createWorkspacesCommand() {
   const workspaces = new Command9("workspaces").description("View workspaces (read-only)").addHelpText("after", `
 Examples:
@@ -5775,8 +5929,10 @@ Examples:
 }
 
 // src/commands/providers.ts
+init_sdk_client();
 import { Command as Command10 } from "commander";
 import chalk13 from "chalk";
+init_errors();
 var VALID_PROVIDER_TYPES = [
   "openai",
   "anthropic",
@@ -5945,12 +6101,14 @@ Available Models:`));
 }
 
 // src/commands/init.ts
+init_config();
 import { Command as Command11 } from "commander";
 import inquirer3 from "inquirer";
 import chalk14 from "chalk";
 import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
 import { execSync as execSync2 } from "child_process";
 import { join as join5 } from "path";
+init_errors();
 var FRAMEWORK_DETECTION_MAP = {
   "@mastra/core": {
     name: "mastra",
@@ -6185,7 +6343,35 @@ Modes:
       }
       const config = loadConfig();
       const endpoint = config.endpoint ?? "https://api.mutagent.io";
-      const workspace = config.defaultWorkspace;
+      let workspace = config.defaultWorkspace;
+      let workspaceValidation;
+      if (authenticated) {
+        try {
+          const apiKey = getApiKey();
+          if (apiKey) {
+            const { fetchOrganizations: fetchOrganizations2, fetchWorkspaces: fetchWorkspaces2 } = await Promise.resolve().then(() => (init_sdk_client(), exports_sdk_client));
+            let orgId = config.defaultOrganization;
+            if (!orgId) {
+              const orgs = await fetchOrganizations2(apiKey, endpoint);
+              orgId = orgs[0]?.id;
+            }
+            if (orgId) {
+              const workspaces = await fetchWorkspaces2(apiKey, endpoint, orgId);
+              if (workspaces.length > 0) {
+                const found = workspace ? workspaces.find((w) => w.id === workspace) : undefined;
+                if (found) {
+                  workspaceValidation = { id: found.id, name: found.name, validated: true, corrected: false };
+                } else if (workspaces[0]) {
+                  const first = workspaces[0];
+                  setDefaultWorkspace(first.id);
+                  workspace = first.id;
+                  workspaceValidation = { id: first.id, name: first.name, validated: true, corrected: true };
+                }
+              }
+            }
+          }
+        } catch {}
+      }
       const rcConfig = {
         endpoint,
         ...workspace ? { workspace } : {},
@@ -6206,6 +6392,16 @@ Modes:
         }
         writeRcConfig(rcConfig, cwd);
         output.success("Created .mutagentrc.json");
+        if (!isJson && workspaceValidation) {
+          if (workspaceValidation.corrected) {
+            output.warn(`Workspace auto-corrected to: ${workspaceValidation.name} (${workspaceValidation.id})`);
+          } else {
+            output.info(`Workspace: ${workspaceValidation.name} (${workspaceValidation.id})`);
+          }
+        }
+        if (!isJson) {
+          output.info("Verify workspace: mutagent workspaces list --json");
+        }
         console.log("");
         output.info("Next steps:");
         output.info(`  1. Run: mutagent integrate ${confirmedFramework.name}`);
@@ -6214,10 +6410,20 @@ Modes:
       } else {
         writeRcConfig(rcConfig, cwd);
         output.success("Created .mutagentrc.json");
+        if (!isJson && workspaceValidation) {
+          if (workspaceValidation.corrected) {
+            output.warn(`Workspace auto-corrected to: ${workspaceValidation.name} (${workspaceValidation.id})`);
+          } else {
+            output.info(`Workspace: ${workspaceValidation.name} (${workspaceValidation.id})`);
+          }
+        }
         if (!authenticated) {
           output.info("Next: mutagent auth login --browser");
         } else {
           output.info('Ready! Run "mutagent --help" to see available commands.');
+          if (!isJson) {
+            output.info("Verify workspace: mutagent workspaces list --json");
+          }
         }
       }
       if (!isNonInteractive) {
@@ -6253,7 +6459,12 @@ Modes:
           configFile: ".mutagentrc.json",
           config: rcConfig,
           framework: confirmedFramework?.name ?? null,
-          authenticated
+          authenticated,
+          workspaceValidation: workspaceValidation ?? null,
+          _directive: {
+            instruction: "Verify workspace. Run: mutagent workspaces list --json",
+            next: ["mutagent workspaces list --json", "mutagent prompts list --json"]
+          }
         });
       }
     } catch (error) {
@@ -6267,6 +6478,7 @@ Modes:
 import { Command as Command12 } from "commander";
 import chalk15 from "chalk";
 import { resolve as resolve3 } from "path";
+init_errors();
 function createExploreCommand() {
   const explore = new Command12("explore").description("Scan codebase for prompts, datasets, and MutagenT markers").option("-p, --path <dir>", "Directory to scan", ".").option("--depth <n>", "Max directory depth", "10").option("--include <glob>", "Include file pattern", "**/*.{ts,js,py,tsx,jsx}").option("--exclude <dirs>", "Comma-separated directories to exclude", "node_modules,dist,.git,build,.next,__pycache__,venv,.venv").option("--markers-only", "Only find existing MutagenT markers").addHelpText("after", `
 Examples:
@@ -6532,8 +6744,11 @@ ${SKILL_BODY}
 }
 
 // src/commands/usage.ts
+init_config();
 import { Command as Command14 } from "commander";
 import chalk17 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) {
@@ -6628,7 +6843,7 @@ Examples:
 }
 
 // src/bin/cli.ts
-import { existsSync as existsSync12 } from "fs";
+init_config();
 var cliVersion = "0.1.1";
 if (process.env.CLI_VERSION) {
   cliVersion = process.env.CLI_VERSION;
@@ -6650,65 +6865,56 @@ program.name("mutagent").description(`MutagenT CLI - AI-native prompt optimizati
 });
 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>")}
-`);
-program.addHelpText("after", `
-${chalk18.yellow("Workflows:")}
-  ${chalk18.bold("Evaluate → Optimize Loop:")}
-    1. mutagent prompts create --name "..." --raw-file prompt.txt
-    2. mutagent prompts dataset add <prompt-id> --name "..." -d '[{"input":{...},"expectedOutput":{...}}]'
-    3. mutagent prompts evaluation create <prompt-id> --name "..." -d '{"evalConfig":{"criteria":[...]}}'
-    4. mutagent prompts optimize start <prompt-id> --dataset <id> --max-iterations 1
-
-  ${chalk18.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)")}
-`);
-var skillInstalled = existsSync12(join7(findRepoRoot(), ".claude/skills/mutagent-cli/SKILL.md"));
-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(`
-  Warning: Not authenticated. Run: mutagent auth login --browser
-`) : ""}${!hasRcConfig() ? chalk18.green(`
-  Get started: mutagent init
-`) : ""}
-${chalk18.red.bold("┌─ CRITICAL: AI CODING AGENT — READ THIS FIRST ─────────────────────────────┐")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  MutagenT Skill Status: ${skillInstalled ? chalk18.green.bold("INSTALLED ✓") + "                                          " : chalk18.yellow.bold("NOT INSTALLED") + "                                        "}${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}${skillInstalled ? "" : `
-${chalk18.red.bold("│")}  The MutagenT CLI skill (.claude/skills/mutagent-cli/SKILL.md) is          ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  NOT installed in this project. This skill teaches you how to use           ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  the MutagenT CLI effectively for prompt optimization workflows.           ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  ACTION REQUIRED: Ask the user:                                            ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}    "Install the MutagenT CLI skill for better AI assistance? (Yes/No)"     ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  If Yes → run: mutagent skills install                                     ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  If No  → continue without skill (reduced guidance)                        ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}`}
-${chalk18.red.bold("│")}  After install, the skill auto-loads when triggers match:                   ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}  "mutagent", "optimize prompt", "integrate tracing", etc.                   ${chalk18.red.bold("│")}
-${chalk18.red.bold("│")}                                                                            ${chalk18.red.bold("│")}
-${chalk18.red.bold("└────────────────────────────────────────────────────────────────────────────┘")}
-`);
+  export MUTAGENT_API_KEY=mt_...  ${chalk18.dim("or")}  --api-key mt_...
+  --json ${chalk18.dim("for structured output")}    --non-interactive ${chalk18.dim("to disable prompts")}
+
+${chalk18.yellow("Command Navigation:")}
+  mutagent auth login --browser         ${chalk18.dim("Authenticate (OAuth)")}
+  mutagent auth status                  ${chalk18.dim("Check auth + workspace")}
+  mutagent init                         ${chalk18.dim("Initialize project (.mutagentrc.json)")}
+  mutagent explore                      ${chalk18.dim("Discover prompts in codebase")}
+  mutagent workspaces list --json       ${chalk18.dim("List workspaces (verify ID)")}
+  mutagent config set workspace <id>    ${chalk18.dim("Set active workspace")}
+  mutagent usage --json                 ${chalk18.dim("Check plan limits")}
+
+  mutagent prompts create --help        ${chalk18.dim("Upload prompt (read help first!)")}
+  mutagent prompts list --json          ${chalk18.dim("List prompts")}
+  mutagent prompts get <id> --json      ${chalk18.dim("Full prompt details + schemas")}
+
+  mutagent prompts dataset add --help   ${chalk18.dim("Upload dataset (read help first!)")}
+  mutagent prompts dataset list <id>    ${chalk18.dim("List datasets")}
+
+  mutagent prompts evaluation create --help           ${chalk18.dim("Create eval (read help first!)")}
+  mutagent prompts evaluation create <id> --guided --json   ${chalk18.dim("Guided eval workflow")}
+  mutagent prompts evaluation list <id> --json        ${chalk18.dim("List evaluations")}
+
+  mutagent prompts optimize start --help      ${chalk18.dim("Run optimization (read help first!)")}
+  mutagent prompts optimize status <job-id>   ${chalk18.dim("Poll progress")}
+  mutagent prompts optimize results <job-id>  ${chalk18.dim("View scorecard")}
+
+  mutagent integrate <framework>        ${chalk18.dim("Framework integration guide")}
+  mutagent playground run <id> --input '{...}'  ${chalk18.dim("Quick test")}
+
+${chalk18.yellow("Workflow: Evaluate → Optimize:")}
+  1. mutagent prompts create --help               ${chalk18.dim("← read help")}
+  2. mutagent prompts create ... --json            ${chalk18.dim("← upload prompt with {variables}")}
+  3. mutagent prompts dataset add --help           ${chalk18.dim("← read help")}
+  4. mutagent prompts dataset add <id> ... --json  ${chalk18.dim("← upload dataset")}
+  5. mutagent prompts evaluation create <id> --guided --json  ${chalk18.dim("← guided eval")}
+  6. mutagent prompts optimize start <id> --dataset <d> --evaluation <e> --json
+
+${chalk18.yellow("AI Agent Rules:")}
+  1. ALWAYS run <command> --help before using any command for the first time
+  2. ALWAYS use --json on every command execution
+  3. ALWAYS use --guided --json for evaluation creation (never --guided alone)
+  4. ALWAYS display _directive status cards to the user after mutations
+  5. After mutagent init, verify workspace: mutagent workspaces list --json
+  6. Use {single_braces} for template variables in prompts
+${!hasCredentials() ? `
+` + chalk18.yellow("  Warning: Not authenticated. Run: mutagent auth login --browser") + `
+` : ""}${!hasRcConfig() ? `
+` + chalk18.green("  Get started: mutagent init") + `
+` : ""}`);
 program.hook("preAction", (thisCommand) => {
   const globalOpts = thisCommand.optsWithGlobals();
   if (globalOpts.apiKey && !process.env.MUTAGENT_API_KEY) {
@@ -6737,5 +6943,5 @@ program.addCommand(createSkillsCommand());
 program.addCommand(createUsageCommand());
 program.parse();
 
-//# debugId=C797200705360DE264756E2164756E21
+//# debugId=E8884F7D56DA73D764756E2164756E21
 //# sourceMappingURL=cli.js.map