@qingflow-tech/qingflow-app-builder-mcp 1.0.39 → 1.0.40

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.39
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.40
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.39 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.40 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.39"
+version = "1.0.40"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -36,15 +36,15 @@ Default modeling rules:
 
 Before any builder write, classify the request:
 
-- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
 - **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
 - **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
 
-For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide.
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
 
 Builder schema inputs should follow agent-intuitive semantics:
 
-- icons may be `icon/color`, `icon_name/icon_color`, `icon_config`, or `icon: {name, color}`
+- primary icon syntax is `icon + color`, for example `icon: "table", color: "blue"`; `icon_name/icon_color`, `icon_config`, and `icon: {name, color}` are compatibility aliases only
 - `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
 - relation fields need a target plus `display_field` and `visible_fields`
 - do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
@@ -67,7 +67,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_get(package_id=...)` to read one known package
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
-  - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - use one `app_schema_apply(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
   - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
@@ -127,7 +128,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
 2. Confirm whether the task is read-only or write-impacting
 3. Classify the build scope:
-   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(apps=[...])`
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(package_id=..., apps=[...])`
    - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
    - record/task/data request -> leave builder and use the matching record/task skill
 4. Resolve the smallest stable target:

package/skills/qingflow-app-builder/references/create-app.md

@@ -6,7 +6,7 @@ This playbook follows the current public builder surface, not legacy package hel
 Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
 
 1. read or create the package through `package_get` / `package_apply`
-2. create the related apps in one `app_schema_apply(apps=[...])` call
+2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
 4. add same-call relation fields with `target_app_ref` when one new app references another new app
 5. choose explicit non-template `icon + color` for each new package/app
@@ -38,7 +38,7 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
 3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
 ## Example
@@ -54,7 +54,8 @@ Create a new package only after the user confirms package creation:
     "profile": "default",
     "package_name": "研发项目管理",
     "create_if_missing": true,
-    "icon": {"name": "briefcase", "color": "azure"}
+    "icon": "briefcase",
+    "color": "azure"
   }
 }
 ```
@@ -80,7 +81,8 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
-    "icon": {"name": "delivery-box-1", "color": "emerald"},
+    "icon": "delivery-box-1",
+    "color": "emerald",
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
@@ -110,7 +112,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
-        "icon": {"name": "business-personalcard", "color": "emerald"},
+        "icon": "business-personalcard",
+        "color": "emerald",
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
         ]
@@ -118,7 +121,8 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "order",
         "app_name": "订单",
-        "icon": {"name": "delivery-box-1", "color": "blue"},
+        "icon": "delivery-box-1",
+        "color": "blue",
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -21,7 +21,7 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 Use this split consistently:
 
-- Complete system/package: `package_apply` first, then one `app_schema_apply(apps=[...])`.
+- Complete system/package: `package_apply` first, then one `app_schema_apply(package_id=..., apps=[...])`.
 - Single app: `app_resolve/app_get` first, then app-scoped apply tools.
 - Record/task/data operation: leave builder and use record/task skills.
 
@@ -103,4 +103,4 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
-- Do not force agent-authored schema into backend-internal names when public aliases exist: icons may use `icon_config` / `icon:{name,color}`, options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.
+- Do not force agent-authored schema into backend-internal names when public keys exist: write icons as `icon + color` first; `icon_config` / `icon:{name,color}` are compatibility aliases only. Options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

package/src/qingflow_mcp/cli/commands/builder.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import argparse
+from copy import deepcopy
 
 from ..context import CliContext
-from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 from ..json_io import load_json_value
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -479,6 +480,7 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     apps_payload = _load_apps_file_arg(args.apps_file)
     apps = apps_payload["apps"]
+    apps_warnings = apps_payload.get("warnings") or []
     package_id = args.package_id
     if package_id is None and apps_payload.get("package_id") is not None:
         package_id = int(apps_payload["package_id"])
@@ -487,6 +489,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
                 fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
+                error_code="APPS_FILE_EMPTY",
             )
         if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
@@ -498,7 +501,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 "schema apply multi-app mode requires --package-id.",
                 fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
             )
-        return context.builder.app_schema_apply(
+        result = context.builder.app_schema_apply(
             profile=args.profile,
             package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -509,6 +512,11 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             update_fields=[],
             remove_fields=[],
         )
+        if apps_warnings and isinstance(result, dict):
+            result_warnings = list(result.get("warnings") or [])
+            result_warnings.extend(deepcopy(apps_warnings))
+            result["warnings"] = result_warnings
+        return result
     has_app_key = bool((args.app_key or "").strip())
     has_app_name = bool((args.app_name or "").strip())
     has_app_title = bool((args.app_title or "").strip())
@@ -545,8 +553,56 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
 def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     if not path:
         return {"apps": []}
+    expected_shape = {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [],
+            }
+        ],
+    }
+    expected_shape_details = {
+        "expected_shape": expected_shape,
+        "expected_shape_json": (
+            '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+            '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
+        ),
+    }
     payload = load_json_value(path, option_name="--apps-file")
     if isinstance(payload, list):
