@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/engine/boot-validator/screens.js

@@ -6,6 +6,7 @@
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
@@ -23,7 +24,7 @@ function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions
     const rowClickActions = rowActions.filter((a) => a.kind === "navigate" && a.rowClick === true);
     if (rowClickActions.length > 1) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has ${rowClickActions.length} ` +
-            "rowActions marked rowClick:true — at most one may fire on a row-body click.");
+            "rowActions marked rowClick:true — at most one may fire on a row-body click. Mark at most one rowAction with rowClick: true.");
     }
 }
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
@@ -44,7 +45,7 @@ function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
     if (listSpec !== undefined) {
         if (fieldDef.type !== "embedded" || fieldDef.multiple !== true) {
             throw new Error(`${where} sets embeddedList, which only applies to an embedded list ` +
-                `(createEmbeddedListField); the field is type "${fieldDef.type}".`);
+                `(createEmbeddedListField); the field is type "${fieldDef.type}". Remove embeddedList or point it at an embedded list field.`);
         }
         for (const cell of listSpec.readOnlyCells ?? []) {
             if (fieldDef.schema[cell] === undefined) {
@@ -59,7 +60,7 @@ function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
         return;
     if (prefill.kind === "today") {
         if (fieldDef.type !== "date") {
-            throw new Error(`${where} prefill "today" needs a date field; the field is type "${fieldDef.type}".`);
+            throw new Error(`${where} prefill "today" needs a date field; the field is type "${fieldDef.type}". Use a date field or a different prefill.`);
         }
         // skip: today carries no property, nothing further to check
         return;
@@ -67,7 +68,7 @@ function validateEditFieldExtras(featureName, screenId, entityDef, fieldSpec) {
     const allowsUserId = fieldDef.type === "text" || fieldDef.type === "reference";
     if (prefill.property === "id" ? !allowsUserId : fieldDef.type !== "text") {
         throw new Error(`${where} prefill currentUser.${prefill.property} does not fit a field of type ` +
-            `"${fieldDef.type}" (displayName and email need text; id needs text or a reference).`);
+            `"${fieldDef.type}" (displayName and email need text; id needs text or a reference). Use a fitting field type or a different prefill property.`);
     }
 }
 function validateNoWidgetRequiredField(featureName, screenId, entityDef, fieldSpec) {
@@ -120,7 +121,7 @@ export function readsNavigateParamsAsFormPrefill(target, explicitEntityId, sourc
 // for the value to land, and a params extractor whose keys don't include
 // the filter's id would silently miss it — both are boot errors instead of
 // a silently-empty dashboard.
-function validateRowActionNavigateParams(featureName, screenId, screenType, screenEntity, action, target) {
+function validateRowActionNavigateParams(featureName, screenId, screenType, screenEntity, action, target, actionLabel = "rowAction") {
     // skip: not a navigate-with-params action — nothing to validate here.
     if (action.kind !== "navigate" || action.params === undefined)
         return;
@@ -136,14 +137,14 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
         const targetDescriptor = action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
         const filter = target.screen.filter;
         if (filter === undefined) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" sets ` +
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params on navigate-target ${targetDescriptor} (dashboard) — target dashboard declares no ` +
                 `filter — params would be a no-op. Remove the params extractor, or add a \`filter\` to the ` +
                 `target dashboard so it has somewhere to read the value from.`);
         }
         const extractedKeys = rowFieldExtractorKeys(action.params);
         if (!extractedKeys.includes(filter.id)) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" sets ` +
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" sets ` +
                 `params [${extractedKeys.join(", ")}] on navigate-target ${targetDescriptor} (dashboard) whose ` +
                 `filter id is "${filter.id}" — none of the extracted keys match, so the filter would stay ` +
                 `unset. Fix the params extractor to produce a "${filter.id}" key, or remove it.`);
@@ -159,7 +160,7 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
                 : `same entity "${screenEntity}" auto-fills row["id"]`})`
             : `screen type "${target.screen.type}"`;
         const targetDescriptor = action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" ` +
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
             `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm, ` +
             `secretMint and entityEdit-create targets read URL search params as initial values. Remove ` +
             `the params extractor or retarget to an actionForm / secretMint / cross-entity ` +
@@ -168,7 +169,7 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
     const formTarget = target.screen;
     if ((formTarget.type === "actionForm" || formTarget.type === "secretMint") &&
         formTarget.submitPrefilled === true) {
-        validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}"`, "navigate-target", action.screen ?? `entity "${action.entity}"`, formTarget, action.params);
+        validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}"`, "navigate-target", action.screen ?? `entity "${action.entity}"`, formTarget, action.params);
     }
 }
 // Shared by projectionDetail and entityEdit: a tab strip needs something to
