@nocobase/plugin-flow-engine 2.1.0-alpha.40 → 2.1.0-alpha.45

package/dist/server/flow-surfaces/authoring-validation.js

@@ -59,6 +59,7 @@ var import_template_reference = require("./template-reference");
 var import_association_interfaces = require("./association-interfaces");
 var import_defaults = require("./blueprint/defaults");
 var import_runjs_authoring = require("./runjs-authoring");
+var import_configure_options = require("./configure-options");
 const MAIN_BLOCK_UNSUPPORTED_SECTIONS = {
   calendar: ["fields", "fieldGroups", "recordActions", "fieldsLayout"],
   kanban: ["fieldGroups", "recordActions", "fieldsLayout"],
@@ -71,6 +72,55 @@ const SORTABLE_BLOCK_TYPES = /* @__PURE__ */ new Set(["table", "details", "list"
 const CHART_BLOCK_TYPES = /* @__PURE__ */ new Set(["chart"]);
 const COMMENTS_PAGE_SIZE_VALUES = /* @__PURE__ */ new Set([5, 10, 20, 50, 100, 200]);
 const RECORD_HISTORY_INTERNAL_COLLECTIONS = /* @__PURE__ */ new Set(["recordHistories", "recordFieldHistories"]);
+const VISIBLE_FIELD_REQUIRED_DATA_BLOCK_TYPES = /* @__PURE__ */ new Set([
+  "table",
+  "list",
+  "gridCard",
+  "details",
+  "createForm",
+  "editForm",
+  "filterForm",
+  "kanban"
+]);
+const VISIBLE_FIELD_MINIMUM_DATA_BLOCK_TYPES = /* @__PURE__ */ new Set(["table", "list", "gridCard", "details"]);
+const RICH_COLLECTION_VISIBLE_FIELD_THRESHOLD = import_public_data_surface_default_filter.FLOW_SURFACE_DEFAULT_FILTER_REQUIRED_FIELD_COUNT * 2;
+const RICH_DATA_BLOCK_VISIBLE_FIELD_MINIMUM = 3;
+const NON_BUSINESS_VISIBLE_FIELD_NAMES = /* @__PURE__ */ new Set([
+  "id",
+  "uid",
+  "createdAt",
+  "updatedAt",
+  "deletedAt",
+  "createdBy",
+  "updatedBy",
+  "deletedBy",
+  "createdById",
+  "updatedById",
+  "deletedById",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "created_by",
+  "updated_by",
+  "deleted_by"
+]);
+const NON_BUSINESS_VISIBLE_FIELD_INTERFACES = /* @__PURE__ */ new Set([
+  "id",
+  "createdAt",
+  "updatedAt",
+  "createdBy",
+  "updatedBy",
+  "sort"
+]);
+const NON_BUSINESS_VISIBLE_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "action",
+  "actions",
+  "button",
+  "divider",
+  "operation",
+  "operations",
+  "sort"
+]);
 const ANT_DESIGN_ICON_NAMES = new Set(Object.keys(antDesignIconAsn || {}));
 const PUBLIC_BLOCK_TYPE_BY_MODEL_USE = {
   TableBlockModel: "table",
@@ -106,9 +156,14 @@ const GRID_CARD_ALLOWED_SETTINGS_KEYS = /* @__PURE__ */ new Set([
   "sorting",
   "layout"
 ]);
+const TABLE_ALLOWED_SETTINGS_KEYS = /* @__PURE__ */ new Set([...(0, import_configure_options.getConfigureOptionKeysForUse)("TableBlockModel"), "sort"]);
+const TABLE_INTERNAL_AUTHORING_KEYS = ["tableSettings", "defaultSorting", "stepParams"];
+const TABLE_SETTINGS_REPAIR_HINT = "Use public table settings keys such as settings.pageSize, settings.sorting, settings.dataScope, settings.density, settings.showRowNumbers, settings.treeTable, settings.dragSort, and settings.dragSortBy. Do not nest persisted tableSettings/defaultSorting/stepParams payloads.";
 const JS_BLOCK_ALLOWED_SETTINGS_KEYS = /* @__PURE__ */ new Set(["title", "description", "className", "code", "version"]);
 const JS_BLOCK_TOP_LEVEL_JS_KEYS = ["code", "version"];
 const JS_BLOCK_INTERNAL_AUTHORING_KEYS = ["props", "decoratorProps", "flowRegistry", "stepParams"];
+const JS_BLOCK_REPAIR_HINT = "This is a jsBlock payload shape problem. Repair this jsBlock using inline settings.code/settings.version, or applyBlueprint assets.scripts.<key>.code plus block.script. Do not change this block type to table, chart, actionPanel, gridCard, or another block type.";
+const CHART_REPAIR_HINT = "This is a chart payload shape problem. Repair this chart using assets.charts.<key>.query/visual plus block.chart, or localized settings.query/settings.visual. Do not change this block type to table, jsBlock, actionPanel, gridCard, or another block type, and do not drop or defer the chart. KPI / summary numbers should use jsBlock; charts are for trends, distributions, rankings, and visual analysis.";
 const CHART_QUERY_MODE_SET = new Set(import_chart_config.CHART_QUERY_MODES);
 const CHART_VISUAL_MODE_SET = new Set(import_chart_config.CHART_VISUAL_MODES);
 const CHART_BASIC_VISUAL_TYPE_SET = new Set(import_chart_config.CHART_BASIC_VISUAL_TYPES);
@@ -264,6 +319,67 @@ const DEFAULT_POPUPS_ALLOWED_KEYS = ["view", "addNew", "edit", "associations"];
 const DEFAULT_POPUP_ACTION_ALLOWED_KEYS = ["name", "description"];
 const DEFAULT_POPUP_ASSOCIATION_ALLOWED_KEYS = ["view", "addNew", "edit"];
 const DEFAULT_POPUP_ACTIONS = ["view", "addNew", "edit"];
+const AUTHORING_AI_EMPLOYEE_WORK_CONTEXT_PUBLIC_KEYS = ["type", "uid", "target"];
+const AUTHORING_AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS = [
+  "title",
+  "message",
+  "autoSend",
+  "skillSettings",
+  "model",
+  "webSearch"
+];
+const AUTHORING_AI_EMPLOYEE_TASK_MESSAGE_PUBLIC_KEYS = ["system", "user", "workContext"];
+const AUTHORING_AI_EMPLOYEE_TASK_MODEL_PUBLIC_KEYS = ["llmService", "model"];
+const AUTHORING_AI_EMPLOYEE_SKILL_SETTINGS_PUBLIC_KEYS = ["skills", "tools", "skillsVersion", "toolsVersion"];
+const AUTHORING_AI_EMPLOYEE_STYLE_PUBLIC_KEYS = ["size", "mask"];
+const AUTHORING_AI_EMPLOYEE_DEFAULT_STYLE = {
+  size: 40,
+  mask: false
+};
+function buildCalendarMainBlockRepairDetails(section) {
+  const popupSectionHint = section === "fieldGroups" || section === "recordActions" || section === "fieldsLayout" ? " Put event form/details content under settings.quickCreatePopup or settings.eventPopup instead of on the calendar main block." : "";
+  return {
+    repairHint: "Calendar main block payload shape issue. Put event bindings under settings.titleField, settings.startField, settings.endField, and optional settings.colorField; do not put collection fields in block fields. Keep block type calendar and repair this payload." + popupSectionHint,
+    example: {
+      type: "calendar",
+      collection: "tasks",
+      settings: {
+        titleField: "title",
+        startField: "startAt",
+        endField: "endAt"
+      }
+    }
+  };
+}
+function buildKanbanMainBlockRepairDetails(section) {
+  return {
+    repairHint: "Kanban main block payload shape issue. Put card display fields in block fields, grouping in settings.groupField, and quick-create/card details under settings.quickCreatePopup or settings.cardPopup. Keep block type kanban and repair this payload.",
+    section,
+    example: {
+      type: "kanban",
+      collection: "tasks",
+      fields: ["title", "priority"],
+      settings: {
+        groupField: "status"
+      }
+    }
+  };
+}
+function buildTwoColumnLayoutRepairDetails() {
+  return {
+    repairHint: "When multiple non-filter blocks should share a row, put them in the same layout row. Do not place every block on a separate row.",
+    example: {
+      layout: {
+        rows: [
+          [
+            { key: "calendar", span: 12 },
+            { key: "kanban", span: 12 }
+          ]
+        ]
+      }
+    }
+  };
+}
 async function assertFlowSurfaceAuthoringPayload(actionName, values, context = {}) {
   const errors = await collectFlowSurfaceAuthoringErrors(actionName, values, context);
   if (errors.length) {
@@ -329,38 +445,43 @@ async function collectNavigationGroupErrors(actionName, values, context, errors)
     return;
   }
   const matchedRoutes = await context.findMenuGroupRoutesByTitle(groupTitle, context.transaction);
-  if (matchedRoutes.length <= 1) {
+  const rootMatchedRoutes = filterRootMenuGroupRoutes(matchedRoutes);
+  if (rootMatchedRoutes.length <= 1) {
     return;
   }
   pushAuthoringError(errors, {
     path: "$.navigation.group.title",
     ruleId: "navigation-group-title-ambiguous",
-    message: `flowSurfaces authoring $.navigation.group.title '${groupTitle}' matches ${matchedRoutes.length} existing menu groups; pass navigation.group.routeId explicitly`,
+    message: `flowSurfaces authoring $.navigation.group.title '${groupTitle}' matches ${rootMatchedRoutes.length} existing root menu groups; pass navigation.group.routeId explicitly`,
     details: {
       title: groupTitle,
-      matches: matchedRoutes.length
+      parentMenuRouteId: null,
+      matches: rootMatchedRoutes.length
     }
   });
 }
 async function collectNavigationIconErrors(actionName, values, context, errors) {
-  var _a, _b;
+  var _a, _b, _c;
   if (actionName !== "applyBlueprint" || (values == null ? void 0 : values.mode) !== "create") {
     return;
   }
   const group = _.isPlainObject((_a = values == null ? void 0 : values.navigation) == null ? void 0 : _a.group) ? values.navigation.group : null;
   const groupRouteId = String((group == null ? void 0 : group.routeId) || "").trim();
-  if (group && !groupRouteId) {
+  if (group && !groupRouteId && group.hideInMenu !== true) {
     const groupIcon = String(group.icon || "").trim();
     if (!groupIcon && await shouldRequireNewNavigationGroupIcon(group, context)) {
       pushAuthoringError(errors, {
         path: "$.navigation.group.icon",
-        ruleId: "missing-menu-group-icon",
-        message: "flowSurfaces authoring $.navigation.group.icon is required when creating a new navigation group"
+        ruleId: "navigation-icon-required",
+        message: "flowSurfaces authoring $.navigation.group.icon is required when creating a visible navigation group",
+        details: {
+          repairHint: "Pass a valid Ant Design icon name such as AppstoreOutlined, DashboardOutlined, or FolderOpenOutlined."
+        }
       });
     } else if (groupIcon && !isValidAntDesignIconName(groupIcon)) {
       pushAuthoringError(errors, {
         path: "$.navigation.group.icon",
-        ruleId: "invalid-menu-group-icon",
+        ruleId: "navigation-icon-unknown",
         message: "flowSurfaces authoring $.navigation.group.icon must be a valid Ant Design icon name",
         details: {
           icon: groupIcon
@@ -370,7 +491,7 @@ async function collectNavigationIconErrors(actionName, values, context, errors)
   } else if (group && String(group.icon || "").trim() && !isValidAntDesignIconName(group.icon)) {
     pushAuthoringError(errors, {
       path: "$.navigation.group.icon",
-      ruleId: "invalid-menu-group-icon",
+      ruleId: "navigation-icon-unknown",
       message: "flowSurfaces authoring $.navigation.group.icon must be a valid Ant Design icon name",
       details: {
         icon: String(group.icon || "").trim()
@@ -382,13 +503,24 @@ async function collectNavigationIconErrors(actionName, values, context, errors)
   if (itemIcon && !isValidAntDesignIconName(itemIcon)) {
     pushAuthoringError(errors, {
       path: "$.navigation.item.icon",
-      ruleId: "invalid-menu-item-icon",
+      ruleId: "navigation-icon-unknown",
       message: "flowSurfaces authoring $.navigation.item.icon must be a valid Ant Design icon name",
       details: {
         icon: itemIcon
       }
     });
   }
+  const pageIcon = String(((_c = values == null ? void 0 : values.page) == null ? void 0 : _c.icon) || "").trim();
+  if (pageIcon && !isValidAntDesignIconName(pageIcon)) {
+    pushAuthoringError(errors, {
+      path: "$.page.icon",
+      ruleId: "navigation-icon-unknown",
+      message: "flowSurfaces authoring $.page.icon must be a valid Ant Design icon name when used as the create-mode page route icon",
+      details: {
+        icon: pageIcon
+      }
+    });
+  }
 }
 async function shouldRequireNewNavigationGroupIcon(group, context) {
   const groupTitle = String((group == null ? void 0 : group.title) || "").trim();
@@ -396,7 +528,22 @@ async function shouldRequireNewNavigationGroupIcon(group, context) {
     return true;
   }
   const matchedRoutes = await context.findMenuGroupRoutesByTitle(groupTitle, context.transaction);
-  return matchedRoutes.length === 0;
+  return filterRootMenuGroupRoutes(matchedRoutes).length === 0;
+}
+function filterRootMenuGroupRoutes(routes) {
+  return _.castArray(routes || []).filter(
+    (route) => routeParentIdMatches(readAuthoringRouteField(route, "parentId"), null)
+  );
+}
+function readAuthoringRouteField(route, key) {
+  var _a;
+  return ((_a = route == null ? void 0 : route.get) == null ? void 0 : _a.call(route, key)) ?? (route == null ? void 0 : route[key]);
+}
+function routeParentIdMatches(routeParentId, parentId) {
+  if (_.isNil(routeParentId) && _.isNil(parentId)) {
+    return true;
+  }
+  return String(routeParentId ?? "") === String(parentId ?? "");
 }
 function isValidAntDesignIconName(value) {
   const normalized = String(value || "").trim();
@@ -494,6 +641,39 @@ function collectChartAssetBlockTreeErrors(block, path, chartAssets, errors) {
     );
   });
 }
+function withJsBlockRepairHint(details = {}) {
+  return {
+    ...details,
+    repairHint: JS_BLOCK_REPAIR_HINT
+  };
+}
+function withChartRepairHint(details = {}) {
+  return {
+    ...details,
+    repairHint: CHART_REPAIR_HINT,
+    repairSteps: [
+      "Keep the block type as chart.",
+      "Define assets.charts.<key>.query and assets.charts.<key>.visual.",
+      "Reference that asset from the chart block with block.chart = <key>.",
+      "Retry the chart payload instead of replacing the chart with another block type or omitting it."
+    ],
+    expectedShape: {
+      assets: {
+        charts: {
+          chartKey: {
+            query: "builder/sql query configuration",
+            visual: "basic/custom visual configuration"
+          }
+        }
+      },
+      block: {
+        type: "chart",
+        chart: "chartKey"
+      }
+    },
+    forbiddenFallbacks: ["table", "jsBlock", "actionPanel", "gridCard", "drop chart", "defer chart"]
+  };
+}
 function collectChartBlockAssetReferenceErrors(block, path, chartAssets, errors) {
   if (!CHART_BLOCK_TYPES.has(String((block == null ? void 0 : block.type) || "").trim())) {
     return;
@@ -502,7 +682,8 @@ function collectChartBlockAssetReferenceErrors(block, path, chartAssets, errors)
     pushAuthoringError(errors, {
       path: `${path}.stepParams`,
       ruleId: "chart-block-step-params-unsupported",
-      message: `flowSurfaces authoring ${path}.stepParams is not accepted on public chart blocks; put chart configuration under assets.charts and reference it with block.chart`
+      message: `flowSurfaces authoring ${path}.stepParams is not accepted on public chart blocks; put chart configuration under assets.charts and reference it with block.chart`,
+      details: withChartRepairHint()
     });
   }
   const chartKey = String(block.chart || "").trim();
@@ -510,7 +691,8 @@ function collectChartBlockAssetReferenceErrors(block, path, chartAssets, errors)
     pushAuthoringError(errors, {
       path: `${path}.chart`,
       ruleId: "chart-block-asset-reference-required",
-      message: `flowSurfaces authoring ${path}.chart must reference one key from assets.charts`
+      message: `flowSurfaces authoring ${path}.chart must reference one key from assets.charts`,
+      details: withChartRepairHint()
     });
     return;
   }
@@ -519,9 +701,9 @@ function collectChartBlockAssetReferenceErrors(block, path, chartAssets, errors)
       path: `${path}.chart`,
       ruleId: "chart-block-asset-reference-missing",
       message: `flowSurfaces authoring ${path}.chart references missing chart asset '${chartKey}'`,
-      details: {
+      details: withChartRepairHint({
         chartKey
-      }
+      })
     });
   }
 }
@@ -535,7 +717,8 @@ function collectChartAssetRegistryErrors(charts, path, context, errors) {
       pushAuthoringError(errors, {
         path: assetPath,
         ruleId: "chart-asset-invalid",
-        message: `flowSurfaces authoring ${assetPath} must be an object`
+        message: `flowSurfaces authoring ${assetPath} must be an object`,
+        details: withChartRepairHint()
       });
       return;
     }
@@ -549,7 +732,8 @@ function collectChartAssetQueryErrors(asset, path, context, errors) {
     pushAuthoringError(errors, {
       path: `${path}.query`,
       ruleId: "chart-query-missing",
-      message: `flowSurfaces authoring ${path}.query is required`
+      message: `flowSurfaces authoring ${path}.query is required`,
+      details: withChartRepairHint()
     });
     return;
   }
@@ -559,9 +743,9 @@ function collectChartAssetQueryErrors(asset, path, context, errors) {
       path: `${path}.query.mode`,
       ruleId: "chart-query-mode-unsupported",
       message: `flowSurfaces authoring ${path}.query.mode '${mode}' is not supported`,
-      details: {
+      details: withChartRepairHint({
         mode
-      }
+      })
     });
     return;
   }
@@ -577,14 +761,16 @@ function collectBuilderChartAssetQueryErrors(query, path, context, errors) {
     pushAuthoringError(errors, {
       path: `${path}.query.resource`,
       ruleId: "chart-builder-query-resource-missing",
-      message: `flowSurfaces authoring ${path}.query.resource.collectionName is required for builder chart assets`
+      message: `flowSurfaces authoring ${path}.query.resource.collectionName is required for builder chart assets`,
+      details: withChartRepairHint()
     });
   }
   if (!Array.isArray(query.measures) || !query.measures.length) {
     pushAuthoringError(errors, {
       path: `${path}.query.measures`,
       ruleId: "chart-builder-query-measures-missing",
-      message: `flowSurfaces authoring ${path}.query.measures must include at least one measure`
+      message: `flowSurfaces authoring ${path}.query.measures must include at least one measure`,
+      details: withChartRepairHint()
     });
   }
   collectForbiddenObjectKeyErrors(
@@ -592,7 +778,8 @@ function collectBuilderChartAssetQueryErrors(query, path, context, errors) {
     `${path}.query`,
     CHART_BUILDER_QUERY_FORBIDDEN_KEYS,
     "chart-builder-query-forbidden-keys",
-    errors
+    errors,
+    withChartRepairHint()
   );
   collectBuilderChartAssetFieldErrors(query, path, context, errors);
 }
@@ -640,11 +827,11 @@ function collectBuilderChartAssetFieldErrors(query, path, context, errors) {
         path: item.fieldPath,
         ruleId: "chart-builder-query-field-unknown",
         message: `flowSurfaces authoring ${item.fieldPath} references unknown field '${fieldPath}' on collection '${dataSourceKey}.${collectionName}'`,
-        details: {
+        details: withChartRepairHint({
           fieldPath,
           dataSourceKey,
           collectionName
-        }
+        })
       });
       continue;
     }
@@ -659,12 +846,12 @@ function collectBuilderChartAssetFieldErrors(query, path, context, errors) {
         path: item.fieldPath,
         ruleId: "chart-builder-query-association-field-requires-subfield",
         message: `flowSurfaces authoring ${item.fieldPath} references association field '${fieldPath}' directly; use scalar subfield '${suggestion.suggestedFieldPath}' for builder charts`,
-        details: {
+        details: withChartRepairHint({
           fieldPath,
           dataSourceKey,
           collectionName,
           ...suggestion
-        }
+        })
       });
     }
   }
