@mindstudio-ai/agent 0.1.4 → 0.1.6

package/dist/cli.js

@@ -682,8 +682,8 @@ var init_metadata = __esm({
       "postToX": {
         stepType: "postToX",
         description: "Create a post on X (Twitter) from the connected account.",
-        usageNotes: "- Requires an X OAuth connection (connectionId).\n- Posts are plain text. Maximum 280 characters.",
-        inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text content of the post (max 280 characters)" }, "connectionId": { "type": "string", "description": "X (Twitter) OAuth connection ID" } }, "required": ["text"] },
+        usageNotes: "- Requires an X OAuth connection (connectionId).\n- Maximum 280 characters of text.\n- Optionally attach up to 4 media items (images, GIFs, or videos) via mediaUrls.\n- Media URLs must be publicly accessible. The service fetches and uploads them to X.\n- Supported formats: JPEG, PNG, GIF, WEBP, MP4. Images up to 5MB, videos up to 512MB.",
+        inputSchema: { "type": "object", "properties": { "text": { "type": "string", "description": "The text content of the post (max 280 characters)" }, "connectionId": { "type": "string", "description": "X (Twitter) OAuth connection ID" }, "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "Up to 4 URLs of images, GIFs, or videos to attach to the post" } }, "required": ["text"] },
         outputSchema: { "description": "This step does not produce output data." }
       },
       "postToZapier": {
@@ -1806,67 +1806,6 @@ var init_steps = __esm({
   }
 });
 
-// src/generated/helpers.ts
-var helpers_exports = {};
-__export(helpers_exports, {
-  applyHelperMethods: () => applyHelperMethods
-});
-function applyHelperMethods(AgentClass) {
-  const proto = AgentClass.prototype;
-  proto.listModels = function() {
-    return this._request("GET", "/helpers/models").then((r) => r.data);
-  };
-  proto.listModelsByType = function(modelType) {
-    return this._request("GET", `/helpers/models/${modelType}`).then((r) => r.data);
-  };
-  proto.listModelsSummary = function() {
-    return this._request("GET", "/helpers/models-summary").then((r) => r.data);
-  };
-  proto.listModelsSummaryByType = function(modelType) {
-    return this._request("GET", `/helpers/models-summary/${modelType}`).then((r) => r.data);
-  };
-  proto.listConnectors = function() {
-    return this._request("GET", "/helpers/connectors").then((r) => r.data);
-  };
-  proto.getConnector = function(serviceId) {
-    return this._request("GET", `/helpers/connectors/${serviceId}`).then((r) => r.data);
-  };
-  proto.getConnectorAction = function(serviceId, actionId) {
-    return this._request("GET", `/helpers/connectors/${serviceId}/${actionId}`).then((r) => r.data);
-  };
-  proto.listConnections = function() {
-    return this._request("GET", "/helpers/connections").then((r) => r.data);
-  };
-  proto.estimateStepCost = function(stepType, step, options) {
-    return this._request("POST", "/helpers/step-cost-estimate", { step: { type: stepType, ...step }, ...options }).then((r) => r.data);
-  };
-  proto.changeName = function(displayName) {
-    return this._request("POST", "/account/change-name", { displayName }).then(() => {
-    });
-  };
-  proto.changeProfilePicture = function(profilePictureUrl) {
-    return this._request("POST", "/account/change-profile-picture", { profilePictureUrl }).then(() => {
-    });
-  };
-  proto.uploadFile = async function(content, options) {
-    const { data } = await this._request("POST", "/account/upload", { extension: options.extension, ...options.type != null && { type: options.type } });
-    const { uploadUrl, url } = data;
-    const buf = content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength);
-    const res = await fetch(uploadUrl, {
-      method: "PUT",
-      body: buf,
-      headers: options.type ? { "Content-Type": options.type } : {}
-    });
-    if (!res.ok) throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
-    return { url };
-  };
-}
-var init_helpers = __esm({
-  "src/generated/helpers.ts"() {
-    "use strict";
-  }
-});
-
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
@@ -1898,7 +1837,6 @@ var init_client = __esm({
     init_rate_limit();
     init_config();
     init_steps();
-    init_helpers();
     DEFAULT_BASE_URL = "https://v1.mindstudio-api.com";
     DEFAULT_MAX_RETRIES = 3;
     MindStudioAgent = class {
@@ -1969,6 +1907,85 @@ var init_client = __esm({
           $billingEvents: billingEvents != null ? JSON.parse(billingEvents) : void 0
         };
       }
+      /**
+       * Execute multiple steps in parallel in a single request.
+       *
+       * All steps run in parallel on the server. Results are returned in the same
+       * order as the input. Individual step failures do not affect other steps —
+       * partial success is possible.
+       *
+       * ```ts
+       * const { results } = await agent.executeStepBatch([
+       *   { stepType: 'generateImage', step: { prompt: 'a sunset' } },
+       *   { stepType: 'textToSpeech', step: { text: 'Hello world' } },
+       * ]);
+       * ```
+       */
+      async executeStepBatch(steps, options) {
+        const threadId = options?.threadId ?? (this._reuseThreadId ? this._threadId : void 0);
+        const { data } = await request(this._httpConfig, "POST", "/steps/execute-batch", {
+          steps,
+          ...options?.appId != null && { appId: options.appId },
+          ...threadId != null && { threadId }
+        });
+        const results = await Promise.all(
+          data.results.map(async (r) => {
+            if (r.output != null) {
+              return {
+                stepType: r.stepType,
+                output: r.output,
+                billingCost: r.billingCost,
+                error: r.error
+              };
+            }
+            if (r.outputUrl) {
+              const res = await fetch(r.outputUrl);
+              if (!res.ok) {
+                return {
+                  stepType: r.stepType,
+                  error: `Failed to fetch output from S3: ${res.status} ${res.statusText}`
+                };
+              }
+              const envelope = await res.json();
+              return {
+                stepType: r.stepType,
+                output: envelope.value,
+                billingCost: r.billingCost
+              };
+            }
+            return {
+              stepType: r.stepType,
+              billingCost: r.billingCost,
+              error: r.error
+            };
+          })
+        );
+        if (this._reuseThreadId && data.threadId) {
+          this._threadId = data.threadId;
+        }
+        return {
+          results,
+          totalBillingCost: data.totalBillingCost,
+          appId: data.appId,
+          threadId: data.threadId
+        };
+      }
+      /**
+       * Get the authenticated user's identity and organization info.
+       *
+       * ```ts
+       * const info = await agent.getUserInfo();
+       * console.log(info.displayName, info.organizationName);
+       * ```
+       */
+      async getUserInfo() {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          "/account/userinfo"
+        );
+        return data;
+      }
       /**
        * List all pre-built agents in the organization.
        *
@@ -2045,13 +2062,155 @@ var init_client = __esm({
           return poll.result;
         }
       }
-      /** @internal Used by generated helper methods. */
+      /** @internal Used by generated action methods. */
       _request(method, path, body) {
         return request(this._httpConfig, method, path, body);
       }
+      // -------------------------------------------------------------------------
+      // Helper methods — models
+      // -------------------------------------------------------------------------
+      /** List all available AI models. */
+      async listModels() {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          "/helpers/models"
+        );
+        return data;
+      }
+      /** List AI models filtered by type. */
+      async listModelsByType(modelType) {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          `/helpers/models/${modelType}`
+        );
+        return data;
+      }
+      /** List all available AI models (summary). Returns only id, name, type, and tags. */
+      async listModelsSummary() {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          "/helpers/models-summary"
+        );
+        return data;
+      }
+      /** List AI models (summary) filtered by type. */
+      async listModelsSummaryByType(modelType) {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          `/helpers/models-summary/${modelType}`
+        );
+        return data;
+      }
+      // -------------------------------------------------------------------------
+      // Helper methods — OAuth connectors & connections
+      // -------------------------------------------------------------------------
+      /**
+       * List available OAuth connector services (Slack, Google, HubSpot, etc.).
+       *
+       * These are third-party integrations from the MindStudio Connector Registry.
+       * For most tasks, use actions directly instead.
+       */
+      async listConnectors() {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          "/helpers/connectors"
+        );
+        return data;
+      }
+      /** Get details for a single OAuth connector service. */
+      async getConnector(serviceId) {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          `/helpers/connectors/${serviceId}`
+        );
+        return data;
+      }
+      /** Get the full configuration for an OAuth connector action, including input fields. */
+      async getConnectorAction(serviceId, actionId) {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          `/helpers/connectors/${serviceId}/${actionId}`
+        );
+        return data;
+      }
+      /** List OAuth connections for the organization. These are authenticated third-party service links. */
+      async listConnections() {
+        const { data } = await request(
+          this._httpConfig,
+          "GET",
+          "/helpers/connections"
+        );
+        return data;
+      }
+      // -------------------------------------------------------------------------
+      // Helper methods — cost estimation
+      // -------------------------------------------------------------------------
+      /** Estimate the cost of executing an action before running it. */
+      async estimateStepCost(stepType, step, options) {
+        const { data } = await request(this._httpConfig, "POST", "/helpers/step-cost-estimate", {
+          step: { type: stepType, ...step },
+          ...options
+        });
+        return data;
+      }
+      // -------------------------------------------------------------------------
+      // Account methods
+      // -------------------------------------------------------------------------
+      /** Update the display name of the authenticated user/agent. */
+      async changeName(displayName) {
+        await request(this._httpConfig, "POST", "/account/change-name", {
+          name: displayName
+        });
+      }
+      /** Update the profile picture of the authenticated user/agent. */
+      async changeProfilePicture(url) {
+        await request(this._httpConfig, "POST", "/account/change-profile-picture", {
+          url
+        });
+      }
+      /**
+       * Upload a file to the MindStudio CDN.
+       *
+       * Gets a signed upload URL, PUTs the file content, and returns the
+       * permanent public URL.
+       */
+      async uploadFile(content, options) {
+        const { data } = await request(
+          this._httpConfig,
+          "POST",
+          "/account/upload",
+          {
+            extension: options.extension,
+            ...options.type != null && { type: options.type }
+          }
+        );
+        const buf = content.buffer.slice(
+          content.byteOffset,
+          content.byteOffset + content.byteLength
+        );
+        const res = await fetch(data.uploadUrl, {
+          method: "PUT",
+          body: buf,
+          headers: options.type ? { "Content-Type": options.type } : {}
+        });
+        if (!res.ok) {
+          throw new MindStudioError(
+            `Upload failed: ${res.status} ${res.statusText}`,
+            "upload_error",
+            res.status
+          );
+        }
+        return { url: data.url };
+      }
     };
     applyStepMethods(MindStudioAgent);