@@ -196,7 +197,7 @@ function validateTabSections(featureName, screenId, screenType, sections) {
         }
         if (tabIds.has(section.id)) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has duplicate tab id ` +
-                `"${section.id}" (sections[${index}]).`);
+                `"${section.id}" (sections[${index}]). Give each tab section a unique id.`);
         }
         tabIds.add(section.id);
     });
@@ -275,7 +276,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
 // for an unregistered key instead of crashing — this check makes the same
 // gap fail loudly at boot instead of silently at render.
 function isRegisteredIcon(icon) {
-    return NAV_ICON_KEYS.includes(icon);
+    return isOneOf(NAV_ICON_KEYS, icon);
 }
 export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
     const resolved = resolveActionIcon(action.id, action.icon);
@@ -398,7 +399,7 @@ function validateDrawerTargetAction(featureName, screenId, screenKind, actionLab
         return;
     validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}"`, "drawer-target", action.screen, target, action.params);
 }
-function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, params) {
+export function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, params) {
     const renderedFieldNames = new Set();
     for (const section of target.layout.sections) {
         if (!isFieldsEditSection(section))
@@ -418,7 +419,7 @@ function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, p
                 ("format" in targetField && targetField.format === "password"));
         if (isSensitiveOrPassword) {
             throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" marks as ` +
-                `sensitive or password — the renderer never prefills those fields and would leave the form empty.`);
+                `sensitive or password — the renderer never prefills those fields and would leave the form empty. Remove that param or prefill a non-sensitive field.`);
         }
         if (!renderedFieldNames.has(fieldName)) {
             throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not render in ` +
@@ -434,12 +435,12 @@ function validateRowActionNavigateTab(featureName, screenId, screenType, actionL
         return;
     if (target === undefined) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
-            `sets tab "${action.tab}", but its navigate-target could not be resolved to a screen.`);
+            `sets tab "${action.tab}", but its navigate-target could not be resolved to a screen. Point the navigate-target at a registered screen.`);
     }
     if (target.screen.type !== "projectionDetail" || target.screen.layout.mode !== "tabs") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
             `sets tab "${action.tab}", but navigate-target screen "${target.screen.id}" is not a ` +
-            `projectionDetail with layout.mode "tabs" — only those read the tab param.`);
+            `projectionDetail with layout.mode "tabs" — only those read the tab param. Remove the tab or navigate to a projectionDetail screen with layout.mode "tabs".`);
     }
     const sectionIds = target.screen.layout.sections
         .map((section) => section.id)
@@ -470,7 +471,7 @@ function resolveRowActionNavigateTarget(featureName, screenId, screenType, actio
         if (detail === undefined) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
                 `navigate-target entity "${action.entity}" has no screen declaring ` +
-                `detailFor: "${action.entity}".`);
+                `detailFor: "${action.entity}". Add detailFor: "${action.entity}" to a screen or navigate to a screen directly.`);
         }
         validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, detail);
         return detail;
@@ -482,7 +483,7 @@ function resolveRowActionNavigateTarget(featureName, screenId, screenType, actio
     const candidateQn = qualifyEntityName(featureName, "screen", action.screen);
     if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
-            `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`);
+            `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`);
     }
     const target = screensByShortId.get(action.screen)?.[0];
     validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, target);
@@ -493,7 +494,7 @@ function resolveRowActionNavigateTarget(featureName, screenId, screenType, actio
 // same registration requirement.
 function validateWriteHandlerRegistered(featureName, screenId, context, handler, allWriteHandlerQns) {
     if (!handler || typeof handler !== "string") {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler.`);
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler. Set handler to a non-empty handler name.`);
     }
     if (!allWriteHandlerQns.has(handler)) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) handler "${handler}" ` +