@@ -691,7 +878,8 @@ function collectSqlChartAssetQueryErrors(query, path, errors) {
     pushAuthoringError(errors, {
       path: `${path}.query.sql`,
       ruleId: "chart-sql-query-text-missing",
-      message: `flowSurfaces authoring ${path}.query.sql must be a non-empty string`
+      message: `flowSurfaces authoring ${path}.query.sql must be a non-empty string`,
+      details: withChartRepairHint()
     });
   }
   collectForbiddenObjectKeyErrors(
@@ -699,7 +887,8 @@ function collectSqlChartAssetQueryErrors(query, path, errors) {
     `${path}.query`,
     CHART_SQL_QUERY_FORBIDDEN_KEYS,
     "chart-sql-query-forbidden-builder-keys",
-    errors
+    errors,
+    withChartRepairHint()
   );
 }
 function collectChartAssetVisualErrors(asset, path, errors) {
@@ -708,7 +897,8 @@ function collectChartAssetVisualErrors(asset, path, errors) {
     pushAuthoringError(errors, {
       path: `${path}.visual`,
       ruleId: "chart-visual-missing",
-      message: `flowSurfaces authoring ${path}.visual is required`
+      message: `flowSurfaces authoring ${path}.visual is required`,
+      details: withChartRepairHint()
     });
     return;
   }
@@ -717,7 +907,8 @@ function collectChartAssetVisualErrors(asset, path, errors) {
     `${path}.visual`,
     CHART_VISUAL_LEGACY_BUILDER_KEYS,
     "chart-visual-legacy-builder-keys-unsupported",
-    errors
+    errors,
+    withChartRepairHint()
   );
   const mode = String(visual.mode || "basic").trim();
   if (!CHART_VISUAL_MODE_SET.has(mode)) {
@@ -725,9 +916,9 @@ function collectChartAssetVisualErrors(asset, path, errors) {
       path: `${path}.visual.mode`,
       ruleId: "chart-visual-mode-unsupported",
       message: `flowSurfaces authoring ${path}.visual.mode '${mode}' is not supported`,
-      details: {
+      details: withChartRepairHint({
         mode
-      }
+      })
     });
     return;
   }