+        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
+            wrapper = payload[0]
+            apps = wrapper.get("apps")
+            if not isinstance(apps, list):
+                raise_config_error(
+                    "--apps-file wrapper object requires an apps array.",
+                    fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw apps array like [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}].",
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    details=expected_shape_details,
+                )
+            result: dict[str, object] = {
+                "apps": apps,
+                "warnings": [
+                    {
+                        "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                        "message": "--apps-file was a singleton wrapper array; normalized it to {package_id, apps}.",
+                    }
+                ],
+            }
+            if wrapper.get("package_id") is not None:
+                result["package_id"] = wrapper.get("package_id")
+            return result
+        if any(isinstance(item, dict) and "apps" in item for item in payload):
+            raise_config_error(
+                "--apps-file root array items must be app items, not package wrapper objects.",
+                fix_hint="Use one object {\"package_id\":1001,\"apps\":[...]} or a raw app array [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}]. Do not wrap multiple {package_id, apps} objects in an array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
+            )
         return {"apps": payload}
     if isinstance(payload, dict):
         apps = payload.get("apps")
@@ -554,6 +610,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             raise_config_error(
                 "--apps-file JSON object requires an apps array.",
                 fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
             )
         result: dict[str, object] = {"apps": apps}
         if payload.get("package_id") is not None:
@@ -562,6 +620,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     raise_config_error(
         "--apps-file must be a JSON array or an object containing apps.",
         fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
+        error_code="APPS_FILE_SHAPE_INVALID",
+        details=expected_shape_details,
     )
 
 

package/src/qingflow_mcp/cli/commands/common.py

@@ -48,14 +48,23 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
     raise QingflowApiError.config_error(f"{label} is required")
 
 
-def raise_config_error(message: str, *, fix_hint: str) -> None:
+def raise_config_error(
+    message: str,
+    *,
+    fix_hint: str | None = None,
+    error_code: str = "CONFIG_ERROR",
+    details: dict[str, Any] | None = None,
+) -> None:
+    error_details: dict[str, Any] = {"fix_hint": fix_hint or message}
+    if details:
+        error_details.update(details)
     raise RuntimeError(
         json.dumps(
             {
                 "category": "config",
                 "message": message,
-                "error_code": "CONFIG_ERROR",
-                "details": {"fix_hint": fix_hint},
+                "error_code": error_code,
+                "details": error_details,
             },
             ensure_ascii=False,
         )

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -383,7 +383,7 @@ class AiBuilderTools(ToolBase):
             remove_fields: list[JSONObject] | None = None,
             apps: list[JSONObject] | None = None,
         ) -> JSONObject:
-            if apps:
+            if apps is not None:
                 if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
@@ -1718,8 +1718,18 @@ class AiBuilderTools(ToolBase):
             icon_color=icon_color,
             icon_config=icon_config,
         )
-        if apps:
-            apps = [_normalize_schema_app_item(item) if isinstance(item, dict) else item for item in apps]
+        if apps is not None:
+            normalized_apps_payload = _normalize_schema_apps_argument(
+                tool_name="app_schema_apply",
+                package_id=package_id,
+                apps=apps,
+            )
+            failure = normalized_apps_payload.get("failure")
+            if isinstance(failure, dict):
+                return _attach_builder_apply_envelope("app_schema_apply", failure)
+            package_id = normalized_apps_payload.get("package_id")  # type: ignore[assignment]
+            apps = normalized_apps_payload.get("apps")  # type: ignore[assignment]
+            input_warnings = list(normalized_apps_payload.get("warnings") or [])
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -1728,6 +1738,10 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 apps=apps,
             )