@@ -539,7 +540,7 @@ function validateFormFieldsMap(featureName, screenId, context, fields, allowEmpt
 function validateOptionsQueryFieldRefs(where, fieldName, payload, siblingFieldNames) {
     for (const ref of optionsQueryFieldRefs(payload)) {
         if (ref === fieldName) {
-            throw new Error(`${where} optionsQueryPayload references itself ({ field: "${ref}" })`);
+            throw new Error(`${where} optionsQueryPayload references itself ({ field: "${ref}" }). Reference a different field of the form.`);
         }
         if (!siblingFieldNames.has(ref)) {
             throw new Error(`${where} optionsQueryPayload references unknown field "${ref}" — it must be another field of the same form`);
@@ -567,30 +568,33 @@ function validateFormSelectOptions(featureName, screenId, context, fieldName, fd
     if (fdef.type === "select") {
         const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) select field "${fieldName}"`;
         if (fdef.conditionalOptions !== undefined) {
-            throw new Error(`${where} declares conditionalOptions — ${CONDITIONAL_OPTIONS_ENTITY_ONLY}`);
+            throw new Error(`${where} declares conditionalOptions — ${CONDITIONAL_OPTIONS_ENTITY_ONLY}. Remove conditionalOptions from this field.`);
         }
         if (fdef.optionsQuery !== undefined) {
             if (fdef.optionsQuery.length === 0) {
-                throw new Error(`${where} has an empty optionsQuery`);
+                throw new Error(`${where} has an empty optionsQuery. Set it to a query name or remove it.`);
             }
             if (fdef.options.length > 0) {
                 throw new Error(`${where} declares both options and optionsQuery — pick one`);
             }
+            if (fdef.optionsAvailabilityQuery !== undefined) {
+                throw new Error(`${where} declares both optionsQuery and optionsAvailabilityQuery — availability only applies to static options`);
+            }
             validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
         }
         else if (fdef.optionsAvailabilityQuery !== undefined) {
             if (fdef.optionsAvailabilityQuery.length === 0) {
-                throw new Error(`${where} has an empty optionsAvailabilityQuery`);
+                throw new Error(`${where} has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`);
             }
             validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
         }
         else if (fdef.optionsQueryPayload !== undefined) {
-            throw new Error(`${where} has optionsQueryPayload without optionsQuery`);
+            throw new Error(`${where} has optionsQueryPayload without optionsQuery. Set optionsQuery or remove optionsQueryPayload.`);
         }
     }
     else if (fdef.type === "multiSelect" && fdef.optionsAvailabilityQuery !== undefined) {
         if (fdef.optionsAvailabilityQuery.length === 0) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) multiSelect field "${fieldName}" has an empty optionsAvailabilityQuery`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) multiSelect field "${fieldName}" has an empty optionsAvailabilityQuery. Set it to a query name or remove it.`);
         }
     }
 }
@@ -663,11 +667,11 @@ function validateFormLayoutSections(featureName, screenId, context, layout, fiel
         if (section.kind === "relatedList") {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) relatedList section ` +
                 `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
-                `primitive (fw#2166).`);
+                `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`);
         }
         if (isWriteFormEditSection(section)) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) writeForm section ` +
-                `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`);
+                `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`);
         }
         validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (${context})`, section);
         for (const fieldSpec of sectionFieldSpecs(section)) {
@@ -699,7 +703,7 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups
     // never matches and the navigation silently lands without an entityId.
     if (typeof redirect !== "string" && redirect.idFrom !== redirect.idFrom.trim()) {
         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom "${redirect.idFrom}" ` +
-            `has leading/trailing whitespace — it would never match a payload field.`);
+            `has leading/trailing whitespace — it would never match a payload field. Remove the whitespace from idFrom.`);
     }
     validateScreenNavTarget(feature.name, screenId, screenKind, "redirect", redirectTarget, allScreenQns, feature.screens);
     // idFrom only means something to a target that carries a record id; the
@@ -757,10 +761,10 @@ function validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, feat
     const { visibleWhen, fallback } = screen;
     const context = `[Feature ${feature.name}] Screen "${screenId}" (${screen.type})`;
     if (visibleWhen === undefined && fallback !== undefined) {
-        throw new Error(`${context} declares fallback without visibleWhen.`);
+        throw new Error(`${context} declares fallback without visibleWhen. Add visibleWhen or remove fallback.`);
     }
     if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
-        throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
+        throw new Error(`${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`);
     }
     if (fallback !== undefined) {
         validateScreenFallback(feature, screenId, screen.type, fallback, allScreenQns, featureMap);
@@ -771,7 +775,7 @@ function validateScreenFallback(feature, screenId, screenType, fallback, allScre
     validateScreenNavTarget(feature.name, screenId, screenType, "fallback", fallback, allScreenQns, feature.screens);
     const fallbackQn = resolveScreenTargetQn(feature.name, fallback);
     if (fallbackQn === qualifyEntityName(feature.name, "screen", screenId)) {
-        throw new Error(`${context} fallback points at the screen itself.`);
+        throw new Error(`${context} fallback points at the screen itself. Point fallback at a different screen.`);
     }
     // A gated fallback could hide in turn and chain or cycle (A→B→A); one hop keeps the
     // runtime gate trivially terminating.
@@ -835,7 +839,7 @@ function validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns
     for (const carryField of confirm.carry) {
         if (typeof carryField !== "string" || carryField.trim() === "") {
             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) has an empty or non-string ` +
-                `entry in "carry".`);
+                `entry in "carry". Use non-empty strings in carry.`);
         }
         if (fieldNames.has(carryField)) {
             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${context}) carry field "${carryField}" ` +
@@ -914,7 +918,7 @@ function validateScreenHasNavArea(feature, screenId, screen, featureMap) {
 function validateRelatedListSection(args) {
     const { featureName, featureMap, where, section } = args;
     if (!section.query || typeof section.query !== "string") {
-        throw new Error(`[Feature ${featureName}] ${where} has empty or non-string query.`);
+        throw new Error(`[Feature ${featureName}] ${where} has empty or non-string query. Set query to a registered query name.`);
     }
     if (section.entity !== undefined) {
         assertRefTargetRegistered(`[Feature ${featureName}] ${where}`, "entity", section.entity, featureName, featureMap);
@@ -945,23 +949,51 @@ function validateRelatedListSection(args) {
         validateRelatedListToolbarActions(args, section.toolbarActions);
     }
 }
+// An empty list has no row, so params resolve against an empty record.
+function rejectEmptyStateActionParams(ctx, actionLabel, action) {
+    const params = action.kind === "navigate" || action.kind === "drawer" ? action.params : undefined;
+    if (params !== undefined) {
+        throw new Error(`[Feature ${ctx.featureName}] ${ctx.where} ${actionLabel} "${action.id}" sets params — an empty list ` +
+            `has no row to read them from, so they would resolve against an empty record. Remove the params.`);
+    }
+}
+// Target checks shared by list/related-list rowActions and emptyState.action:
+// navigate target + params, drawer target, write-handler registration.
+function validateListActionTargets(ctx, actionLabel, action) {
+    const { featureName, screenId, screenType } = ctx;
+    rejectRedirectOnListRowAction(featureName, screenId, screenType, action);
+    if (actionLabel === "emptyState action")
+        rejectEmptyStateActionParams(ctx, actionLabel, action);
+    if (action.kind === "navigate") {
+        const target = resolveRowActionNavigateTarget(featureName, screenId, screenType, actionLabel, action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+        validateRowActionNavigateParams(featureName, screenId, screenType, ctx.screenEntity, action, target, actionLabel);
+    }
+    else if (action.kind === "drawer") {
+        validateDrawerTargetAction(featureName, screenId, screenType, actionLabel, action, ctx.screens);
+    }
+    else if (!ctx.allWriteHandlerQns.has(action.handler)) {
+        throw new Error(`[Feature ${featureName}] ${ctx.where} ` +
+            `${actionLabel} "${action.id}" handler "${action.handler}" ` +
+            `is not a registered write-handler. Check the QN spelling (expected ` +
+            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+    }
+}
 function validateRelatedListRowActions(args, rowActions) {
     const { featureName, screenId, screenType, where, section, screens, allWriteHandlerQns, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
     for (const action of rowActions) {
-        rejectRedirectOnListRowAction(featureName, screenId, screenType, action);
-        if (action.kind === "navigate") {
-            const target = resolveRowActionNavigateTarget(featureName, screenId, screenType, "rowAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
-            validateRowActionNavigateParams(featureName, screenId, screenType, undefined, action, target);
-        }
-        else if (action.kind === "drawer") {
-            validateDrawerTargetAction(featureName, screenId, screenType, "rowAction", action, screens);
-        }
-        else if (!allWriteHandlerQns.has(action.handler)) {
-            throw new Error(`[Feature ${featureName}] ${where} ` +
-                `rowAction "${action.id}" handler "${action.handler}" ` +
-                `is not a registered write-handler. Check the QN spelling (expected ` +
-                `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
-        }
+        validateListActionTargets({
+            featureName,
+            screenId,
+            screenType,
+            screenEntity: undefined,
+            where,
+            screens,
+            allWriteHandlerQns,
+            allScreenQns,
+            navTargetShortIds,
+            screensByShortId,
+            detailForScreens,
+        }, "rowAction", action);
     }
     // section.rowClick (legacy, navigate-only) and a rowActions entry
     // marked rowClick:true both claim the row-body click — same
@@ -981,7 +1013,7 @@ function validateRelatedListDefaultSort(args, defaultSort) {
     const col = section.columns.find((c) => normalizeListColumn(c).field === sortField);
     if (col === undefined) {
         throw new Error(`[Feature ${featureName}] ${where} ` +
-            `defaultSort.field "${sortField}" is not a listed column.`);
+            `defaultSort.field "${sortField}" is not a listed column. Use a listed column as defaultSort.field.`);
     }
     if (normalizeListColumn(col).sortable !== true) {
         throw new Error(`[Feature ${featureName}] ${where} ` +
@@ -1031,7 +1063,16 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
         if ((screen.type === "entityList" || screen.type === "projectionList") &&
             screen.emptyState?.action !== undefined) {
             validateActionHasIcon(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action);
-            validateNavigateActionTab(feature.name, screenId, screen.type, "emptyState action", screen.emptyState.action, navigateLookups);
+            validateListActionTargets({
+                featureName: feature.name,
+                screenId,
+                screenType: screen.type,
+                screenEntity: undefined,
+                where: `Screen "${screenId}" (${screen.type})`,
+                screens: feature.screens,
+                allWriteHandlerQns,
+                ...navigateLookups,
+            }, "emptyState action", screen.emptyState.action);
         }
         // Output of buildAppSchema, which overwrites it — an authored value would be a silent no-op.
         if ((screen.type === "entityEdit" ||
@@ -1062,7 +1103,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // Column-Felder können nicht gegen eine Entity gecheckt werden; sie
             // werden zur Render-Zeit gegen die Projection-Rows aufgelöst).
             if (!screen.query || typeof screen.query !== "string") {
-                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) has empty or non-string query.`);
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) has empty or non-string query. Set query to a registered query name.`);
             }
             if (screen.columns.length === 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) has an empty columns list — ` +
@@ -1084,7 +1125,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 screen.filter.op === "in" &&
                 !Array.isArray(screen.filter.value)) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) filter.op "in" requires ` +
-                    `filter.value to be a readonly array.`);
+                    `filter.value to be a readonly array. Pass an array as filter.value.`);
             }
             if (screen.facets !== undefined) {
                 validateListFacets(`[Feature ${feature.name}] Screen "${screenId}" (projectionList)`, screen.facets, screen.columns, feature.name, featureMap);
@@ -1122,7 +1163,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             // Columns. Kein Entity-Check möglich — Felder werden render-seitig
             // gegen die Query-Response aufgelöst, nicht gegen eine Entity.
             if (!screen.query || typeof screen.query !== "string") {
-                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query.`);
+                throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query. Set query to a registered query name.`);
             }
             if (screen.singleton === true && screen.idParam !== undefined) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
