@octaviaflow/flow-rules 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -45,7 +45,6 @@ __export(exports_src, {
   ActionStatus: () => ActionStatus,
   ActionType: () => ActionType,
   AggregateConfig: () => AggregateConfig,
-  AggregateFunction: () => AggregateFunction,
   AiAgentConfig: () => AiAgentConfig,
   CONDITION_OPERATORS: () => CONDITION_OPERATORS,
   CONFIG_CONTRACTS: () => CONFIG_CONTRACTS,
@@ -67,6 +66,8 @@ __export(exports_src, {
   FILE_EDIT_SCHEMA: () => FILE_EDIT_SCHEMA,
   FILE_EDIT_SOURCES: () => FILE_EDIT_SOURCES,
   FILE_FORMAT_OPERATIONS: () => FILE_FORMAT_OPERATIONS,
+  FILE_INPUT_HELP: () => FILE_INPUT_HELP,
+  FILE_OUTPUT_HELP: () => FILE_OUTPUT_HELP,
   FTP_OPERATIONS: () => FTP_OPERATIONS,
   FieldType: () => FieldType,
   ForEachConfig: () => ForEachConfig,
@@ -76,22 +77,33 @@ __export(exports_src, {
   GroupConfig: () => GroupConfig,
   IDP_EXTRACT_STRATEGIES: () => IDP_EXTRACT_STRATEGIES,
   IdpExtractConfig: () => IdpExtractConfig,
-  JoinType: () => JoinType,
   JsonActionConfig: () => JsonActionConfig,
-  LogicalOperator: () => LogicalOperator,
   MAPPING_FUNCTIONS: () => MAPPING_FUNCTIONS,
   MAPPING_FUNCTION_SPECS: () => MAPPING_FUNCTION_SPECS,
+  MAX_CONDITION_DEPTH: () => MAX_CONDITION_DEPTH,
   MAX_STEP_CONFIG_BYTES: () => MAX_STEP_CONFIG_BYTES,
   ManualTriggerConfig: () => ManualTriggerConfig,
   NodeStatus: () => NodeStatus,
   ONEDRIVE_OPERATIONS: () => ONEDRIVE_OPERATIONS,
   OneDriveActionConfig: () => OneDriveActionConfig,
   PLATFORM_CONFIG_KEYS: () => PLATFORM_CONFIG_KEYS,
+  QUERY_AGGREGATE_FUNCTIONS: () => QUERY_AGGREGATE_FUNCTIONS,
+  QUERY_AUTHORED_SQL_MESSAGE: () => QUERY_AUTHORED_SQL_MESSAGE,
+  QUERY_COMPARISON_OPERATORS: () => QUERY_COMPARISON_OPERATORS,
+  QUERY_CONDITION_OPERATORS: () => QUERY_CONDITION_OPERATORS,
+  QUERY_MODES: () => QUERY_MODES,
+  QUERY_RELATIVE_DATE_OPERATORS: () => QUERY_RELATIVE_DATE_OPERATORS,
+  QUERY_TYPES: () => QUERY_TYPES,
+  QUERY_VISUAL_ONLY_MESSAGE: () => QUERY_VISUAL_ONLY_MESSAGE,
   QueryMode: () => QueryMode,
   QueryType: () => QueryType,
+  RELATIVE_DATE_DIRECTIONS: () => RELATIVE_DATE_DIRECTIONS,
+  RELATIVE_DATE_MAX_AMOUNT: () => RELATIVE_DATE_MAX_AMOUNT,
+  RELATIVE_DATE_UNITS: () => RELATIVE_DATE_UNITS,
   S3ActionConfig: () => S3ActionConfig,
   S3_OPERATIONS: () => S3_OPERATIONS,
   STORAGE_CONNECTOR_IDS: () => STORAGE_CONNECTOR_IDS,
+  STORAGE_DOWNLOAD_OUTPUT_SCHEMA: () => STORAGE_DOWNLOAD_OUTPUT_SCHEMA,
   SortDirection: () => SortDirection,
   StorageActionConfig: () => StorageActionConfig,
   TRANSFORM_MODES: () => TRANSFORM_MODES,
@@ -131,6 +143,7 @@ __export(exports_src, {
   getStorageProvider: () => getStorageProvider,
   groupKeyName: () => groupKeyName,
   inferSchemaFromSample: () => inferSchemaFromSample,
+  isConditionGroup: () => isConditionGroup,
   isEditorPrivateKey: () => isEditorPrivateKey,
   isEventCapableConnector: () => isEventCapableConnector,
   isMappingFunction: () => isMappingFunction,
@@ -138,6 +151,8 @@ __export(exports_src, {
   mappingTransformFunctionName: () => mappingTransformFunctionName,
   migrateDelayConfig: () => migrateDelayConfig,
   queryDefinition: () => queryDefinition,
+  queryFieldsSatisfied: () => queryFieldsSatisfied,
+  queryTablesSatisfied: () => queryTablesSatisfied,
   resolveRecordSchema: () => resolveRecordSchema,
   selectsWithoutValues: () => selectsWithoutValues,
   storageConfigKeys: () => storageConfigKeys,
@@ -146,12 +161,14 @@ __export(exports_src, {
   transformConnectionToEdge: () => transformConnectionToEdge,
   transformFlowToWorkflow: () => transformFlowToWorkflow,
   transformStepToNode: () => transformStepToNode,
+  validateBuildQueryConfig: () => validateBuildQueryConfig,
   validateConnectorTriggerEvents: () => validateConnectorTriggerEvents,
   validateEdge: () => validateEdge,
   validateFlowData: () => validateFlowData,
   validateNode: () => validateNode,
   validateStepConfig: () => validateStepConfig,
   validateStepConfigs: () => validateStepConfigs,
+  validateVisualConfig: () => validateVisualConfig,
   validateWorkflow: () => validateWorkflow
 });
 module.exports = __toCommonJS(exports_src);
@@ -1180,32 +1197,51 @@ var QueryType;
   QueryType["Delete"] = "delete";
   QueryType["Custom"] = "custom";
 })(QueryType ||= {});
-var LogicalOperator;
-((LogicalOperator) => {
-  LogicalOperator["And"] = "and";
-  LogicalOperator["Or"] = "or";
-})(LogicalOperator ||= {});
+var QUERY_MODES = ["visual" /* Visual */];
+var QUERY_TYPES = ["select" /* Select */];
+var QUERY_COMPARISON_OPERATORS = [
+  "=",
+  "!=",
+  ">",
+  "<",
+  ">=",
+  "<=",
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "lessThan",
+  "greaterOrEqual",
+  "lessOrEqual"
+];
+var QUERY_RELATIVE_DATE_OPERATORS = ["inRelative", "notInRelative"];
+var QUERY_CONDITION_OPERATORS = [
+  ...QUERY_COMPARISON_OPERATORS,
+  "contains",
+  "startsWith",
+  "endsWith",
+  "like",
+  "notLike",
+  "in",
+  "notIn",
+  "between",
+  "isNull",
+  "isNotNull",
+  ...QUERY_RELATIVE_DATE_OPERATORS
+];
+var RELATIVE_DATE_DIRECTIONS = ["last", "next", "this"];
+var RELATIVE_DATE_UNITS = ["day", "week", "month", "quarter", "year"];
+var RELATIVE_DATE_MAX_AMOUNT = 3650;
+var MAX_CONDITION_DEPTH = 3;
+var isConditionGroup = (c) => !!c && typeof c === "object" && c.type === "group";
+var QUERY_AGGREGATE_FUNCTIONS = ["COUNT", "COUNT_DISTINCT", "SUM", "AVG", "MIN", "MAX"];
 var SortDirection;
 ((SortDirection) => {
   SortDirection["Ascending"] = "asc";
   SortDirection["Descending"] = "desc";
 })(SortDirection ||= {});
-var JoinType;
-((JoinType) => {
-  JoinType["Inner"] = "inner";
-  JoinType["Left"] = "left";
-  JoinType["Right"] = "right";
-  JoinType["Full"] = "full";
-})(JoinType ||= {});
-var AggregateFunction;
-((AggregateFunction) => {
-  AggregateFunction["Count"] = "count";
-  AggregateFunction["Sum"] = "sum";
-  AggregateFunction["Average"] = "avg";
-  AggregateFunction["Min"] = "min";
-  AggregateFunction["Max"] = "max";
-  AggregateFunction["CountDistinct"] = "count_distinct";
-})(AggregateFunction ||= {});
+// src/catalog/isOneOf.ts
+var isOneOf = (set, value) => typeof value === "string" && set.includes(value);
+
 // src/catalog/general/query/config.ts
 var BuildQueryConfigDefaults = {
   mode: "visual" /* Visual */,
@@ -1215,160 +1251,262 @@ var BuildQueryConfigDefaults = {
   visualConfig: {
     tables: [],
     fields: [],
-    filters: undefined,
+    conditions: [],
     joins: [],
     groupBy: [],
+    aggregates: [],
     sort: [],
-    limit: 10,
-    offset: 0
-  },
-  sqlConfig: {
-    sql: "",
-    parameters: {}
+    limit: 10
   }
 };
-var validateBuildQueryConfig = (config) => {
-  const errors = [];
-  const warnings = [];
-  if (!config.connectorId) {
-    errors.push({
-      field: "connectorId",
-      message: "Please select a connector",
-      severity: "error"
-    });
+var QUERY_VISUAL_ONLY_MESSAGE = "The Query step is built with the visual builder only — set mode to 'visual' and describe the query in " + "visualConfig (tables, fields, conditions, sort, groupBy, aggregates). Hand-written SQL is not accepted.";
+var QUERY_AUTHORED_SQL_MESSAGE = "sqlConfig.sql is written by the visual builder, not by hand — remove sqlConfig and describe the query in " + "visualConfig (tables, fields, conditions, sort, groupBy, aggregates) instead.";
+var err = (field, message) => ({ field, message, severity: "error" });
+var isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var hasValue = (v) => v !== undefined && v !== null && !(typeof v === "string" && v.trim() === "") && !(Array.isArray(v) && v.length === 0);
+var arr = (v) => Array.isArray(v) ? v : [];
+function queryFieldsSatisfied(config) {
+  const vc = isRecord(config?.visualConfig) ? config.visualConfig : undefined;
+  if (!vc)
+    return false;
+  if (vc.selectAll === true)
+    return true;
+  if (arr(vc.fields).length > 0)
+    return true;
+  if (arr(vc.aggregates).length > 0 || arr(vc.groupBy).length > 0)
+    return true;
+  const sql = isRecord(config?.sqlConfig) ? config.sqlConfig.sql : undefined;
+  return arr(vc.tables).length > 0 && nonEmptyString(sql);
+}
+function queryTablesSatisfied(config) {
+  const vc = isRecord(config?.visualConfig) ? config.visualConfig : undefined;
+  if (!vc)
+    return false;
+  return vc.selectAll === true || arr(vc.tables).length > 0;
+}
+var OPERATOR_LIST = QUERY_CONDITION_OPERATORS.join(", ");
+function validateRelative(path, relative) {
+  if (!isRecord(relative)) {
+    return [err(`${path}.relative`, `${path}: a relative-date condition needs relative, e.g. { direction: 'last', amount: 30, unit: 'day' }`)];
   }
-  if (!config.mode) {
-    errors.push({
-      field: "mode",
-      message: "Query mode is required",
-      severity: "error"
-    });
+  const issues = [];
+  const { direction, unit, amount, includeCurrent } = relative;
+  if (!isOneOf(RELATIVE_DATE_DIRECTIONS, direction)) {
+    issues.push(err(`${path}.relative.direction`, `${path}.relative.direction must be one of: ${RELATIVE_DATE_DIRECTIONS.join(", ")} (got "${String(direction)}")`));
   }
-  if (!config.queryType) {
-    errors.push({
-      field: "queryType",
-      message: "Query type is required",
-      severity: "error"
-    });
+  if (!isOneOf(RELATIVE_DATE_UNITS, unit)) {
+    issues.push(err(`${path}.relative.unit`, `${path}.relative.unit must be one of: ${RELATIVE_DATE_UNITS.join(", ")} (got "${String(unit)}")`));
   }
-  if (config.mode === "visual" /* Visual */) {
-    const visualErrors = validateVisualQueryConfig(config.visualConfig);
-    errors.push(...visualErrors);
-  } else if (config.mode === "sql" /* SQL */) {
-    const sqlErrors = validateSQLQueryConfig(config.sqlConfig);
-    errors.push(...sqlErrors);
+  if (direction === "last" || direction === "next") {
+    const ok = typeof amount === "number" && Number.isInteger(amount) && amount >= 1 && amount <= RELATIVE_DATE_MAX_AMOUNT;
+    if (!ok) {
+      issues.push(err(`${path}.relative.amount`, `${path}.relative.amount must be a whole number from 1 to ${RELATIVE_DATE_MAX_AMOUNT} for '${direction}' ` + `(e.g. last 30 days is { direction: 'last', amount: 30, unit: 'day' })`));
+    }
   }
-  if (config.timeout !== undefined) {
-    if (config.timeout < 1000) {
-      errors.push({
-        field: "timeout",
-        message: "Timeout must be at least 1000ms",
-        severity: "error"
-      });
-    } else if (config.timeout > 300000) {
-      warnings.push({
-        field: "timeout",
-        message: "Timeout is very high (>5 minutes)",
-        severity: "warning"
-      });
+  if (includeCurrent !== undefined && typeof includeCurrent !== "boolean") {
+    issues.push(err(`${path}.relative.includeCurrent`, `${path}.relative.includeCurrent must be true or false`));
+  }
+  return issues;
+}
+function validateRow(path, row, inHaving) {
+  const issues = [];
+  if (!nonEmptyString(row.field)) {
+    issues.push(err(`${path}.field`, `${path}: choose the field to compare (field is empty)`));
+  }
+  if (!isOneOf(QUERY_CONDITION_OPERATORS, row.operator)) {
+    issues.push(err(`${path}.operator`, `${path}.operator must be one of: ${OPERATOR_LIST} (got "${String(row.operator)}")`));
+    return issues;
+  }
+  const op = row.operator;
+  const isRelative = isOneOf(QUERY_RELATIVE_DATE_OPERATORS, op);
+  const comparesField = row.valueField !== undefined && row.valueField !== null && row.valueField !== "";
+  if (isRelative) {
+    if (inHaving) {
+      issues.push(err(`${path}.operator`, `${path}: '${op}' filters dates on rows — put it in conditions, not having`));
+    } else {
+      issues.push(...validateRelative(path, row.relative));
+    }
+    if (hasValue(row.value) || comparesField) {
+      issues.push(err(path, `${path}: a relative-date condition takes its window from relative — remove value and valueField`));
     }
+  } else if (row.relative !== undefined) {
+    issues.push(err(`${path}.relative`, `${path}: relative is only used with 'inRelative' or 'notInRelative' — change the operator or remove relative`));
   }
-  if (config.maxRows !== undefined) {
-    if (config.maxRows < 1) {
-      errors.push({
-        field: "maxRows",
-        message: "Max rows must be at least 1",
-        severity: "error"
-      });
-    } else if (config.maxRows > 1e4) {
-      warnings.push({
-        field: "maxRows",
-        message: "Max rows is very high (>10,000). This may impact performance.",
-        severity: "warning"
-      });
+  if (comparesField) {
+    if (inHaving) {
+      issues.push(err(`${path}.valueField`, `${path}: having compares with a value — use value, not valueField`));
+    } else if (!nonEmptyString(row.valueField)) {
+      issues.push(err(`${path}.valueField`, `${path}.valueField must name the field to compare with`));
+    } else if (!isOneOf(QUERY_COMPARISON_OPERATORS, op)) {
+      issues.push(err(`${path}.valueField`, `${path}: comparing with another field works with =, !=, >, <, >=, <= only (got "${op}")`));
+    }
+    if (hasValue(row.value)) {
+      issues.push(err(path, `${path}: set either value (compare with a value) or valueField (compare with another field), not both`));
     }
   }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
-};
-var validateVisualQueryConfig = (config) => {
+  if (row.joinOperator !== undefined && !(typeof row.joinOperator === "string" && /^(and|or)$/i.test(row.joinOperator))) {
+    issues.push(err(`${path}.joinOperator`, `${path}.joinOperator must be AND or OR (got "${String(row.joinOperator)}")`));
+  }
+  return issues;
+}
+function validateConditionList(path, list, depth) {
+  if (list === undefined || list === null)
+    return [];
+  if (!Array.isArray(list))
+    return [err(path, `${path} must be a list of conditions`)];
+  const issues = [];
+  list.forEach((item, i) => {
+    const at = `${path}[${i}]`;
+    if (!isRecord(item)) {
+      issues.push(err(at, `${at} must be a condition ({ field, operator, value }) or a group ({ type: 'group', conditions })`));
+      return;
+    }
+    if (isConditionGroup(item)) {
+      if (depth + 1 > MAX_CONDITION_DEPTH) {
+        issues.push(err(at, `${at}: groups can nest at most ${MAX_CONDITION_DEPTH} levels deep — move this group up a level or combine its conditions`));
+        return;
+      }
+      if (item.joinOperator !== undefined && !(typeof item.joinOperator === "string" && /^(and|or)$/i.test(item.joinOperator))) {
+        issues.push(err(`${at}.joinOperator`, `${at}.joinOperator must be AND or OR (got "${String(item.joinOperator)}")`));
+      }
+      if (!Array.isArray(item.conditions) || item.conditions.length === 0) {
+        issues.push(err(`${at}.conditions`, `${at}: a group needs at least one condition — add one or remove the group`));
+        return;
+      }
+      issues.push(...validateConditionList(`${at}.conditions`, item.conditions, depth + 1));
+      return;
+    }
+    issues.push(...validateRow(at, item, false));
+  });
+  return issues;
+}
+function validateAggregates(vc) {
+  const list = vc.aggregates;
+  if (list === undefined || list === null)
+    return [];
+  if (!Array.isArray(list))
+    return [err("visualConfig.aggregates", "visualConfig.aggregates must be a list of { fn, field, alias }")];
+  const issues = [];
+  list.forEach((a, i) => {
+    const at = `visualConfig.aggregates[${i}]`;
+    if (!isRecord(a)) {
+      issues.push(err(at, `${at} must be { fn, field, alias }`));
+      return;
+    }
+    const fn = typeof a.fn === "string" ? a.fn.toUpperCase() : a.fn;
+    if (!isOneOf(QUERY_AGGREGATE_FUNCTIONS, fn)) {
+      issues.push(err(`${at}.fn`, `${at}.fn must be one of: ${QUERY_AGGREGATE_FUNCTIONS.join(", ")} (got "${String(a.fn)}")`));
+      return;
+    }
+    const allRows = !nonEmptyString(a.field) || a.field.trim() === "*";
+    if (allRows && fn !== "COUNT") {
+      issues.push(err(`${at}.field`, `${at}: ${fn} needs a field to work on — set field to a column name`));
+    }
+    if (a.alias !== undefined && a.alias !== null && !nonEmptyString(a.alias)) {
+      issues.push(err(`${at}.alias`, `${at}.alias must be a name for the result column, or left out`));
+    }
+  });
+  return issues;
+}
+function validateHaving(vc) {
+  const list = vc.having;
+  if (list === undefined || list === null || Array.isArray(list) && list.length === 0)
+    return [];
+  if (!Array.isArray(list))
+    return [err("visualConfig.having", "visualConfig.having must be a list of conditions")];
+  const aggregates = arr(vc.aggregates).filter(isRecord);
+  const groupBy = arr(vc.groupBy).filter(nonEmptyString);
+  if (aggregates.length === 0 && groupBy.length === 0) {
+    return [err("visualConfig.having", "visualConfig.having filters grouped results, so it needs aggregates or groupBy — add them, or move these filters to conditions")];
+  }
+  const names = new Set([
+    ...groupBy,
+    ...aggregates.map((a) => a.alias).filter(nonEmptyString)
+  ]);
+  const issues = [];
+  list.forEach((row, i) => {
+    const at = `visualConfig.having[${i}]`;
+    if (!isRecord(row) || isConditionGroup(row)) {
+      issues.push(err(at, `${at} must be a single condition ({ field, operator, value }); groups are not used in having`));
+      return;
+    }
+    issues.push(...validateRow(at, row, true));
+    if (nonEmptyString(row.field) && !names.has(row.field)) {
+      const known = [...names];
+      issues.push(err(`${at}.field`, `${at}.field must be an aggregate alias or a groupBy column (got "${row.field}"` + (known.length > 0 ? `; available: ${known.join(", ")})` : "; give the aggregate an alias first)")));
+    }
+  });
+  return issues;
+}
+function validateVisualConfig(config) {
+  const vc = config.visualConfig;
+  if (!isRecord(vc)) {
+    return [err("visualConfig", "visualConfig is required — describe the query with tables (what to read), fields (which columns) and optional conditions")];
+  }
+  const issues = [];
+  if (!queryTablesSatisfied(config)) {
+    issues.push(err("visualConfig.tables", "At least one table must be selected (visualConfig.tables)"));
+  }
+  if (!queryFieldsSatisfied(config)) {
+    issues.push(err("visualConfig.fields", "At least one field must be selected (visualConfig.fields), or add aggregates / groupBy for a summary query"));
+  }
+  if (arr(vc.tables).length > 1 && arr(vc.joins).length === 0) {
+    issues.push(err("visualConfig.joins", "Joins are required when selecting from multiple tables (visualConfig.joins)"));
+  }
+  if (vc.distinct !== undefined && typeof vc.distinct !== "boolean") {
+    issues.push(err("visualConfig.distinct", "visualConfig.distinct must be true or false"));
+  }
+  issues.push(...validateConditionList("visualConfig.conditions", vc.conditions, 0));
+  issues.push(...validateAggregates(vc));
+  issues.push(...validateHaving(vc));
+  return issues;
+}
+var validateBuildQueryConfig = (config) => {
+  const c = config;
   const errors = [];
-  if (!config) {
-    errors.push({
-      field: "visualConfig",
-      message: "Visual query configuration is required",
-      severity: "error"
-    });
-    return errors;
+  const warnings = [];
+  if (!c.connectorId) {
+    errors.push(err("connectorId", "Please select a connector (connectorId)"));
   }
-  if (!config.tables || config.tables.length === 0) {
-    errors.push({
-      field: "visualConfig.tables",
-      message: "At least one table must be selected",
-      severity: "error"
-    });
+  const mode = c.mode;
+  const visual = mode === undefined || mode === null || mode === "" || isOneOf(QUERY_MODES, mode);
+  if (!visual) {
+    errors.push(err("mode", `Mode must be one of: ${QUERY_MODES.join(", ")} (got "${String(mode)}"). ${QUERY_VISUAL_ONLY_MESSAGE}`));
+  } else if (!mode) {
+    errors.push(err("mode", "Query mode is required — set mode to 'visual'"));
   }
-  if (!config.fields || config.fields.length === 0) {
-    errors.push({
-      field: "visualConfig.fields",
-      message: "At least one field must be selected",
-      severity: "error"
-    });
+  const queryType = c.queryType;
+  if (!queryType) {
+    errors.push(err("queryType", "Query type is required — set queryType to 'select'"));
+  } else if (!isOneOf(QUERY_TYPES, queryType)) {
+    errors.push(err("queryType", `Query type must be one of: ${QUERY_TYPES.join(", ")} (got "${String(queryType)}"). ` + "The Query step only reads data — use a Transform step to insert, update or delete."));
   }
-  if (config.tables && config.tables.length > 1) {
-    if (!config.joins || config.joins.length === 0) {
-      errors.push({
-        field: "visualConfig.joins",
-        message: "Joins are required when selecting from multiple tables",
-        severity: "error"
-      });
+  if (visual) {
+    const sql = isRecord(c.sqlConfig) ? c.sqlConfig.sql : undefined;
+    if (nonEmptyString(sql) && !isRecord(c.visualConfig)) {
+      errors.push(err("sqlConfig.sql", QUERY_AUTHORED_SQL_MESSAGE));
+    } else {
+      errors.push(...validateVisualConfig(c));
     }
   }
-  const hasAggregates = config.fields?.some((field) => field.aggregate);
-  const hasNonAggregates = config.fields?.some((field) => !field.aggregate);
-  if (hasAggregates && hasNonAggregates) {
-    if (!config.groupBy || config.groupBy.length === 0) {
-      errors.push({
-        field: "visualConfig.groupBy",
-        message: "Group by is required when mixing aggregate and non-aggregate fields",
-        severity: "error"
-      });
+  const timeout = c.timeout;
+  if (typeof timeout === "number") {
+    if (timeout < 1000) {
+      errors.push(err("timeout", "Timeout must be at least 1000ms"));
+    } else if (timeout > 300000) {
+      warnings.push({ field: "timeout", message: "Timeout is very high (>5 minutes)", severity: "warning" });
     }
   }
-  return errors;
-};
-var validateSQLQueryConfig = (config) => {
-  const errors = [];
-  if (!config) {
-    errors.push({
-      field: "sqlConfig",
-      message: "SQL query configuration is required",
-      severity: "error"
-    });
-    return errors;
-  }
-  if (!config.sql || config.sql.trim().length === 0) {
-    errors.push({
-      field: "sqlConfig.sql",
-      message: "SQL query is required",
-      severity: "error"
-    });
-  } else {
-    const sql = config.sql.trim().toLowerCase();
-    const dangerousKeywords = ["drop", "truncate", "alter", "create", "grant", "revoke"];
-    const hasDangerousKeyword = dangerousKeywords.some((keyword) => sql.includes(keyword + " "));
-    if (hasDangerousKeyword) {
-      errors.push({
-        field: "sqlConfig.sql",
-        message: "SQL query contains potentially dangerous operations (DROP, TRUNCATE, ALTER, etc.)",
-        severity: "error"
-      });
+  const maxRows = c.maxRows;
+  if (typeof maxRows === "number") {
+    if (maxRows < 1) {
+      errors.push(err("maxRows", "Max rows must be at least 1"));
+    } else if (maxRows > 1e4) {
+      warnings.push({ field: "maxRows", message: "Max rows is very high (>10,000). This may impact performance.", severity: "warning" });
     }
   }
-  return errors;
+  return { valid: errors.length === 0, errors, warnings };
 };
 function isQueryableConnector(connector) {
   if (connector.isQueryable !== undefined) {
@@ -1400,17 +1538,26 @@ var BuildQueryContractSchema = {
   mode: {
     type: "select",
     required: true,
-    options: ["visual", "sql"],
-    description: "visual: the query is built from visualConfig; sql: the query is the text in sqlConfig.sql"
+    options: QUERY_MODES,
+    description: "Always 'visual': the Query step is built with the visual builder and described in visualConfig. Hand-written SQL is not accepted."
   },
   queryType: {
     type: "select",
     required: true,
-    options: ["select", "insert", "update", "delete", "custom"],
-    description: "Only select is a read; the write types exist for the SQL mode of database connectors"
+    options: QUERY_TYPES,
+    description: "Always 'select': the Query step reads data. Use a Transform step to write."
+  },
+  visualConfig: {
+    type: "object",
+    required: false,
+    description: 'The query. tables: the table or object to read; fields: "table.column" names to return; ' + "conditions: filters { field, operator, value } (or valueField to compare two fields, or operator " + "'inRelative' with relative { direction: last|next|this, amount, unit: day|week|month|quarter|year } for date windows), " + `which may be grouped { type: 'group', conditions } up to ${MAX_CONDITION_DEPTH} levels deep and joined with AND/OR; ` + "distinct; groupBy; aggregates [{ fn: COUNT|COUNT_DISTINCT|SUM|AVG|MIN|MAX, field, alias }]; " + "having: filters on aggregate aliases or groupBy columns; sort [{ field, direction }]; maxRows: the run cap (up to 10,000)."
+  },
+  sqlConfig: {
+    type: "object",
+    required: false,
+    derived: true,
+    description: "Compiled from visualConfig by the editor or the server. Never write it — describe the query in visualConfig."
   },
-  visualConfig: { type: "object", required: false },
-  sqlConfig: { type: "object", required: false },
   timeout: { type: "number", required: false },
   maxRows: { type: "number", required: false }
 };
@@ -1419,11 +1566,11 @@ var BuildQueryContractSchema = {
 var queryDefinition = {
   id: "query",
   name: "Query",
-  description: "Execute queries against connected databases, APIs, and CRMs",
-  longDescription: "Create powerful queries using either a visual no-code builder or advanced SQL editor. Supports databases (PostgreSQL, MySQL, MongoDB, etc.), APIs (REST, GraphQL), and CRMs (Salesforce, HubSpot). Query results can be used as input for downstream actions.",
+  description: "Read records from a connected database, app or CRM",
+  longDescription: "Pick a table or object, the fields you want and any filters, and the Query step reads the matching records. Filters can be grouped with AND / OR, compare two fields, or use a date window such as the last 30 days. You can also remove duplicates, count, total or average values by group, filter those totals, and sort the result. Works with databases (PostgreSQL, MySQL, SQL Server, MongoDB and more), apps (QuickBooks, HubSpot, Jira, Shopify, Google Sheets and more) and CRMs (Salesforce). The records it returns can be used by the steps that follow.",
   category: "database" /* Database */,
   type: "query" /* Query */,
-  tags: ["query", "database", "sql", "visual-builder", "no-code", "api", "crm", "built-in"],
+  tags: ["query", "database", "visual-builder", "no-code", "filter", "api", "crm", "built-in"],
   status: "stable" /* Stable */,
   icon: "QueryQueue",
   color: "#0043ce",
@@ -1441,17 +1588,12 @@ var queryDefinition = {
         key: "mode",
         label: "Query Mode",
         type: "select" /* Select */,
-        description: "Choose between visual query builder or SQL editor",
+        description: "Always 'visual' — the query is built with the visual builder",
         options: [
           {
-            label: "Visual Builder (No-Code)",
+            label: "Visual Builder",
             value: "visual" /* Visual */,
-            description: "Build queries visually without writing code"
-          },
-          {
-            label: "SQL Editor (Advanced)",
-            value: "sql" /* SQL */,
-            description: "Write raw SQL queries with syntax highlighting"
+            description: "Pick the table, fields and filters — no code needed"
           }
         ],
         defaultValue: "visual" /* Visual */,
@@ -1499,7 +1641,7 @@ var queryDefinition = {
         key: "visualConfig.fields",
         label: "Select Fields",
         type: "array" /* Array */,
-        description: "Choose fields to include in the query result",
+        description: 'The fields to return, as "table.column". Not needed for a summary query (aggregates / groupBy) or when every table and field is selected.',
         validation: { required: true },
         conditional: [
           {
@@ -1542,39 +1684,6 @@ var queryDefinition = {
           }
         ]
       },
-      {
-        key: "sqlConfig.sql",
-        label: "SQL Query",
-        type: "code" /* Code */,
-        language: "sql",
-        description: "Write your SQL query here",
-        placeholder: "SELECT * FROM users WHERE status = 'active' LIMIT 100",
-        validation: { required: true },
-        conditional: [
-          {
-            field: "mode",
-            operator: "==",
-            value: "sql" /* SQL */,
-            action: "show"
-          }
-        ]
-      },
-      {
-        key: "sqlConfig.parameters",
-        label: "Query Parameters",
-        type: "json" /* JSON */,
-        description: 'Parameters for parameterized queries (e.g., {"userId": 123})',
-        validation: { required: false },
-        advanced: true,
-        conditional: [
-          {
-            field: "mode",
-            operator: "==",
-            value: "sql" /* SQL */,
-            action: "show"
-          }
-        ]
-      },
       {
         key: "timeout",
         label: "Query Timeout (ms)",
@@ -1588,7 +1697,7 @@ var queryDefinition = {
         key: "maxRows",
         label: "Max Rows",
         type: "number" /* Number */,
-        description: "Legacy step-level field — NOT read at run. Cap a visual Query with visualConfig.maxRows; in SQL mode write a LIMIT.",
+        description: "Legacy step-level field — not read at run. To cap a run, set visualConfig.maxRows.",
         defaultValue: 1000,
         validation: { required: false, min: 1, max: 1e4 },
         advanced: true
@@ -1604,7 +1713,7 @@ var queryDefinition = {
       {
         id: "query_mode",
         label: "Query Configuration",
-        description: "Configure how you want to build your query",
+        description: "The query is built with the visual builder",
         fields: ["mode", "queryType"]
       },
       {
@@ -1613,12 +1722,6 @@ var queryDefinition = {
         description: "Build your query visually without writing code",
         fields: ["visualConfig.tables", "visualConfig.fields", "visualConfig.limit"]
       },
-      {
-        id: "sql_editor",
-        label: "SQL Editor",
-        description: "Write raw SQL queries",
-        fields: ["sqlConfig.sql", "sqlConfig.parameters"]
-      },
       {
         id: "settings",
         label: "Advanced Settings",
@@ -1658,7 +1761,7 @@ var queryDefinition = {
       {
         key: "generatedSQL",
         type: "string" /* String */,
-        description: "The SQL query that was executed (for visual builder mode)",
+        description: "The query that ran, compiled from the visual builder",
         example: "SELECT id, name, email FROM users WHERE status = 'active' LIMIT 100"
       }
     ],
@@ -1784,6 +1887,32 @@ var aggregateDefinition = {
   testable: false
 };
 
+// src/catalog/storage/fileHelp.ts
+var FILE_OUTPUT_HELP = {
+  operation: "The operation that ran",
+  data: "File contents, for text files such as CSV, JSON or TXT",
+  s3Key: "The file itself, for PDF, Excel, images and other non-text files. Pass it to Excel, CSV, IDP or an Upload step.",
+  fileName: "File name",
+  mimeType: "File type, e.g. text/csv or application/pdf",
+  path: "Where the file was read from"
+};
+var FILE_INPUT_HELP = {
+  uploadContent: "Leave blank to upload the file from the step before, or pick a value from an earlier step, or type the content.",
+  formatContent: (format) => `The ${format} from an earlier step (a download or a generated file), or paste the ${format} here.`,
+  excelContent: "The Excel file from an earlier step (a download or a generated file)."
+};
+var STORAGE_DOWNLOAD_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    operation: { type: "string", description: FILE_OUTPUT_HELP.operation },
+    data: { type: "string", description: FILE_OUTPUT_HELP.data },
+    s3Key: { type: "string", description: FILE_OUTPUT_HELP.s3Key },
+    fileName: { type: "string", description: FILE_OUTPUT_HELP.fileName },
+    mimeType: { type: "string", description: FILE_OUTPUT_HELP.mimeType },
+    path: { type: "string", description: FILE_OUTPUT_HELP.path }
+  }
+};
+
 // src/catalog/storage/csv-action/index.ts
 var csvActionDefinition = {
   id: "csv_action",
@@ -1798,7 +1927,7 @@ var csvActionDefinition = {
   inputSchema: {
     fields: [
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Parse (CSV → Records)", value: "parse" }, { label: "Generate (Records → CSV)", value: "generate" }, { label: "Edit existing file", value: "edit" }], defaultValue: "parse", validation: { required: true } },
-      { key: "content", label: "CSV Content", type: "string" /* String */, description: "Paste CSV content or use FX token from upstream step" },
+      { key: "content", label: "CSV Content", type: "string" /* String */, description: FILE_INPUT_HELP.formatContent("CSV") },
       { key: "delimiter", label: "Delimiter", type: "select" /* Select */, options: [{ label: "Comma (,)", value: "," }, { label: "Semicolon (;)", value: ";" }, { label: "Tab", value: "\t" }, { label: "Pipe (|)", value: "|" }], defaultValue: "," },
       { key: "headerRow", label: "Header Row", type: "number" /* Number */, description: "Row number containing column headers (default: 1)", defaultValue: 1 },
       { key: "encoding", label: "Encoding", type: "select" /* Select */, options: [{ label: "UTF-8", value: "utf-8" }, { label: "Latin-1", value: "latin1" }, { label: "ASCII", value: "ascii" }], defaultValue: "utf-8" },
@@ -1838,7 +1967,7 @@ var jsonActionDefinition = {
     fields: [
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Parse (JSON → Records)", value: "parse" }, { label: "Generate (Records → JSON)", value: "generate" }, { label: "Edit existing file", value: "edit" }], defaultValue: "parse", validation: { required: true } },
       { key: "format", label: "Format", type: "select" /* Select */, options: [{ label: "JSON (array)", value: "json" }, { label: "JSONL (one object per line)", value: "jsonl" }], defaultValue: "json" },
-      { key: "content", label: "JSON Content", type: "string" /* String */, description: "Paste JSON content or use FX token from upstream step" },
+      { key: "content", label: "JSON Content", type: "string" /* String */, description: FILE_INPUT_HELP.formatContent("JSON") },
       { key: "prettyPrint", label: "Pretty Print", type: "boolean" /* Boolean */, description: "Format output with indentation", defaultValue: true },
       { key: "fileName", label: "Output File Name", type: "string" /* String */, defaultValue: "export.json" }
     ]
@@ -1874,7 +2003,7 @@ var xmlActionDefinition = {
   inputSchema: {
     fields: [
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Parse (XML → Records)", value: "parse" }, { label: "Generate (Records → XML)", value: "generate" }, { label: "Edit existing file", value: "edit" }], defaultValue: "parse", validation: { required: true } },
-      { key: "content", label: "XML Content", type: "string" /* String */, description: "Paste XML or use FX token" },
+      { key: "content", label: "XML Content", type: "string" /* String */, description: FILE_INPUT_HELP.formatContent("XML") },
       { key: "rootElement", label: "Root Element", type: "string" /* String */, description: "Root XML element name (for generate)", defaultValue: "data" },
       { key: "rowElement", label: "Row Element", type: "string" /* String */, description: "Element name per record (for generate)", defaultValue: "row" },
       { key: "fileName", label: "Output File Name", type: "string" /* String */, defaultValue: "export.xml" }
@@ -1911,7 +2040,7 @@ var excelActionDefinition = {
   inputSchema: {
     fields: [
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Parse (Excel → Records)", value: "parse" }, { label: "Generate (Records → Excel)", value: "generate" }, { label: "Edit existing file", value: "edit" }], defaultValue: "parse", validation: { required: true } },
-      { key: "content", label: "Excel File", type: "string" /* String */, description: "S3 key of uploaded Excel file or FX token from upstream" },
+      { key: "content", label: "Excel File", type: "string" /* String */, description: FILE_INPUT_HELP.excelContent },
       { key: "sheetName", label: "Sheet Name", type: "string" /* String */, description: "Name of sheet to read (default: first sheet)" },
       { key: "headerRow", label: "Header Row", type: "number" /* Number */, description: "Row number containing headers", defaultValue: 1 },
       { key: "fileName", label: "Output File Name", type: "string" /* String */, defaultValue: "export.xlsx" }
@@ -1923,7 +2052,7 @@ var excelActionDefinition = {
       { key: "data", type: "array" /* Array */, description: "Parsed records (parse mode) — loop these with a ForEach. File metadata in generate mode." },
       { key: "columns", type: "json" /* JSON */, description: "Column names" },
       { key: "rowCount", type: "number" /* Number */, description: "Number of records" },
-      { key: "s3Key", type: "string" /* String */, description: "S3 key of generated file" }
+      { key: "s3Key", type: "string" /* String */, description: "The generated Excel file. Pass it to an Upload step to save it." }
     ],
     sampleOutput: { data: [{ id: 1, name: "Widget" }], columns: ["id", "name"], rowCount: 1 }
   },
@@ -1953,7 +2082,7 @@ var s3ActionDefinition = {
       { key: "bucket", label: "Bucket Name", type: "string" /* String */, description: "S3 bucket name (defaults to the connector’s bucket)" },
       { key: "key", label: "Object Key (Path)", type: "string" /* String */, description: "S3 object key, e.g. data/reports/monthly.csv" },
       { key: "prefix", label: "Prefix (for List)", type: "string" /* String */, description: "Filter objects by prefix (folder path)" },
-      { key: "content", label: "File Content (for Upload)", type: "string" /* String */, description: "Content to upload — use FX token from upstream step" },
+      { key: "content", label: "File Content (for Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent },
       { key: "contentType", label: "Content Type", type: "string" /* String */, description: "MIME type (e.g. text/csv, application/json)", defaultValue: "application/octet-stream" },
       { key: "destBucket", label: "Destination Bucket (for Copy)", type: "string" /* String */ },
       { key: "destKey", label: "Destination Key (for Copy)", type: "string" /* String */ },
@@ -1994,7 +2123,7 @@ var ftpActionDefinition = {
       { key: "connector", label: "FTP / SFTP Connection", type: "connection" /* Connection */, description: "Select a configured FTP/SFTP connector from Integrations", validation: { required: true } },
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Download File", value: "download" }, { label: "Upload File", value: "upload" }, { label: "List Files", value: "list" }, { label: "Delete File", value: "delete" }, { label: "Move / Rename", value: "move" }], defaultValue: "download", validation: { required: true } },
       { key: "remotePath", label: "Remote Path", type: "string" /* String */, description: "File or folder path on the server (use file explorer to browse)" },
-      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: "Content to upload — use FX token from upstream step" },
+      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent },
       { key: "fileName", label: "File Name (Upload)", type: "string" /* String */, description: "Name for the uploaded file" },
       { key: "destPath", label: "Destination Path (Move)", type: "string" /* String */, description: "New path for moved/renamed file" },
       { key: "ifExists", label: "If File Exists", type: "select" /* Select */, options: [{ label: "Overwrite", value: "overwrite" }, { label: "Skip", value: "skip" }], defaultValue: "overwrite" }
@@ -2035,7 +2164,7 @@ var googleDriveActionDefinition = {
       { key: "fileId", label: "File ID / Path", type: "string" /* String */, description: "Google Drive file ID (use file explorer to browse)" },
       { key: "folderId", label: "Folder ID", type: "string" /* String */, description: "Target folder (root if empty)" },
       { key: "fileName", label: "File Name", type: "string" /* String */ },
-      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: "Content to upload — use FX token from upstream" },
+      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent },
       { key: "mimeType", label: "MIME Type", type: "string" /* String */, defaultValue: "application/octet-stream" },
       { key: "destFolderId", label: "Destination Folder (Move/Copy)", type: "string" /* String */ },
       { key: "shareEmail", label: "Share With Email", type: "string" /* String */ },
@@ -2077,7 +2206,7 @@ var dropboxActionDefinition = {
       { key: "connector", label: "Dropbox Account", type: "connection" /* Connection */, description: "Select a connected Dropbox account", validation: { required: true } },
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Download File", value: "download" }, { label: "Upload File", value: "upload" }, { label: "List Files", value: "list" }, { label: "Delete", value: "delete" }, { label: "Move", value: "move" }, { label: "Copy", value: "copy" }, { label: "Create Folder", value: "create_folder" }, { label: "Get Shared Link", value: "shared_link" }], defaultValue: "download", validation: { required: true } },
       { key: "path", label: "File / Folder Path", type: "string" /* String */, description: "Path on Dropbox (use file explorer to browse)" },
-      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: "Content to upload — use FX token from upstream" },
+      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent },
       { key: "fileName", label: "File Name (Upload)", type: "string" /* String */ },
       { key: "destPath", label: "Destination Path (Move/Copy)", type: "string" /* String */ },
       { key: "mode", label: "Upload Mode", type: "select" /* Select */, options: [{ label: "Add (fail if exists)", value: "add" }, { label: "Overwrite", value: "overwrite" }], defaultValue: "overwrite" }
@@ -2117,7 +2246,7 @@ var onedriveActionDefinition = {
       { key: "operation", label: "Operation", type: "select" /* Select */, options: [{ label: "Download File", value: "download" }, { label: "Upload File", value: "upload" }, { label: "List Files", value: "list" }, { label: "Delete", value: "delete" }, { label: "Move", value: "move" }, { label: "Copy", value: "copy" }], defaultValue: "download", validation: { required: true } },
       { key: "path", label: "File / Folder Path", type: "string" /* String */, description: "Path on OneDrive (use file explorer to browse)" },
       { key: "itemId", label: "Item ID", type: "string" /* String */, description: "OneDrive item ID (alternative to path)" },
-      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: "Content to upload — use FX token from upstream" },
+      { key: "content", label: "File Content (Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent },
       { key: "fileName", label: "File Name (Upload)", type: "string" /* String */ },
       { key: "destPath", label: "Destination Path (Move/Copy)", type: "string" /* String */ }
     ]
@@ -2175,14 +2304,17 @@ var storageActionDefinition = {
       },
       { key: "path", label: "Path", type: "string" /* String */, description: "File or folder path — use the file browser in the panel." },
       { key: "destPath", label: "Destination path", type: "string" /* String */, description: "Target for copy / move." },
-      { key: "content", label: "File content (for Upload)", type: "string" /* String */, description: "Content to upload — bind an FX token from an upstream step." }
+      { key: "content", label: "File content (for Upload)", type: "string" /* String */, description: FILE_INPUT_HELP.uploadContent }
     ]
   },
   outputSchema: {
     type: "object",
     properties: [
       { key: "operation", type: "string" /* String */, description: "The operation that ran" },
-      { key: "data", type: "json" /* JSON */, description: "Operation result or downloaded content" },
+      { key: "data", type: "json" /* JSON */, description: `Download: ${FILE_OUTPUT_HELP.data}. Other operations: their result.` },
+      { key: "s3Key", type: "string" /* String */, description: `Download: ${FILE_OUTPUT_HELP.s3Key}` },
+      { key: "fileName", type: "string" /* String */, description: `Download: ${FILE_OUTPUT_HELP.fileName}` },
+      { key: "mimeType", type: "string" /* String */, description: `Download: ${FILE_OUTPUT_HELP.mimeType}` },
       { key: "files", type: "json" /* JSON */, description: "Listing (for the List operation)" },
       { key: "path", type: "string" /* String */, description: "Affected file/folder path" },
       { key: "url", type: "string" /* String */, description: "Signed URL (for the Get signed URL operation)" }
@@ -2824,6 +2956,10 @@ function isSatisfiedOutOfBand(actionId, fieldKey, config) {
       return true;
     return Array.isArray(config.blocks) && config.blocks.length > 0;
   }
+  if (actionId === "query" && fieldKey === "visualConfig.fields")
+    return queryFieldsSatisfied(config);
+  if (actionId === "query" && fieldKey === "visualConfig.tables")
+    return queryTablesSatisfied(config);
   return false;
 }
 var MESSAGE_BODY_ACTIONS = new Set([
@@ -3718,9 +3854,6 @@ var EmailConfig = {
     }
   }
 };
-// src/catalog/isOneOf.ts
-var isOneOf = (set, value) => typeof value === "string" && set.includes(value);
-
 // src/catalog/general/transform/config.ts
 var TRANSFORM_MODES = ["visual", "expression"];
 var TRANSFORM_OPERATIONS = [
@@ -4628,10 +4761,10 @@ var FILE_EDIT_SCHEMA = {
   matchOp: { type: "select", required: false, options: FILE_EDIT_MATCH_OPS, description: 'set_fields: comparison; "=" by default' },
   matchValue: { type: "string", required: false, description: "set_fields: value compared against" },
   setFields: { type: "object", required: false, description: "set_fields: { column: newValue } applied to matching rows" },
-  destination: { type: "select", required: false, options: FILE_EDIT_DESTINATIONS, description: '"new" writes an edited copy (default); "in_place" overwrites an S3 source' },
+  destination: { type: "select", required: false, options: FILE_EDIT_DESTINATIONS, description: '"new" writes an edited copy (default); "in_place" overwrites the source file' },
   outputFileName: { type: "string", required: false, description: 'Name of the edited copy when destination is "new"' },
   source: { type: "select", required: false, options: FILE_EDIT_SOURCES, description: "Where the file to edit comes from; inferred from content when absent" },
-  s3Key: { type: "string", required: false, description: 'source "s3": platform-bucket key of the file to edit' },
+  s3Key: { type: "string", required: false, description: `source "s3": an earlier step's file (its s3Key output) to edit` },
   url: { type: "url", required: false, description: 'source "url": the file to edit is fetched from here' }
 };
 function fileEditErrors(config) {
@@ -4663,7 +4796,7 @@ var CsvActionConfig = {
   },
   schema: {
     operation: { type: "select", required: true, options: FILE_FORMAT_OPERATIONS, description: "parse (CSV → records), generate (records → CSV) or edit an existing file" },
-    content: { type: "text", required: false, description: "CSV text, or an FX token from an upstream step" },
+    content: { type: "text", required: false, description: "CSV text, or a reference to an earlier step's file content" },
     delimiter: { type: "select", required: false, options: [",", ";", "\t", "|"] },
     headerRow: { type: "number", required: false, min: 1, description: "1-based row that holds the column headers" },
     encoding: { type: "string", required: false, description: "Text encoding (utf-8 by default)" },
@@ -4689,7 +4822,7 @@ var JsonActionConfig = {
   schema: {
     operation: { type: "select", required: true, options: FILE_FORMAT_OPERATIONS, description: "parse (JSON → records), generate (records → JSON) or edit an existing file" },
     format: { type: "select", required: false, options: ["json", "jsonl"], description: "json (array) or jsonl (one object per line)" },
-    content: { type: "text", required: false, description: "JSON text, or an FX token from an upstream step" },
+    content: { type: "text", required: false, description: "JSON text, or a reference to an earlier step's file content" },
     prettyPrint: { type: "boolean", required: false, description: "generate: indent the output" },
     fileName: { type: "string", required: false, description: "generate: name of the produced file" },
     jsonl: { type: "boolean", required: false, description: "edit: treat the file as JSONL" },
@@ -4716,7 +4849,7 @@ var XmlActionConfig = {
   },
   schema: {
     operation: { type: "select", required: true, options: FILE_FORMAT_OPERATIONS, description: "parse (XML → records), generate (records → XML) or edit an existing file" },
-    content: { type: "text", required: false, description: "XML text, or an FX token from an upstream step" },
+    content: { type: "text", required: false, description: "XML text, or a reference to an earlier step's file content" },
     rootElement: { type: "string", required: false, description: "generate: root element name" },
     rowElement: { type: "string", required: false, description: "Element that holds one record" },
     fileName: { type: "string", required: false, description: "generate: name of the produced file" },
@@ -4738,7 +4871,7 @@ var ExcelActionConfig = {
   },
   schema: {
     operation: { type: "select", required: true, options: FILE_FORMAT_OPERATIONS, description: "parse (Excel → records), generate (records → Excel) or edit an existing file" },
-    content: { type: "text", required: false, description: "Platform-bucket key of the workbook, base64 bytes, or an FX token from an upstream step" },
+    content: { type: "text", required: false, description: "A reference to an earlier step's Excel file (its s3Key output), or base64 bytes" },
     sheetName: { type: "string", required: false, description: "Sheet to read; the first sheet when absent" },
     headerRow: { type: "number", required: false, min: 1, description: "1-based row that holds the column headers" },
     fileName: { type: "string", required: false, description: "generate: name of the produced file" },
@@ -4756,7 +4889,7 @@ var FIXED_SCHEMA = {
   connector: { type: "connection", required: true, description: "Storage connector instance; its provider decides the operations" },
   operation: { type: "select", required: true, description: "Per provider: list, download, upload, delete, copy, move, presign, share, create_folder, transfer, sync" },
   outputAs: { type: "string", required: false, description: "Name of this step's output in the run's data bag" },
-  content: { type: "text", required: false, description: "upload: the body" },
+  content: { type: "text", required: false, description: "upload: the file content; blank uploads the file the step before produced" },
   destConnector: { type: "connection", required: false, description: "transfer / sync: destination connector instance" },
   destPath: { type: "string", required: false, description: "transfer / sync: destination path; also move / copy destination on path-based providers" },
   sourceIsDirectory: { type: "boolean", required: false, description: "transfer: copy a folder recursively" },