-    applyHelperMethods(MindStudioAgent);
   }
 });
 
@@ -2115,9 +2274,9 @@ async function startMcpServer(options) {
           capabilities: { tools: {} },
           serverInfo: {
             name: "mindstudio-agent",
-            version: "0.1.4"
+            version: "0.1.6"
           },
-          instructions: "Welcome to MindStudio \u2014 a platform with 200+ AI models, 850+ third-party integrations, and pre-built agents.\n\nGetting started:\n1. Call `listAgents` to verify your connection and see available agents.\n2. Call `changeName` to set your display name \u2014 use your name or whatever your user calls you. This is how you'll appear in MindStudio request logs.\n3. If you have a profile picture or icon, call `uploadFile` to upload it, then `changeProfilePicture` with the returned URL. This helps users identify your requests in their logs.\n4. Call `listSteps` to discover all available step methods and helpers.\n\nThen use the tools to generate text, images, video, audio, search the web, work with data sources, run agents, and more.\n\nImportant:\n- AI-powered steps (text generation, image generation, video, audio, etc.) cost money. Before running these, call `estimateStepCost` and confirm with the user before proceeding \u2014 unless they've explicitly told you to go ahead.\n- Not all agents from `listAgents` are configured for API use. Do not try to run an agent just because it appears in the list \u2014 it will likely fail. Only run agents the user specifically asks you to run."
+          instructions: "Welcome to MindStudio \u2014 a platform with 200+ AI models, 850+ third-party integrations, and pre-built agents.\n\nGetting started:\n1. Call `listAgents` to verify your connection and see available agents.\n2. Call `changeName` to set your display name \u2014 use your name or whatever your user calls you. This is how you'll appear in MindStudio request logs.\n3. If you have a profile picture or icon, call `uploadFile` to upload it, then `changeProfilePicture` with the returned URL. This helps users identify your requests in their logs.\n4. Call `listActions` to discover all available actions.\n\nThen use the tools to generate text, images, video, audio, search the web, work with data sources, run agents, and more.\n\nImportant:\n- AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Before running these, call `estimateActionCost` and confirm with the user before proceeding \u2014 unless they've explicitly told you to go ahead.\n- Not all agents from `listAgents` are configured for API use. Do not try to run an agent just because it appears in the list \u2014 it will likely fail. Only run agents the user specifically asks you to run."
         });
         break;
       case "notifications/initialized":