@@ -736,7 +927,8 @@ function collectChartAssetVisualErrors(asset, path, errors) {
       pushAuthoringError(errors, {
         path: `${path}.visual.raw`,
         ruleId: "chart-custom-visual-raw-missing",
-        message: `flowSurfaces authoring ${path}.visual.raw is required for custom chart assets`
+        message: `flowSurfaces authoring ${path}.visual.raw is required for custom chart assets`,
+        details: withChartRepairHint()
       });
     }
     collectForbiddenObjectKeyErrors(
@@ -744,7 +936,8 @@ function collectChartAssetVisualErrors(asset, path, errors) {
       `${path}.visual`,
       CHART_CUSTOM_VISUAL_FORBIDDEN_KEYS,
       "chart-custom-visual-public-keys-unsupported",
-      errors
+      errors,
+      withChartRepairHint()
     );
     return;
   }
@@ -753,23 +946,25 @@ function collectChartAssetVisualErrors(asset, path, errors) {
     pushAuthoringError(errors, {
       path: `${path}.visual.type`,
       ruleId: "chart-visual-type-missing",
-      message: `flowSurfaces authoring ${path}.visual.type is required for basic chart assets`
+      message: `flowSurfaces authoring ${path}.visual.type is required for basic chart assets`,
+      details: withChartRepairHint()
     });
   } else if (!CHART_BASIC_VISUAL_TYPE_SET.has(type)) {
     pushAuthoringError(errors, {
       path: `${path}.visual.type`,
       ruleId: "chart-visual-type-unsupported",
       message: `flowSurfaces authoring ${path}.visual.type '${type}' is not supported`,
-      details: {
+      details: withChartRepairHint({
         type
-      }
+      })
     });
   }
   if (!_.isPlainObject(visual.mappings)) {
     pushAuthoringError(errors, {
       path: `${path}.visual.mappings`,
       ruleId: "chart-visual-mappings-missing",
-      message: `flowSurfaces authoring ${path}.visual.mappings is required for basic chart assets`
+      message: `flowSurfaces authoring ${path}.visual.mappings is required for basic chart assets`,
+      details: withChartRepairHint()
     });
     return;
   }