@@ -1175,7 +1216,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                             if (navigate.tab !== undefined &&
                                 !screen.layout.sections.some((section) => section.id === navigate.tab)) {
                                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
-                                    `navigates to tab "${navigate.tab}", which is not a section id on this screen.`);
+                                    `navigates to tab "${navigate.tab}", which is not a section id on this screen. Navigate to an existing section id or remove navigate.tab.`);
                             }
                         }
                         else {
@@ -1204,14 +1245,14 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             if (Array.isArray(screen.header?.subtitle)) {
                 if (screen.header.subtitleHref !== undefined) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets header.subtitleHref ` +
-                        `together with a multi-part header.subtitle — subtitleHref only works with the string form.`);
+                        `together with a multi-part header.subtitle — subtitleHref only works with the string form. Use a single-field subtitle or remove subtitleHref.`);
                 }
                 const seenPartFields = new Set();
                 for (const part of screen.header.subtitle) {
                     const partField = typeof part === "string" ? part : part.field;
                     if (seenPartFields.has(partField)) {
                         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) header.subtitle ` +
-                            `lists field "${partField}" twice.`);
+                            `lists field "${partField}" twice. List each field once.`);
                     }
                     seenPartFields.add(partField);
                     const navigate = typeof part === "string" ? undefined : part.navigate;