+            if input_warnings:
+                result_warnings = list(result.get("warnings") or [])
+                result_warnings.extend(deepcopy(input_warnings))
+                result["warnings"] = result_warnings
             return _attach_builder_apply_envelope("app_schema_apply", result)
         result = self._app_schema_apply_once(
             profile=profile,
@@ -1803,9 +1817,13 @@ class AiBuilderTools(ToolBase):
         if not apps:
             return _config_failure(
                 tool_name="app_schema_apply",
+                error_code="APPS_FILE_EMPTY",
                 message="app_schema_apply multi-app mode requires non-empty apps.",
                 fix_hint="Pass apps as a non-empty list of app schema items.",
             )
+        shape_failure = _schema_apps_shape_failure(tool_name="app_schema_apply", apps=apps)
+        if shape_failure is not None:
+            return shape_failure
         icon_errors: list[JSONObject] = []
         seen_new_app_icons: dict[str, int] = {}
         for index, raw_item in enumerate(apps):
@@ -2932,6 +2950,109 @@ def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
     return normalized
 
 
+def _schema_apps_expected_shape() -> JSONObject:
+    return {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [{"name": "员工名称", "type": "text", "as_data_title": True}],
+            }
+        ],
+    }
+
+
+def _schema_apps_expected_shape_json() -> str:
+    return (
+        '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+        '"icon":"business-personalcard","color":"emerald","add_fields":[{"name":"员工名称","type":"text","as_data_title":true}]}]}'
+    )
+
+
+def _is_schema_apps_wrapper_item(item: object) -> bool:
+    return isinstance(item, dict) and "apps" in item
+
+
+def _schema_apps_shape_failure(*, tool_name: str, apps: list[JSONObject]) -> JSONObject | None:
+    for index, item in enumerate(apps):
+        if _is_schema_apps_wrapper_item(item):
+            return _config_failure(
+                tool_name=tool_name,
+                error_code="APPS_FILE_SHAPE_INVALID",
+                message="apps[] items must be app schema items, not package wrapper objects.",
+                fix_hint=(
+                    "For MCP pass package_id separately and apps=[{app_name, icon, color, add_fields}]. "
+                    'For CLI use --apps-file with {"package_id":1001,"apps":[...]}. '
+                    "Do not pass multiple {package_id, apps} wrapper objects inside apps[]."
+                ),
+                details={
+                    "index": index,
+                    "row_number": index + 1,
+                    "expected_shape": _schema_apps_expected_shape(),
+                    "expected_shape_json": _schema_apps_expected_shape_json(),
+                },
+            )
+    return None
+
+
+def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, apps: list[JSONObject]) -> JSONObject:
+    normalized_package_id = package_id
+    normalized_apps: list[JSONObject] = apps
+    warnings: list[JSONObject] = []
+
+    if len(apps) == 1 and _is_schema_apps_wrapper_item(apps[0]):
+        wrapper = apps[0]
+        wrapper_apps = wrapper.get("apps")
+        if not isinstance(wrapper_apps, list):
+            return {
+                "failure": _config_failure(
+                    tool_name=tool_name,
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    message="apps singleton wrapper requires an apps array.",
+                    fix_hint='Use {"package_id":1001,"apps":[...]} in CLI, or pass MCP package_id=1001 and apps=[...].',
+                    details={
+                        "expected_shape": _schema_apps_expected_shape(),
+                        "expected_shape_json": _schema_apps_expected_shape_json(),
+                    },
+                )
+            }
+        if normalized_package_id is None and wrapper.get("package_id") is not None:
+            try:
+                normalized_package_id = int(wrapper.get("package_id"))
+            except (TypeError, ValueError):
+                return {
+                    "failure": _config_failure(
+                        tool_name=tool_name,
+                        error_code="APPS_FILE_SHAPE_INVALID",
+                        message="apps singleton wrapper package_id must be an integer.",
+                        fix_hint="Pass package_id as a number at the top level.",
+                        details={
+                            "expected_shape": _schema_apps_expected_shape(),
+                            "expected_shape_json": _schema_apps_expected_shape_json(),
+                        },
+                    )
+                }
+        normalized_apps = wrapper_apps
+        warnings.append(
+            {
+                "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                "message": "apps was a singleton wrapper array; normalized it to package_id + apps.",
+            }
+        )
+    else:
+        failure = _schema_apps_shape_failure(tool_name=tool_name, apps=apps)
+        if failure is not None:
+            return {"failure": failure}
+
+    normalized_items: list[JSONObject] = []
+    for item in normalized_apps:
+        normalized_items.append(_normalize_schema_app_item(item) if isinstance(item, dict) else item)
+    return {"package_id": normalized_package_id, "apps": normalized_items, "warnings": warnings}
+
+
 def _compile_multi_app_schema_item_refs(
     item: JSONObject,
     client_key_to_app_key: dict[str, str],
@@ -4438,7 +4559,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
             "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
-            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
+            "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
             "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
@@ -5024,12 +5145,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode: package_id + app_name + create_if_missing=true",
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
             "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
-            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
+            "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
             "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
             "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",