@@ -781,14 +976,14 @@ function collectChartAssetVisualErrors(asset, path, errors) {
       path: `${path}.visual.mappings`,
       ruleId: "chart-visual-required-mappings-missing",
       message: `flowSurfaces authoring ${path}.visual.mappings is missing required keys: ${missingMappings.join(", ")}`,
-      details: {
+      details: withChartRepairHint({
         type,
         missingMappings
-      }
+      })
     });
   }
 }
-function collectForbiddenObjectKeyErrors(value, path, forbiddenKeys, ruleId, errors) {
+function collectForbiddenObjectKeyErrors(value, path, forbiddenKeys, ruleId, errors, details = {}) {
   if (!_.isPlainObject(value)) {
     return;
   }
@@ -801,6 +996,7 @@ function collectForbiddenObjectKeyErrors(value, path, forbiddenKeys, ruleId, err
     ruleId,
     message: `flowSurfaces authoring ${path} does not accept keys: ${keys.join(", ")}`,
     details: {
+      ...details,
       keys
     }
   });
@@ -3186,11 +3382,13 @@ function collectBlockErrors(block, path, errors, localKeys, context) {
     context
   );
   collectSemanticBindingErrors(block, blockType, path, errors, context);
+  collectVisibleDataBlockFieldErrors(block, blockType, path, errors, context);
   collectCommentsBlockErrors(block, blockType, path, errors, context);
   collectRecordHistoryBlockErrors(block, blockType, path, errors, context);
   collectChartDisplayTitleErrors(block, blockType, path, errors);
   collectTreeTableExplicitFieldsErrors(block, blockType, path, errors, context);
   collectTreeConnectFieldsErrors((_a = block.settings) == null ? void 0 : _a.connectFields, `${path}.settings.connectFields`, errors);
+  collectTableSettingsErrors(block, blockType, path, errors);
   collectGridCardSettingsErrors(block, blockType, path, errors);
   const descendantContext = getBlockDescendantValidationContext(block, context);
   collectActionListErrors(block.actions, `${path}.actions`, errors, block, descendantContext, "actions");
@@ -3214,7 +3412,8 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
     pushAuthoringError(errors, {
       path: `${path}.type`,
       ruleId: "jsBlock-type-alias-unsupported",
-      message: `flowSurfaces authoring ${path}.type must be "jsBlock"; "js" is only an action type and is not a public JSBlock block alias. Use ${path}.settings.code for inline JSBlock code`
+      message: `flowSurfaces authoring ${path}.type must be "jsBlock"; "js" is only an action type and is not a public JSBlock block alias. Use ${path}.settings.code for inline JSBlock code`,
+      details: withJsBlockRepairHint()
     });
     return;
   }