@@ -1243,7 +1284,16 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 }
                 if (section.kind === "relatedList" && section.emptyState?.action !== undefined) {
                     validateActionHasIcon(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" emptyState action`, section.emptyState.action);
-                    validateNavigateActionTab(feature.name, screenId, "projectionDetail", `section "${sectionLabel}" emptyState action`, section.emptyState.action, navigateLookups);
+                    validateListActionTargets({
+                        featureName: feature.name,
+                        screenId,
+                        screenType: "projectionDetail",
+                        screenEntity: undefined,
+                        where: `Screen "${screenId}" (projectionDetail) section "${sectionLabel}"`,
+                        screens: feature.screens,
+                        allWriteHandlerQns,
+                        ...navigateLookups,
+                    }, "emptyState action", section.emptyState.action);
                 }
                 if (isExtensionEditSection(section)) {
                     // projectionDetail is read-only (no composed form submit) — an
@@ -1317,7 +1367,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         if (section.fieldDefs[fieldName] === undefined) {
                             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
                                 `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
-                                `a type declared there.`);
+                                `a type declared there. Add the field to fieldDefs.`);
                         }
                     }
                     if (screen.layout.mode === "wizard") {
@@ -1410,11 +1460,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 if (section.kind === "relatedList") {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) relatedList section ` +
                         `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
-                        `primitive (fw#2166).`);
+                        `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`);
                 }
                 if (isWriteFormEditSection(section)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) writeForm section ` +
-                        `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`);
+                        `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`);
                 }
                 validateFieldsXorGroups(`[Feature ${feature.name}] Screen "${screenId}" (configEdit)`, section);
                 for (const fieldSpec of sectionFieldSpecs(section)) {
@@ -1431,15 +1481,15 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             for (const fname of fieldNames) {
                 const qualified = screen.configKeys[fname];
                 if (qualified === undefined) {
-                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" hat ` +
-                        `keinen Eintrag in configKeys-Map. Jedes deklarierte Field braucht ein Mapping zu ` +
-                        `einem qualifizierten Config-Key (\`<feature>:config:<short>\`).`);
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" has ` +
+                        `no entry in the configKeys map. Every declared field needs a mapping to a ` +
+                        `qualified config key (\`<feature>:config:<short>\`). Add one to configKeys.`);
                 }
                 const configKeyDef = configKeyDefsByQn.get(qualified);
                 if (configKeyDef === undefined) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" → ` +