@@ -2130,7 +2289,7 @@ async function startMcpServer(options) {
         const args = params.arguments ?? {};
         try {
           let result;
-          if (toolName === "listSteps") {
+          if (toolName === "listActions") {
             const meta = await getMetadata();
             const summary = {};
             for (const [name, step] of Object.entries(meta)) {
@@ -2167,7 +2326,7 @@ async function startMcpServer(options) {
             );
           } else if (toolName === "listConnections") {
             result = await getAgent().listConnections();
-          } else if (toolName === "estimateStepCost") {
+          } else if (toolName === "estimateActionCost") {
             result = await getAgent().estimateStepCost(
               args.stepType,
               args.step,
@@ -2196,6 +2355,10 @@ async function startMcpServer(options) {
               extension: ext,
               ...mimeType && { type: mimeType }
             });
+          } else if (toolName === "executeBatch") {
+            result = await getAgent().executeStepBatch(
+              args.steps
+            );
           } else if (toolName === "listAgents") {
             result = await getAgent().listAgents();
           } else if (toolName === "runAgent") {
@@ -2277,21 +2440,22 @@ var init_mcp = __esm({
       listModelsByType: "List AI models filtered by type.",
       listModelsSummary: "List all AI models (summary: id, name, type, tags).",
       listModelsSummaryByType: "List AI models (summary) filtered by type.",
-      listConnectors: "List available connector services and their actions.",
-      getConnector: "Get details for a connector service.",
-      getConnectorAction: "Get full configuration for a connector action.",
-      listConnections: "List OAuth connections for the organization.",
-      estimateStepCost: "Estimate the cost of executing a step before running it.",
+      listConnectors: "List available OAuth connector services (third-party integrations). For most tasks, use actions directly instead.",
+      getConnector: "Get details for an OAuth connector service.",
+      getConnectorAction: "Get full configuration for an OAuth connector action.",
+      listConnections: "List OAuth connections for the organization (authenticated third-party service links).",
+      estimateStepCost: "Estimate the cost of executing an action before running it.",
       changeName: "Update the display name of the authenticated agent.",
       changeProfilePicture: "Update the profile picture of the authenticated agent.",
       uploadFile: "Upload a file to the MindStudio CDN.",
       listAgents: "List all pre-built agents in the organization.",
-      runAgent: "Run a pre-built agent and wait for the result."
+      runAgent: "Run a pre-built agent and wait for the result.",
+      executeBatch: "Execute multiple actions in parallel in a single request."
     };
     HELPER_TOOLS = [
       {
-        name: "listSteps",
-        description: "List all available methods with their descriptions. Returns a compact { method: description } map. Call this to discover what steps and helpers are available, then call a specific method by name. Tip: if you haven't already, call `changeName` to set your display name first.",
+        name: "listActions",
+        description: "List all available actions with their descriptions. Returns a compact { action: description } map. Call this to discover what actions are available, then call a specific action by name. Tip: if you haven't already, call `changeName` to set your display name first.",
         inputSchema: { type: "object", properties: {} }
       },
       {
@@ -2350,12 +2514,12 @@ var init_mcp = __esm({
       },
       {
         name: "listConnectors",
-        description: "List available connector services (Slack, Google, HubSpot, etc.) and their actions.",
+        description: "List available OAuth connector services (Slack, Google, HubSpot, etc.) and their actions. These are third-party integrations \u2014 for most tasks, use actions directly instead.",
         inputSchema: { type: "object", properties: {} }
       },
       {
         name: "getConnector",
-        description: "Get details for a single connector service by ID.",
+        description: "Get details for a single OAuth connector service by ID.",
         inputSchema: {
           type: "object",
           properties: { serviceId: { type: "string" } },
@@ -2364,7 +2528,7 @@ var init_mcp = __esm({
       },
       {
         name: "getConnectorAction",
-        description: "Get the full configuration for a connector action, including all input fields needed to call it via runFromConnectorRegistry.",
+        description: "Get the full configuration for an OAuth connector action, including all input fields needed to call it via runFromConnectorRegistry.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2382,22 +2546,22 @@ var init_mcp = __esm({
       },
       {
         name: "listConnections",
-        description: "List OAuth connections for the organization. Use the returned connection IDs when calling connector actions.",
+        description: "List OAuth connections for the organization (authenticated third-party service links). Use the returned connection IDs when calling OAuth connector actions.",
         inputSchema: { type: "object", properties: {} }
       },
       {
-        name: "estimateStepCost",
-        description: "Estimate the cost of executing a step before running it. Pass the same step config you would use for execution.",
+        name: "estimateActionCost",
+        description: "Estimate the cost of executing an action before running it. Pass the same config you would use for execution.",
         inputSchema: {
           type: "object",
           properties: {
             stepType: {
               type: "string",
-              description: 'The step type name (e.g. "generateText").'
+              description: 'The action type name (e.g. "generateText").'
             },
             step: {
               type: "object",
-              description: "The step input parameters.",
+              description: "The action input parameters.",
               additionalProperties: true
             },
             appId: {
@@ -2454,6 +2618,37 @@ var init_mcp = __esm({
           required: ["filePath"]
         }
       },
+      {
+        name: "executeBatch",
+        description: "Execute multiple actions in parallel in a single request. All steps run in parallel on the server. Results are returned in the same order as the input. Individual step failures do not affect other steps \u2014 partial success is possible. Maximum 50 steps per batch.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            steps: {
+              type: "array",
+              description: "Array of steps to execute.",
+              minItems: 1,
+              maxItems: 50,
+              items: {
+                type: "object",
+                properties: {
+                  stepType: {
+                    type: "string",
+                    description: 'The action type name (e.g. "generateImage", "textToSpeech").'
+                  },
+                  step: {
+                    type: "object",
+                    description: "Action input parameters.",
+                    additionalProperties: true
+                  }
+                },
+                required: ["stepType", "step"]
+              }
+            }
+          },
+          required: ["steps"]
+        }
+      },
       {
         name: "listAgents",
         description: "List all pre-built agents in the organization along with org metadata.",
@@ -2495,44 +2690,66 @@ import { parseArgs } from "util";
 import { execSync } from "child_process";
 import { readFileSync as readFileSync3 } from "fs";
 import { extname as extname2 } from "path";
-var HELP = `Usage: mindstudio <command | method> [options]
+var HELP = `Usage: mindstudio <command> [options]
+
+Run actions:
+  <action> [json | --flags]            Run an action directly
+  run <action> [json | --flags]        Run an action (explicit form)
+  estimate-cost <action> [json]        Estimate cost before running
+
+Discover:
+  list-actions [--json] [--summary]    List all available actions
+  info <action>                        Show action details and parameters
+  list-models [--type <t>] [--summary] List available AI models
+
+Batch:
+  batch [json]                         Execute multiple actions in parallel
+
+Pre-built agents:
+  agents [--json]                      List agents in your organization
+  run-agent <appId> [json | --flags]   Run an agent and wait for result
+
+Account:
+  login                                Authenticate with MindStudio
+  logout                               Clear stored credentials
+  whoami                               Show current user and organization
+  change-name <name>                   Update your display name
+  change-profile-picture <url>         Update your profile picture
+  upload <filepath>                    Upload a file to the MindStudio CDN
 
-Commands:
-  login                       Authenticate with MindStudio (opens browser)
-  logout                      Clear stored credentials
-  whoami                      Show current authentication status
-  upload <filepath>             Upload a file to the MindStudio CDN
-  <method> [json | --flags]   Execute a step method (shorthand for exec)
-  exec <method> [json | --flags]   Execute a step method
-  list [--json] [--summary]   List available methods (--summary for compact JSON)
-  info <method>               Show method details (params, types, output)
-  agents [--json]             List pre-built agents in your organization
-  run <appId> [json | --flags]  Run a pre-built agent and wait for result
-  mcp                         Start MCP server (JSON-RPC over stdio)
+OAuth integrations:
+  list-connectors [<id> [<actionId>]]  Browse OAuth connector services
+  list-connections                     List your OAuth connections
+
+Other:
+  mcp                                  Start MCP server (JSON-RPC over stdio)
 
 Options:
-  --api-key <key>          API key (or set MINDSTUDIO_API_KEY env)
-  --base-url <url>         API base URL
-  --app-id <id>            App ID for thread context
-  --thread-id <id>         Thread ID for state persistence
-  --output-key <key>       Extract a single field from the result
-  --no-meta                Strip $-prefixed metadata from output
-  --workflow <name>        Workflow to execute (run command)
-  --version <ver>          App version override, e.g. "draft" (run command)
-  --json                   Output as JSON (list/agents only)
-  --help                   Show this help
+  --api-key <key>    API key (or set MINDSTUDIO_API_KEY env var)
+  --base-url <url>   API base URL override
+  --app-id <id>      App ID for thread context
+  --thread-id <id>   Thread ID for state persistence
+  --output-key <key> Extract a single field from the result
+  --no-meta          Strip $-prefixed metadata from output
+  --workflow <name>  Workflow to execute (run-agent only)
+  --version <ver>    App version, e.g. "draft" (run-agent only)
+  --json             Output as JSON
+  --summary          Compact output (list-actions, list-models)
+  --type <type>      Filter by model type (list-models)
+  --help             Show this help
 
 Examples:
-  mindstudio login
   mindstudio generate-image --prompt "a sunset"
-  mindstudio generate-image --prompt "a sunset" --output-key imageUrl
   mindstudio generate-text --message "hello" --no-meta
-  mindstudio generate-image '{"prompt":"a sunset"}'
+  mindstudio generate-image '{"prompt":"a sunset"}' --output-key imageUrl
   echo '{"query":"test"}' | mindstudio search-google
+  mindstudio estimate-cost generate-image --prompt "a sunset"
+  mindstudio list-actions --summary
   mindstudio info generate-image
-  mindstudio list --json
+  mindstudio list-models --type image_generation
+  mindstudio batch '[{"stepType":"generateImage","step":{"prompt":"a cat"}}]'
+  mindstudio run-agent <appId> --query "hello"
   mindstudio agents
-  mindstudio run <appId> --query "hello"
   mindstudio mcp
 `;
 function camelToKebab(s) {
@@ -2586,6 +2803,10 @@ function fatal(message) {
   process.stderr.write(JSON.stringify({ error: { message } }) + "\n");
   process.exit(1);
 }
+function usageBlock(lines) {
+  process.stderr.write("\n" + lines.map((l) => "  " + l).join("\n") + "\n\n");
+  process.exit(1);
+}
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -2593,19 +2814,6 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8").trim();
 }
-var HELPER_NAMES = /* @__PURE__ */ new Set([
-  "listModels",
-  "listModelsByType",
-  "listModelsSummary",
-  "listModelsSummaryByType",
-  "listConnectors",
-  "getConnector",
-  "getConnectorAction",
-  "listConnections",
-  "estimateStepCost",
-  "changeName",
-  "changeProfilePicture"
-]);
 function resolveMethodOrFail(name, metadataKeys) {
   if (metadataKeys.has(name)) return name;
   const camel = kebabToCamel(name);
@@ -2622,36 +2830,18 @@ function resolveMethodOrFail(name, metadataKeys) {
   }
   const suggestion = bestDist <= 3 ? ` Did you mean '${bestMatch}'?` : "";
   fatal(
-    `Unknown method: ${name}.${suggestion} Run 'mindstudio list' to see available methods.`
+    `Unknown action: ${name}.${suggestion} Run 'mindstudio list-actions' to see available actions.`
   );
 }
 async function getAllMethodKeys() {
   const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
-  return /* @__PURE__ */ new Set([...Object.keys(stepMetadata2), ...HELPER_NAMES]);
+  return new Set(Object.keys(stepMetadata2));
 }
-var HELPER_DESCRIPTIONS2 = {
-  listModels: "List all available AI models.",
-  listModelsByType: "List AI models filtered by type.",
-  listModelsSummary: "List all AI models (summary: id, name, type, tags).",
-  listModelsSummaryByType: "List AI models (summary) filtered by type.",
-  listConnectors: "List available connector services and their actions.",
-  getConnector: "Get details for a connector service.",
-  getConnectorAction: "Get full configuration for a connector action.",
-  listConnections: "List OAuth connections for the organization.",
-  estimateStepCost: "Estimate the cost of executing a step before running it.",
-  changeName: "Update the display name of the authenticated agent.",
-  changeProfilePicture: "Update the profile picture of the authenticated agent.",
-  listAgents: "List all pre-built agents in the organization.",
-  runAgent: "Run a pre-built agent and wait for the result."
-};
 function buildSummary(stepMetadata2) {
   const summary = {};
   for (const [name, meta] of Object.entries(stepMetadata2)) {
     summary[name] = meta.description;
   }
-  for (const [name, desc] of Object.entries(HELPER_DESCRIPTIONS2)) {
-    summary[name] = desc;
-  }
   return summary;
 }
 async function cmdList(asJson, asSummary) {
@@ -2686,79 +2876,6 @@ async function cmdList(asJson, asSummary) {
 async function cmdInfo(rawMethod) {
   const allKeys = await getAllMethodKeys();
   const method = resolveMethodOrFail(rawMethod, allKeys);
-  if (HELPER_NAMES.has(method)) {
-    const helpers = {
-      listModels: {
-        desc: "List all available AI models.",
-        input: "(none)",
-        output: "{ models: MindStudioModel[] }"
-      },
-      listModelsByType: {
-        desc: "List AI models filtered by type.",
-        input: "modelType: string (required)",
-        output: "{ models: MindStudioModel[] }"
-      },
-      listModelsSummary: {
-        desc: "List all AI models (summary: id, name, type, tags).",
-        input: "(none)",
-        output: "{ models: MindStudioModelSummary[] }"
-      },
-      listModelsSummaryByType: {
-        desc: "List AI models (summary) filtered by type.",
-        input: "modelType: string (required)",
-        output: "{ models: MindStudioModelSummary[] }"
-      },
-      listConnectors: {
-        desc: "List available connector services and their actions.",
-        input: "(none)",
-        output: "{ services: ConnectorService[] }"
-      },
-      getConnector: {
-        desc: "Get details for a connector service.",
-        input: "serviceId: string (required)",
-        output: "{ service: ConnectorService }"
-      },
-      getConnectorAction: {
-        desc: "Get full configuration for a connector action.",
-        input: "serviceId: string, actionId: string (both required)",
-        output: "{ action: ConnectorActionDetail }"
-      },
-      listConnections: {
-        desc: "List OAuth connections for the organization.",
-        input: "(none)",
-        output: "{ connections: Connection[] }"
-      },
-      estimateStepCost: {
-        desc: "Estimate the cost of executing a step before running it.",
-        input: "stepType: string (required), step: object, appId?: string, workflowId?: string",
-        output: "{ costType?: string, estimates?: StepCostEstimateEntry[] }"
-      },
-      changeName: {
-        desc: "Update the display name of the authenticated agent.",
-        input: "displayName: string (required)",
-        output: "(none)"
-      },
-      changeProfilePicture: {
-        desc: "Update the profile picture of the authenticated agent.",
-        input: "profilePictureUrl: string (required)",
-        output: "(none)"
-      }
-    };
-    const h = helpers[method];
-    process.stderr.write(`
-  ${camelToKebab(method)}
-
-`);
-    process.stderr.write(`  ${h.desc}
-
-`);
-    process.stderr.write(`  Input:  ${h.input}
-`);
-    process.stderr.write(`  Output: ${h.output}
-
-`);
-    return;
-  }
   const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
   const meta = stepMetadata2[method];
   const out = [];
@@ -2814,61 +2931,21 @@ async function cmdExec(method, input, options) {
   await Promise.resolve().then(() => (init_steps(), steps_exports)).then(
     (m) => m.applyStepMethods(MindStudioAgent2)
   );
-  await Promise.resolve().then(() => (init_helpers(), helpers_exports)).then(
-    (m) => m.applyHelperMethods(MindStudioAgent2)
-  );
   const agent = new MindStudioAgent2({
     apiKey: options.apiKey,
     baseUrl: options.baseUrl
   });
-  let result;
-  if (method === "listModels") {
-    result = await agent.listModels();
-  } else if (method === "listModelsByType") {
-    result = await agent.listModelsByType(input.modelType);
-  } else if (method === "listModelsSummary") {
-    result = await agent.listModelsSummary();
-  } else if (method === "listModelsSummaryByType") {
-    result = await agent.listModelsSummaryByType(input.modelType);
-  } else if (method === "listConnectors") {
-    result = await agent.listConnectors();
-  } else if (method === "getConnector") {
-    result = await agent.getConnector(input.serviceId);
-  } else if (method === "getConnectorAction") {
-    result = await agent.getConnectorAction(
-      input.serviceId,
-      input.actionId
-    );
-  } else if (method === "listConnections") {
-    result = await agent.listConnections();
-  } else if (method === "estimateStepCost") {
-    result = await agent.estimateStepCost(
-      input.stepType,
-      input.step,
-      {
-        appId: input.appId,
-        workflowId: input.workflowId
-      }
+  const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
+  const meta = stepMetadata2[method];
+  if (!meta) {
+    fatal(
+      `Unknown action: ${method}. Run 'mindstudio list-actions' to see available actions.`
     );
-  } else if (method === "changeName") {
-    await agent.changeName(input.displayName);
-    result = { success: true };
-  } else if (method === "changeProfilePicture") {
-    await agent.changeProfilePicture(input.profilePictureUrl);
-    result = { success: true };
-  } else {
-    const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
-    const meta = stepMetadata2[method];
-    if (!meta) {
-      fatal(
-        `Unknown method: ${method}. Run 'mindstudio list' to see available methods.`
-      );
-    }
-    result = await agent.executeStep(meta.stepType, input, {
-      appId: options.appId,
-      threadId: options.threadId
-    });
   }
+  const result = await agent.executeStep(meta.stepType, input, {
+    appId: options.appId,
+    threadId: options.threadId
+  });
   if (options.outputKey) {
     const val = result[options.outputKey];
     if (typeof val === "string") {
@@ -2915,6 +2992,62 @@ async function cmdAgents(asJson, options) {
     }
   }
 }
+function createAgent(options) {
+  return Promise.resolve().then(() => (init_client(), client_exports)).then(
+    ({ MindStudioAgent: MindStudioAgent2 }) => new MindStudioAgent2({
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl
+    })
+  );
+}
+function jsonOut(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+async function cmdListModels(options) {
+  const agent = await createAgent(options);
+  if (options.summary) {
+    const result = options.type ? await agent.listModelsSummaryByType(options.type) : await agent.listModelsSummary();
+    jsonOut(result);
+  } else {
+    const result = options.type ? await agent.listModelsByType(options.type) : await agent.listModels();
+    jsonOut(result);
+  }
+}
+async function cmdListConnectors(args, options) {
+  const agent = await createAgent(options);
+  if (args.length >= 2) {
+    const result = await agent.getConnectorAction(args[0], args[1]);
+    jsonOut(result);
+  } else if (args.length === 1) {
+    const result = await agent.getConnector(args[0]);
+    jsonOut(result);
+  } else {
+    const result = await agent.listConnectors();
+    jsonOut(result);
+  }
+}
+async function cmdListConnections(options) {
+  const agent = await createAgent(options);
+  const result = await agent.listConnections();
+  jsonOut(result);
+}
+async function cmdEstimateStepCost(method, input, options) {
+  const agent = await createAgent(options);
+  const result = await agent.estimateStepCost(method, input);
+  jsonOut(result);
+}
+async function cmdChangeName(name, options) {
+  const agent = await createAgent(options);
+  await agent.changeName(name);
+  process.stderr.write(`  Display name updated to: ${name}
+`);
+}
+async function cmdChangeProfilePicture(url, options) {
+  const agent = await createAgent(options);
+  await agent.changeProfilePicture(url);
+  process.stderr.write(`  Profile picture updated.
+`);
+}
 async function cmdRun(appId, variables, options) {
   const { MindStudioAgent: MindStudioAgent2 } = await Promise.resolve().then(() => (init_client(), client_exports));
   const agent = new MindStudioAgent2({
@@ -2945,6 +3078,52 @@ async function cmdRun(appId, variables, options) {
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   }
 }
+async function cmdBatch(input, options) {
+  if (!Array.isArray(input)) {
+    fatal(
+      `Batch input must be a JSON array of { stepType, step } objects.
+Example: mindstudio batch '[{"stepType":"generateImage","step":{"prompt":"a cat"}}]'`
+    );
+  }
+  for (let i = 0; i < input.length; i++) {
+    const item = input[i];
+    if (!item || typeof item !== "object" || !item.stepType || !item.step) {
+      fatal(
+        `Invalid step at index ${i}: each entry must have "stepType" and "step" fields.`
+      );
+    }
+  }
+  const { stepMetadata: stepMetadata2 } = await Promise.resolve().then(() => (init_metadata(), metadata_exports));
+  const metaByName = new Map(
+    Object.entries(stepMetadata2).map(([name, m]) => [name, m])
+  );
+  const steps = input.map(
+    (item, i) => {
+      let meta = metaByName.get(item.stepType);
+      if (!meta) {
+        const camel = item.stepType.replace(
+          /-([a-z])/g,
+          (_, c) => c.toUpperCase()
+        );
+        meta = metaByName.get(camel);
+      }
+      if (meta) {
+        return { stepType: meta.stepType, step: item.step };
+      }
+      return { stepType: item.stepType, step: item.step };
+    }
+  );
+  const agent = await createAgent(options);
+  const result = await agent.executeStepBatch(steps, {
+    appId: options.appId,
+    threadId: options.threadId
+  });
+  if (options.noMeta) {
+    process.stdout.write(JSON.stringify(result.results, null, 2) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+}
 var MIME_TYPES2 = {
   png: "image/png",
   jpg: "image/jpeg",
@@ -2967,9 +3146,6 @@ async function cmdUpload(filePath, options) {
   const content = readFileSync3(filePath);
   const mimeType = MIME_TYPES2[ext];
   const { MindStudioAgent: MindStudioAgent2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-  await Promise.resolve().then(() => (init_helpers(), helpers_exports)).then(
-    (m) => m.applyHelperMethods(MindStudioAgent2)
-  );
   const agent = new MindStudioAgent2({
     apiKey: options.apiKey,
     baseUrl: options.baseUrl
@@ -3003,7 +3179,7 @@ function isNewerVersion(current, latest) {
   return false;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.4";
+  const currentVersion = "0.1.6";
   if (!currentVersion) return null;
   try {
     const { loadConfig: loadConfig2, saveConfig: saveConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
@@ -3032,7 +3208,7 @@ async function checkForUpdate() {
   }
 }
 function printUpdateNotice(latestVersion) {
-  const currentVersion = "0.1.4";
+  const currentVersion = "0.1.6";
   process.stderr.write(
     `
   ${ansi.cyanBright("Update available")} ${ansi.gray(currentVersion + " \u2192")} ${ansi.cyanBold(latestVersion)}
@@ -3103,10 +3279,11 @@ var SPINNER_FRAMES = [
 ];
 async function cmdLogin(options) {
   const baseUrl = options.baseUrl ?? process.env.MINDSTUDIO_BASE_URL ?? process.env.REMOTE_HOSTNAME ?? DEFAULT_BASE_URL2;
+  process.stderr.write("\x1B[2J\x1B[H");
   process.stderr.write("\n");
   printLogo();
   process.stderr.write("\n");
-  const ver = "0.1.4";
+  const ver = "0.1.6";
   process.stderr.write(
     `  ${ansi.bold("MindStudio Agent")} ${ver ? " " + ansi.gray("v" + ver) : ""}
 `
@@ -3255,11 +3432,62 @@ async function cmdWhoami(options) {
       apiKey: options.apiKey,
       baseUrl: options.baseUrl
     });
-    const result = await agent.listAgents();
+    const info = await agent.getUserInfo();
+    process.stderr.write(
+      `\r\x1B[K  ${ansi.greenBold("\u25CF")} ${ansi.green("Connected")}
+
+`
+    );
+    process.stderr.write(`  ${ansi.bold("User")}
+`);
+    process.stderr.write(
+      `  ${ansi.gray("Name:")}  ${info.displayName}
+`
+    );
+    process.stderr.write(
+      `  ${ansi.gray("ID:")}    ${ansi.gray(info.userId)}
+`
+    );
+    process.stderr.write(`
+  ${ansi.bold("Organization")}
+`);
+    process.stderr.write(
+      `  ${ansi.gray("Name:")}  ${info.organizationName}
+`
+    );
     process.stderr.write(
-      `\r\x1B[K  ${ansi.greenBold("\u25CF")} ${ansi.green("Connected")} ${ansi.gray("\u2014")} ${result.orgName} ${ansi.gray("(" + result.orgId + ")")}
+      `  ${ansi.gray("ID:")}    ${ansi.gray(info.organizationId)}
 `
     );
+    if (info.members && info.members.length > 0) {
+      process.stderr.write(`
+  ${ansi.bold("Members")}
+`);
+      const nameWidth = Math.max(
+        4,
+        ...info.members.map((m) => m.displayName.length)
+      );
+      const roleWidth = Math.max(
+        4,
+        ...info.members.map((m) => m.role.length)
+      );
+      process.stderr.write(
+        `  ${ansi.gray("Name".padEnd(nameWidth))}  ${ansi.gray("Role".padEnd(roleWidth))}  ${ansi.gray("Type")}
+`
+      );
+      process.stderr.write(
+        `  ${ansi.gray("\u2500".repeat(nameWidth))}  ${ansi.gray("\u2500".repeat(roleWidth))}  ${ansi.gray("\u2500".repeat(5))}
+`
+      );
+      for (const member of info.members) {
+        const type = member.isAgent ? ansi.cyan("agent") : "user";
+        process.stderr.write(
+          `  ${member.displayName.padEnd(nameWidth)}  ${ansi.gray(member.role.padEnd(roleWidth))}  ${type}
+`
+        );
+      }
+    }
+    process.stderr.write("\n");
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     process.stderr.write(
@@ -3290,15 +3518,15 @@ var GLOBAL_STRING_FLAGS = /* @__PURE__ */ new Set([
 ]);
 function findMethodSplit(argv) {
   let startIdx = 0;
-  let hasExec = false;
+  let hasRun = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith("--")) {
       if (GLOBAL_STRING_FLAGS.has(arg)) i++;
       continue;
     }
-    if (arg === "exec") {
-      hasExec = true;
+    if (arg === "run") {
+      hasRun = true;
       startIdx = i + 1;
     } else {
       startIdx = i;
@@ -3311,7 +3539,7 @@ function findMethodSplit(argv) {
       if (GLOBAL_STRING_FLAGS.has(arg)) i++;
       continue;
     }
-    if (hasExec || i === startIdx) {
+    if (hasRun || i === startIdx) {
       return { rawMethod: arg, stepArgv: argv.slice(i + 1) };
     }
     break;
@@ -3332,6 +3560,7 @@ async function main() {
       "no-meta": { type: "boolean", default: false },
       workflow: { type: "string" },
       version: { type: "string" },
+      type: { type: "string" },
       json: { type: "boolean", default: false },
       summary: { type: "boolean", default: false },
       help: { type: "boolean", default: false }
@@ -3376,7 +3605,7 @@ async function main() {
       });
       return;
     }
-    if (command === "list") {
+    if (command === "list-actions") {
       await cmdList(values.json, values.summary);
       return;
     }
@@ -3387,11 +3616,83 @@ async function main() {
       });
       return;
     }
-    if (command === "run") {
+    if (command === "batch") {
+      let input2;
+      const firstArg = positionals[1];
+      if (firstArg && firstArg.startsWith("[")) {
+        try {
+          input2 = parseJson5(firstArg);
+        } catch {
+          fatal(`Invalid JSON input: ${firstArg}`);
+        }
+      } else if (!process.stdin.isTTY) {
+        const raw = (await readStdin()).trim();
+        if (raw) {
+          try {
+            input2 = parseJson5(raw);
+          } catch {
+            fatal(`Invalid JSON on stdin: ${raw}`);
+          }
+        }
+      }
+      if (input2 === void 0) {
+        usageBlock([
+          "batch \u2014 Execute multiple actions in parallel",
+          "",
+          "Usage:",
+          `  mindstudio batch '[{ "stepType": "<action>", "step": { ... } }, ...]'`,
+          "  cat steps.json | mindstudio batch",
+          "",
+          'Each entry needs "stepType" (action name) and "step" (input object).',
+          "Maximum 50 steps per batch. Results come back in the same order.",
+          "Individual failures don't affect other steps.",
+          "",
+          "Options:",
+          "  --app-id <id>      App ID for thread context",
+          "  --thread-id <id>   Thread ID for state persistence",
+          "  --no-meta          Strip top-level metadata from output",
+          "",
+          "Examples:",
+          "  mindstudio batch '[",
+          '    { "stepType": "generateImage", "step": { "prompt": "a sunset" } },',
+          '    { "stepType": "textToSpeech", "step": { "text": "hello world" } }',
+          "  ]'",
+          "",
+          `  echo '[{"stepType":"searchGoogle","step":{"query":"cats"}}]' | mindstudio batch`
+        ]);
+      }
+      await cmdBatch(input2, {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"],
+        appId: values["app-id"],
+        threadId: values["thread-id"],
+        noMeta: values["no-meta"]
+      });
+      return;
+    }
+    if (command === "run-agent") {
       const appId = positionals[1];
       if (!appId)
-        fatal("Missing app ID. Usage: mindstudio run <appId> [json | --flags]");
-      const runArgv = process.argv.slice(process.argv.indexOf("run") + 2);
+        usageBlock([
+          "run-agent \u2014 Run a pre-built agent and wait for the result",
+          "",
+          "Usage:",
+          "  mindstudio run-agent <appId> [json | --flags]",
+          "",
+          "Options:",
+          "  --workflow <name>  Workflow to execute (default: app default)",
+          '  --version <ver>    App version, e.g. "draft" (default: "live")',
+          "  --output-key <key> Extract a single field from the result",
+          "  --no-meta          Strip metadata from output",
+          "",
+          "Examples:",
+          '  mindstudio run-agent abc123 --query "hello"',
+          `  mindstudio run-agent abc123 '{"query": "hello"}'`,
+          "  mindstudio run-agent abc123 --workflow summarize --version draft",
+          "",
+          'Tip: run "mindstudio agents" to list available agent IDs.'
+        ]);
+      const runArgv = process.argv.slice(process.argv.indexOf("run-agent") + 2);
       const stepArgs = [];
       for (let i = 0; i < runArgv.length; i++) {
         const arg = runArgv[i];
@@ -3439,13 +3740,145 @@ async function main() {
     if (command === "upload") {
       const filePath = positionals[1];
       if (!filePath)
-        fatal("Missing file path. Usage: mindstudio upload <filepath>");
+        usageBlock([
+          "upload \u2014 Upload a file to the MindStudio CDN",
+          "",
+          "Usage:",
+          "  mindstudio upload <filepath>",
+          "",
+          "Returns the permanent public URL for the uploaded file.",
+          "",
+          "Examples:",
+          "  mindstudio upload photo.png",
+          "  mindstudio upload /path/to/document.pdf"
+        ]);
       await cmdUpload(filePath, {
         apiKey: values["api-key"],
         baseUrl: values["base-url"]
       });
       return;
     }
+    if (command === "list-models" || command === "list-models-by-type" || command === "list-models-summary" || command === "list-models-summary-by-type") {
+      const authOpts = {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      };
+      let type;
+      let summary = false;
+      if (command === "list-models-by-type" || command === "list-models-summary-by-type") {
+        type = positionals[1];
+        if (!type)
+          usageBlock([
+            `${command} \u2014 List AI models filtered by type`,
+            "",
+            "Usage:",
+            `  mindstudio ${command} <type>`,
+            "",
+            "Types:",
+            "  llm_chat, image_generation, video_generation,",
+            "  video_analysis, text_to_speech, vision, transcription",
+            "",
+            "Examples:",
+            `  mindstudio ${command} image_generation`,
+            `  mindstudio ${command} llm_chat`
+          ]);
+      }
+      if (command === "list-models-summary" || command === "list-models-summary-by-type") {
+        summary = true;
+      }
+      if (command === "list-models") {
+        const typeFlag = values.type;
+        if (typeFlag) type = typeFlag;
+        if (values.summary) summary = true;
+      }
+      await cmdListModels({ ...authOpts, type, summary });
+      return;
+    }
+    if (command === "list-connectors") {
+      await cmdListConnectors(positionals.slice(1), {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      });
+      return;
+    }
+    if (command === "list-connections") {
+      await cmdListConnections({
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      });
+      return;
+    }
+    if (command === "estimate-cost") {
+      const stepMethod = positionals[1];
+      if (!stepMethod)
+        usageBlock([
+          "estimate-cost \u2014 Estimate the cost of an action before running it",
+          "",
+          "Usage:",
+          "  mindstudio estimate-cost <action> [json | --flags]",
+          "",
+          "Examples:",
+          '  mindstudio estimate-cost generate-image --prompt "a sunset"',
+          `  mindstudio estimate-cost generate-text '{"message": "hello"}'`,
+          "",
+          'Tip: run "mindstudio list-actions" to see available actions.'
+        ]);
+      const costArgv = positionals.slice(2);
+      let costInput;
+      const firstArg = costArgv[0];
+      if (firstArg && firstArg.startsWith("{")) {
+        try {
+          costInput = parseJson5(firstArg);
+        } catch {
+          fatal(`Invalid JSON input: ${firstArg}`);
+        }
+      } else {
+        costInput = parseStepFlags(costArgv);
+      }
+      await cmdEstimateStepCost(stepMethod, costInput, {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      });
+      return;
+    }
+    if (command === "change-name") {
+      const name = positionals[1];
+      if (!name)
+        usageBlock([
+          "change-name \u2014 Update your display name",
+          "",
+          "Usage:",
+          "  mindstudio change-name <name>",
+          "",
+          "Examples:",
+          '  mindstudio change-name "My Agent"'
+        ]);
+      await cmdChangeName(name, {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      });
+      return;
+    }
+    if (command === "change-profile-picture") {
+      const url = positionals[1];
+      if (!url)
+        usageBlock([
+          "change-profile-picture \u2014 Update your profile picture",
+          "",
+          "Usage:",
+          "  mindstudio change-profile-picture <url>",
+          "",
+          "Examples:",
+          "  mindstudio change-profile-picture https://example.com/avatar.png",
+          "",
+          'Tip: use "mindstudio upload" to host an image first.'
+        ]);
+      await cmdChangeProfilePicture(url, {
+        apiKey: values["api-key"],
+        baseUrl: values["base-url"]
+      });
+      return;
+    }
     if (command === "mcp") {
       const { startMcpServer: startMcpServer2 } = await Promise.resolve().then(() => (init_mcp(), mcp_exports));
       await startMcpServer2({
@@ -3457,13 +3890,48 @@ async function main() {
     if (command === "info") {
       const rawMethod2 = positionals[1];
       if (!rawMethod2)
-        fatal("Missing method name. Usage: mindstudio info <method>");
+        usageBlock([
+          "info \u2014 Show action details and parameters",
+          "",
+          "Usage:",
+          "  mindstudio info <action>",
+          "",
+          "Shows the description, input parameters (with types and",
+          "defaults), and output fields for an action.",
+          "",
+          "Examples:",
+          "  mindstudio info generate-image",
+          "  mindstudio info search-google",
+          "",
+          'Tip: run "mindstudio list-actions" to see available actions.'
+        ]);
       await cmdInfo(rawMethod2);
       return;
     }
     const split = findMethodSplit(process.argv.slice(2));
     if (!split)
-      fatal("Missing method name. Usage: mindstudio <method> [json | --flags]");
+      usageBlock([
+        "Run an action directly",
+        "",
+        "Usage:",
+        "  mindstudio <action> [json | --flags]",
+        "  mindstudio run <action> [json | --flags]",
+        "",
+        "Input can be inline JSON, --flags, or piped via stdin.",
+        "",
+        "Options:",
+        "  --app-id <id>      App ID for thread context",
+        "  --thread-id <id>   Thread ID for state persistence",
+        "  --output-key <key> Extract a single field from the result",
+        "  --no-meta          Strip $-prefixed metadata from output",
+        "",
+        "Examples:",
+        '  mindstudio generate-image --prompt "a sunset"',
+        `  mindstudio search-google '{"query": "cats"}'`,
+        `  echo '{"message":"hello"}' | mindstudio generate-text`,
+        "",
+        'Tip: run "mindstudio list-actions" to see available actions.'
+      ]);
     const { rawMethod, stepArgv } = split;
     const allKeys = await getAllMethodKeys();
     const method = resolveMethodOrFail(rawMethod, allKeys);