@@ -3228,7 +3427,8 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
     pushAuthoringError(errors, {
       path: `${path}.${key}`,
       ruleId: `jsBlock-top-level-${key}-unsupported`,
-      message: `flowSurfaces authoring ${path}.${key} is not accepted on public jsBlock blocks; use ${path}.settings.code and ${path}.settings.version for inline JS code`
+      message: `flowSurfaces authoring ${path}.${key} is not accepted on public jsBlock blocks; use ${path}.settings.code and ${path}.settings.version for inline JS code`,
+      details: withJsBlockRepairHint({ key })
     });
   });
   JS_BLOCK_INTERNAL_AUTHORING_KEYS.forEach((key) => {
@@ -3239,16 +3439,17 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
       path: `${path}.${key}`,
       ruleId: key === "stepParams" ? "jsBlock-stepParams-unsupported" : "jsBlock-internal-field-unsupported",
       message: `flowSurfaces authoring ${path}.${key} is not accepted on public jsBlock blocks; use ${path}.settings.code and ${path}.settings.version instead of internal persisted fields`,
-      details: {
+      details: withJsBlockRepairHint({
         key
-      }
+      })
     });
   });
   if (hasOwn(block, "script") && context.authoringActionName !== "applyBlueprint") {
     pushAuthoringError(errors, {
       path: `${path}.script`,
       ruleId: "jsBlock-script-unsupported",
-      message: `flowSurfaces authoring ${path}.script is only supported by applyBlueprint assets.scripts; use ${path}.settings.code for localized jsBlock inline JS code`
+      message: `flowSurfaces authoring ${path}.script is only supported by applyBlueprint assets.scripts; use ${path}.settings.code for localized jsBlock inline JS code`,
+      details: withJsBlockRepairHint()
     });
   }
   const settings = _.isPlainObject(block.settings) ? block.settings : void 0;
@@ -3261,10 +3462,10 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
         path: `${path}.settings.${key}`,
         ruleId: "jsBlock-settings-unsupported-key",
         message: `flowSurfaces authoring ${path}.settings.${key} is not part of the public jsBlock contract; use ${path}.settings.code and ${path}.settings.version for inline JS code`,
-        details: {
+        details: withJsBlockRepairHint({
           key,
           allowedKeys: Array.from(JS_BLOCK_ALLOWED_SETTINGS_KEYS)
-        }
+        })
       });
     });
   }
@@ -3274,9 +3475,9 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
       path: `${path}.script`,
       ruleId: "jsBlock-mixed-inline-and-script",
       message: `flowSurfaces authoring ${path} cannot combine script asset references with ${inlineKeys.map((key) => `settings.${key}`).join(", ")}; use either applyBlueprint assets.scripts + block.script or inline ${path}.settings.code`,
-      details: {
+      details: withJsBlockRepairHint({
         inlineKeys
-      }
+      })
     });
   }
   const hasInlineCode = typeof (settings == null ? void 0 : settings.code) === "string" && !!settings.code.trim();
@@ -3286,7 +3487,8 @@ function collectJsBlockPublicContractErrors(block, path, errors, context) {
     pushAuthoringError(errors, {
       path,
       ruleId: "jsBlock-source-required",
-      message: `flowSurfaces authoring ${path} jsBlock must include inline ${path}.settings.code or, for applyBlueprint only, a block.script asset reference`
+      message: `flowSurfaces authoring ${path} jsBlock must include inline ${path}.settings.code or, for applyBlueprint only, a block.script asset reference`,
+      details: withJsBlockRepairHint()
     });
   }
 }
@@ -3302,16 +3504,17 @@ function collectJsBlockConfigurePublicContractErrors(changes, path, errors) {
       path: `${path}.${key}`,
       ruleId: key === "stepParams" ? "jsBlock-stepParams-unsupported" : "jsBlock-internal-field-unsupported",
       message: `flowSurfaces authoring ${path}.${key} is not accepted on public jsBlock configure changes; use ${path}.code and ${path}.version instead of internal persisted fields`,
-      details: {
+      details: withJsBlockRepairHint({
         key
-      }
+      })
     });
   });
   if (hasOwn(changes, "script")) {
     pushAuthoringError(errors, {
       path: `${path}.script`,
       ruleId: "jsBlock-script-unsupported",
-      message: `flowSurfaces authoring ${path}.script is only supported by applyBlueprint assets.scripts; use ${path}.code for localized jsBlock configure JS code`
+      message: `flowSurfaces authoring ${path}.script is only supported by applyBlueprint assets.scripts; use ${path}.code for localized jsBlock configure JS code`,
+      details: withJsBlockRepairHint()
     });
   }
   const inlineKeys = JS_BLOCK_TOP_LEVEL_JS_KEYS.filter((key) => hasOwn(changes, key));
@@ -3320,9 +3523,9 @@ function collectJsBlockConfigurePublicContractErrors(changes, path, errors) {
       path: `${path}.script`,
       ruleId: "jsBlock-mixed-inline-and-script",
       message: `flowSurfaces authoring ${path} cannot combine script asset references with ${inlineKeys.map((key) => `${path}.${key}`).join(", ")}; use either applyBlueprint assets.scripts + block.script or localized ${path}.code`,
-      details: {
+      details: withJsBlockRepairHint({
         inlineKeys
-      }
+      })
     });
   }
   if (!hasOwn(changes, "settings")) {
@@ -3333,7 +3536,8 @@ function collectJsBlockConfigurePublicContractErrors(changes, path, errors) {
     pushAuthoringError(errors, {
       path: `${path}.settings`,
       ruleId: "jsBlock-settings-unsupported-key",
-      message: `flowSurfaces authoring ${path}.settings is not part of the public jsBlock configure contract; use ${path}.code and ${path}.version`
+      message: `flowSurfaces authoring ${path}.settings is not part of the public jsBlock configure contract; use ${path}.code and ${path}.version`,
+      details: withJsBlockRepairHint()
     });
     return;
   }
@@ -3342,9 +3546,9 @@ function collectJsBlockConfigurePublicContractErrors(changes, path, errors) {
       path: `${path}.settings.${key}`,
       ruleId: "jsBlock-settings-unsupported-key",
       message: `flowSurfaces authoring ${path}.settings.${key} is not part of the public jsBlock configure contract; use ${path}.${key}`,
-      details: {
+      details: withJsBlockRepairHint({
         key
-      }
+      })
     });
   });
 }
@@ -3376,7 +3580,8 @@ function collectUnsupportedMainBlockSectionErrors(block, blockType, path, errors
     pushAuthoringError(errors, {
       path: `${path}.${section}`,
       ruleId: `${blockType}-main-block-unsupported-${section}`,
-      message: `flowSurfaces authoring ${path} ${blockType} main blocks do not support ${section}`
+      message: `flowSurfaces authoring ${path} ${blockType} main blocks do not support ${section}`,
+      details: blockType === "calendar" ? buildCalendarMainBlockRepairDetails(section) : blockType === "kanban" ? buildKanbanMainBlockRepairDetails(section) : void 0
     });
   });
 }
@@ -3393,7 +3598,8 @@ function collectApplyBlueprintKanbanFieldLimitErrors(block, blockType, path, err
     message: `flowSurfaces authoring ${path}.fields supports at most 2 fields for applyBlueprint kanban main blocks`,
     details: {
       max: 2,
-      count: block.fields.length
+      count: block.fields.length,
+      repairHint: "Kanban main block fields controls compact card display only. Keep at most 2 fields in applyBlueprint kanban fields, move richer card details to settings.cardPopup, and keep block type kanban."
     }
   });
 }