-                        `Config-Key "${qualified}" ist in keiner Feature-Registry deklariert. Tippfehler? ` +
-                        `Erwartetes Format: "<feature>:config:<short>". Bekannte Keys: ${[...configKeyDefsByQn.keys()].sort().join(", ") || "(keine)"}`);
+                        `Config key "${qualified}" is not declared in any feature registry. Typo? ` +
+                        `Expected format: "<feature>:config:<short>". Known keys: ${[...configKeyDefsByQn.keys()].sort().join(", ") || "(none)"}`);
                 }
                 if (isWriteOnlyField(screen.fields[fname]) && !isEncryptedAtRest(configKeyDef)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" declares writeOnly ` +
@@ -1463,7 +1513,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             for (const revealField of screen.reveal.fields) {
                 if (typeof revealField.field !== "string" || revealField.field.trim() === "") {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (secretMint) has a reveal.fields entry ` +
-                        `with an empty or non-string "field".`);
+                        `with an empty or non-string "field". Set field to a non-empty string.`);
                 }
                 if (revealFieldNames.has(revealField.field)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (secretMint) reveal.fields has a ` +
@@ -1472,7 +1522,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 revealFieldNames.add(revealField.field);
                 if (typeof revealField.label !== "string" || revealField.label.trim() === "") {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (secretMint) reveal.fields entry ` +
-                        `"${revealField.field}" has an empty or non-string "label".`);
+                        `"${revealField.field}" has an empty or non-string "label". Set label to a non-empty string.`);
                 }
             }
             validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns);
@@ -1607,7 +1657,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 }
                 if (screen.filter.op === "in" && !Array.isArray(screen.filter.value)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter.op "in" requires ` +
-                        `filter.value to be a readonly array.`);
+                        `filter.value to be a readonly array. Pass an array as filter.value.`);
                 }
             }
             // Tier 2.7e-1: rowActions pinnen — navigate-target existiert (selbes
@@ -1678,7 +1728,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
                         if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
                             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) toolbarAction "${action.id}" ` +
-                                `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`);
+                                `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`);
                         }
                         if (action.tab !== undefined) {
                             resolveRowActionNavigateTarget(feature.name, screenId, "entityList", "toolbarAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
@@ -1746,11 +1796,11 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 if (section.kind === "relatedList") {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) relatedList section ` +
                         `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
-                        `primitive (fw#2166).`);
+                        `primitive (fw#2166). Move the section to a projectionDetail screen or remove it.`);
                 }
                 if (isWriteFormEditSection(section)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit) writeForm section ` +
-                        `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`);
+                        `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive. Move the section to a projectionDetail screen or remove it.`);
                 }
                 validateFieldsXorGroups(`[Feature ${feature.name}] Screen "${screenId}" (entityEdit)`, section);
                 for (const fieldSpec of sectionFieldSpecs(section)) {
@@ -1818,7 +1868,7 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
     const panelIds = new Set();
     const addPanelId = (id, context) => {
         if (panelIds.has(id)) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${id}" (${context}).`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) has duplicate panel id "${id}" (${context}). Give each panel a unique id.`);
         }
         panelIds.add(id);
     };
@@ -1847,9 +1897,9 @@ function validateDashboardScreen(featureName, screenId, screen, featureMap) {
 function validateDashboardTimeRange(featureName, screenId, timeRange, filterId) {
     const prefix = `[Feature ${featureName}] Screen "${screenId}" (dashboard) timeRange`;
     if (timeRange.id.length === 0)
-        throw new Error(`${prefix} has an empty id.`);
+        throw new Error(`${prefix} has an empty id. Set a non-empty id.`);
     if (timeRange.id === filterId) {
-        throw new Error(`${prefix} id "${timeRange.id}" collides with the filter id — both live in the URL search params.`);
+        throw new Error(`${prefix} id "${timeRange.id}" collides with the filter id — both live in the URL search params. Use an id different from the filter id.`);
     }
     if (timeRange.options.length === 0) {
         throw new Error(`${prefix}.options is empty — declare at least one option.`);
@@ -1857,15 +1907,15 @@ function validateDashboardTimeRange(featureName, screenId, timeRange, filterId)
     const values = new Set();
     for (const option of timeRange.options) {
         if (option.value.length === 0 || option.label.length === 0) {
-            throw new Error(`${prefix} option needs a non-empty value and label.`);
+            throw new Error(`${prefix} option needs a non-empty value and label. Give every option both.`);
         }
         if (values.has(option.value)) {
-            throw new Error(`${prefix}.options has duplicate value "${option.value}".`);
+            throw new Error(`${prefix}.options has duplicate value "${option.value}". Use each option value once.`);
         }
         values.add(option.value);
     }
     if (!values.has(timeRange.default)) {
-        throw new Error(`${prefix}.default "${timeRange.default}" is not among the options (${[...values].join(", ")}).`);
+        throw new Error(`${prefix}.default "${timeRange.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`);
     }
 }
 const EMBEDDABLE_SCREEN_TYPES = new Set([
@@ -1901,7 +1951,7 @@ export function validateDashboardScreenPanel(featureName, screenId, panel, featu
 }
 function validateDashboardPanelVisibleWhen(context, visibleWhen) {
     if (visibleWhen !== undefined && (visibleWhen.query === "" || visibleWhen.field === "")) {
-        throw new Error(`${context} visibleWhen needs a non-empty query and field.`);
+        throw new Error(`${context} visibleWhen needs a non-empty query and field. Set both visibleWhen.query and visibleWhen.field.`);
     }
 }
 function validateDashboardPanelSpan(featureName, screenId, panel) {
@@ -1912,10 +1962,10 @@ function validateDashboardPanelSpan(featureName, screenId, panel) {
 function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelId) {
     const context = `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}"`;
     if (panel.stats.length === 0) {
-        throw new Error(`${context} has an empty stats list.`);
+        throw new Error(`${context} has an empty stats list. Add at least one stat.`);
     }
     if (panel.subtitle !== undefined && panel.label === undefined) {
-        throw new Error(`${context} sets subtitle without label — an unlabeled group renders as a KPI strip without a header.`);
+        throw new Error(`${context} sets subtitle without label — an unlabeled group renders as a KPI strip without a header. Set a label or remove subtitle.`);
     }
     validateDashboardPanelSpan(featureName, screenId, panel);
     validateDashboardPanelVisibleWhen(context, panel.visibleWhen);
@@ -1925,22 +1975,27 @@ function validateDashboardStatGroupPanel(featureName, screenId, panel, addPanelI
             throw new Error(`${context} child "${stat.id}" sets visibleWhen — gate the whole group instead; a hidden cell would leave a gap in the strip.`);
         }
         if (!stat.query || typeof stat.query !== "string") {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty or non-string query.`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty or non-string query. Set query to a registered query name.`);
         }
         if (stat.valueField.length === 0) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField.`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}" has empty valueField. Set valueField to a field of the query result.`);
         }
         validateDashboardValueFormat(featureName, screenId, stat.id, stat.valueFormat);
     }
 }