@@ -3489,6 +3695,7 @@ async function collectConfigureErrors(values, errors, context) {
   collectCommentsBlockErrors(changesBlock, hostBlockType, "$.changes", errors, context);
   collectRecordHistoryBlockErrors(changesBlock, hostBlockType, "$.changes", errors, context);
   collectChartDisplayTitleErrors(changes, hostBlockType, "$.changes", errors);
+  collectTableSettingsErrors(changes, hostBlockType, "$.changes", errors, { directSettings: true });
   collectGridCardSettingsErrors(changes, hostBlockType, "$.changes", errors, { directSettings: true });
   collectAssignValuesErrors(changes.assignValues, "$.changes.assignValues", errors, changesBlock, context);
   collectTriggerWorkflowsErrors(changes.triggerWorkflows, "$.changes.triggerWorkflows", errors);
@@ -3531,9 +3738,18 @@ function pushAuthoringError(errors, error) {
     type: "bad_request",
     code: "FLOW_SURFACE_AUTHORING_VALIDATION_ERROR",
     status: 400,
-    ...error
+    ...error,
+    message: appendRepairHintToAuthoringMessage(error)
   });
 }
+function appendRepairHintToAuthoringMessage(error) {
+  var _a;
+  const repairHint = typeof ((_a = error.details) == null ? void 0 : _a.repairHint) === "string" ? error.details.repairHint.trim() : "";
+  if (!repairHint || error.message.includes(repairHint)) {
+    return error.message;
+  }
+  return `${error.message}. ${repairHint}`;
+}
 function hasOwnDefined(value, key) {
   return _.isPlainObject(value) && Object.prototype.hasOwnProperty.call(value, key) && !_.isUndefined(value[key]);
 }
@@ -3696,7 +3912,8 @@ function collectPublicLayoutErrors(layout, layoutPath, knownEntries, kind, error
     pushAuthoringError(errors, {
       path: `${layoutPath}.rows`,
       ruleId: "block-layout-single-column",
-      message: `flowSurfaces authoring ${layoutPath}.rows must not place every non-filter block on its own row`
+      message: `flowSurfaces authoring ${layoutPath}.rows must not place every non-filter block on its own row`,
+      details: buildTwoColumnLayoutRepairDetails()
     });
   }
 }
@@ -4140,6 +4357,195 @@ function doesBlockConsumeDefaultFilterAction(block) {
   const blockType = String((block == null ? void 0 : block.type) || "").trim();
   return (0, import_public_data_surface_default_filter.isFlowSurfacePublicDataSurfaceBlockType)(blockType) && !(0, import_template_reference.hasFlowSurfaceTemplateDocument)(block == null ? void 0 : block.template);
 }
+function collectVisibleDataBlockFieldErrors(block, blockType, path, errors, context) {
+  if (!VISIBLE_FIELD_REQUIRED_DATA_BLOCK_TYPES.has(blockType) || (0, import_template_reference.hasFlowSurfaceTemplateReference)(block == null ? void 0 : block.template)) {
+    return;
+  }
+  const fieldEntries = collectVisibleDataBlockFieldEntries(block, path);
+  const validBusinessFieldNames = collectVisibleDataBlockValidBusinessFieldNames(block, context, fieldEntries);
+  if (!fieldEntries.length || !validBusinessFieldNames.length) {
+    const hasBlockFields2 = Array.isArray(block == null ? void 0 : block.fields);
+    const hasBlockFieldGroups2 = Array.isArray(block == null ? void 0 : block.fieldGroups);
+    const fieldConfigPath2 = !hasBlockFields2 && hasBlockFieldGroups2 ? `${path}.fieldGroups` : `${path}.fields`;
+    const fieldConfigLabel2 = !hasBlockFields2 && hasBlockFieldGroups2 ? `${path}.fieldGroups[].fields` : `${path}.fields`;
+    const suggestedFields = pickVisibleDataBlockFieldSuggestions(block, context);
+    pushAuthoringError(errors, {
+      path: fieldConfigPath2,
+      ruleId: "data-block-visible-fields-required",
+      message: `flowSurfaces authoring ${path} ${blockType} block has no valid business fields. Add collection field names to ${fieldConfigLabel2}; defaults.collections.*.fieldGroups only configures generated popups/forms and is not a substitute for visible block columns.`,
+      details: {
+        blockType,
+        collection: getBlockCollectionName(block, context),
+        fieldCount: fieldEntries.length,
+        ...suggestedFields.length ? { suggestion: { fields: suggestedFields } } : {}
+      }
+    });
+    return;
+  }
+  if (!VISIBLE_FIELD_MINIMUM_DATA_BLOCK_TYPES.has(blockType)) {
+    return;
+  }
+  if (hasUnknownVisibleDataBlockFieldPath(block, context, fieldEntries)) {
+    return;
+  }
+  const eligibleBusinessFields = collectVisibleDataBlockEligibleBusinessFieldNames(block, context);
+  if (eligibleBusinessFields.length < RICH_COLLECTION_VISIBLE_FIELD_THRESHOLD) {
+    return;
+  }
+  const requiredFieldCount = Math.min(RICH_DATA_BLOCK_VISIBLE_FIELD_MINIMUM, eligibleBusinessFields.length);
+  if (validBusinessFieldNames.length >= requiredFieldCount) {
+    return;
+  }
+  const hasBlockFields = Array.isArray(block == null ? void 0 : block.fields);
+  const hasBlockFieldGroups = Array.isArray(block == null ? void 0 : block.fieldGroups);
+  const fieldConfigPath = !hasBlockFields && hasBlockFieldGroups ? `${path}.fieldGroups` : `${path}.fields`;
+  const fieldConfigLabel = !hasBlockFields && hasBlockFieldGroups ? `${path}.fieldGroups[].fields` : `${path}.fields`;
+  pushAuthoringError(errors, {
+    path: fieldConfigPath,
+    ruleId: "data-block-visible-fields-minimum",
+    message: `flowSurfaces authoring ${path} ${blockType} block only has ${validBusinessFieldNames.length} valid business field(s). Add at least ${requiredFieldCount} collection field names to ${fieldConfigLabel}; defaults.collections.*.fieldGroups only configures generated popups/forms and is not a substitute for visible block columns.`,
+    details: {
+      blockType,
+      collection: getBlockCollectionName(block, context),
+      fieldCount: validBusinessFieldNames.length,
+      requiredFieldCount,
+      eligibleBusinessFieldCount: eligibleBusinessFields.length,
+      suggestion: {
+        fields: eligibleBusinessFields.slice(0, requiredFieldCount)
+      }
+    }
+  });
+}
+function collectVisibleDataBlockFieldEntries(block, path) {
+  const entries = [];
+  if (Array.isArray(block == null ? void 0 : block.fields)) {
+    block.fields.forEach((field, index) => {
+      entries.push({ field, path: `${path}.fields[${index}]` });
+    });
+  }
+  if (Array.isArray(block == null ? void 0 : block.fieldGroups)) {
+    block.fieldGroups.forEach((group, groupIndex) => {
+      if (!Array.isArray(group == null ? void 0 : group.fields)) {
+        return;
+      }
+      group.fields.forEach((field, fieldIndex) => {
+        entries.push({
+          field,
+          path: `${path}.fieldGroups[${groupIndex}].fields[${fieldIndex}]`
+        });
+      });
+    });
+  }
+  return entries;
+}
+function collectVisibleDataBlockValidBusinessFieldNames(block, context, fieldEntries) {
+  const names = /* @__PURE__ */ new Set();
+  fieldEntries.forEach((entry) => {
+    const fieldPath = getAssociationAwareFieldPathInput(entry.field);
+    if (!fieldPath || fieldPath.startsWith("$") || fieldPath.startsWith("{{")) {
+      return;
+    }
+    if (!isVisibleDataBlockBusinessField(entry.field, block, context)) {
+      return;
+    }
+    names.add((0, import_service_helpers.normalizeFieldPath)(fieldPath));
+  });
+  return Array.from(names);
+}
+function hasUnknownVisibleDataBlockFieldPath(block, context, fieldEntries) {
+  const collection = getBlockCollection(block, context);
+  if (!collection) {
+    return false;
+  }
+  return fieldEntries.some((entry) => {
+    const fieldPath = getAssociationAwareFieldPathInput(entry.field);
+    if (!fieldPath || fieldPath.startsWith("$") || fieldPath.startsWith("{{")) {
+      return false;
+    }
+    return !(0, import_service_helpers.resolveFieldFromCollection)(collection, (0, import_service_helpers.normalizeFieldPath)(fieldPath));
+  });
+}
+function collectVisibleDataBlockEligibleBusinessFieldNames(block, context) {
+  const collection = getBlockCollection(block, context);
+  if (!collection) {
+    return [];
+  }
+  return (0, import_service_helpers.getCollectionFields)(collection).map((field) => {
+    const name = String((0, import_service_helpers.getFieldName)(field) || "").trim();
+    if (!name || !isVisibleDataBlockMinimumCandidateResolvedField(field, name)) {
+      return "";
+    }
+    return name;
+  }).filter(Boolean);
+}
+function isVisibleDataBlockMinimumCandidateResolvedField(field, fieldName) {
+  if (!isVisibleDataBlockBusinessResolvedField(field, fieldName)) {
+    return false;
+  }
+  if ((0, import_service_helpers.isAssociationField)(field)) {
+    return false;
+  }
+  if (/Id$/.test(fieldName)) {
+    return false;
+  }
+  return true;
+}
+function isVisibleDataBlockBusinessField(field, block, context) {
+  const fieldPath = getAssociationAwareFieldPathInput(field);
+  if (!fieldPath || fieldPath.startsWith("$") || fieldPath.startsWith("{{")) {
+    return false;
+  }
+  if (_.isPlainObject(field)) {
+    if (field.hidden === true || field.internal === true || field.synthetic === true || field.actionOnly === true) {
+      return false;
+    }
+    const semanticType = String(field.type || field.fieldType || field.interface || "").trim();
+    if (semanticType && NON_BUSINESS_VISIBLE_FIELD_TYPES.has(semanticType)) {
+      return false;
+    }
+  }
+  const collection = getBlockCollection(block, context);
+  if (!collection) {
+    return true;
+  }
+  const resolvedField = (0, import_service_helpers.resolveFieldFromCollection)(collection, (0, import_service_helpers.normalizeFieldPath)(fieldPath));
+  if (!resolvedField) {
+    return true;
+  }
+  const fieldName = (0, import_service_helpers.getFieldName)(resolvedField) || fieldPath;
+  return isVisibleDataBlockBusinessResolvedField(resolvedField, fieldName);
+}
+function pickVisibleDataBlockFieldSuggestions(block, context) {
+  const collection = getBlockCollection(block, context);
+  if (!collection) {
+    return [];
+  }
+  return (0, import_service_helpers.getCollectionFields)(collection).map((field) => {
+    const name = String((0, import_service_helpers.getFieldName)(field) || "").trim();
+    if (!name || !isVisibleDataBlockBusinessResolvedField(field, name)) {
+      return "";
+    }
+    return name;
+  }).filter(Boolean).slice(0, 3);
+}
+function isVisibleDataBlockBusinessResolvedField(field, fieldName) {
+  var _a;
+  if (NON_BUSINESS_VISIBLE_FIELD_NAMES.has(fieldName)) {
+    return false;
+  }
+  const fieldInterface = String((0, import_service_helpers.getFieldInterface)(field) || "").trim();
+  if (NON_BUSINESS_VISIBLE_FIELD_INTERFACES.has(fieldInterface)) {
+    return false;
+  }
+  const fieldType = String((0, import_service_helpers.getFieldType)(field) || "").trim();
+  if (NON_BUSINESS_VISIBLE_FIELD_TYPES.has(fieldType)) {
+    return false;
+  }
+  if ((field == null ? void 0 : field.hidden) === true || ((_a = field == null ? void 0 : field.options) == null ? void 0 : _a.hidden) === true) {
+    return false;
+  }
+  return true;
+}
 function hasConcreteFilterItem(value) {
   if (!_.isPlainObject(value)) {
     return false;
@@ -4768,6 +5174,43 @@ function getCollectionFilterTargetKey(collection) {
 function normalizeDataSourceKey(value) {
   return String(value || "main").trim() || "main";
 }
+function collectTableSettingsErrors(block, blockType, blockPath, errors, options = {}) {
+  if (blockType !== "table" || !_.isPlainObject(block)) {
+    return;
+  }
+  TABLE_INTERNAL_AUTHORING_KEYS.forEach((key) => {
+    if (Object.prototype.hasOwnProperty.call(block, key)) {
+      pushTableSettingsUnsupportedError(errors, `${blockPath}.${key}`, key);
+    }
+  });
+  const hasSettings = _.isPlainObject(block == null ? void 0 : block.settings);
+  if (!hasSettings) {
+    return;
+  }
+  const settings = block.settings;
+  const settingsPath = `${blockPath}.settings`;
+  Object.keys(settings).forEach((key) => {
+    if (TABLE_ALLOWED_SETTINGS_KEYS.has(key) && options.directSettings !== true) {
+      return;
+    }
+    if (options.directSettings === true && !TABLE_INTERNAL_AUTHORING_KEYS.includes(key)) {
+      return;
+    }
+    pushTableSettingsUnsupportedError(errors, `${settingsPath}.${key}`, key);
+  });
+}
+function pushTableSettingsUnsupportedError(errors, path, key) {
+  pushAuthoringError(errors, {
+    path,
+    ruleId: "table-settings-unsupported-key",
+    message: `flowSurfaces authoring ${path} is not part of the public table settings contract`,
+    details: {
+      key,
+      allowedKeys: Array.from(TABLE_ALLOWED_SETTINGS_KEYS),
+      repairHint: TABLE_SETTINGS_REPAIR_HINT
+    }
+  });
+}
 function collectGridCardSettingsErrors(block, blockType, blockPath, errors, options = {}) {
   const hasSettings = _.isPlainObject(block == null ? void 0 : block.settings);
   if (!hasSettings && options.directSettings !== true) {
@@ -4853,8 +5296,115 @@ function collectActionListErrors(actions, path, errors, block, context = {}, slo
   if (!Array.isArray(actions)) {
     return;
   }
+  collectDuplicateAIEmployeeActionErrors(actions, path, errors, block);
   actions.forEach((action, index) => collectActionErrors(action, `${path}[${index}]`, errors, block, context, slot));
 }
+function collectDuplicateAIEmployeeActionErrors(actions, path, errors, block) {
+  const seen = /* @__PURE__ */ new Map();
+  actions.forEach((action, index) => {
+    const actionType = resolveAuthoringActionType(action, block);
+    if (actionType !== "aiEmployee" || !_.isPlainObject(action)) {
+      return;
+    }
+    const identity = buildAuthoringAIEmployeeActionIdentity(action.settings);
+    if (!identity) {
+      return;
+    }
+    const currentPath = `${path}[${index}]`;
+    const previousPath = seen.get(identity);
+    if (previousPath) {
+      pushAuthoringError(errors, {
+        path: currentPath,
+        ruleId: "duplicate-ai-employee-action",
+        message: `flowSurfaces authoring ${currentPath} duplicates an existing AI employee action in the same action container; reuse or update the existing button instead of appending another identical AI employee action.`,
+        details: {
+          duplicateOf: previousPath,
+          repairHint: "Remove the duplicate aiEmployee action, or change username, task title/key, or workContext if this is a genuinely different AI employee action."
+        }
+      });
+      return;
+    }
+    seen.set(identity, currentPath);
+  });
+}
+function buildAuthoringAIEmployeeActionIdentity(settings) {
+  if (!_.isPlainObject(settings)) {
+    return "";
+  }
+  const username = String(settings.username || "").trim();
+  if (!username) {
+    return "";
+  }
+  return stableSerializeAuthoringValue(normalizeAuthoringAIEmployeePublicSettingsForIdentity(settings));
+}
+function normalizeAuthoringAIEmployeePublicSettingsForIdentity(settings) {
+  return {
+    username: String(settings.username || "").trim(),
+    auto: typeof settings.auto === "boolean" ? settings.auto : false,
+    workContext: Object.prototype.hasOwnProperty.call(settings, "workContext") ? normalizeAuthoringAIEmployeeWorkContextForIdentity(settings.workContext) : [{ type: "flow-model", target: "self" }],
+    tasks: normalizeAuthoringAIEmployeeTasksForIdentity(settings.tasks),
+    style: {
+      ...AUTHORING_AI_EMPLOYEE_DEFAULT_STYLE,
+      ..._.isPlainObject(settings.style) ? _.pick(settings.style, AUTHORING_AI_EMPLOYEE_STYLE_PUBLIC_KEYS) : {}
+    }
+  };
+}
+function normalizeAuthoringAIEmployeeWorkContextForIdentity(value) {
+  return _.castArray(value || []).map((item) => {
+    if (!_.isPlainObject(item)) {
+      return item;
+    }
+    const output = _.pick(item, AUTHORING_AI_EMPLOYEE_WORK_CONTEXT_PUBLIC_KEYS);
+    if (!Object.prototype.hasOwnProperty.call(output, "type") || _.isUndefined(output.type) || output.type === null) {
+      output.type = "flow-model";
+    }
+    return output;
+  });
+}
+function normalizeAuthoringAIEmployeeTasksForIdentity(value) {
+  return _.castArray(value || []).map((task) => {
+    if (!_.isPlainObject(task)) {
+      return task;
+    }
+    const output = _.pick(task, AUTHORING_AI_EMPLOYEE_TASK_PUBLIC_SETTING_KEYS);
+    if (_.isPlainObject(output.message)) {
+      output.message = _.pick(output.message, AUTHORING_AI_EMPLOYEE_TASK_MESSAGE_PUBLIC_KEYS);
+      if (_.isPlainObject(output.message.workContext)) {
+        output.message.workContext = normalizeAuthoringAIEmployeeWorkContextForIdentity(output.message.workContext);
+      } else if (Array.isArray(output.message.workContext)) {
+        output.message.workContext = normalizeAuthoringAIEmployeeWorkContextForIdentity(output.message.workContext);
+      }
+    }
+    if (Object.prototype.hasOwnProperty.call(task, "prompt") && !Object.prototype.hasOwnProperty.call(output.message || {}, "user")) {
+      output.message = {
+        ..._.isPlainObject(output.message) ? output.message : {},
+        user: task.prompt
+      };
+    }
+    if (_.isPlainObject(output.model)) {
+      output.model = _.pick(output.model, AUTHORING_AI_EMPLOYEE_TASK_MODEL_PUBLIC_KEYS);
+    }
+    if (_.isPlainObject(output.skillSettings)) {
+      output.skillSettings = _.pick(output.skillSettings, AUTHORING_AI_EMPLOYEE_SKILL_SETTINGS_PUBLIC_KEYS);
+      if (Array.isArray(output.skillSettings.skills) && !Object.prototype.hasOwnProperty.call(output.skillSettings, "skillsVersion")) {
+        output.skillSettings.skillsVersion = 2;
+      }
+      if (Array.isArray(output.skillSettings.tools) && !Object.prototype.hasOwnProperty.call(output.skillSettings, "toolsVersion")) {
+        output.skillSettings.toolsVersion = 2;
+      }
+    }
+    return output;
+  });
+}
+function stableSerializeAuthoringValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableSerializeAuthoringValue(item)).join(",")}]`;
+  }
+  if (_.isPlainObject(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableSerializeAuthoringValue(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
 function resolveAuthoringActionType(action, block) {
   const rawType = typeof action === "string" ? action : _.isPlainObject(action) ? action.type : "";
   const normalized = String(rawType || "").trim().toLowerCase();
@@ -5388,7 +5938,8 @@ function collectApplyBlueprintScriptAssetReferenceErrors(spec, path, errors, con
       pushAuthoringError(errors, {
         path: `${path}.script`,
         ruleId: "apply-blueprint-script-asset-key-invalid",
-        message: `flowSurfaces applyBlueprint ${publicPath}.script must be a non-empty string asset key; use settings.code for inline JS code`
+        message: `flowSurfaces applyBlueprint ${publicPath}.script must be a non-empty string asset key; use settings.code for inline JS code`,
+        details: withJsBlockRepairHint()
       });
       return;
     }
@@ -5399,14 +5950,18 @@ function collectApplyBlueprintScriptAssetReferenceErrors(spec, path, errors, con
     pushAuthoringError(errors, {
       path: `${path}.script`,
       ruleId: "apply-blueprint-script-asset-code-required",
-      message: `flowSurfaces applyBlueprint ${publicPath}.script references script asset '${scriptKey}' without non-empty code; use settings.code for inline JS code`
+      message: `flowSurfaces applyBlueprint ${publicPath}.script references script asset '${scriptKey}' without non-empty code; use settings.code for inline JS code`,
+      details: withJsBlockRepairHint({
+        scriptKey
+      })
     });
     return;
   }
   pushAuthoringError(errors, {
     path: `${path}.script`,
     ruleId: "apply-blueprint-script-asset-key-invalid",
-    message: `flowSurfaces applyBlueprint ${publicPath}.script must be a string asset key; use settings.code for inline JS code`
+    message: `flowSurfaces applyBlueprint ${publicPath}.script must be a string asset key; use settings.code for inline JS code`,
+    details: withJsBlockRepairHint()
   });
 }
 function hasApplyBlueprintRunnableScriptAssetReference(script, context) {