+function validateFromTodayWindowReach(where, panel) {
+    if (panel.initialWindow === "from-today" && panel.ranges === undefined && panel.brush !== true) {
+        throw new Error(`${where}.initialWindow "from-today" needs ranges or brush, otherwise data before today is unreachable.`);
+    }
+}
 function validateDashboardChartDisplay(featureName, screenId, panel) {
     validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
     const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) chart-panel "${panel.id}"`;
     if (panel.scrollable !== undefined && typeof panel.scrollable !== "boolean") {
-        throw new Error(`${where} has a non-boolean scrollable.`);
+        throw new Error(`${where} has a non-boolean scrollable. Use true or false.`);
     }
     if (panel.scrollable === true && panel.chart !== "stacked-area") {
-        throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it.`);
+        throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it. Remove scrollable or use chart "stacked-area".`);
     }
     validateStackedAreaOnlyProps(where, panel);
     validateStackedAreaEnumProp(where, "dateFormat", panel.dateFormat, ["day", "month"]);
@@ -1951,8 +2006,9 @@ function validateDashboardChartDisplay(featureName, screenId, panel) {
     validateStackedAreaEnumProp(where, "markerLegend", panel.markerLegend, ["list", "legend"]);
     const nonBooleanProp = ["brush", "legendTotals", "markerLabels"].find((prop) => panel[prop] !== undefined && typeof panel[prop] !== "boolean");
     if (nonBooleanProp !== undefined) {
-        throw new Error(`${where} has a non-boolean ${nonBooleanProp}.`);
+        throw new Error(`${where} has a non-boolean ${nonBooleanProp}. Use true or false.`);
     }
+    validateFromTodayWindowReach(where, panel);
     for (const [key, color] of Object.entries(panel.seriesColors ?? {})) {
         if (typeof color !== "string" || color.trim() === "") {
             throw new Error(`${where} seriesColors["${key}"] must be a non-empty CSS color.`);
@@ -1987,7 +2043,7 @@ function validateStackedAreaOnlyProps(where, panel) {
         "markerLabels",
     ].filter((prop) => panel[prop] !== undefined);
     if (stackedAreaOnly.length > 0) {
-        throw new Error(`${where} sets ${stackedAreaOnly.join(", ")} on chart "${panel.chart}" — only "stacked-area" supports it.`);
+        throw new Error(`${where} sets ${stackedAreaOnly.join(", ")} on chart "${panel.chart}" — only "stacked-area" supports it. Remove these props or use chart "stacked-area".`);
     }
 }
 const DASHBOARD_CHART_TONES = new Set([
@@ -1998,7 +2054,7 @@ const DASHBOARD_CHART_TONES = new Set([
 ]);
 function validateDashboardChartMarkerKind(where, look) {
     if (look.tone === undefined && look.color === undefined) {
-        throw new Error(`${where} needs a tone or a color.`);
+        throw new Error(`${where} needs a tone or a color. Set tone or color.`);
     }
     if (look.tone !== undefined && !DASHBOARD_CHART_TONES.has(look.tone)) {
         throw new Error(`${where}.tone "${String(look.tone)}" is not one of ${[...DASHBOARD_CHART_TONES].join(", ")}.`);
@@ -2017,10 +2073,10 @@ function validateDashboardChartRanges(where, ranges) {
     const values = new Set();
     for (const option of ranges.options) {
         if (option.value.length === 0 || option.label.length === 0) {
-            throw new Error(`${where} option needs a non-empty value and label.`);
+            throw new Error(`${where} option needs a non-empty value and label. Give every option both.`);
         }
         if (values.has(option.value)) {
-            throw new Error(`${where}.options has duplicate value "${option.value}".`);
+            throw new Error(`${where}.options has duplicate value "${option.value}". Use each option value once.`);
         }
         if (option.months !== undefined && (!Number.isInteger(option.months) || option.months <= 0)) {
             throw new Error(`${where} option "${option.value}" months "${String(option.months)}" must be a positive integer.`);
@@ -2028,7 +2084,7 @@ function validateDashboardChartRanges(where, ranges) {
         values.add(option.value);
     }
     if (!values.has(ranges.default)) {
-        throw new Error(`${where}.default "${ranges.default}" is not among the options (${[...values].join(", ")}).`);
+        throw new Error(`${where}.default "${ranges.default}" is not among the options (${[...values].join(", ")}). Set default to one of the options.`);
     }
 }
 const CURRENCY_CODE_RE = /^[A-Z]{3}$/;
@@ -2038,6 +2094,9 @@ function validateDashboardValueFormat(featureName, screenId, panelId, valueForma
     if (valueFormat === undefined)
         return;
     const where = `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panelId}" valueFormat`;
+    if (valueFormat.kind !== "currency") {
+        throw new Error(`${where}.kind "${String(valueFormat.kind)}" must be "currency".`);
+    }
     if (!CURRENCY_CODE_RE.test(valueFormat.currency)) {
         throw new Error(`${where}.currency "${String(valueFormat.currency)}" must be a 3-letter uppercase ISO currency code.`);
     }
@@ -2055,12 +2114,12 @@ export function validateDashboardCustomPanel(featureName, screenId, panel) {
 }
 function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
     if (!panel.query || typeof panel.query !== "string") {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query.`);
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}" has empty or non-string query. Set query to a registered query name.`);
     }
     validateDashboardPanelSpan(featureName, screenId, panel);
     if (panel.kind === "stat") {
         if (panel.valueField.length === 0) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField.`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-panel "${panel.id}" has empty valueField. Set valueField to a field of the query result.`);
         }
         validateDashboardValueFormat(featureName, screenId, panel.id, panel.valueFormat);
     }
@@ -2069,7 +2128,7 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
         validateDashboardChartDisplay(featureName, screenId, panel);
     if (panel.kind === "list") {
         if (panel.columns.length === 0) {
-            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list.`);
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) list-panel "${panel.id}" has an empty columns list. Add at least one column.`);
         }
         for (const col of panel.columns) {
             const normalized = normalizeListColumn(col);
@@ -2082,10 +2141,10 @@ function validateDashboardQueryPanel(featureName, screenId, panel, featureMap) {
 }
 function validateDashboardFilterDefinition(featureName, screenId, filter) {
     if (filter.id.length === 0) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty id.`);
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty id. Set a non-empty id.`);
     }
     if (filter.label.length === 0) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty label.`);
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter has an empty label. Set a non-empty label.`);
     }
     const hasOptions = filter.options !== undefined;
     const hasOptionsQuery = filter.optionsQuery !== undefined;
@@ -2098,7 +2157,7 @@ function validateDashboardFilterDefinition(featureName, screenId, filter) {
             `declare at least one option or use optionsQuery instead.`);
     }
     if (hasOptionsQuery && filter.optionsQuery?.length === 0) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty.`);
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty. Set optionsQuery to a query name or remove it.`);
     }
 }
 // Form-check für ListColumn-Renderer in der PlatformComponent-Form
@@ -2119,7 +2178,7 @@ function rejectInertColumnSortable(featureName, screenId, screenType, column) {
         ? "set sortable: true on the entity field instead"
         : "sorting is derived from the query's Zod schema; only sortable: false is honored";
     throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) column "${column.field}" sets sortable — ` +
-        `it is ignored here; ${source}.`);
+        `it is ignored here; ${source}. Remove sortable from this column.`);
 }
 export function validateColumnRendererForm(featureName, screenId, column) {
     const renderer = column.renderer;
@@ -2190,7 +2249,7 @@ function validateListFacets(prefix, facets, columns, currentFeatureName, feature
     const seenFacetFields = new Set();
     for (const facet of facets) {
         if (seenFacetFields.has(facet.field)) {
-            throw new Error(`${prefix} declares facet "${facet.field}" more than once.`);
+            throw new Error(`${prefix} declares facet "${facet.field}" more than once. Declare each facet field once.`);
         }
         seenFacetFields.add(facet.field);
         if (facet.type !== "reference" && !columnFieldNames.has(facet.field)) {