@qingflow-tech/qingflow-app-user-mcp 1.0.10 → 1.0.12

package/src/qingflow_mcp/builder_facade/service.py

@@ -14,13 +14,13 @@ from urllib.parse import quote_plus, unquote_plus
 from uuid import uuid4
 
 from ..backend_client import BackendRequestContext
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error
 from ..json_types import JSONObject
 from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_TYPE
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults
+from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults, workspace_icon_config
 from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import _build_viewgraph_questions, _compact_dict, extract_field_map
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
@@ -374,7 +374,18 @@ class AiBuilderFacade:
         if existing.get("error_code") == "AMBIGUOUS_PACKAGE":
             return existing
         if existing.get("error_code") == "PACKAGE_RESOLVE_FAILED":
-            if existing.get("backend_code") not in {40002, 40027}:
+            existing_details = existing.get("details") if isinstance(existing.get("details"), dict) else {}
+            existing_transport_error = (
+                existing_details.get("transport_error") if isinstance(existing_details.get("transport_error"), dict) else {}
+            )
+            existing_error = QingflowApiError(
+                category=str(existing_transport_error.get("category") or ""),
+                message=str(existing.get("message") or ""),
+                backend_code=existing.get("backend_code"),
+                http_status=existing.get("http_status"),
+                request_id=existing.get("request_id"),
+            )
+            if is_auth_like_error(existing_error) or backend_code_value_int(existing.get("backend_code")) not in {40002, 40027}:
                 return existing
             lookup_permission_blocked = {
                 "backend_code": existing.get("backend_code"),
@@ -468,7 +479,17 @@ class AiBuilderFacade:
         try:
             detail_result = self.packages.package_get(profile=profile, tag_id=effective_package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as error:
-            detail_read_error = _coerce_api_error(error)
+            api_error = _coerce_api_error(error)
+            if _is_optional_builder_lookup_error(api_error):
+                detail_read_error = api_error
+            else:
+                return _failed_from_api_error(
+                    "PACKAGE_GET_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"package_id": effective_package_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": effective_package_id}},
+                )
 
         detail = detail_result.get("result") if isinstance(detail_result, dict) and isinstance(detail_result.get("result"), dict) else {}
         base = base_result.get("result") if isinstance(base_result.get("result"), dict) else {}
@@ -476,14 +497,17 @@ class AiBuilderFacade:
         source = detail if detail else base
         layout_tag_items = _select_package_layout_tag_items(detail=detail, base=base)
         warnings: list[JSONObject] = []
+        if isinstance(detail_result, dict) and isinstance(detail_result.get("warnings"), list):
+            warnings.extend(deepcopy(item) for item in detail_result.get("warnings", []) if isinstance(item, dict))
         if detail_read_error is not None:
             warnings.append(
-                {
-                    "code": "PACKAGE_DETAIL_READ_DEGRADED",
-                    "message": "package_get used baseInfo because the package detail endpoint was not readable",
-                    "backend_code": detail_read_error.backend_code,
-                    "http_status": detail_read_error.http_status,
-                }
+                _warning(
+                    "PACKAGE_DETAIL_READ_DEGRADED",
+                    "package_get used baseInfo because the package detail endpoint was not readable",
+                    backend_code=detail_read_error.backend_code,
+                    http_status=detail_read_error.http_status,
+                    request_id=detail_read_error.request_id,
+                )
             )
         public_items = _public_package_items_from_tag_items(layout_tag_items)
         item_count = summary.get("itemCount")
@@ -624,8 +648,34 @@ class AiBuilderFacade:
             if layout_result.get("status") not in {"success", "partial_success"}:
                 return _apply_permission_outcomes(layout_result, *permission_outcomes)
 
+        write_executed = bool(
+            created
+            or (
+                metadata_requested
+                and isinstance(update_result, dict)
+                and update_result.get("status") in {"success", "partial_success"}
+                and not bool(update_result.get("noop"))
+            )
+            or (
+                items is not None
+                and isinstance(layout_result, dict)
+                and layout_result.get("status") in {"success", "partial_success"}
+                and not bool(layout_result.get("noop"))
+            )
+        )
         verification = self.package_get(profile=profile, package_id=effective_package_id)
         if verification.get("status") != "success":
+            if write_executed:
+                return _apply_permission_outcomes(
+                    _post_write_readback_pending_result(
+                        error_code="PACKAGE_READBACK_PENDING",
+                        message="applied package; final package readback is unavailable",
+                        normalized_args=normalized_args,
+                        details={"package_id": effective_package_id, "verification_result": verification},
+                        suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": effective_package_id}},
+                    ),
+                    *permission_outcomes,
+                )
             return _apply_permission_outcomes(verification, *permission_outcomes)
         expected_visibility = None
         if visibility is not None:
@@ -643,6 +693,11 @@ class AiBuilderFacade:
         layout_verified = True
         if items is not None and layout_result is not None:
             layout_verified = bool(layout_result.get("verified"))
+        layout_error_code = (
+            str(layout_result.get("error_code") or "").strip()
+            if isinstance(layout_result, dict) and layout_result.get("error_code")
+            else None
+        )
         response_verification: JSONObject = {
             "package_exists": True,
             "package_created": created,
@@ -660,21 +715,36 @@ class AiBuilderFacade:
                     if key in update_verification:
                         response_verification[key] = deepcopy(update_verification.get(key))
         response_verified = metadata_verified and layout_verified and response_verification.get("visibility_verified") is not False
+        response_warnings = []
+        if isinstance(layout_result, dict) and isinstance(layout_result.get("warnings"), list):
+            response_warnings.extend(deepcopy(layout_result.get("warnings") or []))
         response: JSONObject = {
             "status": "success" if response_verified else "partial_success",
-            "error_code": None,
+            "error_code": None if response_verified else layout_error_code,
             "recoverable": False,
             "message": "applied package" if response_verified else "applied package with unverified readback",
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
-            "details": {"layout_result": layout_result} if layout_result is not None else {},
+            "details": {
+                **({"layout_result": layout_result} if layout_result is not None else {}),
+                **(
+                    {"layout_write_error": layout_result.get("details", {}).get("write_error")}
+                    if isinstance(layout_result, dict)
+                    and isinstance(layout_result.get("details"), dict)
+                    and isinstance(layout_result.get("details", {}).get("write_error"), dict)
+                    else {}
+                ),
+            },
             "request_id": None,
             "suggested_next_call": None,
             "noop": not (created or metadata_requested or items is not None),
-            "warnings": [],
+            "warnings": response_warnings,
             "verification": response_verification,
             "verified": response_verified,
+            "write_executed": write_executed,
+            "write_succeeded": write_executed,
+            "safe_to_retry": not write_executed,
             **{
                 key: deepcopy(value)
                 for key, value in verification.items()
@@ -719,7 +789,6 @@ class AiBuilderFacade:
         if _coerce_positive_int(tag_id) is None:
             return _failed("TAG_ID_REQUIRED", "tag_id must be positive", normalized_args=normalized_args, suggested_next_call=None)
         try:
-            current = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=True)
             current_base = self.packages.package_get_base(profile=profile, tag_id=tag_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
@@ -730,8 +799,37 @@ class AiBuilderFacade:
                 details={"tag_id": tag_id},
                 suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
             )
-        raw_current = current.get("result") if isinstance(current.get("result"), dict) else {}
+        current: JSONObject | None = None
+        detail_read_error: QingflowApiError | None = None
+        try:
+            current = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _is_optional_builder_lookup_error(api_error):
+                detail_read_error = api_error
+            else:
+                return _failed_from_api_error(
+                    "PACKAGE_UPDATE_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"tag_id": tag_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "tag_id": tag_id}},
+                )
+        raw_current = current.get("result") if isinstance(current, dict) and isinstance(current.get("result"), dict) else {}
         raw_current_base = current_base.get("result") if isinstance(current_base.get("result"), dict) else {}
+        warnings: list[JSONObject] = []
+        if isinstance(current, dict) and isinstance(current.get("warnings"), list):
+            warnings.extend(deepcopy(item) for item in current.get("warnings", []) if isinstance(item, dict))
+        if detail_read_error is not None:
+            warnings.append(
+                _warning(
+                    "PACKAGE_DETAIL_READ_DEGRADED",
+                    "package_update used baseInfo because the package detail endpoint was not readable",
+                    backend_code=detail_read_error.backend_code,
+                    http_status=detail_read_error.http_status,
+                    request_id=detail_read_error.request_id,
+                )
+            )
         current_name = str(raw_current.get("tagName") or raw_current_base.get("tagName") or "").strip() or None
         desired_name = str(package_name or current_name or "").strip() or current_name or "未命名应用包"
         desired_icon = encode_workspace_icon_with_defaults(
@@ -772,7 +870,13 @@ class AiBuilderFacade:
             )
         verification = self.package_get(profile=profile, package_id=tag_id)
         if verification.get("status") != "success":
-            return verification
+            return _post_write_readback_pending_result(
+                error_code="PACKAGE_UPDATE_READBACK_PENDING",
+                message="updated package; package readback is unavailable",
+                normalized_args=normalized_args,
+                details={"tag_id": tag_id, "package_id": tag_id, "verification_result": verification},
+                suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": tag_id}},
+            )
         package_name_verified = str(verification.get("package_name") or "").strip() == desired_name
         package_icon_verified = str(verification.get("icon") or "").strip() == desired_icon
         visibility_verified = _visibility_matches_expected(
@@ -792,7 +896,7 @@ class AiBuilderFacade:
             "request_id": update_result.get("request_id") if isinstance(update_result, dict) else None,
             "suggested_next_call": None if verified else {"tool_name": "package_get", "arguments": {"profile": profile, "package_id": tag_id}},
             "noop": False,
-            "warnings": [],
+            "warnings": warnings,
             "verification": {
                 "package_exists": True,
                 "package_name_verified": package_name_verified,
@@ -800,6 +904,8 @@ class AiBuilderFacade:
                 "visibility_verified": visibility_verified,
             },
             "verified": verified,
+            "write_executed": True,
+            "safe_to_retry": False,
             **{
                 key: deepcopy(value)
                 for key, value in verification.items()
@@ -876,16 +982,25 @@ class AiBuilderFacade:
             "suggested_next_call": None,
             "noop": False,
             "verification": {},
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
-    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+    def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         listed = self.packages.package_list(profile=profile, trial_status=trial_status, include_raw=False)
+        raw_items = listed.get("items") if isinstance(listed.get("items"), list) else []
+        items = [_publicize_package_list_item(item) for item in raw_items if isinstance(item, dict)]
+        normalized_query = str(query or "").strip()
+        if normalized_query:
+            filtered_items = [item for item in items if _package_list_item_matches_query(item, normalized_query)]
+        else:
+            filtered_items = items
         return {
             "status": "success",
             "error_code": None,
             "recoverable": False,
             "message": "listed packages",
-            "normalized_args": {"trial_status": trial_status},
+            "normalized_args": {"trial_status": trial_status, "query": normalized_query},
             "missing_fields": [],
             "allowed_values": {},
             "details": {},
@@ -894,8 +1009,12 @@ class AiBuilderFacade:
             "noop": False,
             "verification": {},
             "trial_status": trial_status,
-            "items": listed.get("items") if isinstance(listed.get("items"), list) else [],
-            "count": listed.get("count") or 0,
+            "query": normalized_query,
+            "items": filtered_items,
+            "count": len(filtered_items),
+            "matched_count": len(filtered_items),
+            "unfiltered_count": len(items),
+            "filter_mode": "local_packages",
             "source_shape": listed.get("source_shape"),
             "retried": bool(listed.get("retried", False)),
         }
@@ -916,6 +1035,14 @@ class AiBuilderFacade:
             current_detail_result = self.packages.package_get(profile=profile, tag_id=package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as detail_error:
             detail_api_error = _coerce_api_error(detail_error)
+            if not _is_optional_builder_lookup_error(detail_api_error):
+                return _failed_from_api_error(
+                    "PACKAGE_LAYOUT_READ_FAILED",
+                    detail_api_error,
+                    normalized_args=normalized_args,
+                    details={"package_id": package_id},
+                    suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
+                )
         try:
             current_base_result = self.packages.package_get_base(profile=profile, tag_id=package_id, include_raw=True)
         except (QingflowApiError, RuntimeError) as base_error:
@@ -996,7 +1123,9 @@ class AiBuilderFacade:
         permission_outcomes: list[PermissionCheckOutcome] = []
         needs_group_create = any(_coerce_positive_int(group.get("group_id")) is None for group in desired_groups)
         needs_group_delete = bool(deleted_group_ids)
-        needs_edit_app = bool(normalized_items)
+        # sortGroupUnderPackage is always called for a layout apply and is guarded by
+        # backend MoveGroupAuth, which maps to package editAppStatus.
+        needs_edit_app = True
         for required_permission in (
             (["add_app"] if needs_group_create else [])
             + (["edit_app"] if needs_edit_app else [])
@@ -1094,13 +1223,47 @@ class AiBuilderFacade:
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 return _apply_permission_outcomes(
-                    _failed_from_api_error(
-                        "PACKAGE_GROUP_DELETE_FAILED",
-                        api_error,
-                        normalized_args=normalized_args,
-                        details={"package_id": package_id, "group_id": group_id},
-                        suggested_next_call=None,
-                    ),
+                    {
+                        "status": "partial_success",
+                        "error_code": "PACKAGE_APPLY_PARTIAL",
+                        "recoverable": True,
+                        "message": "package layout sort was applied, but a later group delete failed",
+                        "normalized_args": normalized_args,
+                        "missing_fields": [],
+                        "allowed_values": {},
+                        "details": {
+                            "package_id": package_id,
+                            "group_id": group_id,
+                            "group_operations": group_operations,
+                            "sort_result": sort_result,
+                            "write_error": {
+                                "message": api_error.message,
+                                "transport_error": _transport_error_payload(api_error),
+                            },
+                        },
+                        "request_id": api_error.request_id,
+                        "backend_code": api_error.backend_code,
+                        "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                        "suggested_next_call": None,
+                        "noop": False,
+                        "warnings": [
+                            _warning(
+                                "PACKAGE_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
+                                "package layout write was partially applied before a later write step failed; do not blindly repeat the same package apply",
+                                **_transport_error_payload(api_error),
+                            )
+                        ],
+                        "verification": {
+                            "layout_applied": True,
+                            "write_incomplete": True,
+                            "metadata_unverified": True,
+                        },
+                        "verified": False,
+                        "package_id": package_id,
+                        "write_executed": True,
+                        "write_succeeded": True,
+                        "safe_to_retry": False,
+                    },
                     *permission_outcomes,
                 )
             group_operations.append({"action": "delete", "group_id": group_id})
@@ -1155,6 +1318,25 @@ class AiBuilderFacade:
                 details={"query": requested},
                 suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
             )
+        if listed.get("status") == "failed" and listed.get("error_code") == "CONTACT_DIRECTORY_PERMISSION_DENIED":
+            return _failed(
+                "CONTACT_DIRECTORY_PERMISSION_DENIED",
+                str(listed.get("message") or "Contact-directory management data is not readable for the current user."),
+                normalized_args=normalized_args,
+                details={
+                    "query": requested,
+                    "permission_boundary": "contact_directory",
+                    "fix_hint": (
+                        "This builder member lookup uses the contact-directory management route. "
+                        "For record member/department field candidates, use record_member_candidates "
+                        "or record_department_candidates instead."
+                    ),
+                },
+                suggested_next_call=None,
+                request_id=listed.get("request_id") if isinstance(listed.get("request_id"), str) else None,
+                backend_code=listed.get("backend_code"),
+                http_status=listed.get("http_status"),
+            )
         items = []
         for item in _extract_directory_items(listed):
             uid = _coerce_positive_int(item.get("uid") or item.get("id"))
@@ -1200,6 +1382,23 @@ class AiBuilderFacade:
                 details={"keyword": requested},
                 suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
             )
+        if listed.get("status") == "failed":
+            permission_boundary = "contact_role" if listed.get("error_code") == "CONTACT_ROLE_PERMISSION_DENIED" else None
+            return _failed(
+                str(listed.get("error_code") or "ROLE_SEARCH_FAILED"),
+                str(listed.get("message") or "role search failed"),
+                normalized_args=normalized_args,
+                details={
+                    "keyword": requested,
+                    "permission_boundary": permission_boundary,
+                },
+                suggested_next_call=None
+                if permission_boundary
+                else {"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
+                backend_code=listed.get("backend_code"),
+                request_id=listed.get("request_id"),
+                http_status=listed.get("http_status"),
+            )
         page = listed.get("page") if isinstance(listed.get("page"), dict) else {}
         raw_items = page.get("list") if isinstance(page.get("list"), list) else []
         items = []
@@ -1272,6 +1471,8 @@ class AiBuilderFacade:
                     "role_id": exact[0]["role_id"],
                     "role_name": exact[0]["role_name"],
                     "role_icon": exact[0].get("role_icon"),
+                    "write_executed": False,
+                    "safe_to_retry": True,
                 }
             if len(exact) > 1:
                 return _failed(
@@ -1332,6 +1533,8 @@ class AiBuilderFacade:
             "role_id": role_id,
             "role_name": requested_name,
             "role_icon": normalized_args["role_icon"],
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
     def _resolve_role_references(
@@ -1362,6 +1565,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches_result = self.role_search(profile=profile, keyword=requested, page_num=1, page_size=50)
+            if matches_result.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "role",
+                        "value": requested,
+                        "error_code": matches_result.get("error_code") or "ROLE_SEARCH_FAILED",
+                        "message": matches_result.get("message"),
+                        "backend_code": matches_result.get("backend_code"),
+                        "request_id": matches_result.get("request_id"),
+                    }
+                )
+                continue
             items = matches_result.get("items", []) if matches_result.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and item.get("role_name") == requested]
             if len(exact) != 1:
@@ -1423,6 +1638,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            if matches.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "member_email",
+                        "value": requested,
+                        "error_code": matches.get("error_code") or "MEMBER_SEARCH_FAILED",
+                        "message": matches.get("message"),
+                        "backend_code": matches.get("backend_code"),
+                        "request_id": matches.get("request_id"),
+                    }
+                )
+                continue
             items = matches.get("items", []) if matches.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and str(item.get("email") or "").strip().lower() == requested.lower()]
             if len(exact) != 1:
@@ -1442,6 +1669,18 @@ class AiBuilderFacade:
             if not requested:
                 continue
             matches = self.member_search(profile=profile, query=requested, page_num=1, page_size=50, contain_disable=False)
+            if matches.get("status") != "success":
+                issues.append(
+                    {
+                        "kind": "member_name",
+                        "value": requested,
+                        "error_code": matches.get("error_code") or "MEMBER_SEARCH_FAILED",
+                        "message": matches.get("message"),
+                        "backend_code": matches.get("backend_code"),
+                        "request_id": matches.get("request_id"),
+                    }
+                )
+                continue
             items = matches.get("items", []) if matches.get("status") == "success" else []
             exact = [item for item in items if isinstance(item, dict) and str(item.get("name") or "").strip() == requested]
             if len(exact) != 1:
@@ -1470,23 +1709,6 @@ class AiBuilderFacade:
         seen_ids: set[int] = set()
         if not dept_ids and not dept_names:
             return {"department_entries": resolved, "issues": issues}
-        listed = self.directory.directory_list_all_departments(
-            profile=profile,
-            parent_dept_id=None,
-            max_depth=20,
-            max_items=5000,
-        )
-        items = _extract_directory_items(listed)
-        by_id: dict[int, dict[str, Any]] = {}
-        by_name: dict[str, list[dict[str, Any]]] = {}
-        for item in items:
-            dept_id = _coerce_positive_int(item.get("deptId") or item.get("id"))
-            if dept_id is None:
-                continue
-            by_id[dept_id] = item
-            dept_name = str(item.get("deptName") or item.get("departName") or item.get("name") or "").strip()
-            if dept_name:
-                by_name.setdefault(dept_name, []).append(item)
 
         def add_department(item: dict[str, Any], *, fallback_name: str | None = None) -> None:
             dept_id = _coerce_positive_int(item.get("deptId") or item.get("id"))
@@ -1506,7 +1728,40 @@ class AiBuilderFacade:
             normalized = _coerce_positive_int(dept_id)
             if normalized is None:
                 continue
-            add_department(by_id.get(normalized) or {"deptId": normalized}, fallback_name=str(normalized))
+            add_department({"deptId": normalized}, fallback_name=str(normalized))
+
+        if not dept_names:
+            return {"department_entries": resolved, "issues": issues}
+
+        listed = self.directory.directory_list_all_departments(
+            profile=profile,
+            parent_dept_id=None,
+            max_depth=20,
+            max_items=5000,
+        )
+        if listed.get("status") == "failed" and listed.get("error_code") == "CONTACT_DIRECTORY_PERMISSION_DENIED":
+            for dept_name in dept_names:
+                requested = str(dept_name or "").strip()
+                if not requested:
+                    continue
+                issues.append(
+                    {
+                        "kind": "department_name",
+                        "value": requested,
+                        "error_code": "CONTACT_DIRECTORY_PERMISSION_DENIED",
+                        "message": "department names require contact-directory lookup; pass dept_ids or grant directory access",
+                        "backend_code": listed.get("backend_code"),
+                        "request_id": listed.get("request_id"),
+                    }
+                )
+            return {"department_entries": resolved, "issues": issues}
+
+        items = _extract_directory_items(listed)
+        by_name: dict[str, list[dict[str, Any]]] = {}
+        for item in items:
+            dept_name = str(item.get("deptName") or item.get("departName") or item.get("name") or "").strip()
+            if dept_name:
+                by_name.setdefault(dept_name, []).append(item)
 
         for dept_name in dept_names:
             requested = str(dept_name or "").strip()
@@ -1573,6 +1828,18 @@ class AiBuilderFacade:
                 page_size=100,
                 simple=True,
             )
+            if listed.get("status") == "failed":
+                issues.append(
+                    {
+                        "kind": "external_member_email",
+                        "value": requested,
+                        "error_code": listed.get("error_code") or "EXTERNAL_MEMBER_SEARCH_FAILED",
+                        "message": listed.get("message"),
+                        "backend_code": listed.get("backend_code"),
+                        "request_id": listed.get("request_id"),
+                    }
+                )
+                continue
             items = _extract_directory_items(listed)
             exact = [
                 item
@@ -1607,6 +1874,9 @@ class AiBuilderFacade:
         elif error_code.endswith("_NOT_FOUND"):
             public_code = "VISIBILITY_SUBJECT_NOT_FOUND"
             message = f"{kind} '{requested_value}' was not found in the visibility directory"
+        elif "PERMISSION_DENIED" in error_code or error_code.endswith("_FAILED"):
+            public_code = "VISIBILITY_SUBJECT_LOOKUP_FAILED"
+            message = f"{kind} '{requested_value}' could not be resolved because the visibility directory lookup failed"
         else:
             public_code = "VISIBILITY_SUBJECT_UNSUPPORTED"
             message = f"{kind} visibility selector is unsupported"
@@ -2022,6 +2292,9 @@ class AiBuilderFacade:
             "tag_id": tag_id,
             "tag_ids_after": tag_ids_after,
             "attached": attached,
+            "write_executed": not already_attached,
+            "write_succeeded": not already_attached or attached,
+            "safe_to_retry": bool(already_attached),
         }
         if verification_error is not None:
             response["details"]["verification_error"] = _transport_error_payload(verification_error)
@@ -2134,6 +2407,8 @@ class AiBuilderFacade:
             "verification": {"released": True},
             "app_key": app_key,
             "released": True,
+            "write_executed": True,
+            "safe_to_retry": False,
         }
 
     def app_resolve(
@@ -2214,11 +2489,20 @@ class AiBuilderFacade:
         if not requested:
             return _failed("APP_NAME_REQUIRED", "app_name or app_key is required", suggested_next_call=None)
         if package_tag_id is not None and package_tag_id > 0:
-            package_matches = self._resolve_app_matches_in_package(
-                profile=profile,
-                app_name=requested,
-                package_tag_id=package_tag_id,
-            )
+            try:
+                package_matches = self._resolve_app_matches_in_package(
+                    profile=profile,
+                    app_name=requested,
+                    package_tag_id=package_tag_id,
+                )
+            except (QingflowApiError, RuntimeError) as exc:
+                api_error = _coerce_api_error(exc)
+                return _failed_from_api_error(
+                    "APP_RESOLVE_FAILED",
+                    api_error,
+                    details={"app_name": requested, "package_tag_id": package_tag_id, "match_scope": "package"},
+                    suggested_next_call=None,
+                )
             if len(package_matches) == 1:
                 match = package_matches[0]
                 return {
@@ -2243,12 +2527,50 @@ class AiBuilderFacade:
                     details={"app_name": requested, "package_tag_id": package_tag_id, "matches": package_matches},
                     suggested_next_call=None,
                 )
+        try:
+            visible_matches = self._resolve_app_matches_in_visible_apps(
+                profile=profile,
+                app_name=requested,
+                package_tag_id=package_tag_id,
+            )
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            return _failed_from_api_error(
+                "APP_RESOLVE_FAILED",
+                api_error,
+                details={"app_name": requested, "package_tag_id": package_tag_id, "match_scope": "visible_apps"},
+                suggested_next_call=None,
+            )
+        if len(visible_matches) == 1:
+            match = visible_matches[0]
+            return {
+                "status": "success",
+                "error_code": None,
+                "recoverable": False,
+                "message": "resolved app",
+                "normalized_args": {"app_name": requested, "package_tag_id": package_tag_id},
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {"match_scope": "visible_apps"},
+                "request_id": None,
+                "suggested_next_call": None,
+                "noop": False,
+                "verification": {},
+                **match,
+            }
+        if len(visible_matches) > 1:
+            return _failed(
+                "AMBIGUOUS_APP",
+                f"multiple apps matched '{requested}'",
+                details={"app_name": requested, "package_tag_id": package_tag_id, "matches": visible_matches},
+                suggested_next_call=None,
+            )
         search_error: QingflowApiError | None = None
         try:
             search = self.apps.app_search(profile=profile, keyword=requested, page_num=1, page_size=200)
         except (QingflowApiError, RuntimeError) as exc:
             api_error = _coerce_api_error(exc)
-            if package_tag_id is None or package_tag_id <= 0 or api_error.backend_code not in {40002, 40027}:
+            if is_auth_like_error(api_error) or package_tag_id is None or package_tag_id <= 0 or backend_code_int(api_error) not in {40002, 40027}:
                 return _failed_from_api_error(
                     "APP_NOT_FOUND" if api_error.http_status == 404 else "APP_RESOLVE_FAILED",
                     api_error,
@@ -2257,6 +2579,7 @@ class AiBuilderFacade:
                 )
             search = {}
             search_error = api_error
+        search_permission_blocked = _search_permission_blocked_from_warnings(search) if isinstance(search, dict) else None
         apps = search.get("apps") if isinstance(search.get("apps"), list) else []
         matches = []
         for item in apps:
@@ -2275,8 +2598,16 @@ class AiBuilderFacade:
             if package_tag_id is not None and package_tag_id > 0:
                 try:
                     base = self.apps.app_get_base(profile=profile, app_key=candidate_key, include_raw=True)
-                except (QingflowApiError, RuntimeError):
-                    continue
+                except (QingflowApiError, RuntimeError) as exc:
+                    api_error = _coerce_api_error(exc)
+                    if _is_optional_builder_lookup_error(api_error):
+                        continue
+                    return _failed_from_api_error(
+                        "APP_RESOLVE_FAILED",
+                        api_error,
+                        details={"app_name": requested, "candidate_app_key": candidate_key, "package_tag_id": package_tag_id},
+                        suggested_next_call=None,
+                    )
                 result = base.get("result") if isinstance(base.get("result"), dict) else {}
                 resolved_tag_ids = _coerce_int_list(result.get("tagIds"))
                 if resolved_tag_ids:
@@ -2290,12 +2621,7 @@ class AiBuilderFacade:
                     "tag_ids": tag_ids,
                 }
             )
-        if not matches and package_tag_id is not None and package_tag_id > 0 and search_error is not None:
-            visible_matches = self._resolve_app_matches_in_visible_apps(
-                profile=profile,
-                app_name=requested,
-                package_tag_id=package_tag_id,
-            )
+        if not matches and search_error is not None:
             if len(visible_matches) == 1:
                 match = visible_matches[0]
                 return {
@@ -2355,6 +2681,14 @@ class AiBuilderFacade:
                         if search_error is not None
                         else {}
                     ),
+                    **(
+                        {
+                            "search_permission_blocked": search_permission_blocked,
+                            "match_scope": "visible_apps_fallback",
+                        }
+                        if search_permission_blocked is not None
+                        else {}
+                    ),
                 },
                 suggested_next_call=None,
             )
@@ -2540,21 +2874,45 @@ class AiBuilderFacade:
         normalized_args = request.model_dump(mode="json")
         app_key = request.app_key
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="edit_app",
-            normalized_args=normalized_args,
-        )
-        if permission_outcome.block is not None:
-            return permission_outcome.block
-        permission_outcomes.append(permission_outcome)
+        button_write_intent = bool(request.upsert_buttons or request.patch_buttons or request.remove_buttons)
+        if button_write_intent:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="edit_app",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
+        if request.view_configs:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
 
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
+        view_config_refs = [
+            binding.button_ref
+            for config in request.view_configs
+            for binding in config.buttons
+        ]
+        needs_button_inventory = button_write_intent or any(
+            _coerce_positive_int(ref) is None for ref in view_config_refs
+        )
         try:
-            existing_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+            existing_buttons = (
+                self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+                if needs_button_inventory
+                else []
+            )
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             return finalize(_failed_from_api_error(
@@ -2785,19 +3143,22 @@ class AiBuilderFacade:
                 )
             )
 
-        edit_version_no, edit_context_error = self._ensure_app_edit_context(
-            profile=profile,
-            app_key=app_key,
-            normalized_args=normalized_args,
-            failure_code="CUSTOM_BUTTON_APPLY_FAILED",
-        )
-        if edit_context_error is not None:
-            return finalize(edit_context_error)
-
+        edit_version_no = None
+        if button_write_intent:
+            edit_version_no, edit_context_error = self._ensure_app_edit_context(
+                profile=profile,
+                app_key=app_key,
+                normalized_args=normalized_args,
+                failure_code="CUSTOM_BUTTON_APPLY_FAILED",
+            )
+            if edit_context_error is not None:
+                return finalize(edit_context_error)
+
         created: list[dict[str, Any]] = []
         updated: list[dict[str, Any]] = []
         removed: list[dict[str, Any]] = []
         failed: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
         client_key_map: dict[str, int] = {}
         write_executed = False
 
@@ -2820,7 +3181,15 @@ class AiBuilderFacade:
                             ]
                             if len(matches) == 1:
                                 button_id = _coerce_positive_int(matches[0].get("button_id"))
-                        except (QingflowApiError, RuntimeError):
+                        except (QingflowApiError, RuntimeError) as error:
+                            readback_errors.append(
+                                {
+                                    "resource": "custom_buttons",
+                                    "phase": "create_id_lookup",
+                                    "index": op["index"],
+                                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                                }
+                            )
                             button_id = None
                     entry = {
                         "index": op["index"],
@@ -2868,13 +3237,29 @@ class AiBuilderFacade:
             try:
                 write_executed = True
                 self.buttons.custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+                delete_readback = self._verify_custom_button_deleted_by_id(profile=profile, app_key=app_key, button_id=button_id)
                 removed.append(
                     {
                         "index": op["index"],
                         "operation": "remove",
-                        "status": "success",
+                        "status": delete_readback.get("status") or "readback_pending",
                         "button_id": button_id,
                         "button_text": selector.button_text or (existing_by_id.get(button_id) or {}).get("button_text"),
+                        "delete_executed": True,
+                        "readback_status": delete_readback.get("readback_status"),
+                        "safe_to_retry_delete": False,
+                        **(
+                            {
+                                "error_code": delete_readback.get("error_code"),
+                                "message": delete_readback.get("message"),
+                                "request_id": delete_readback.get("request_id"),
+                                "backend_code": delete_readback.get("backend_code"),
+                                "http_status": delete_readback.get("http_status"),
+                                "transport_error": delete_readback.get("transport_error"),
+                            }
+                            if delete_readback.get("readback_status") != "deleted"
+                            else {}
+                        ),
                     }
                 )
             except (QingflowApiError, RuntimeError) as error:
@@ -2892,12 +3277,21 @@ class AiBuilderFacade:
                     }
                 )
 
+        needs_button_list_readback = bool(created or updated or (request.view_configs and needs_button_inventory))
         readback_buttons: list[dict[str, Any]] = []
         readback_failed = False
-        try:
-            readback_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            readback_failed = True
+        if needs_button_list_readback:
+            try:
+                readback_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append(
+                    {
+                        "resource": "custom_buttons",
+                        "phase": "final_list",
+                        "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                    }
+                )
+                readback_failed = True
         readback_ids = {
             button_id
             for item in readback_buttons
@@ -2918,10 +3312,12 @@ class AiBuilderFacade:
             for item in removed
             if _coerce_positive_int(item.get("button_id")) is not None
         ]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed)
+        remove_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed)
         verified = (
             not readback_failed
             and all(button_id in readback_ids for button_id in created_ids + updated_ids)
-            and all(button_id not in readback_ids for button_id in removed_ids)
+            and removed_verified
             and not failed
             and all(_coerce_positive_int(item.get("button_id")) is not None for item in created)
         )
@@ -2980,6 +3376,20 @@ class AiBuilderFacade:
                     else "custom button writes all failed or produced no confirmed result; application was not published",
                 )
             )
+        if remove_readback_pending:
+            warnings.append(
+                _warning(
+                    "CUSTOM_BUTTON_DELETE_READBACK_PENDING",
+                    "custom button delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
+        if readback_errors:
+            warnings.append(
+                _warning(
+                    "CUSTOM_BUTTON_READBACK_UNAVAILABLE",
+                    "custom button write was executed but readback is unavailable",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -2995,6 +3405,7 @@ class AiBuilderFacade:
                 "edit_version_no": edit_version_no,
                 "button_ids_by_client_key": client_key_map,
                 "readback_failed": readback_failed,
+                **({"readback_errors": readback_errors} if readback_errors else {}),
                 "compiled_match_rules": {
                     str(index): _summarize_compiled_match_rules(config.get("que_relation") or [])
                     for index, config in compiled_add_data_configs.items()
@@ -3009,7 +3420,9 @@ class AiBuilderFacade:
                 "readback_loaded": not readback_failed,
                 "created_verified": not readback_failed and all(button_id in readback_ids for button_id in created_ids),
                 "updated_verified": not readback_failed and all(button_id in readback_ids for button_id in updated_ids),
-                "removed_verified": not readback_failed and all(button_id not in readback_ids for button_id in removed_ids),
+                "removed_verified": removed_verified,
+                "remove_readback_pending": remove_readback_pending,
+                "removed_readback_results": deepcopy(removed),
                 "view_button_bindings_verified": view_config_verified,
             },
             "verified": verified,
@@ -3026,7 +3439,15 @@ class AiBuilderFacade:
             "write_succeeded": write_succeeded,
             "safe_to_retry": not write_executed,
         }
-        return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=write_succeeded, response=response, edit_version_no=edit_version_no))
+        return finalize(
+            self._append_publish_result(
+                profile=profile,
+                app_key=app_key,
+                publish=bool(write_succeeded and button_write_intent),
+                response=response,
+                edit_version_no=edit_version_no,
+            )
+        )
 
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
@@ -3195,6 +3616,9 @@ class AiBuilderFacade:
                 "verified": False,
                 "app_key": app_key,
                 "button_id": button_id,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
             if _is_permission_restricted_api_error(api_error):
                 response = _apply_permission_outcomes(
@@ -3308,6 +3732,9 @@ class AiBuilderFacade:
                 "verified": False,
                 "app_key": app_key,
                 "button_id": button_id,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
             if _is_permission_restricted_api_error(api_error):
                 response = _apply_permission_outcomes(
@@ -3374,30 +3801,35 @@ class AiBuilderFacade:
             return finalize(edit_context_error)
 
         self.buttons.custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+        delete_readback = self._verify_custom_button_deleted_by_id(profile=profile, app_key=app_key, button_id=button_id)
+        verified = delete_readback.get("readback_status") == "deleted"
         return finalize(
             self._append_publish_result(
                 profile=profile,
                 app_key=app_key,
                 publish=True,
                 response={
-                    "status": "success",
-                    "error_code": None,
-                    "recoverable": False,
-                    "message": "deleted custom button",
+                    "status": "success" if verified else "partial_success",
+                    "error_code": None if verified else delete_readback.get("error_code") or "CUSTOM_BUTTON_DELETE_READBACK_PENDING",
+                    "recoverable": not verified,
+                    "message": "deleted custom button" if verified else "custom button delete completed; readback pending",
                     "normalized_args": normalized_args,
                     "missing_fields": [],
                     "allowed_values": {},
                     "details": {},
-                    "request_id": None,
-                    "suggested_next_call": None,
+                    "request_id": delete_readback.get("request_id"),
+                    "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
                     "noop": False,
-                    "warnings": [],
-                    "verification": {"custom_button_deleted": True},
-                    "verified": True,
+                    "warnings": [] if verified else [_warning("CUSTOM_BUTTON_DELETE_READBACK_PENDING", "custom button delete was sent, but deletion readback is not fully verified")],
+                    "verification": {"custom_button_deleted": verified, "delete_readback": delete_readback},
+                    "verified": verified,
                     "app_key": app_key,
                     "button_id": button_id,
                     "edit_version_no": edit_version_no,
-                    "deleted": True,
+                    "deleted": verified,
+                    "delete_executed": True,
+                    "readback_status": delete_readback.get("readback_status"),
+                    "safe_to_retry_delete": False,
                 },
             )
         )
@@ -3641,15 +4073,32 @@ class AiBuilderFacade:
         normalized_args = request.model_dump(mode="json", exclude_none=True)
         app_key = request.app_key
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="data_manage",
-            normalized_args=normalized_args,
+        resource_write_intent = bool(
+            request.upsert_resources
+            or request.patch_resources
+            or request.remove_associated_item_ids
+            or request.reorder_associated_item_ids
         )
-        if permission_outcome.block is not None:
-            return permission_outcome.block
-        permission_outcomes.append(permission_outcome)
+        if resource_write_intent:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="edit_app",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
+        if request.view_configs:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+            )
+            if permission_outcome.block is not None:
+                return permission_outcome.block
+            permission_outcomes.append(permission_outcome)
 
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
@@ -3912,14 +4361,16 @@ class AiBuilderFacade:
             }
             return finalize(response)
 
-        edit_version_no, edit_context_error = self._ensure_app_edit_context(
-            profile=profile,
-            app_key=app_key,
-            normalized_args=normalized_args,
-            failure_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
-        )
-        if edit_context_error is not None:
-            return finalize(edit_context_error)
+        edit_version_no = None
+        if resource_write_intent:
+            edit_version_no, edit_context_error = self._ensure_app_edit_context(
+                profile=profile,
+                app_key=app_key,
+                normalized_args=normalized_args,
+                failure_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
+            )
+            if edit_context_error is not None:
+                return finalize(edit_context_error)
 
         created: list[dict[str, Any]] = []
         updated: list[dict[str, Any]] = []
@@ -3928,6 +4379,8 @@ class AiBuilderFacade:
         reordered: list[int] = []
         view_config_results: list[dict[str, Any]] = []
         failed: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
+        verification_errors: list[JSONObject] = []
         write_executed = False
 
         for op in upsert_ops:
@@ -3940,20 +4393,33 @@ class AiBuilderFacade:
                         client_key_to_id[str(patch.client_key)] = item_id
                 elif op["operation"] == "create":
                     write_executed = True
-                    self._associated_resource_create(
+                    create_result = self._associated_resource_create(
                         profile=profile,
                         app_key=app_key,
                         patch=patch,
                         match_rules_override=compiled_resource_match_rules.get(int(op["index"])),
                     )
-                    readback_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-                    matches = [
-                        item
-                        for item in readback_resources
-                        if _associated_resource_matches_patch(item, patch)
-                        and _coerce_positive_int(item.get("associated_item_id")) is not None
-                    ]
-                    created_id = _coerce_positive_int(matches[0].get("associated_item_id")) if len(matches) == 1 else None
+                    created_id = _extract_associated_resource_id_from_result(create_result)
+                    try:
+                        readback_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+                        matches = [
+                            item
+                            for item in readback_resources
+                            if _associated_resource_matches_patch(item, patch)
+                            and _coerce_positive_int(item.get("associated_item_id")) is not None
+                        ]
+                        readback_id = _coerce_positive_int(matches[0].get("associated_item_id")) if len(matches) == 1 else None
+                        if readback_id is not None:
+                            created_id = readback_id
+                    except (QingflowApiError, RuntimeError) as error:
+                        readback_errors.append(
+                            {
+                                "resource": "associated_resources",
+                                "phase": "create_id_lookup",
+                                "index": op["index"],
+                                "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                            }
+                        )
                     created.append(_associated_resource_result_entry("create", op["index"], patch, associated_item_id=created_id))
                     if created_id is not None and patch.client_key:
                         client_key_to_id[str(patch.client_key)] = created_id
@@ -3989,7 +4455,16 @@ class AiBuilderFacade:
             try:
                 write_executed = True
                 self._associated_resource_delete(profile=profile, app_key=app_key, associated_item_id=item_id)
-                removed.append({"associated_item_id": item_id, "status": "success"})
+                removed.append(
+                    {
+                        "associated_item_id": item_id,
+                        "operation": "remove",
+                        "status": "readback_pending",
+                        "delete_executed": True,
+                        "readback_status": "unavailable",
+                        "safe_to_retry_delete": False,
+                    }
+                )
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "remove", "associated_item_id": item_id, "status": "failed", "error_code": "ASSOCIATED_RESOURCE_WRITE_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
@@ -4003,10 +4478,17 @@ class AiBuilderFacade:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "reorder", "associated_item_ids": reorder_ids, "status": "failed", "error_code": "ASSOCIATED_RESOURCE_REORDER_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
 
-        try:
-            resources_after = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            resources_after = []
+        resources_after: list[dict[str, Any]] = []
+        resources_after_loaded = False
+        resources_after_readback_failed = False
+        if request.view_configs:
+            try:
+                resources_after = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+                resources_after_loaded = True
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append({"resource": "associated_resources", "phase": "pre_view_config", "transport_error": _transport_error_payload(_coerce_api_error(error))})
+                resources_after = []
+                resources_after_readback_failed = True
 
         for index, view_config in enumerate(request.view_configs):
             resolved_view_config_ids = resolved_associated_item_refs.get(f"view_configs[{index}].associated_item_ids", [])
@@ -4066,7 +4548,15 @@ class AiBuilderFacade:
                             available_resources=refreshed_resources,
                         )
                         verified_config = _associated_resources_config_matches(expected_config, actual_config)
-                except (QingflowApiError, RuntimeError):
+                except (QingflowApiError, RuntimeError) as error:
+                    verification_errors.append(
+                        {
+                            "resource": "view_associated_resources_config",
+                            "phase": "view_config_readback",
+                            "view_key": view_config.view_key,
+                            "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                        }
+                    )
                     actual_config = {}
                     verified_config = False
                 view_config_results.append({"index": index, "view_key": view_config.view_key, "view_name": view_name, "status": "success" if verified_config else "partial_success", "associated_resources_verified": verified_config, "expected": expected_config, "actual": actual_config})
@@ -4074,21 +4564,31 @@ class AiBuilderFacade:
                 api_error = _coerce_api_error(error)
                 failed.append({"operation": "view_config", "index": index, "view_key": view_config.view_key, "view_name": view_name, "status": "failed", "error_code": "VIEW_ASSOCIATED_RESOURCES_WRITE_FAILED", "message": api_error.message, "transport_error": _transport_error_payload(api_error)})
 
-        final_resources: list[dict[str, Any]] = []
-        readback_failed = False
-        try:
-            final_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
-            readback_failed = True
+        final_resources: list[dict[str, Any]] = resources_after if resources_after_loaded else []
+        readback_failed = resources_after_readback_failed
+        if not resources_after_loaded and not resources_after_readback_failed:
+            try:
+                final_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                readback_errors.append({"resource": "associated_resources", "phase": "final_pool", "transport_error": _transport_error_payload(_coerce_api_error(error))})
+                readback_failed = True
         final_by_id = _associated_resource_index(final_resources)
+        if removed:
+            removed = self._verify_associated_resources_deleted_by_pool(
+                deleted_items=removed,
+                resources=final_resources,
+                readback_failed=readback_failed,
+            )
         created_ids = [int(item["associated_item_id"]) for item in created if _coerce_positive_int(item.get("associated_item_id")) is not None]
         updated_ids = [int(item["associated_item_id"]) for item in updated if _coerce_positive_int(item.get("associated_item_id")) is not None]
         unchanged_ids = [int(item["associated_item_id"]) for item in unchanged if _coerce_positive_int(item.get("associated_item_id")) is not None]
         removed_ids = [int(item["associated_item_id"]) for item in removed if _coerce_positive_int(item.get("associated_item_id")) is not None]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed)
+        remove_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed)
         pool_verified = (
             not readback_failed
             and all(item_id in final_by_id for item_id in created_ids + updated_ids + unchanged_ids)
-            and all(item_id not in final_by_id for item_id in removed_ids)
+            and removed_verified
             and not failed
             and all(_coerce_positive_int(item.get("associated_item_id")) is not None for item in created)
         )
@@ -4123,6 +4623,27 @@ class AiBuilderFacade:
                     else "associated resource writes all failed or produced no confirmed result; application was not published",
                 )
             )
+        if remove_readback_pending:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCE_DELETE_READBACK_PENDING",
+                    "associated resource delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
+        if readback_errors:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE",
+                    "associated resource write was executed but readback is unavailable",
+                )
+            )
+        if verification_errors:
+            warnings.append(
+                _warning(
+                    "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE",
+                    "associated resource view config write was executed but verification readback is unavailable",
+                )
+            )
         response = {
             "status": status,
             "error_code": error_code,
@@ -4135,6 +4656,8 @@ class AiBuilderFacade:
                 "edit_version_no": edit_version_no,
                 "associated_item_ids_by_client_key": client_key_to_id,
                 "readback_failed": readback_failed,
+                **({"readback_errors": readback_errors} if readback_errors else {}),
+                **({"verification_errors": verification_errors} if verification_errors else {}),
                 "compiled_match_rules": {
                     str(index): _summarize_compiled_match_rules(rules)
                     for index, rules in compiled_resource_match_rules.items()
@@ -4145,7 +4668,14 @@ class AiBuilderFacade:
             "suggested_next_call": None if verified else {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": False,
             "warnings": warnings,
-            "verification": {"associated_resources_verified": pool_verified, "associated_resource_view_configs_verified": view_configs_verified, "readback_loaded": not readback_failed},
+            "verification": {
+                "associated_resources_verified": pool_verified,
+                "associated_resource_view_configs_verified": view_configs_verified,
+                "readback_loaded": not readback_failed,
+                "removed_verified": removed_verified,
+                "remove_readback_pending": remove_readback_pending,
+                "removed_readback_results": deepcopy(removed),
+            },
             "verified": verified,
             "app_key": app_key,
             "app_name": app_name,
@@ -4163,11 +4693,39 @@ class AiBuilderFacade:
             "safe_to_retry": not write_executed,
             "associated_resources": final_resources,
         }
-        response = self._append_publish_result(profile=profile, app_key=app_key, publish=write_succeeded, response=response, edit_version_no=edit_version_no)
+        response = self._append_publish_result(
+            profile=profile,
+            app_key=app_key,
+            publish=bool(write_succeeded and resource_write_intent),
+            response=response,
+            edit_version_no=edit_version_no,
+        )
         if response.get("published") and view_config_results:
             try:
                 post_publish_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                details = response.get("details") if isinstance(response.get("details"), dict) else {}
+                response["details"] = details
+                post_publish_readback_errors = details.get("readback_errors") if isinstance(details.get("readback_errors"), list) else []
+                post_publish_readback_errors.append(
+                    {
+                        "resource": "associated_resources",
+                        "phase": "post_publish_pool",
+                        "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                    }
+                )
+                details["readback_errors"] = post_publish_readback_errors
+                warnings = response.get("warnings")
+                if not isinstance(warnings, list):
+                    warnings = []
+                    response["warnings"] = warnings
+                if not any(isinstance(warning, dict) and warning.get("code") == "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE" for warning in warnings):
+                    warnings.append(
+                        _warning(
+                            "ASSOCIATED_RESOURCES_READBACK_UNAVAILABLE",
+                            "associated resource write was executed but readback is unavailable",
+                        )
+                    )
                 post_publish_resources = final_resources
             if post_publish_resources:
                 response["associated_resources"] = post_publish_resources
@@ -4185,7 +4743,30 @@ class AiBuilderFacade:
                         config if isinstance(config, dict) else {},
                         available_resources=post_publish_resources,
                     )
-                except (QingflowApiError, RuntimeError):
+                except (QingflowApiError, RuntimeError) as error:
+                    details = response.get("details") if isinstance(response.get("details"), dict) else {}
+                    response["details"] = details
+                    post_publish_verification_errors = details.get("verification_errors") if isinstance(details.get("verification_errors"), list) else []
+                    post_publish_verification_errors.append(
+                        {
+                            "resource": "view_associated_resources_config",
+                            "phase": "post_publish_view_config_readback",
+                            "view_key": view_key,
+                            "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                        }
+                    )
+                    details["verification_errors"] = post_publish_verification_errors
+                    warnings = response.get("warnings")
+                    if not isinstance(warnings, list):
+                        warnings = []
+                        response["warnings"] = warnings
+                    if not any(isinstance(warning, dict) and warning.get("code") == "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE" for warning in warnings):
+                        warnings.append(
+                            _warning(
+                                "ASSOCIATED_RESOURCE_VIEW_CONFIG_VERIFICATION_UNAVAILABLE",
+                                "associated resource view config write was executed but verification readback is unavailable",
+                            )
+                        )
                     continue
                 if _associated_resources_config_matches(expected_config, actual_config):
                     result["status"] = "success"
@@ -4235,11 +4816,14 @@ class AiBuilderFacade:
         *,
         profile: str,
         app_name: str,
-        package_tag_id: int,
+        package_tag_id: int | None,
     ) -> list[JSONObject]:
         try:
             listing = self.apps.app_list(profile=profile, ship_auth=False)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
             return []
         items = listing.get("items") if isinstance(listing.get("items"), list) else []
         matches: list[JSONObject] = []
@@ -4257,7 +4841,7 @@ class AiBuilderFacade:
             tag_id = _coerce_positive_int(item.get("tag_id"))
             if tag_id is not None and tag_id not in tag_ids:
                 tag_ids.append(tag_id)
-            if package_tag_id not in tag_ids:
+            if package_tag_id is not None and package_tag_id > 0 and package_tag_id not in tag_ids:
                 continue
             seen_app_keys.add(candidate_key)
             matches.append({"app_key": candidate_key, "app_name": title, "tag_ids": tag_ids})
@@ -4272,7 +4856,10 @@ class AiBuilderFacade:
     ) -> list[JSONObject]:
         try:
             package_result = self.packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=True)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
             return []
         raw_package = package_result.get("result") if isinstance(package_result.get("result"), dict) else {}
         tag_items = raw_package.get("tagItems") if isinstance(raw_package.get("tagItems"), list) else []
@@ -4311,23 +4898,15 @@ class AiBuilderFacade:
             "tag_ids": _coerce_int_list(base.get("tagIds")),
             "can_edit_app": _coerce_optional_bool(base.get("editItemStatus")),
             "can_manage_data": _coerce_optional_bool(base.get("dataManageStatus")),
+            "can_manage_views": (
+                _coerce_optional_bool(base.get("beingViewManageStatus"))
+                if "beingViewManageStatus" in base
+                else _coerce_optional_bool(base.get("dataManageStatus"))
+            ),
             "can_delete_app": _coerce_optional_bool(base.get("deleteItemStatus")),
             "can_copy_app": _coerce_optional_bool(base.get("copyAppStatus")),
         }
 
-    def _derive_can_edit_app_base(self, *, profile: str, permission_summary: JSONObject) -> bool:
-        if permission_summary.get("can_edit_app") is not True:
-            return False
-        tag_ids = _coerce_int_list(permission_summary.get("tag_ids"))
-        for tag_id in tag_ids:
-            try:
-                package_permission = self._read_package_permission_summary(profile=profile, tag_id=tag_id)
-            except (QingflowApiError, RuntimeError):
-                return False
-            if package_permission.get("can_edit_tag") is not True:
-                return False
-        return True
-
     def _read_portal_permission_summary(self, *, dash_key: str, portal_result: dict[str, Any]) -> JSONObject:
         tag_ids = _coerce_int_list(portal_result.get("tagIds"))
         if not tag_ids:
@@ -4352,42 +4931,45 @@ class AiBuilderFacade:
         app_key: str,
         required_permission: str,
         normalized_args: JSONObject,
+        permission_summary: JSONObject | None = None,
     ) -> PermissionCheckOutcome:
-        try:
-            permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            if _is_permission_restricted_api_error(api_error):
-                return _permission_skip_outcome(
-                    scope="app",
-                    target={"app_key": app_key},
-                    required_permission=required_permission,
-                    transport_error=_transport_error_payload(api_error),
-                )
-            return PermissionCheckOutcome(
-                block=_failed(
-                    "APP_PERMISSION_UNVERIFIED",
-                    "could not confirm current user's builder permissions for this app",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": app_key,
-                        "required_permission": required_permission,
-                        "permission_read_error": {
-                            "message": api_error.message,
-                            "http_status": api_error.http_status,
-                            "backend_code": api_error.backend_code,
-                            "category": api_error.category,
+        if permission_summary is None:
+            try:
+                permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if _is_permission_restricted_api_error(api_error):
+                    return _permission_skip_outcome(
+                        scope="app",
+                        target={"app_key": app_key},
+                        required_permission=required_permission,
+                        transport_error=_transport_error_payload(api_error),
+                    )
+                return PermissionCheckOutcome(
+                    block=_failed(
+                        "APP_PERMISSION_UNVERIFIED",
+                        "could not confirm current user's builder permissions for this app",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "required_permission": required_permission,
+                            "permission_read_error": {
+                                "message": api_error.message,
+                                "http_status": api_error.http_status,
+                                "backend_code": api_error.backend_code,
+                                "category": api_error.category,
+                            },
                         },
-                    },
-                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-                    request_id=api_error.request_id,
-                    backend_code=api_error.backend_code,
-                    http_status=None if api_error.http_status == 404 else api_error.http_status,
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                        request_id=api_error.request_id,
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                    )
                 )
-            )
         permission_key = {
             "edit_app": "can_edit_app",
             "data_manage": "can_manage_data",
+            "view_manage": "can_manage_views",
         }.get(required_permission)
         if permission_key is None:
             return PermissionCheckOutcome()
@@ -4401,12 +4983,15 @@ class AiBuilderFacade:
             )
         if permission_value is not False:
             return PermissionCheckOutcome()
-        error_code = "EDIT_APP_UNAUTHORIZED" if required_permission == "edit_app" else "DATA_MANAGE_UNAUTHORIZED"
-        message = (
-            "current user does not have builder edit-app permission on this app"
-            if required_permission == "edit_app"
-            else "current user does not have data-management permission on this app"
-        )
+        if required_permission == "edit_app":
+            error_code = "EDIT_APP_UNAUTHORIZED"
+            message = "current user does not have builder edit-app permission on this app"
+        elif required_permission == "view_manage":
+            error_code = "VIEW_MANAGE_UNAUTHORIZED"
+            message = "current user does not have view-management permission on this app"
+        else:
+            error_code = "DATA_MANAGE_UNAUTHORIZED"
+            message = "current user does not have data-management permission on this app"
         return PermissionCheckOutcome(
             block=_failed(
                 error_code,
@@ -4569,38 +5154,78 @@ class AiBuilderFacade:
                     details={"app_key": app_key},
                     suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, "app_key": app_key}},
                 )
-        views, views_unavailable = self._load_views_result(
+        views, views_unavailable, views_read_error = self._load_views_result(
             profile=profile,
             app_key=app_key,
             tolerate_404=True,
             tolerate_permission_restricted=True,
+            include_error=True,
         )
         view_summaries = _summarize_views(views)
+        readback_errors: list[JSONObject] = []
         charts_unavailable = False
         try:
             chart_items, _chart_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
             chart_summaries = _summarize_charts(chart_items)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             charts_unavailable = True
             chart_summaries = []
+            readback_errors.append(
+                {
+                    "resource": "charts",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
         associated_resources_unavailable = False
         try:
             associated_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             associated_resources_unavailable = True
             associated_resources = []
+            readback_errors.append(
+                {
+                    "resource": "associated_resources",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
         custom_buttons_unavailable = False
         try:
             custom_buttons = self._load_custom_buttons_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             custom_buttons_unavailable = True
             custom_buttons = []
-        workflow, workflow_unavailable = self._load_workflow_result(
+            readback_errors.append(
+                {
+                    "resource": "custom_buttons",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(_coerce_api_error(error)),
+                }
+            )
+        workflow, workflow_unavailable, workflow_read_error = self._load_workflow_result(
             profile=profile,
             app_key=app_key,
             tolerate_404=True,
             tolerate_permission_restricted=True,
+            include_error=True,
         )
+        if views_read_error is not None:
+            readback_errors.append(
+                {
+                    "resource": "views",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(views_read_error),
+                }
+            )
+        if workflow_read_error is not None:
+            readback_errors.append(
+                {
+                    "resource": "workflow",
+                    "phase": "summary",
+                    "transport_error": _transport_error_payload(workflow_read_error),
+                }
+            )
         verification_hints = _build_verification_hints(
             tag_ids=_coerce_int_list(base_result.get("tagIds")),
             fields=parsed["fields"],
@@ -4634,12 +5259,14 @@ class AiBuilderFacade:
             or base_result.get("name")
             or app_key
         ).strip() or app_key
+        app_icon = str(base_result.get("appIcon") or "").strip() or None
         response = AppReadSummaryResponse(
             app_key=app_key,
             app_name=app_name,
             name=app_name,
             title=app_name,
-            app_icon=str(base_result.get("appIcon") or "").strip() or None,
+            app_icon=app_icon,
+            icon_config=workspace_icon_config(app_icon),
             visibility=_public_visibility_from_member_auth(base_result.get("auth")),
             tag_ids=_coerce_int_list(base_result.get("tagIds")),
             publish_status=base_result.get("appPublishStatus"),
@@ -4666,7 +5293,7 @@ class AiBuilderFacade:
             "normalized_args": {"app_key": app_key},
             "missing_fields": [],
             "allowed_values": {},
-            "details": {},
+            "details": {"readback_errors": readback_errors} if readback_errors else {},
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
@@ -4695,13 +5322,54 @@ class AiBuilderFacade:
             if not result.get("suggested_next_call"):
                 result["suggested_next_call"] = {"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}}
             return result
-        permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        try:
+            permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not _is_permission_restricted_api_error(api_error):
+                raise
+            result["message"] = "read app config summary; editability unverified"
+            result["editability"] = {
+                "can_edit_app_base": None,
+                "can_edit_form": None,
+                "can_edit_flow": None,
+                "can_edit_views": None,
+                "can_edit_charts": None,
+            }
+            details = result.get("details") if isinstance(result.get("details"), dict) else {}
+            permission_read_errors = details.get("permission_read_errors") if isinstance(details.get("permission_read_errors"), list) else []
+            permission_read_errors.append(
+                {
+                    "resource": "app_permission",
+                    "app_key": app_key,
+                    "required_permission": None,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            details["permission_read_errors"] = permission_read_errors
+            details["permission_check_skipped"] = True
+            result["details"] = details
+            warnings = result.get("warnings") if isinstance(result.get("warnings"), list) else []
+            warnings.append(
+                _warning(
+                    "APP_EDITABILITY_UNAVAILABLE",
+                    "could not confirm current user's builder permissions for this app; app summary remains available",
+                    app_key=app_key,
+                    **_transport_error_payload(api_error),
+                )
+            )
+            result["warnings"] = warnings
+            verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+            verification["editability_unavailable"] = True
+            result["verification"] = verification
+            result["verified"] = False
+            return result
         result["message"] = "read app config summary"
         result["editability"] = {
-            "can_edit_app_base": self._derive_can_edit_app_base(profile=profile, permission_summary=permission_summary),
+            "can_edit_app_base": permission_summary.get("can_edit_app"),
             "can_edit_form": permission_summary.get("can_edit_app"),
-            "can_edit_flow": permission_summary.get("can_manage_data"),
-            "can_edit_views": permission_summary.get("can_manage_data"),
+            "can_edit_flow": permission_summary.get("can_edit_app"),
+            "can_edit_views": permission_summary.get("can_manage_views"),
             "can_edit_charts": permission_summary.get("can_manage_data"),
         }
         return result
@@ -4909,6 +5577,8 @@ class AiBuilderFacade:
                     "would_update": bool(update_fields),
                 },
                 "verified": True,
+                "write_executed": False,
+                "safe_to_retry": True,
                 "app_key": app_key,
                 "apply": False,
                 "repair_plan": plans,
@@ -4935,6 +5605,8 @@ class AiBuilderFacade:
                     "applied": False,
                 },
                 "verified": True,
+                "write_executed": False,
+                "safe_to_retry": True,
                 "app_key": app_key,
                 "apply": True,
                 "repair_plan": plans,
@@ -4952,6 +5624,7 @@ class AiBuilderFacade:
         )
         if apply_result.get("status") == "failed":
             return apply_result
+        verification_error: JSONObject | None = None
         try:
             reread = self._load_base_schema_state(profile=profile, app_key=app_key)
             verified_fields = cast(list[dict[str, Any]], reread["parsed"].get("fields") or [])
@@ -4972,17 +5645,36 @@ class AiBuilderFacade:
                     if plan["would_update"]:
                         plan["applied"] = True
                         applied_fields.append(plan["field_name"])
-        except (QingflowApiError, RuntimeError):
-            pass
+        except (QingflowApiError, RuntimeError) as error:
+            verification_error = _transport_error_payload(_coerce_api_error(error))
         apply_result["message"] = "repaired code block fields"
         apply_result["apply"] = True
         apply_result["repair_plan"] = plans
         apply_result["applied_fields"] = applied_fields
+        if verification_error is None:
+            existing_details = apply_result.get("details") if isinstance(apply_result.get("details"), dict) else {}
+            existing_verification_error = existing_details.get("verification_error") if isinstance(existing_details, dict) else None
+            if isinstance(existing_verification_error, dict):
+                verification_error = deepcopy(existing_verification_error)
+        if verification_error is not None:
+            details = apply_result.get("details") if isinstance(apply_result.get("details"), dict) else {}
+            details = deepcopy(details)
+            details["code_block_repair_verification_error"] = verification_error
+            apply_result["details"] = details
+            warnings = apply_result.get("warnings") if isinstance(apply_result.get("warnings"), list) else []
+            apply_result["warnings"] = [
+                *warnings,
+                _warning(
+                    "CODE_BLOCK_REPAIR_VERIFICATION_UNAVAILABLE",
+                    "code block repair write was executed but post-write verification readback is unavailable",
+                ),
+            ]
         apply_result["verification"] = {
             **(apply_result.get("verification") if isinstance(apply_result.get("verification"), dict) else {}),
             "code_block_fields_scanned": len(plans),
             "would_update": bool(update_fields),
             "applied": bool(applied_fields),
+            **({"code_block_repair_verification_unavailable": True} if verification_error is not None else {}),
         }
         return apply_result
 
@@ -5023,10 +5715,43 @@ class AiBuilderFacade:
                 suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
             )
         parsed = state["parsed"]
+        warnings: list[dict[str, Any]] = []
+        field_lookup = _build_public_field_lookup(cast(list[dict[str, Any]], parsed["fields"]))
+        chart_fields: list[dict[str, Any]] = []
+        try:
+            qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
+            chart_fields = _compact_public_chart_fields_read(
+                app_key=app_key,
+                qingbi_fields=[item for item in qingbi_fields if isinstance(item, dict)],
+                field_lookup=field_lookup,
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if is_auth_like_error(api_error) or (
+                backend_code_int(api_error) not in {40002, 40027, 404}
+                and api_error.http_status != 404
+            ):
+                return _failed_from_api_error(
+                    "APP_GET_FIELDS_FAILED",
+                    api_error,
+                    normalized_args={"app_key": app_key},
+                    details={"app_key": app_key, "resource": "qingbi_fields"},
+                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                )
+            warnings.append(
+                _warning(
+                    "QINGBI_FIELDS_READ_FAILED",
+                    "form fields were read, but QingBI chart fields could not be read; chart configuration should use chart_fields when available",
+                    backend_code=api_error.backend_code,
+                    request_id=api_error.request_id,
+                )
+            )
         response = AppFieldsReadResponse(
             app_key=app_key,
             fields=[_compact_public_field_read(field=field, layout=parsed["layout"]) for field in parsed["fields"]],
             field_count=len(parsed["fields"]),
+            chart_fields=chart_fields,
+            chart_field_count=len(chart_fields),
             form_settings=_form_settings_from_schema(state["schema"], parsed["fields"]),
         )
         return {
@@ -5041,7 +5766,7 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "warnings": [],
+            "warnings": warnings,
             "verification": {"app_exists": True},
             "verified": True,
             **response.model_dump(mode="json"),
@@ -5281,13 +6006,23 @@ class AiBuilderFacade:
                 continue
             try:
                 portal_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if not _is_optional_builder_lookup_error(api_error):
+                    return _failed_from_api_error(
+                        "PORTAL_LIST_FAILED",
+                        api_error,
+                        normalized_args={},
+                        details={"dash_key": dash_key, "resource": "portal_detail"},
+                        suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+                    )
                 permission_verified = False
                 warnings.append(
                     _warning(
                         "PORTAL_PERMISSION_READ_UNAVAILABLE",
                         f"builder portal_list skipped `{dash_key}` because portal detail readback was unavailable during permission verification",
                         dash_key=dash_key,
+                        **_transport_error_payload(api_error),
                     )
                 )
                 continue
@@ -5339,8 +6074,10 @@ class AiBuilderFacade:
             sorted_items = self.charts.qingbi_report_list_sorted(profile=profile, app_key=app_key, page_num=1, page_size=500).get("items") or []
             if isinstance(sorted_items, list):
                 return sorted_items, "sorted"
-        except (QingflowApiError, RuntimeError):
-            pass
+        except (QingflowApiError, RuntimeError) as exc:
+            api_error = _coerce_api_error(exc)
+            if not _is_optional_builder_lookup_error(api_error):
+                raise
         fallback_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
         return list(fallback_items) if isinstance(fallback_items, list) else [], "fallback"
 
@@ -5783,6 +6520,7 @@ class AiBuilderFacade:
             if button_id is not None:
                 button_inventory[button_id] = item
         valid_custom_button_ids = (set(button_inventory) | set(created_ids) | set(updated_ids)) - set(removed_ids)
+        allow_unverified_numeric_button_ids = not bool(valid_custom_button_ids)
         write_executed = False
         write_succeeded = False
         all_verified = True
@@ -5834,6 +6572,7 @@ class AiBuilderFacade:
                     button_inventory=button_inventory,
                     valid_custom_button_ids=valid_custom_button_ids,
                     reason_path=f"view_configs[{config_index}].buttons[{button_index}].button_ref",
+                    allow_unverified_numeric_id=allow_unverified_numeric_button_ids,
                 )
                 if ref_issue:
                     config_issues.append(ref_issue)
@@ -5845,6 +6584,7 @@ class AiBuilderFacade:
                     binding=view_binding,
                     current_fields_by_name=current_fields_by_name,
                     valid_custom_button_ids=valid_custom_button_ids,
+                    allow_unverified_custom_button_id=allow_unverified_numeric_button_ids,
                 )
                 if binding_issues:
                     config_issues.extend(binding_issues)
@@ -6034,6 +6774,7 @@ class AiBuilderFacade:
                 details={"dash_key": dash_key, "being_draft": being_draft},
                 suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
             )
+        dash_icon = str(result.get("dashIcon") or "").strip() or None
         response = PortalGetResponse(
             dash_key=dash_key,
             being_draft=being_draft,
@@ -6047,7 +6788,8 @@ class AiBuilderFacade:
                 )
                 if tag_id is not None
             ],
-            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            dash_icon=dash_icon,
+            icon_config=workspace_icon_config(dash_icon),
             hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
             visibility=_public_visibility_from_member_auth(result.get("auth")),
             auth=deepcopy(result.get("auth")) if isinstance(result.get("auth"), dict) else {},
@@ -6086,6 +6828,7 @@ class AiBuilderFacade:
                 details={"dash_key": dash_key, "being_draft": being_draft},
                 suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key, "being_draft": being_draft}},
             )
+        dash_icon = str(result.get("dashIcon") or "").strip() or None
         response = PortalReadSummaryResponse(
             dash_key=dash_key,
             being_draft=being_draft,
@@ -6099,7 +6842,8 @@ class AiBuilderFacade:
                 )
                 if tag_id is not None
             ],
-            dash_icon=str(result.get("dashIcon") or "").strip() or None,
+            dash_icon=dash_icon,
+            icon_config=workspace_icon_config(dash_icon),
             hide_copyright=bool(result.get("hideCopyright")) if "hideCopyright" in result else None,
             config_keys=sorted(str(key) for key in (result.get("config") or {}).keys()) if isinstance(result.get("config"), dict) else [],
             dash_global_config_keys=sorted(str(key) for key in (result.get("dashGlobalConfig") or {}).keys()) if isinstance(result.get("dashGlobalConfig"), dict) else [],
@@ -6138,6 +6882,7 @@ class AiBuilderFacade:
             )
 
         warnings: list[dict[str, Any]] = []
+        readback_errors: list[JSONObject] = []
         verification = {
             "view_exists": True,
             "base_info_verified": True,
@@ -6148,39 +6893,133 @@ class AiBuilderFacade:
 
         base_info: dict[str, Any] = {}
         try:
-            base_info_payload = self.views.view_get_base_info(profile=profile, viewgraph_key=view_key, passcode=None).get("result") or {}
+            base_info_response = self.views.view_get_base_info(profile=profile, viewgraph_key=view_key, passcode=None)
+            base_info_payload = base_info_response.get("result") or {}
             if isinstance(base_info_payload, dict):
                 base_info = deepcopy(base_info_payload)
-        except (QingflowApiError, RuntimeError):
+            base_info_verification = (
+                base_info_response.get("verification")
+                if isinstance(base_info_response.get("verification"), dict)
+                else {}
+            )
+            if base_info_verification.get("base_info_verified") is False:
+                verification["base_info_verified"] = False
+                for warning in base_info_response.get("warnings") or []:
+                    if not isinstance(warning, dict):
+                        continue
+                    warnings.append(deepcopy(warning))
+                    readback_errors.append(
+                        {
+                            "resource": "view_base_info",
+                            "phase": "view_get",
+                            "view_key": view_key,
+                            "transport_error": {
+                                "http_status": warning.get("http_status"),
+                                "backend_code": warning.get("backend_code"),
+                                "category": warning.get("category"),
+                                "request_id": warning.get("request_id"),
+                            },
+                        }
+                    )
+        except (QingflowApiError, RuntimeError) as error:
             verification["base_info_verified"] = False
-            warnings.append(_warning("VIEW_BASE_INFO_UNAVAILABLE", "view base info readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_base_info"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_base_info",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_BASE_INFO_UNAVAILABLE", "view base info readback is unavailable", **_transport_error_payload(api_error)))
 
         questions: list[dict[str, Any]] = []
         try:
             questions_payload = self.views.view_list_questions(profile=profile, viewgraph_key=view_key).get("result") or []
             if isinstance(questions_payload, list):
                 questions = [deepcopy(item) for item in questions_payload if isinstance(item, dict)]
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             verification["questions_verified"] = False
-            warnings.append(_warning("VIEW_QUESTIONS_UNAVAILABLE", "view question list readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_questions"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_questions",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_QUESTIONS_UNAVAILABLE", "view question list readback is unavailable", **_transport_error_payload(api_error)))
 
         associations: list[dict[str, Any]] = []
         try:
             associations_payload = self.views.view_list_associations(profile=profile, viewgraph_key=view_key).get("result") or []
             if isinstance(associations_payload, list):
                 associations = [deepcopy(item) for item in associations_payload if isinstance(item, dict)]
-        except (QingflowApiError, RuntimeError):
+        except (QingflowApiError, RuntimeError) as error:
             verification["associations_verified"] = False
-            warnings.append(_warning("VIEW_ASSOCIATIONS_UNAVAILABLE", "view association list readback is unavailable"))
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error):
+                return _failed_from_api_error(
+                    "VIEW_GET_FAILED",
+                    api_error,
+                    normalized_args={"view_key": view_key},
+                    details={"view_key": view_key, "resource": "view_associations"},
+                    suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                )
+            readback_errors.append(
+                {
+                    "resource": "view_associations",
+                    "phase": "view_get",
+                    "view_key": view_key,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            )
+            warnings.append(_warning("VIEW_ASSOCIATIONS_UNAVAILABLE", "view association list readback is unavailable", **_transport_error_payload(api_error)))
 
         app_key = str(_first_present(config, "appKey", "formKey") or _first_present(base_info, "appKey", "formKey") or "").strip()
         associated_resources: list[dict[str, Any]] = []
         if app_key:
             try:
                 associated_resources = self._load_associated_resources_for_builder(profile=profile, app_key=app_key)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
                 verification["associated_resources_verified"] = False
-                warnings.append(_warning("VIEW_ASSOCIATED_RESOURCES_UNAVAILABLE", "view associated resource pool readback is unavailable"))
+                api_error = _coerce_api_error(error)
+                if not _is_optional_builder_lookup_error(api_error):
+                    return _failed_from_api_error(
+                        "VIEW_GET_FAILED",
+                        api_error,
+                        normalized_args={"view_key": view_key},
+                        details={"view_key": view_key, "app_key": app_key, "resource": "associated_resources"},
+                        suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, "view_key": view_key}},
+                    )
+                readback_errors.append(
+                    {
+                        "resource": "associated_resources",
+                        "phase": "view_get",
+                        "view_key": view_key,
+                        "app_key": app_key,
+                        "transport_error": _transport_error_payload(api_error),
+                    }
+                )
+                warnings.append(_warning("VIEW_ASSOCIATED_RESOURCES_UNAVAILABLE", "view associated resource pool readback is unavailable", **_transport_error_payload(api_error)))
         associated_resources_config = _extract_view_associated_resources_config(
             config if isinstance(config, dict) else {},
             available_resources=associated_resources,
@@ -6213,7 +7052,7 @@ class AiBuilderFacade:
             "normalized_args": {"view_key": view_key},
             "missing_fields": [],
             "allowed_values": {},
-            "details": {},
+            "details": {"readback_errors": readback_errors} if readback_errors else {},
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
@@ -6250,15 +7089,34 @@ class AiBuilderFacade:
             )
 
         try:
-            config = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id).get("result") or {}
+            config_response = self.charts.qingbi_report_get_config(profile=profile, chart_id=chart_id)
+            config = config_response.get("result") or {}
+            config_warnings = config_response.get("warnings") if isinstance(config_response.get("warnings"), list) else []
+            warnings.extend(item for item in config_warnings if isinstance(item, dict))
+            config_verification = (
+                config_response.get("verification") if isinstance(config_response.get("verification"), dict) else {}
+            )
+            if config_verification:
+                verification.update(config_verification)
         except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if not _is_optional_builder_lookup_error(api_error) and backend_code_int(api_error) != 81007:
+                return _failed_from_api_error(
+                    "CHART_GET_FAILED",
+                    api_error,
+                    normalized_args={"chart_id": chart_id},
+                    details={"chart_id": chart_id, "resource": "chart_config"},
+                    suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
+                )
             fallback_config: dict[str, Any] | None = None
+            fallback_api_error: QingflowApiError | None = None
             try:
                 data_fallback = self.charts.qingbi_report_get_data(profile=profile, chart_id=chart_id, payload={}).get("result") or {}
                 config_from_data = data_fallback.get("config") if isinstance(data_fallback, dict) else None
                 if isinstance(config_from_data, dict):
                     fallback_config = deepcopy(config_from_data)
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as fallback_error:
+                fallback_api_error = _coerce_api_error(fallback_error)
                 fallback_config = None
             if isinstance(fallback_config, dict):
                 config = fallback_config
@@ -6269,12 +7127,17 @@ class AiBuilderFacade:
                     )
                 )
             else:
-                api_error = _coerce_api_error(error)
+                details: JSONObject = {
+                    "chart_id": chart_id,
+                    "config_error": _transport_error_payload(api_error),
+                }
+                if fallback_api_error is not None:
+                    details["data_fallback_error"] = _transport_error_payload(fallback_api_error)
                 return _failed_from_api_error(
                     "CHART_GET_FAILED",
                     api_error,
                     normalized_args={"chart_id": chart_id},
-                    details={"chart_id": chart_id},
+                    details=details,
                     suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
                 )
 
@@ -6986,16 +7849,6 @@ class AiBuilderFacade:
             if add_permission_outcome.block is not None:
                 return add_permission_outcome.block
             permission_outcomes.append(add_permission_outcome)
-            if requested_field_changes:
-                edit_permission_outcome = self._guard_package_permission(
-                    profile=profile,
-                    tag_id=permission_tag_id,
-                    required_permission="edit_app",
-                    normalized_args=normalized_args,
-                )
-                if edit_permission_outcome.block is not None:
-                    return edit_permission_outcome.block
-                permission_outcomes.append(edit_permission_outcome)
             resolved = self._create_target_app_shell(
                 profile=profile,
                 app_name=app_name,
@@ -7095,6 +7948,9 @@ class AiBuilderFacade:
                 "created": True,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
                 "tag_ids_after": list(target.tag_ids),
                 "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                 "publish_requested": False,
@@ -7323,7 +8179,34 @@ class AiBuilderFacade:
         )
 
         if not added and not updated and not removed and not normalized_code_block_fields and not data_display_selection.has_any and not bool(resolved.get("created")):
-            base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            try:
+                base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                if bool(visual_result.get("updated")):
+                    return finalize(_post_write_readback_pending_result(
+                        error_code="APP_BASE_READBACK_PENDING",
+                        message="updated app base metadata; app base readback is unavailable",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": target.app_key,
+                            "verification_error": _transport_error_payload(api_error),
+                            "app_name_after": effective_app_name,
+                            "app_base_updated": True,
+                            "field_diff": {"added": [], "updated": [], "removed": []},
+                        },
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": target.app_key}},
+                        request_id=api_error.request_id,
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                    ))
+                return finalize(_failed_from_api_error(
+                    "APP_BASE_READBACK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": target.app_key}, resource="app_base", error=api_error),
+                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": target.app_key}},
+                ))
             tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
             actual_app_name = str(base_info.get("formTitle") or effective_app_name).strip() or effective_app_name
@@ -7361,6 +8244,9 @@ class AiBuilderFacade:
                 "created": False,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": verified,
+                "write_executed": bool(visual_result.get("updated")),
+                "write_succeeded": bool(visual_result.get("updated")),
+                "safe_to_retry": not bool(visual_result.get("updated")),
                 "tag_ids_after": tag_ids_after,
                 "package_attached": package_attached,
             }
@@ -7398,7 +8284,7 @@ class AiBuilderFacade:
             self.apps.app_update_form_schema(profile=profile, app_key=target.app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if api_error.backend_code == 49614:
+            if backend_code_int(api_error) == 49614:
                 return _failed(
                     "MULTIPLE_RELATION_FIELDS_UNSUPPORTED",
                     "backend currently rejects apps with more than one relation field; keep one real relation field and use text/reference summary fields for additional cross-object links.",
@@ -7570,6 +8456,9 @@ class AiBuilderFacade:
                 after_fields=current_fields,
             ),
             "verified": False,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
             "tag_ids_after": [],
             "package_attached": None,
         }
@@ -7675,8 +8564,7 @@ class AiBuilderFacade:
                 response["details"] = details
             details["verification_error"] = {
                 "message": verification_error.message,
-                "http_status": verification_error.http_status,
-                "backend_code": verification_error.backend_code,
+                **_transport_error_payload(verification_error),
             }
         return finalize(response)
 
@@ -7813,6 +8701,9 @@ class AiBuilderFacade:
                     "fallback_applied": None,
                 },
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         payload = _build_form_payload_from_existing_schema(
@@ -7830,7 +8721,7 @@ class AiBuilderFacade:
             self.apps.app_update_form_schema(profile=profile, app_key=app_key, payload=payload)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            if api_error.backend_code == 400 and target_layout.get("sections"):
+            if backend_code_int(api_error) == 400 and target_layout.get("sections"):
                 flattened_layout = _flatten_layout_sections(target_layout)
                 fallback_payload = _build_form_payload_from_existing_schema(
                     current_schema=schema_result,
@@ -7885,12 +8776,22 @@ class AiBuilderFacade:
                 "message": "applied app layout; layout readback pending",
                 "normalized_args": normalized_args,
                 "missing_fields": [],
-                "allowed_values": {"modes": ["merge", "replace"]},
-                "details": {},
-                "request_id": None,
+                "allowed_values": {"modes": ["merge", "replace"]},
+                "details": {"readback_error": _transport_error_payload(api_error)},
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
                 "suggested_next_call": {"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
                 "noop": False,
-                "warnings": [],
+                "warnings": [
+                    _warning(
+                        "READBACK_UNAVAILABLE_AFTER_WRITE",
+                        "write was executed but layout readback is unavailable",
+                        backend_code=api_error.backend_code,
+                        http_status=None if api_error.http_status == 404 else api_error.http_status,
+                        request_id=api_error.request_id,
+                    )
+                ],
                 "verification": {"layout_verified": False, "layout_summary_verified": False, "layout_read_unavailable": True},
                 "app_key": app_key,
                 "app_name": app_name,
@@ -7902,8 +8803,10 @@ class AiBuilderFacade:
                     "fallback_applied": fallback_applied,
                 },
                 "verified": False,
+                "write_executed": True,
+                "write_succeeded": True,
+                "safe_to_retry": False,
             }
-            response["request_id"] = api_error.request_id
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         verified_layout = _parse_schema(verified_schema)["layout"]
         layout_verified = _layouts_equal(verified_layout, applied_layout) or _layouts_semantically_equal(verified_layout, applied_layout)
@@ -7959,6 +8862,9 @@ class AiBuilderFacade:
                 "fallback_applied": fallback_applied,
             },
             "verified": layout_verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -7983,7 +8889,7 @@ class AiBuilderFacade:
         permission_outcome = self._guard_app_permission(
             profile=profile,
             app_key=app_key,
-            required_permission="data_manage",
+            required_permission="edit_app",
             normalized_args=normalized_args,
         )
         if permission_outcome.block is not None:
@@ -8184,6 +9090,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "flow_diff": {"mode": "replace", "node_count": desired_node_count},
             "verified": workflow_verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -8228,15 +9137,57 @@ class AiBuilderFacade:
                 "app_key": app_key,
                 "views_diff": {"created": [], "updated": [], "removed": []},
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
             return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         permission_outcomes: list[PermissionCheckOutcome] = []
-        permission_outcome = self._guard_app_permission(
-            profile=profile,
-            app_key=app_key,
-            required_permission="data_manage",
-            normalized_args=normalized_args,
-        )
+        app_permission_summary: JSONObject | None = None
+        app_permission_error: QingflowApiError | None = None
+        try:
+            app_permission_summary = self._read_app_permission_summary(profile=profile, app_key=app_key)
+        except (QingflowApiError, RuntimeError) as error:
+            app_permission_error = _coerce_api_error(error)
+            app_permission_summary = None
+        if app_permission_error is not None:
+            if _is_permission_restricted_api_error(app_permission_error):
+                permission_outcome = _permission_skip_outcome(
+                    scope="app",
+                    target={"app_key": app_key},
+                    required_permission="view_manage",
+                    transport_error=_transport_error_payload(app_permission_error),
+                )
+            else:
+                permission_outcome = PermissionCheckOutcome(
+                    block=_failed(
+                        "APP_PERMISSION_UNVERIFIED",
+                        "could not confirm current user's builder permissions for this app",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "required_permission": "view_manage",
+                            "permission_read_error": {
+                                "message": app_permission_error.message,
+                                "http_status": app_permission_error.http_status,
+                                "backend_code": app_permission_error.backend_code,
+                                "category": app_permission_error.category,
+                            },
+                        },
+                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                        request_id=app_permission_error.request_id,
+                        backend_code=app_permission_error.backend_code,
+                        http_status=None if app_permission_error.http_status == 404 else app_permission_error.http_status,
+                    )
+                )
+        else:
+            permission_outcome = self._guard_app_permission(
+                profile=profile,
+                app_key=app_key,
+                required_permission="view_manage",
+                normalized_args=normalized_args,
+                permission_summary=app_permission_summary,
+            )
         if permission_outcome.block is not None:
             return permission_outcome.block
         permission_outcomes.append(permission_outcome)
@@ -8269,6 +9220,35 @@ class AiBuilderFacade:
             if name and key:
                 existing_by_key[key] = view
                 existing_by_name.setdefault(name, []).append(view)
+        creating_view_names = [
+            patch.name
+            for patch in upsert_views
+            if not patch.view_key and not existing_by_name.get(patch.name)
+        ]
+        if creating_view_names:
+            if app_permission_error is not None and _is_permission_restricted_api_error(app_permission_error):
+                create_permission_outcome = _permission_skip_outcome(
+                    scope="app",
+                    target={"app_key": app_key},
+                    required_permission="data_manage",
+                    transport_error=_transport_error_payload(app_permission_error),
+                )
+            else:
+                create_permission_outcome = self._guard_app_permission(
+                    profile=profile,
+                    app_key=app_key,
+                    required_permission="data_manage",
+                    normalized_args=normalized_args,
+                    permission_summary=app_permission_summary,
+                )
+            if create_permission_outcome.block is not None:
+                details = create_permission_outcome.block.get("details")
+                if isinstance(details, dict):
+                    details["operation"] = "view_create"
+                    details["view_names"] = creating_view_names
+                    details["also_required_permission"] = "view_manage"
+                return create_permission_outcome.block
+            permission_outcomes.append(create_permission_outcome)
         parsed_schema = _parse_schema(schema)
         field_names = {field["name"] for field in parsed_schema["fields"]}
         if patch_views:
@@ -8343,8 +9323,26 @@ class AiBuilderFacade:
                         being_draft=True,
                         include_raw=False,
                     )
-                except (QingflowApiError, RuntimeError):
-                    continue
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    if _is_optional_builder_lookup_error(api_error):
+                        continue
+                    failed = _failed_from_api_error(
+                        "CUSTOM_BUTTON_DETAIL_READ_FAILED",
+                        api_error,
+                        normalized_args=normalized_args,
+                        details=_with_state_read_blocked_details(
+                            {"app_key": app_key, "button_id": button_id},
+                            resource="custom_button",
+                            error=api_error,
+                        ),
+                        suggested_next_call={
+                            "tool_name": "app_custom_button_get",
+                            "arguments": {"profile": profile, "app_key": app_key, "button_id": button_id},
+                        },
+                    )
+                    failed.update({"write_executed": False, "write_succeeded": False, "safe_to_retry": True})
+                    return finalize(failed)
                 detail_result = detail.get("result")
                 if isinstance(detail_result, dict):
                     custom_button_details_by_id[button_id] = _normalize_custom_button_detail(detail_result)
@@ -8404,13 +9402,56 @@ class AiBuilderFacade:
             if len(matches) == 1:
                 key = _extract_view_key(matches[0])
                 removed_name = _extract_view_name(matches[0]) or selector_text
-                self.views.view_delete(profile=profile, viewgraph_key=key)
-                removed.append(removed_name)
-                if key:
-                    removed_keys.add(key)
-                    existing_by_key.pop(key, None)
-                existing_by_name.pop(removed_name, None)
-                view_results.append({"name": removed_name, "view_key": key, "type": None, "status": "removed"})
+                try:
+                    self.views.view_delete(profile=profile, viewgraph_key=key)
+                    delete_readback = self._verify_view_deleted_by_key(profile=profile, view_key=key)
+                    removed.append(removed_name)
+                    if key:
+                        removed_keys.add(key)
+                        existing_by_key.pop(key, None)
+                    existing_by_name.pop(removed_name, None)
+                    view_results.append(
+                        {
+                            "name": removed_name,
+                            "view_key": key,
+                            "type": None,
+                            "status": delete_readback.get("status") or "readback_pending",
+                            "operation": "delete",
+                            "delete_executed": True,
+                            "readback_status": delete_readback.get("readback_status"),
+                            "safe_to_retry_delete": False,
+                            **(
+                                {
+                                    "error_code": delete_readback.get("error_code"),
+                                    "message": delete_readback.get("message"),
+                                    "request_id": delete_readback.get("request_id"),
+                                    "backend_code": delete_readback.get("backend_code"),
+                                    "http_status": delete_readback.get("http_status"),
+                                    "transport_error": delete_readback.get("transport_error"),
+                                }
+                                if delete_readback.get("readback_status") != "deleted"
+                                else {}
+                            ),
+                        }
+                    )
+                except (QingflowApiError, RuntimeError) as error:
+                    api_error = _coerce_api_error(error)
+                    failed_view = {
+                        "name": removed_name,
+                        "view_key": key,
+                        "type": None,
+                        "status": "failed",
+                        "operation": "delete",
+                        "delete_executed": False,
+                        "safe_to_retry_delete": True,
+                        "error_code": "VIEW_DELETE_FAILED",
+                        "message": _public_error_message("VIEW_APPLY_FAILED", api_error),
+                        "request_id": api_error.request_id,
+                        "backend_code": api_error.backend_code,
+                        "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                    }
+                    failed_views.append(failed_view)
+                    view_results.append(deepcopy(failed_view))
         created: list[str] = []
         updated: list[str] = []
         existing_view_list = [
@@ -8776,7 +9817,7 @@ class AiBuilderFacade:
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 should_retry_minimal = operation_phase != "default_view_apply_config_sync" and (
-                    api_error.backend_code == 48104
+                    backend_code_int(api_error) == 48104
                     or (patch.type.value == "table" and bool(patch.filters) and api_error.http_status is not None and api_error.http_status >= 500)
                 )
                 if should_retry_minimal:
@@ -8950,17 +9991,21 @@ class AiBuilderFacade:
                 failed_views.append(failure_entry)
                 view_results.append(failure_entry)
                 continue
-        try:
-            verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return finalize(_failed_from_api_error(
-                "VIEWS_READ_FAILED",
-                api_error,
-                normalized_args=normalized_args,
-                details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
-                suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
-            ))
+        needs_view_list_readback = bool(created or updated)
+        verified_view_result: list[dict[str, Any]] | None = []
+        verified_views_unavailable = False
+        if needs_view_list_readback:
+            try:
+                verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return finalize(_failed_from_api_error(
+                    "VIEWS_READ_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": app_key}, resource="views", error=api_error),
+                    suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                ))
         verified_names = {
             _extract_view_name(item)
             for item in (verified_view_result or [])
@@ -9248,8 +10293,27 @@ class AiBuilderFacade:
                         "view_key": item.get("view_key"),
                         "type": item.get("type"),
                         "status": "removed",
-                        "present_in_readback": None if verified_views_unavailable else name in verified_names,
-                        "removed_verified": None if verified_views_unavailable else name not in verified_names,
+                        "present_in_readback": False,
+                        "removed_verified": True,
+                        "delete_executed": bool(item.get("delete_executed")),
+                        "readback_status": item.get("readback_status") or "deleted",
+                        "safe_to_retry_delete": False,
+                    }
+                )
+            elif status == "readback_pending" and item.get("operation") == "delete":
+                readback_status = str(item.get("readback_status") or "unavailable")
+                verification_by_view.append(
+                    {
+                        "name": name,
+                        "view_key": item.get("view_key"),
+                        "type": item.get("type"),
+                        "status": "readback_pending",
+                        "present_in_readback": True if readback_status == "still_exists" else None,
+                        "removed_verified": False,
+                        "delete_executed": bool(item.get("delete_executed")),
+                        "readback_status": readback_status,
+                        "safe_to_retry_delete": False,
+                        "error_code": item.get("error_code"),
                     }
                 )
             else:
@@ -9262,10 +10326,17 @@ class AiBuilderFacade:
                         "error_code": item.get("error_code"),
                     }
                 )
+        removed_delete_results = [
+            item
+            for item in view_results
+            if item.get("operation") == "delete" and bool(item.get("delete_executed"))
+        ]
+        removed_verified = all(str(item.get("readback_status") or "") == "deleted" for item in removed_delete_results)
+        delete_readback_pending = any(str(item.get("readback_status") or "") != "deleted" for item in removed_delete_results)
         verified = (
             (not verified_views_unavailable)
             and all(name in verified_names for name in created + updated)
-            and all(name not in verified_names for name in removed)
+            and removed_verified
         )
         view_filters_verified = verified and not filter_readback_pending and not filter_mismatches
         view_query_conditions_verified = verified and not query_condition_readback_pending and not query_condition_mismatches
@@ -9342,6 +10413,9 @@ class AiBuilderFacade:
                 "app_name": app_name,
                 "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
                 "verified": verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified,
+                "write_executed": bool(created or updated or removed),
+                "write_succeeded": bool(created or updated or removed),
+                "safe_to_retry": not bool(created or updated or removed),
             }
             return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
         warnings: list[dict[str, Any]] = []
@@ -9360,6 +10434,13 @@ class AiBuilderFacade:
                     "system buttons verified, but draft custom button bindings are not fully visible through view readback yet",
                 )
             )
+        if delete_readback_pending:
+            warnings.append(
+                _warning(
+                    "VIEW_DELETE_READBACK_PENDING",
+                    "view delete was sent, but deletion readback is not fully verified; do not blindly repeat delete",
+                )
+            )
         all_verified = verified and view_filters_verified and view_query_conditions_verified and view_associated_resources_verified and view_buttons_verified
         response = {
             "status": "success" if all_verified else "partial_success",
@@ -9407,6 +10488,7 @@ class AiBuilderFacade:
                 "query_condition_readback_pending": query_condition_readback_pending,
                 "associated_resource_readback_pending": associated_resource_readback_pending,
                 "button_readback_pending": button_readback_pending,
+                "delete_readback_pending": delete_readback_pending,
                 "custom_button_readback_pending": custom_button_readback_pending,
                 "custom_button_readback_pending_entries": deepcopy(custom_button_readback_pending_entries),
                 "by_view": verification_by_view,
@@ -9415,6 +10497,9 @@ class AiBuilderFacade:
             "app_name": app_name,
             "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": all_verified,
+            "write_executed": bool(created or updated or removed),
+            "write_succeeded": bool(created or updated or removed),
+            "safe_to_retry": not bool(created or updated or removed),
         }
         return finalize(self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response))
 
@@ -9475,8 +10560,21 @@ class AiBuilderFacade:
                 "tag_ids_after": tag_ids_before,
                 "views_ok": True,
                 "verified": True,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
             }
-        version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        try:
+            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "PUBLISH_PRECHECK_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "phase": "prepare_publish_edit_version"},
+                suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+            )
         edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
         try:
             self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
@@ -9494,13 +10592,18 @@ class AiBuilderFacade:
             base = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True).get("result") or {}
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "APP_READ_FAILED",
-                api_error,
+            result = _post_write_readback_pending_result(
+                error_code="PUBLISH_READBACK_PENDING",
+                message="published app; app base readback is unavailable",
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details={"app_key": app_key, "edit_version_no": edit_version_no, "readback_error": _transport_error_payload(api_error)},
                 suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                request_id=api_error.request_id,
+                backend_code=api_error.backend_code,
+                http_status=None if api_error.http_status == 404 else api_error.http_status,
             )
+            result.update({"app_key": app_key, "published": None, "verified": False})
+            return result
         tag_ids_after = _coerce_int_list(base.get("tagIds"))
         app_name_after = str(base.get("formTitle") or base.get("title") or base.get("appName") or app_name_before or "").strip() or None
         package_attached = None if not expected_package_tag_id else expected_package_tag_id in tag_ids_after
@@ -9508,13 +10611,18 @@ class AiBuilderFacade:
             views, views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
-            return _failed_from_api_error(
-                "VIEWS_READ_FAILED",
-                api_error,
+            result = _post_write_readback_pending_result(
+                error_code="VIEWS_READBACK_PENDING",
+                message="published app; views readback is unavailable",
                 normalized_args=normalized_args,
-                details={"app_key": app_key},
+                details={"app_key": app_key, "edit_version_no": edit_version_no, "readback_error": _transport_error_payload(api_error)},
                 suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
+                request_id=api_error.request_id,
+                backend_code=api_error.backend_code,
+                http_status=None if api_error.http_status == 404 else api_error.http_status,
             )
+            result.update({"app_key": app_key, "app_name": app_name_after, "published": bool(base.get("appPublishStatus") in {1, 2}), "verified": False})
+            return result
         views = views or []
         views_ok = isinstance(views, list) and not views_unavailable
         verified = bool(base.get("appPublishStatus") in {1, 2}) and (package_attached is not False) and views_ok
@@ -9549,6 +10657,9 @@ class AiBuilderFacade:
             "tag_ids_after": tag_ids_after,
             "views_ok": views_ok,
             "verified": verified,
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
         }
 
     def _expand_chart_partial_patches(
@@ -9671,6 +10782,167 @@ class AiBuilderFacade:
             )
         return expanded, issues, results
 
+    def _verify_view_deleted_by_key(self, *, profile: str, view_key: str) -> JSONObject:
+        try:
+            self.views.view_get_config(profile=profile, viewgraph_key=view_key)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _delete_readback_is_not_found(api_error):
+                return {
+                    "view_key": view_key,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "view_key": view_key,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "VIEW_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but view existence could not be verified by view_key readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "view_key": view_key,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "VIEW_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the view still exists during view_key readback",
+        }
+
+    def _verify_custom_button_deleted_by_id(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        try:
+            def runner(_: Any, context: BackendRequestContext) -> object:
+                return self.buttons.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton/{button_id}",
+                    params={"beingDraft": True},
+                )
+
+            self.buttons._run(profile, runner)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _delete_readback_is_not_found(api_error):
+                return {
+                    "button_id": button_id,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "button_id": button_id,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "CUSTOM_BUTTON_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but custom button existence could not be verified by button_id readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "button_id": button_id,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "CUSTOM_BUTTON_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the custom button still exists during button_id readback",
+        }
+
+    def _verify_associated_resources_deleted_by_pool(
+        self,
+        *,
+        deleted_items: list[JSONObject],
+        resources: list[dict[str, Any]],
+        readback_failed: bool,
+    ) -> list[JSONObject]:
+        existing_by_id = _associated_resource_index(resources) if not readback_failed else {}
+        verified_items: list[JSONObject] = []
+        for item in deleted_items:
+            associated_item_id = _coerce_positive_int(item.get("associated_item_id"))
+            verified = deepcopy(item)
+            verified["operation"] = "remove"
+            verified["delete_executed"] = True
+            verified["safe_to_retry_delete"] = False
+            if associated_item_id is None or readback_failed:
+                verified["status"] = "readback_pending"
+                verified["readback_status"] = "unavailable"
+                verified["error_code"] = "ASSOCIATED_RESOURCE_DELETE_READBACK_UNAVAILABLE"
+                verified["message"] = "delete request completed, but associated resource pool readback is unavailable"
+            elif associated_item_id in existing_by_id:
+                verified["status"] = "readback_pending"
+                verified["readback_status"] = "still_exists"
+                verified["error_code"] = "ASSOCIATED_RESOURCE_DELETE_READBACK_STILL_EXISTS"
+                verified["message"] = "delete request completed, but the associated resource still exists in pool readback"
+            else:
+                verified["status"] = "removed"
+                verified["readback_status"] = "deleted"
+                verified.pop("error_code", None)
+                verified.pop("message", None)
+            verified_items.append(verified)
+        return verified_items
+
+    def _verify_chart_deleted_by_id(self, *, profile: str, chart_id: str) -> JSONObject:
+        base_result: dict[str, Any] | None = None
+        try:
+            raw = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
+            base_result = raw if isinstance(raw, dict) else {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            if _chart_delete_readback_is_not_found(api_error):
+                return {
+                    "chart_id": chart_id,
+                    "operation": "delete",
+                    "status": "removed",
+                    "delete_executed": True,
+                    "readback_status": "deleted",
+                    "safe_to_retry_delete": False,
+                }
+            return {
+                "chart_id": chart_id,
+                "operation": "delete",
+                "status": "readback_pending",
+                "delete_executed": True,
+                "readback_status": "unavailable",
+                "safe_to_retry_delete": False,
+                "error_code": "CHART_DELETE_READBACK_UNAVAILABLE",
+                "message": "delete request completed, but chart existence could not be verified by chart_id readback",
+                "request_id": api_error.request_id,
+                "backend_code": api_error.backend_code,
+                "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                "transport_error": _transport_error_payload(api_error),
+            }
+        return {
+            "chart_id": chart_id,
+            "operation": "delete",
+            "status": "readback_pending",
+            "delete_executed": True,
+            "readback_status": "still_exists",
+            "safe_to_retry_delete": False,
+            "error_code": "CHART_DELETE_READBACK_STILL_EXISTS",
+            "message": "delete request completed, but the chart still exists during chart_id readback",
+            "readback_name": base_result.get("chartName") or base_result.get("name") if isinstance(base_result, dict) else None,
+        }
+
     def chart_apply(self, *, profile: str, request: ChartApplyRequest) -> JSONObject:
         normalized_args = request.model_dump(mode="json")
         permission_outcomes: list[PermissionCheckOutcome] = []
@@ -9695,21 +10967,27 @@ class AiBuilderFacade:
         def finalize(response: JSONObject) -> JSONObject:
             return _apply_permission_outcomes(response, *permission_outcomes)
 
-        try:
-            schema_state = self._load_base_schema_state(profile=profile, app_key=app_key)
-            parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
-            fields = parsed.get("fields") if isinstance(parsed.get("fields"), list) else []
-            qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
-            existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-        except (QingflowApiError, RuntimeError) as error:
-            api_error = _coerce_api_error(error)
-            return finalize(_failed_from_api_error(
-                "CHART_APPLY_FAILED",
-                api_error,
-                normalized_args=normalized_args,
-                details=_with_state_read_blocked_details({"app_key": app_key}, resource="chart", error=api_error),
-                suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-            ))
+        fields: list[dict[str, Any]] = []
+        qingbi_fields: list[Any] = []
+        existing_chart_items: list[Any] = []
+        existing_chart_list_source: str | None = None
+        needs_chart_inventory = bool(request.upsert_charts or request.patch_charts or request.reorder_chart_ids)
+        if needs_chart_inventory:
+            try:
+                schema_state = self._load_base_schema_state(profile=profile, app_key=app_key)
+                parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
+                fields = parsed.get("fields") if isinstance(parsed.get("fields"), list) else []
+                qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
+                existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return finalize(_failed_from_api_error(
+                    "CHART_APPLY_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details=_with_state_read_blocked_details({"app_key": app_key}, resource="chart", error=api_error),
+                    suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
+                ))
 
         field_lookup = _build_public_field_lookup(fields)
         qingbi_fields_by_id = {
@@ -9717,6 +10995,11 @@ class AiBuilderFacade:
             for item in qingbi_fields
             if isinstance(item, dict) and item.get("fieldId")
         }
+        chart_field_lookup = _build_qingbi_chart_field_lookup(
+            app_key=app_key,
+            qingbi_fields=[item for item in qingbi_fields if isinstance(item, dict)],
+            field_lookup=field_lookup,
+        )
         existing_by_id = {
             _extract_chart_identifier(item): deepcopy(item)
             for item in existing_chart_items
@@ -9759,8 +11042,12 @@ class AiBuilderFacade:
         updated_ids: list[str] = []
         removed_ids: list[str] = []
         failed_items: list[dict[str, Any]] = []
+        delete_readback_issues: list[dict[str, Any]] = []
 
         for patch in upsert_charts:
+            chart_id = ""
+            target_type = ""
+            config_payload: dict[str, Any] | None = None
             try:
                 dataset_source = _chart_patch_dataset_source_type(patch)
                 if dataset_source:
@@ -9799,6 +11086,14 @@ class AiBuilderFacade:
                         f"existing chart '{chart_id or patch.name}' uses dataset report source '{existing_source_type}' and is not supported for update yet. "
                         "Update it in QingBI directly, then attach the existing report with app_associated_resources_apply using report_source='dataset'."
                     )
+                if existing is None or config_update_requested:
+                    config_payload = _build_public_chart_config_payload(
+                        patch=patch,
+                        app_key=app_key,
+                        field_lookup=field_lookup,
+                        chart_field_lookup=chart_field_lookup,
+                        qingbi_fields_by_id=qingbi_fields_by_id,
+                    )
                 if existing is None:
                     temp_chart_id = str(patch.chart_id or f"mcp_{uuid4().hex[:16]}")
                     create_payload = {
@@ -9817,18 +11112,21 @@ class AiBuilderFacade:
                     create_result = self.charts.qingbi_report_create(profile=profile, payload=create_payload).get("result") or {}
                     created_chart_id = _extract_chart_identifier(create_result or {})
                     if not created_chart_id:
-                        refreshed_items, _ = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-                        refreshed_matches = _find_charts_by_name(
-                            refreshed_items,
-                            chart_name=patch.name,
-                            chart_type=target_type,
-                        )
-                        if len(refreshed_matches) == 1:
-                            created_chart_id = _extract_chart_identifier(refreshed_matches[0])
-                        elif len(refreshed_matches) > 1:
-                            raise ValueError(
-                                f"created chart '{patch.name}' could not be uniquely resolved from readback; supply chart_id on the next update"
+                        try:
+                            refreshed_items, _ = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+                            refreshed_matches = _find_charts_by_name(
+                                refreshed_items,
+                                chart_name=patch.name,
+                                chart_type=target_type,
                             )
+                            if len(refreshed_matches) == 1:
+                                created_chart_id = _extract_chart_identifier(refreshed_matches[0])
+                            elif len(refreshed_matches) > 1:
+                                raise ValueError(
+                                    f"created chart '{patch.name}' could not be uniquely resolved from readback; supply chart_id on the next update"
+                                )
+                        except (QingflowApiError, RuntimeError):
+                            created_chart_id = temp_chart_id
                     if not created_chart_id:
                         raise ValueError(
                             f"created chart '{patch.name}' did not return a real chart_id and could not be confirmed from readback"
@@ -9882,13 +11180,7 @@ class AiBuilderFacade:
 
                 config_updated = False
                 if existing is None or config_update_requested:
-                    config_payload = _build_public_chart_config_payload(
-                        patch=patch,
-                        app_key=app_key,
-                        field_lookup=field_lookup,
-                        qingbi_fields_by_id=qingbi_fields_by_id,
-                    )
-                    self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload)
+                    self.charts.qingbi_report_update_config(profile=profile, chart_id=chart_id, payload=config_payload or {})
                     config_updated = True
                 if existing is not None and chart_id not in updated_ids and config_updated:
                     updated_ids.append(chart_id)
@@ -9918,11 +11210,21 @@ class AiBuilderFacade:
                 )
             except (QingflowApiError, RuntimeError, ValueError, VisibilityResolutionError) as error:
                 api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
+                diagnostics = (
+                    error.diagnostics
+                    if isinstance(error, ChartRuleViolation)
+                    else _explain_chart_backend_validation_error(api_error=api_error, chart_type=target_type or patch.chart_type.value, payload=config_payload)
+                    if api_error is not None
+                    else None
+                )
                 failure = {
-                    "chart_id": str(locals().get("chart_id") or patch.chart_id or ""),
+                    "chart_id": str(chart_id or patch.chart_id or ""),
                     "name": patch.name,
+                    "chart_type": patch.chart_type.value,
                     "status": "failed",
-                    "message": str(error),
+                    "error_code": diagnostics.get("rule_code") if isinstance(diagnostics, dict) else "CHART_APPLY_FAILED",
+                    "message": str(diagnostics.get("message") if isinstance(diagnostics, dict) and diagnostics.get("message") else error),
+                    "diagnostics": diagnostics,
                     "request_id": api_error.request_id if api_error else None,
                     "backend_code": api_error.backend_code if api_error else None,
                     "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
@@ -9934,12 +11236,18 @@ class AiBuilderFacade:
             try:
                 self.charts.qingbi_report_delete(profile=profile, chart_id=chart_id)
                 removed_ids.append(chart_id)
-                chart_results.append({"chart_id": chart_id, "status": "removed"})
+                delete_result = self._verify_chart_deleted_by_id(profile=profile, chart_id=chart_id)
+                if delete_result.get("readback_status") != "deleted":
+                    delete_readback_issues.append(delete_result)
+                chart_results.append(delete_result)
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
                 failure = {
                     "chart_id": chart_id,
+                    "operation": "delete",
                     "status": "failed",
+                    "delete_executed": False,
+                    "safe_to_retry_delete": True,
                     "message": _public_error_message("CHART_APPLY_FAILED", api_error),
                     "request_id": api_error.request_id,
                     "backend_code": api_error.backend_code,
@@ -9974,30 +11282,41 @@ class AiBuilderFacade:
                 chart_results.append(failure)
 
         noop = not created_ids and not updated_ids and not removed_ids and not reordered and not failed_items
-        try:
-            readback_items, readback_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
-            readback_ids = {
-                _extract_chart_identifier(item)
-                for item in readback_items
-                if isinstance(item, dict) and _extract_chart_identifier(item)
-            }
-            verified = (
-                all(chart_id in readback_ids for chart_id in created_ids + updated_ids)
-                and all(chart_id not in readback_ids for chart_id in removed_ids)
-            )
-            if request.reorder_chart_ids:
-                ordered_readback = [
+        write_executed = bool(created_ids or updated_ids or removed_ids or reordered)
+        write_succeeded = write_executed
+        needs_list_readback = bool(created_ids or updated_ids or reordered)
+        delete_readback_unavailable = any(item.get("readback_status") == "unavailable" for item in delete_readback_issues)
+        deletes_verified = not delete_readback_issues
+        readback_unavailable = False
+        readback_error: QingflowApiError | None = None
+        readback_list_source: str | None = existing_chart_list_source
+        if needs_list_readback:
+            try:
+                readback_items, readback_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
+                readback_ids = {
                     _extract_chart_identifier(item)
                     for item in readback_items
                     if isinstance(item, dict) and _extract_chart_identifier(item)
-                ]
-                requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
-                verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
-            readback_unavailable = False
-        except (QingflowApiError, RuntimeError):
-            verified = False
-            readback_unavailable = True
-            readback_list_source = None
+                }
+                verified = all(chart_id in readback_ids for chart_id in created_ids + updated_ids)
+                if request.reorder_chart_ids:
+                    ordered_readback = [
+                        _extract_chart_identifier(item)
+                        for item in readback_items
+                        if isinstance(item, dict) and _extract_chart_identifier(item)
+                    ]
+                    requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
+                    verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
+                readback_unavailable = False
+            except (QingflowApiError, RuntimeError) as error:
+                readback_error = _coerce_api_error(error)
+                verified = False
+                readback_unavailable = True
+                readback_list_source = None
+        else:
+            verified = True
+        verified = verified and deletes_verified
+        any_readback_unavailable = readback_unavailable or delete_readback_unavailable
 
         if failed_items:
             successful_changes = bool(created_ids or updated_ids or removed_ids or reordered)
@@ -10009,56 +11328,79 @@ class AiBuilderFacade:
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
-                "details": {"per_chart_results": chart_results},
-                "request_id": failed_items[0].get("request_id"),
+                "details": {
+                    "per_chart_results": chart_results,
+                    **({"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {}),
+                },
+                "request_id": failed_items[0].get("request_id") or (readback_error.request_id if readback_error is not None else None),
                 "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
-                "backend_code": failed_items[0].get("backend_code"),
-                "http_status": failed_items[0].get("http_status"),
+                "backend_code": failed_items[0].get("backend_code") or (readback_error.backend_code if readback_error is not None else None),
+                "http_status": failed_items[0].get("http_status") or (None if readback_error is None or readback_error.http_status == 404 else readback_error.http_status),
                 "noop": noop,
                 "warnings": _chart_apply_warnings(
                     failed_items=failed_items,
                     readback_unavailable=readback_unavailable,
                     verified=False if failed_items else verified,
+                    delete_readback_issues=delete_readback_issues,
                 ),
                 "verification": {
                     "charts_verified": False if failed_items else verified,
-                    "readback_unavailable": readback_unavailable,
-                    "chart_order_verified": False if request.reorder_chart_ids else (readback_list_source == "sorted"),
+                    "readback_unavailable": any_readback_unavailable,
+                    "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
+                    "chart_order_verified": False if request.reorder_chart_ids else True,
                     "chart_list_source": readback_list_source or existing_chart_list_source,
                 },
                 "app_key": app_key,
                 "app_name": app_name,
                 "chart_results": chart_results,
                 "verified": False if failed_items else verified,
+                "write_executed": write_executed,
+                "write_succeeded": write_succeeded,
+                "safe_to_retry": not write_executed,
             })
         result_verified = verified or noop
+        pending_delete = bool(delete_readback_issues)
+        pending_error_code = "CHART_DELETE_READBACK_PENDING" if pending_delete and not readback_unavailable else "CHART_READBACK_PENDING"
+        pending_message = "applied chart operations; delete readback pending" if pending_delete else "applied chart operations; readback pending"
+        pending_suggestion = (
+            {"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": str(delete_readback_issues[0].get("chart_id") or "CHART_ID")}}
+            if pending_delete
+            else {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}}
+        )
         return finalize({
             "status": "success" if result_verified else "partial_success",
-            "error_code": None if result_verified else "CHART_READBACK_PENDING",
+            "error_code": None if result_verified else pending_error_code,
             "recoverable": not result_verified,
-            "message": "no chart changes requested" if noop else ("applied chart operations" if verified else "applied chart operations; readback pending"),
+            "message": "no chart changes requested" if noop else ("applied chart operations" if verified else pending_message),
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
-            "details": {},
-            "request_id": None,
-            "suggested_next_call": None if result_verified else {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
+            "details": {"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {},
+            "request_id": readback_error.request_id if readback_error is not None else None,
+            "suggested_next_call": None if result_verified else pending_suggestion,
+            "backend_code": readback_error.backend_code if readback_error is not None else None,
+            "http_status": None if readback_error is None or readback_error.http_status == 404 else readback_error.http_status,
             "noop": noop,
             "warnings": _chart_apply_warnings(
                 failed_items=[],
                 readback_unavailable=False if noop else readback_unavailable,
                 verified=result_verified,
+                delete_readback_issues=delete_readback_issues,
             ),
             "verification": {
                 "charts_verified": result_verified,
-                "readback_unavailable": False if noop else readback_unavailable,
-                "chart_order_verified": True if noop and not request.reorder_chart_ids else (readback_list_source == "sorted" and result_verified if request.reorder_chart_ids else readback_list_source == "sorted"),
+                "readback_unavailable": False if noop else any_readback_unavailable,
+                "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
+                "chart_order_verified": (readback_list_source == "sorted" and result_verified) if request.reorder_chart_ids else True,
                 "chart_list_source": existing_chart_list_source if noop else readback_list_source,
             },
             "app_key": app_key,
             "app_name": app_name,
             "chart_results": chart_results,
             "verified": result_verified,
+            "write_executed": write_executed,
+            "write_succeeded": write_succeeded,
+            "safe_to_retry": not write_executed,
         })
 
     def portal_apply(self, *, profile: str, request: PortalApplyRequest) -> JSONObject:
@@ -10139,15 +11481,6 @@ class AiBuilderFacade:
             if package_add_outcome.block is not None:
                 return package_add_outcome.block
             permission_outcomes.append(package_add_outcome)
-            package_edit_outcome = self._guard_package_permission(
-                profile=profile,
-                tag_id=target_package_tag_id,
-                required_permission="edit_app",
-                normalized_args=normalized_args,
-            )
-            if package_edit_outcome.block is not None:
-                return package_edit_outcome.block
-            permission_outcomes.append(package_edit_outcome)
         if not sections_requested:
             unsupported_base_only_keys: list[str] = []
             if request.hide_copyright is not None:
@@ -10167,7 +11500,12 @@ class AiBuilderFacade:
                     },
                     suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                 )
+        write_executed = False
+        draft_readback_error: JSONObject | None = None
+        live_readback_error: JSONObject | None = None
+        update_payload: dict[str, Any] = {}
         try:
+            layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
                 create_payload = _build_public_portal_base_payload(
                     dash_name=request.dash_name or "未命名门户",
@@ -10181,6 +11519,7 @@ class AiBuilderFacade:
                     base_payload=None,
                 )
                 create_result = self.portals.portal_create(profile=profile, payload=create_payload)
+                write_executed = True
                 created = create_result.get("result") if isinstance(create_result.get("result"), dict) else {}
                 dash_key = str(created.get("dashKey") or "")
                 if not dash_key:
@@ -10191,7 +11530,15 @@ class AiBuilderFacade:
                         details={"create_result": created},
                         suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
                     )
-                base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+                try:
+                    base_payload = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+                except (QingflowApiError, RuntimeError) as read_error:
+                    api_read_error = _coerce_api_error(read_error)
+                    draft_readback_error = {
+                        "phase": "created_portal_draft_readback",
+                        "transport_error": _transport_error_payload(api_read_error),
+                    }
+                    base_payload = {}
             update_payload = _build_public_portal_base_payload(
                 dash_name=request.dash_name or str(base_payload.get("dashName") or "").strip() or "未命名门户",
                 package_tag_id=target_package_tag_id,
@@ -10204,9 +11551,15 @@ class AiBuilderFacade:
                 base_payload=base_payload,
             )
             if sections_requested:
-                component_payload = self._build_portal_components_from_sections(profile=profile, sections=request.sections)
+                component_payload = self._build_portal_components_from_sections(
+                    profile=profile,
+                    sections=request.sections,
+                    layout_preset=request.layout_preset,
+                )
+                layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload)
                 update_payload["components"] = component_payload
                 self.portals.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
+                write_executed = True
             self.portals.portal_update_base_info(
                 profile=profile,
                 dash_key=dash_key,
@@ -10217,9 +11570,70 @@ class AiBuilderFacade:
                     "tags": deepcopy(update_payload.get("tags") or []),
                 },
             )
-            draft_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+            write_executed = True
+            try:
+                draft_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=True).get("result") or {}
+            except (QingflowApiError, RuntimeError) as read_error:
+                api_read_error = _coerce_api_error(read_error)
+                draft_readback_error = {
+                    "phase": "portal_draft_readback",
+                    "transport_error": _transport_error_payload(api_read_error),
+                }
+                draft_result = {}
         except (QingflowApiError, RuntimeError, ValueError) as error:
             api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
+            if write_executed:
+                transport_error = _transport_error_payload(api_error) if api_error is not None else None
+                warning = _warning(
+                    "PORTAL_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
+                    "one or more portal write steps executed before a later write step failed",
+                )
+                if transport_error is not None:
+                    for key in ("backend_code", "http_status", "request_id"):
+                        if transport_error.get(key) is not None:
+                            warning[key] = transport_error.get(key)
+                return finalize({
+                    "status": "partial_success",
+                    "error_code": "PORTAL_APPLY_PARTIAL",
+                    "recoverable": True,
+                    "message": "some portal write steps executed; a later portal write step failed",
+                    "normalized_args": normalized_args,
+                    "missing_fields": [],
+                    "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
+                    "details": {
+                        "dash_key": dash_key or None,
+                        "write_error": (
+                            {"message": api_error.message, "transport_error": transport_error}
+                            if api_error is not None
+                            else {"message": str(error)}
+                        ),
+                    },
+                    "request_id": api_error.request_id if api_error else None,
+                    "backend_code": api_error.backend_code if api_error else None,
+                    "http_status": None if api_error is None or api_error.http_status == 404 else api_error.http_status,
+                    "suggested_next_call": {"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+                    "noop": False,
+                    "warnings": [warning],
+                    "verification": {
+                        "draft_verified": False,
+                        "draft_metadata_verified": False,
+                        "live_verified": None,
+                        "live_metadata_verified": None,
+                        "published": False,
+                        "publish_failed": False,
+                        "write_incomplete": True,
+                        "readback_unavailable": False,
+                        "metadata_unverified": True,
+                    },
+                    "dash_key": dash_key,
+                    "dash_name": update_payload.get("dashName") if isinstance(update_payload, dict) else None,
+                    "package_id": target_package_tag_id,
+                    "created": creating,
+                    "published": False,
+                    "verified": False,
+                    "write_executed": True,
+                    "safe_to_retry": False,
+                })
             return _failed(
                 "PORTAL_APPLY_FAILED",
                 _public_error_message("PORTAL_APPLY_FAILED", api_error) if api_error else str(error),
@@ -10234,19 +11648,35 @@ class AiBuilderFacade:
         live_result: dict[str, Any] | None = None
         published = False
         publish_failed = False
+        publish_error: JSONObject | None = None
         if request.publish:
             try:
                 self.portals.portal_publish(profile=profile, dash_key=dash_key)
                 published = True
-                live_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=False).get("result") or {}
-            except (QingflowApiError, RuntimeError):
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
                 publish_failed = True
+                publish_error = {
+                    "message": api_error.message,
+                    "transport_error": _transport_error_payload(api_error),
+                }
+            if published:
+                try:
+                    live_result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=False).get("result") or {}
+                except (QingflowApiError, RuntimeError) as read_error:
+                    api_read_error = _coerce_api_error(read_error)
+                    live_readback_error = {
+                        "phase": "portal_live_readback",
+                        "transport_error": _transport_error_payload(api_read_error),
+                    }
 
         draft_components = draft_result.get("components") if isinstance(draft_result, dict) else None
         expected_count = len(request.sections) if sections_requested else None
         draft_verified = isinstance(draft_result, dict) and (
             expected_count is None or (isinstance(draft_components, list) and len(draft_components) == expected_count)
         )
+        if draft_readback_error is not None:
+            draft_verified = False
         draft_meta_verified, draft_meta_mismatches = _verify_portal_readback(
             actual=draft_result,
             expected_payload=update_payload,
@@ -10274,6 +11704,8 @@ class AiBuilderFacade:
                     )
                 )
             )
+            if live_readback_error is not None:
+                live_verified = False
             live_meta_verified, live_meta_mismatches = _verify_portal_readback(
                 actual=live_result,
                 expected_payload=update_payload,
@@ -10307,6 +11739,24 @@ class AiBuilderFacade:
             live_meta_verified=live_meta_verified,
             publish_requested=request.publish,
         )
+        details_payload = {
+            "verification_mismatches": {
+                "draft": draft_meta_mismatches,
+                "live": live_meta_mismatches,
+            },
+            **({"publish_error": publish_error} if publish_error is not None else {}),
+            **({"draft_readback_error": draft_readback_error} if draft_readback_error is not None else {}),
+            **({"live_readback_error": live_readback_error} if live_readback_error is not None else {}),
+        }
+        readback_transport_error = _readback_transport_error_from_details(details_payload)
+        if draft_readback_error is not None or live_readback_error is not None:
+            warning = _warning("READBACK_UNAVAILABLE_AFTER_WRITE", "write was executed but portal readback is unavailable")
+            if readback_transport_error is not None:
+                for key in ("backend_code", "http_status", "request_id"):
+                    if readback_transport_error.get(key) is not None:
+                        warning[key] = readback_transport_error.get(key)
+            warnings.append(warning)
+        warnings.extend(_portal_layout_warning_items(layout_diagnostics))
         return finalize({
             "status": status,
             "error_code": error_code,
@@ -10323,16 +11773,14 @@ class AiBuilderFacade:
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"]},
-            "details": {
-                "verification_mismatches": {
-                    "draft": draft_meta_mismatches,
-                    "live": live_meta_mismatches,
-                }
-            },
-            "request_id": None,
+            "details": details_payload,
+            "request_id": (readback_transport_error or {}).get("request_id"),
+            "backend_code": (readback_transport_error or {}).get("backend_code"),
+            "http_status": (readback_transport_error or {}).get("http_status"),
             "suggested_next_call": None if verified else {"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
             "noop": False,
             "warnings": warnings,
+            "layout_diagnostics": layout_diagnostics,
             "verification": {
                 "draft_verified": draft_verified,
                 "draft_metadata_verified": draft_meta_verified,
@@ -10340,6 +11788,8 @@ class AiBuilderFacade:
                 "live_metadata_verified": live_meta_verified,
                 "published": published,
                 "publish_failed": publish_failed,
+                "readback_unavailable": draft_readback_error is not None or live_readback_error is not None,
+                "metadata_unverified": draft_readback_error is not None or live_readback_error is not None,
             },
             "dash_key": dash_key,
             "dash_name": update_payload.get("dashName"),
@@ -10347,6 +11797,8 @@ class AiBuilderFacade:
             "created": creating,
             "published": published,
             "verified": verified,
+            "write_executed": write_executed or published,
+            "safe_to_retry": not (write_executed or published),
             "draft_result": draft_result,
             "live_result": live_result,
         })
@@ -10354,7 +11806,17 @@ class AiBuilderFacade:
     def _publish_current_edit_version(self, *, profile: str, app_key: str, edit_version_no: int | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key}
         if edit_version_no is None:
-            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+            try:
+                version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                return _failed_from_api_error(
+                    "PUBLISH_PRECHECK_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "phase": "prepare_publish_edit_version"},
+                    suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, "app_key": app_key}},
+                )
             edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
         try:
             self.apps.app_publish(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
@@ -10488,6 +11950,7 @@ class AiBuilderFacade:
             response["status"] = "partial_success"
             response["error_code"] = response.get("error_code") or publish_result.get("error_code")
             response["recoverable"] = True
+            response["verified"] = False
             response["message"] = f"{response.get('message') or 'apply succeeded'}; publish failed"
             if not response.get("suggested_next_call"):
                 response["suggested_next_call"] = publish_result.get("suggested_next_call")
@@ -10576,7 +12039,8 @@ class AiBuilderFacade:
         app_key: str,
         tolerate_404: bool,
         tolerate_permission_restricted: bool = False,
-    ) -> tuple[Any, bool]:
+        include_error: bool = False,
+    ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
             views = self.views.view_list_flat(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
@@ -10598,18 +12062,19 @@ class AiBuilderFacade:
                             )
                         )
                     ):
-                        return [], True
+                        return ([], True, legacy_api_error) if include_error else ([], True)
                     raise
                 legacy_result = legacy_views.get("result")
                 if _is_view_collection_shape(legacy_result):
-                    return _normalize_view_collection(legacy_result), False
+                    result = _normalize_view_collection(legacy_result)
+                    return (result, False, api_error) if include_error else (result, False)
                 if tolerate_404:
-                    return [], True
+                    return ([], True, api_error) if include_error else ([], True)
                 raise error
             raise
         normalized_views = _normalize_view_collection(views.get("result"))
         if normalized_views:
-            return normalized_views, False
+            return (normalized_views, False, None) if include_error else (normalized_views, False)
         try:
             legacy_views = self.views.view_list(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as legacy_error:
@@ -10624,11 +12089,12 @@ class AiBuilderFacade:
                     )
                 )
             ):
-                return normalized_views, False
+                return (normalized_views, False, legacy_api_error) if include_error else (normalized_views, False)
             raise
         legacy_result = legacy_views.get("result")
         legacy_normalized = _normalize_view_collection(legacy_result)
-        return legacy_normalized or normalized_views, False
+        result = legacy_normalized or normalized_views
+        return (result, False, None) if include_error else (result, False)
 
     def _load_workflow_result(
         self,
@@ -10637,7 +12103,8 @@ class AiBuilderFacade:
         app_key: str,
         tolerate_404: bool,
         tolerate_permission_restricted: bool = False,
-    ) -> tuple[Any, bool]:
+        include_error: bool = False,
+    ) -> tuple[Any, bool] | tuple[Any, bool, QingflowApiError | None]:
         try:
             workflow = self.workflows.workflow_list_nodes(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
@@ -10646,9 +12113,10 @@ class AiBuilderFacade:
                 api_error.http_status == 404
                 or (tolerate_permission_restricted and _is_permission_restricted_api_error(api_error))
             ):
-                return [], True
+                return ([], True, api_error) if include_error else ([], True)
             raise
-        return workflow.get("result"), False
+        result = workflow.get("result")
+        return (result, False, None) if include_error else (result, False)
 
     def _load_app_state(self, *, profile: str, app_key: str) -> dict[str, Any]:
         state = self._load_base_schema_state(profile=profile, app_key=app_key)
@@ -10943,6 +12411,7 @@ class AiBuilderFacade:
         *,
         profile: str,
         sections: list[PortalSectionPatch],
+        layout_preset: str | None = None,
     ) -> list[dict[str, Any]]:
         resolved_components: list[dict[str, Any]] = []
         pc_x = 0
@@ -10959,9 +12428,15 @@ class AiBuilderFacade:
                     pc_y=pc_y,
                     pc_row_height=pc_row_height,
                     mobile_y=mobile_y,
+                    layout_preset=layout_preset,
                 )
             else:
-                position_payload = _portal_position_payload(section.position)
+                position_payload = _portal_position_payload(section.position, inferred_mobile_y=mobile_y)
+                mobile = position_payload.get("mobile") if isinstance(position_payload.get("mobile"), dict) else {}
+                mobile_y = max(
+                    mobile_y,
+                    int(mobile.get("y") or 0) + int(mobile.get("rows") or 0),
+                )
             dash_style = deepcopy(section.dash_style_config) if isinstance(section.dash_style_config, dict) else None
             component: dict[str, Any]
             if section.source_type == "chart":
@@ -11794,10 +13269,11 @@ def _resolve_custom_button_view_button_ref(
     button_inventory: dict[int, dict[str, Any]],
     valid_custom_button_ids: set[int],
     reason_path: str,
+    allow_unverified_numeric_id: bool = False,
 ) -> tuple[int | None, dict[str, Any] | None]:
     explicit_id = _coerce_positive_int(button_ref)
     if explicit_id is not None:
-        if explicit_id in valid_custom_button_ids:
+        if explicit_id in valid_custom_button_ids or allow_unverified_numeric_id:
             return explicit_id, None
         return None, {
             "error_code": "UNKNOWN_CUSTOM_BUTTON",
@@ -12074,11 +13550,16 @@ def _failed_from_api_error(
     suggested_next_call: JSONObject | None = None,
     recoverable: bool = True,
 ) -> JSONObject:
-    effective_error_code = "APP_EDIT_LOCKED" if error.backend_code == 40074 else error_code
+    if is_auth_like_error(error):
+        effective_error_code = "AUTH_REQUIRED"
+    elif backend_code_int(error) == 40074:
+        effective_error_code = "APP_EDIT_LOCKED"
+    else:
+        effective_error_code = error_code
     public_message = _public_error_message(effective_error_code, error)
     public_http_status = None if error.http_status == 404 else error.http_status
     merged_details = dict(details or {})
-    if error.backend_code == 40074:
+    if backend_code_int(error) == 40074:
         owner = _extract_edit_lock_owner(error.message)
         merged_details.setdefault("lock_owner_name", owner.get("lock_owner_name"))
         merged_details.setdefault("lock_owner_email", owner.get("lock_owner_email"))
@@ -12120,6 +13601,91 @@ def _failed_from_api_error(
     )
 
 
+def _post_write_readback_pending_result(
+    *,
+    error_code: str,
+    message: str,
+    normalized_args: JSONObject | None = None,
+    details: JSONObject | None = None,
+    suggested_next_call: JSONObject | None = None,
+    request_id: str | None = None,
+    backend_code: Any = None,
+    http_status: int | None = None,
+) -> JSONObject:
+    effective_details = details or {}
+    transport_error = _readback_transport_error_from_details(effective_details)
+    effective_backend_code = backend_code if backend_code is not None else (transport_error or {}).get("backend_code")
+    effective_http_status = http_status if http_status is not None else (transport_error or {}).get("http_status")
+    effective_request_id = request_id if request_id is not None else (transport_error or {}).get("request_id")
+    warning = _warning("READBACK_UNAVAILABLE_AFTER_WRITE", "write was executed but post-write readback is unavailable")
+    for key, value in (
+        ("backend_code", effective_backend_code),
+        ("http_status", effective_http_status),
+        ("request_id", effective_request_id),
+    ):
+        if value is not None:
+            warning[key] = value
+    return {
+        "status": "partial_success",
+        "error_code": error_code,
+        "recoverable": True,
+        "message": message,
+        "normalized_args": normalized_args or {},
+        "missing_fields": [],
+        "allowed_values": {},
+        "details": effective_details,
+        "suggested_next_call": suggested_next_call,
+        "request_id": effective_request_id,
+        "backend_code": effective_backend_code,
+        "http_status": effective_http_status,
+        "noop": False,
+        "warnings": [warning],
+        "verification": {
+            "readback_unavailable": True,
+            "metadata_unverified": True,
+        },
+        "verified": False,
+        "write_executed": True,
+        "write_succeeded": True,
+        "safe_to_retry": False,
+    }
+
+
+def _readback_transport_error_from_details(details: JSONObject) -> JSONObject | None:
+    direct = details.get("transport_error")
+    if isinstance(direct, dict):
+        return direct
+    for key in (
+        "readback_error",
+        "verification_error",
+        "draft_readback_error",
+        "live_readback_error",
+        "state_read_blocked",
+    ):
+        value = details.get(key)
+        if isinstance(value, dict) and isinstance(value.get("transport_error"), dict):
+            return value.get("transport_error")
+    verification_result = details.get("verification_result")
+    if isinstance(verification_result, dict):
+        verification_details = verification_result.get("details")
+        if isinstance(verification_details, dict):
+            nested = verification_details.get("transport_error")
+            if isinstance(nested, dict):
+                payload = dict(nested)
+                for key in ("backend_code", "http_status", "request_id", "category"):
+                    if payload.get(key) is None and verification_result.get(key) is not None:
+                        payload[key] = verification_result.get(key)
+                return payload
+        payload = {
+            key: verification_result.get(key)
+            for key in ("backend_code", "http_status", "request_id", "category")
+            if verification_result.get(key) is not None
+        }
+        if payload:
+            return payload
+    return None
+
+
 def _transport_error_payload(error: QingflowApiError) -> JSONObject:
     return {
         "http_status": error.http_status,
@@ -12130,7 +13696,30 @@ def _transport_error_payload(error: QingflowApiError) -> JSONObject:
 
 
 def _is_permission_restricted_api_error(error: QingflowApiError) -> bool:
-    return error.backend_code in {40002, 40027}
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
+
+
+def _is_optional_builder_lookup_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027, 404} or error.http_status == 404
+
+
+def _search_permission_blocked_from_warnings(payload: JSONObject) -> JSONObject | None:
+    warnings = payload.get("warnings")
+    if not isinstance(warnings, list):
+        return None
+    for item in warnings:
+        if not isinstance(item, dict) or item.get("code") != "APP_SEARCH_FALLBACK_VISIBLE_APPS":
+            continue
+        return {
+            "backend_code": item.get("backend_code"),
+            "http_status": item.get("http_status"),
+            "request_id": item.get("request_id"),
+        }
+    return None
 
 
 def _append_response_detail(details: JSONObject, *, key: str, value: Any) -> None:
@@ -12331,7 +13920,7 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
 
 
 def _public_error_message(error_code: str, error: QingflowApiError) -> str:
-    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+    if backend_code_int(error) == 40074 or error_code == "APP_EDIT_LOCKED":
         owner = _extract_edit_lock_owner(error.message)
         owner_label = owner.get("lock_owner_email") or owner.get("lock_owner_name")
         if owner_label:
@@ -12360,6 +13949,30 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
     return mapping.get(error_code, "requested builder resource is unavailable in the current route")
 
 
+def _chart_delete_readback_is_not_found(error: QingflowApiError) -> bool:
+    return _delete_readback_is_not_found(error)
+
+
+def _delete_readback_is_not_found(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    if error.http_status == 404 or backend_code in {404, 40038, 81007}:
+        return True
+    message = str(error.message or "").lower()
+    return any(
+        marker in message
+        for marker in (
+            "object not exist",
+            "not found",
+            "not exist",
+            "does not exist",
+            "不存在",
+            "未找到",
+        )
+    )
+
+
 def _extract_edit_lock_owner(message: str) -> JSONObject:
     text = str(message or "").strip()
     if not text:
@@ -12664,18 +14277,20 @@ def _build_public_dimension_fields(
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
+    chart_type: str = "chart",
 ) -> list[dict[str, Any]]:
     dimensions: list[dict[str, Any]] = []
     for selector in selectors:
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(selector, chart_field_lookup=chart_field_lookup, chart_type=chart_type, role="dimension")
+        field_id = _chart_field_id(qingbi_field)
+        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         dimensions.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
+                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
                 "orderType": "default",
                 "alignType": "left",
                 "dateFormat": "yyyy-MM-dd",
@@ -12717,27 +14332,540 @@ def _default_public_total_metric() -> dict[str, Any]:
     }
 
 
+_QINGBI_TOTAL_FIELD_ID = ":-100"
+_QINGBI_DECIMAL_FIELD_TYPES = {"decimal", "number", "numeric", "amount", "integer", "int", "long", "double", "float"}
+
+
+class ChartRuleViolation(ValueError):
+    def __init__(self, diagnostics: dict[str, Any]) -> None:
+        self.diagnostics = diagnostics
+        super().__init__(str(diagnostics.get("message") or diagnostics.get("next_action") or "chart rule violation"))
+
+
+def _chart_field_id(field: dict[str, Any]) -> str:
+    return str(field.get("fieldId") or field.get("field_id") or "").strip()
+
+
+def _chart_field_name(field: dict[str, Any]) -> str | None:
+    name = str(field.get("fieldName") or field.get("field_name") or "").strip()
+    return name or None
+
+
+def _chart_fields(payload: dict[str, Any], key: str) -> list[dict[str, Any]]:
+    value = payload.get(key)
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _chart_field_summary(field: dict[str, Any]) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "field_id": _chart_field_id(field),
+            "field_name": _chart_field_name(field),
+            "field_type": field.get("fieldType") or field.get("field_type"),
+            "field_source": field.get("fieldSource") or field.get("field_source"),
+            "bi_formula_type": field.get("biFormulaType") or field.get("bi_formula_type"),
+            "aggre_field_id": field.get("aggreFieldId") or field.get("aggre_field_id"),
+        }
+    )
+
+
+def _chart_duplicate_fields(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen: dict[str, dict[str, Any]] = {}
+    duplicates: dict[str, dict[str, Any]] = {}
+    for field in fields:
+        field_id = _chart_field_id(field)
+        if not field_id:
+            continue
+        if field_id in seen:
+            duplicates[field_id] = _chart_field_summary(field)
+        else:
+            seen[field_id] = field
+    return list(duplicates.values())
+
+
+def _chart_rule_diagnostics(
+    *,
+    rule_code: str,
+    chart_type: str,
+    message: str,
+    expected: str,
+    actual: dict[str, Any],
+    next_action: str,
+    offending_fields: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return _compact_dict(
+        {
+            "rule_code": rule_code,
+            "chart_type": chart_type,
+            "message": message,
+            "expected": expected,
+            "actual": actual,
+            "offending_fields": offending_fields or [],
+            "next_action": next_action,
+        }
+    )
+
+
+def _raise_chart_rule(
+    *,
+    rule_code: str,
+    chart_type: str,
+    message: str,
+    expected: str,
+    actual: dict[str, Any],
+    next_action: str,
+    offending_fields: list[dict[str, Any]] | None = None,
+) -> None:
+    raise ChartRuleViolation(
+        _chart_rule_diagnostics(
+            rule_code=rule_code,
+            chart_type=chart_type,
+            message=message,
+            expected=expected,
+            actual=actual,
+            next_action=next_action,
+            offending_fields=offending_fields,
+        )
+    )
+
+
+_QINGBI_TOTAL_FIELD_ALIASES = {_QINGBI_TOTAL_FIELD_ID, "数据总量", "data_total", "total", "count"}
+
+
+def _qingbi_field_que_id(*, app_key: str, field_id: Any) -> int | None:
+    raw = str(field_id or "").strip()
+    if not raw or raw == _QINGBI_TOTAL_FIELD_ID:
+        return None
+    if raw.startswith("field_"):
+        return _coerce_positive_int(raw.removeprefix("field_"))
+    if raw.startswith(f"{app_key}:"):
+        return _coerce_positive_int(raw.split(":", 1)[1])
+    if ":" in raw:
+        return _coerce_positive_int(raw.rsplit(":", 1)[1])
+    return _coerce_positive_int(raw)
+
+
+def _dedupe_qingbi_fields(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    deduped: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for field in fields:
+        field_id = _chart_field_id(field)
+        key = field_id or json.dumps(field, sort_keys=True, ensure_ascii=False, default=str)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(field)
+    return deduped
+
+
+def _build_qingbi_chart_field_lookup(
+    *,
+    app_key: str,
+    qingbi_fields: list[dict[str, Any]],
+    field_lookup: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    by_selector: dict[str, list[dict[str, Any]]] = {}
+    form_by_que_id = field_lookup.get("by_que_id") or {}
+
+    def add_selector(key: Any, field: dict[str, Any]) -> None:
+        normalized = str(key or "").strip()
+        if not normalized:
+            return
+        by_selector.setdefault(normalized, []).append(field)
+        lower = normalized.lower()
+        if lower != normalized:
+            by_selector.setdefault(lower, []).append(field)
+
+    for raw_field in qingbi_fields:
+        if not isinstance(raw_field, dict):
+            continue
+        field_id = _chart_field_id(raw_field)
+        if not field_id:
+            continue
+        field = deepcopy(raw_field)
+        que_id = _qingbi_field_que_id(app_key=app_key, field_id=field_id)
+        form_field = form_by_que_id.get(que_id) if que_id is not None else None
+        if isinstance(form_field, dict):
+            field["_public_form_field"] = deepcopy(form_field)
+        if not _chart_field_name(field) and isinstance(form_field, dict) and form_field.get("name"):
+            field["fieldName"] = form_field.get("name")
+
+        add_selector(field_id, field)
+        if que_id is not None:
+            add_selector(que_id, field)
+            add_selector(f"field_{que_id}", field)
+            if isinstance(form_field, dict):
+                add_selector(form_field.get("field_id"), field)
+        title = _chart_field_name(field)
+        if title:
+            add_selector(title, field)
+    return {"by_selector": by_selector}
+
+
+def _compact_public_chart_fields_read(
+    *,
+    app_key: str,
+    qingbi_fields: list[dict[str, Any]],
+    field_lookup: dict[str, dict[str, Any]],
+) -> list[dict[str, Any]]:
+    form_by_que_id = field_lookup.get("by_que_id") or {}
+    compact_fields: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for field in qingbi_fields:
+        if not isinstance(field, dict):
+            continue
+        bi_field_id = _chart_field_id(field)
+        if not bi_field_id or bi_field_id in seen:
+            continue
+        seen.add(bi_field_id)
+        que_id = _qingbi_field_que_id(app_key=app_key, field_id=bi_field_id)
+        form_field = form_by_que_id.get(que_id) if que_id is not None else None
+        public_field_id = (
+            str(form_field.get("field_id"))
+            if isinstance(form_field, dict) and form_field.get("field_id")
+            else f"field_{que_id}"
+            if que_id is not None
+            else bi_field_id
+        )
+        title = _chart_field_name(field) or (
+            str(form_field.get("name")) if isinstance(form_field, dict) and form_field.get("name") else bi_field_id
+        )
+        compact_fields.append(
+            _compact_dict(
+                {
+                    "field_id": public_field_id,
+                    "que_id": que_id,
+                    "bi_field_id": bi_field_id,
+                    "title": title,
+                    "field_type": field.get("fieldType") or field.get("field_type"),
+                    "system_field": bool(que_id is not None and not isinstance(form_field, dict)),
+                    "available_for_charts": True,
+                }
+            )
+        )
+    return compact_fields
+
+
+def _chart_field_candidates(
+    selector: Any,
+    *,
+    chart_field_lookup: dict[str, Any],
+) -> list[dict[str, Any]]:
+    raw = str(selector or "").strip()
+    if not raw:
+        return []
+    by_selector = chart_field_lookup.get("by_selector") if isinstance(chart_field_lookup.get("by_selector"), dict) else {}
+    return _dedupe_qingbi_fields(list(by_selector.get(raw) or by_selector.get(raw.lower()) or []))
+
+
+def _resolve_qingbi_chart_field(
+    selector: Any,
+    *,
+    chart_field_lookup: dict[str, Any],
+    chart_type: str,
+    role: str,
+) -> dict[str, Any]:
+    raw = str(selector or "").strip()
+    if not raw:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
+            chart_type=chart_type,
+            message="chart field selector cannot be empty",
+            expected="use a field from app_get_fields.chart_fields",
+            actual={"selector": raw, "role": role},
+            next_action="Call app_get_fields and choose a field from chart_fields for chart dimensions, metrics, filters, or query conditions.",
+        )
+    if raw in _QINGBI_TOTAL_FIELD_ALIASES or raw.lower() in _QINGBI_TOTAL_FIELD_ALIASES:
+        if role == "metric":
+            return _default_public_total_metric()
+        _raise_chart_rule(
+            rule_code="CHART_TOTAL_FIELD_NOT_ALLOWED",
+            chart_type=chart_type,
+            message="数据总量 is only valid as a metric field, not as a dimension/filter/query field",
+            expected="use 数据总量 only in indicator_field_ids or omit metrics for count-style charts",
+            actual={"selector": raw, "role": role},
+            next_action="Choose a real QingBI field from app_get_fields.chart_fields for dimensions, filters, and query conditions.",
+            offending_fields=[{"field_id": _QINGBI_TOTAL_FIELD_ID, "field_name": "数据总量"}],
+        )
+    candidates = _chart_field_candidates(raw, chart_field_lookup=chart_field_lookup)
+    if not candidates:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
+            chart_type=chart_type,
+            message=f"field '{raw}' was not found in QingBI datasource fields for this app",
+            expected="chart fields must come from app_get_fields.chart_fields, not record schema or form-only fields",
+            actual={"selector": raw, "role": role},
+            next_action="Call app_get_fields and choose a field from chart_fields; if the system field is absent there, QingBI cannot use it for this report.",
+        )
+    if len(candidates) > 1:
+        _raise_chart_rule(
+            rule_code="CHART_FIELD_AMBIGUOUS",
+            chart_type=chart_type,
+            message=f"field '{raw}' matched multiple QingBI datasource fields",
+            expected="use an unambiguous field selector such as bi_field_id or field_<queId>",
+            actual={"selector": raw, "role": role, "candidate_count": len(candidates)},
+            next_action="Use one of the returned candidate bi_field_id values or field_<queId> selectors.",
+            offending_fields=[_chart_field_summary(item) for item in candidates],
+        )
+    return deepcopy(candidates[0])
+
+
+def _check_chart_slot_duplicates(*, chart_type: str, payload: dict[str, Any], slot_names: list[str]) -> None:
+    for slot_name in slot_names:
+        duplicates = _chart_duplicate_fields(_chart_fields(payload, slot_name))
+        if duplicates:
+            _raise_chart_rule(
+                rule_code="CHART_FIELD_ID_REPEAT",
+                chart_type=chart_type,
+                message=f"{chart_type} chart has duplicate field ids in {slot_name}",
+                expected=f"{slot_name} must not contain duplicated fieldId values",
+                actual={"slot": slot_name, "duplicate_count": len(duplicates)},
+                offending_fields=duplicates,
+                next_action="Use different fields for this slot, or remove the duplicated field before retrying.",
+            )
+
+
+def _histogram_metric_issue(metric: dict[str, Any]) -> dict[str, Any] | None:
+    field_id = _chart_field_id(metric)
+    if field_id == _QINGBI_TOTAL_FIELD_ID:
+        return {
+            "rule_code": "HISTOGRAM_DEFAULT_TOTAL_METRIC_UNSUPPORTED",
+            "message": "histogram cannot use 数据总量 as its metric",
+            "next_action": "Pass one explicit numeric field in indicator_field_ids and set config.aggregate such as sum/avg.",
+        }
+    field_type = str(metric.get("fieldType") or metric.get("field_type") or "").strip().lower()
+    if field_type not in _QINGBI_DECIMAL_FIELD_TYPES:
+        return {
+            "rule_code": "HISTOGRAM_METRIC_FIELD_TYPE_UNSUPPORTED",
+            "message": "histogram metric must be a numeric field",
+            "next_action": "Choose one number/amount field as indicator_field_ids for histogram.",
+        }
+    field_source = str(metric.get("fieldSource") or metric.get("field_source") or "").strip().lower()
+    bi_formula_type = str(metric.get("biFormulaType") or metric.get("bi_formula_type") or "").strip().lower()
+    aggre_field_id = str(metric.get("aggreFieldId") or metric.get("aggre_field_id") or "").strip()
+    if field_source == "formula" and (bi_formula_type in {"chart_agg", "agg"} or aggre_field_id):
+        return {
+            "rule_code": "HISTOGRAM_AGG_FORMULA_METRIC_UNSUPPORTED",
+            "message": "histogram metric cannot be an aggregate formula field",
+            "next_action": "Choose a plain numeric field, not an aggregate formula field.",
+        }
+    return None
+
+
+def _validate_public_chart_payload_rules(payload: dict[str, Any]) -> None:
+    chart_type = str(payload.get("chartType") or "").strip().lower()
+    dimensions = _chart_fields(payload, "selectedDimensions")
+    metrics = _chart_fields(payload, "selectedMetrics")
+    _check_chart_slot_duplicates(
+        chart_type=chart_type,
+        payload=payload,
+        slot_names=[
+            "selectedDimensions",
+            "selectedMetrics",
+            "xDimensions",
+            "yDimensions",
+            "xMetrics",
+            "yMetrics",
+            "leftMetrics",
+            "rightMetrics",
+        ],
+    )
+
+    if chart_type == "gauge":
+        if dimensions:
+            _raise_chart_rule(
+                rule_code="GAUGE_DIMENSION_NOT_ALLOWED",
+                chart_type=chart_type,
+                message="gauge chart must not have dimensions",
+                expected="0 dimensions",
+                actual={"dimension_count": len(dimensions)},
+                offending_fields=[_chart_field_summary(field) for field in dimensions],
+                next_action="Remove dimension_field_ids for gauge. The CLI clears public dimensions, but custom selectedDimensions in config must also be removed.",
+            )
+        if len(metrics) != 2:
+            _raise_chart_rule(
+                rule_code="GAUGE_METRIC_COUNT_INVALID",
+                chart_type=chart_type,
+                message="gauge chart requires exactly two metrics",
+                expected="exactly 2 non-duplicated metrics; one real metric plus 数据总量 is allowed",
+                actual={"metric_count": len(metrics), "metric_field_ids": [_chart_field_id(field) for field in metrics]},
+                offending_fields=[_chart_field_summary(field) for field in metrics],
+                next_action="Pass two different indicator_field_ids, or pass one explicit real numeric metric so the CLI can pair it with 数据总量.",
+            )
+    elif chart_type == "histogram":
+        if len(dimensions) > 1:
+            _raise_chart_rule(
+                rule_code="HISTOGRAM_DIMENSION_COUNT_INVALID",
+                chart_type=chart_type,
+                message="histogram chart supports at most one dimension",
+                expected="0 or 1 dimension",
+                actual={"dimension_count": len(dimensions)},
+                offending_fields=[_chart_field_summary(field) for field in dimensions],
+                next_action="Keep at most one dimension_field_ids value for histogram.",
+            )
+        if len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="HISTOGRAM_METRIC_COUNT_INVALID",
+                chart_type=chart_type,
+                message="histogram chart requires exactly one explicit metric",
+                expected="exactly 1 plain numeric metric",
+                actual={"metric_count": len(metrics), "metric_field_ids": [_chart_field_id(field) for field in metrics]},
+                offending_fields=[_chart_field_summary(field) for field in metrics],
+                next_action="Pass exactly one numeric field in indicator_field_ids; histogram cannot rely on the default count metric.",
+            )
+        issue = _histogram_metric_issue(metrics[0])
+        if issue:
+            _raise_chart_rule(
+                rule_code=str(issue["rule_code"]),
+                chart_type=chart_type,
+                message=str(issue["message"]),
+                expected="one plain decimal metric; not 数据总量 and not aggregate formula",
+                actual={"metric": _chart_field_summary(metrics[0])},
+                offending_fields=[_chart_field_summary(metrics[0])],
+                next_action=str(issue["next_action"]),
+            )
+    elif chart_type == "heatmap":
+        if len(dimensions) != 2 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="HEATMAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="heatmap chart requires two dimensions and one metric",
+                expected="2 dimensions and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly two dimension_field_ids and one indicator_field_ids value for heatmap.",
+            )
+    elif chart_type == "waterfall":
+        if len(dimensions) != 1 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="WATERFALL_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="waterfall chart requires one dimension and one metric",
+                expected="1 dimension and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly one dimension_field_ids value and one indicator_field_ids value for waterfall.",
+            )
+    elif chart_type == "treemap":
+        if len(dimensions) < 1 or len(dimensions) > 2 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="TREEMAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="treemap chart requires one or two dimensions and one metric",
+                expected="1-2 dimensions and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass one or two dimension_field_ids values and exactly one indicator_field_ids value for treemap.",
+            )
+    elif chart_type == "map":
+        if len(dimensions) != 1 or len(metrics) != 1:
+            _raise_chart_rule(
+                rule_code="MAP_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="map chart requires one dimension and one metric",
+                expected="1 dimension and 1 metric",
+                actual={"dimension_count": len(dimensions), "metric_count": len(metrics)},
+                next_action="Pass exactly one location/address dimension and one metric for map.",
+            )
+    elif chart_type == "scatter":
+        x_metrics = _chart_fields(payload, "xMetrics")
+        y_metrics = _chart_fields(payload, "yMetrics")
+        if not dimensions or len(x_metrics) != 1 or len(y_metrics) != 1:
+            _raise_chart_rule(
+                rule_code="SCATTER_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="scatter chart requires at least one dimension, one x metric, and one y metric",
+                expected=">=1 dimensions, exactly 1 x metric and 1 y metric",
+                actual={"dimension_count": len(dimensions), "x_metric_count": len(x_metrics), "y_metric_count": len(y_metrics)},
+                next_action="Pass at least one dimension_field_ids value and one or two indicator_field_ids values for scatter.",
+            )
+    elif chart_type == "dualaxes":
+        left_metrics = _chart_fields(payload, "leftMetrics")
+        right_metrics = _chart_fields(payload, "rightMetrics")
+        if not dimensions or (not left_metrics and not right_metrics):
+            _raise_chart_rule(
+                rule_code="DUALAXES_FIELD_COUNT_INVALID",
+                chart_type=chart_type,
+                message="dualaxes chart requires at least one dimension and at least one metric axis",
+                expected=">=1 dimensions and at least one left/right metric",
+                actual={"dimension_count": len(dimensions), "left_metric_count": len(left_metrics), "right_metric_count": len(right_metrics)},
+                next_action="Pass at least one dimension_field_ids value and one or two indicator_field_ids values for dualaxes.",
+            )
+
+
+def _explain_chart_backend_validation_error(
+    *,
+    api_error: QingflowApiError,
+    chart_type: str,
+    payload: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    backend_code = backend_code_int(api_error)
+    if backend_code not in {81002, 81005}:
+        return None
+    chart_type = str(chart_type or (payload or {}).get("chartType") or "").strip().lower()
+    if isinstance(payload, dict):
+        try:
+            _validate_public_chart_payload_rules(payload)
+        except ChartRuleViolation as violation:
+            return violation.diagnostics
+    if backend_code == 81005:
+        duplicate_fields: list[dict[str, Any]] = []
+        if isinstance(payload, dict):
+            for slot_name in [
+                "selectedDimensions",
+                "selectedMetrics",
+                "xDimensions",
+                "yDimensions",
+                "xMetrics",
+                "yMetrics",
+                "leftMetrics",
+                "rightMetrics",
+            ]:
+                duplicate_fields.extend(_chart_duplicate_fields(_chart_fields(payload, slot_name)))
+        return _chart_rule_diagnostics(
+            rule_code="CHART_FIELD_ID_REPEAT",
+            chart_type=chart_type,
+            message="QingBI rejected the chart because one field id is repeated in a chart slot",
+            expected="field ids must be unique within each dimension/metric slot",
+            actual={"backend_code": backend_code},
+            offending_fields=duplicate_fields,
+            next_action="Remove duplicated fields or pass two different explicit metrics before retrying.",
+        )
+    return _chart_rule_diagnostics(
+        rule_code="WRONG_METRIC_COUNT_OR_TYPE",
+        chart_type=chart_type,
+        message="QingBI rejected the chart because metric count or metric type does not satisfy this chart type",
+        expected="use the chart-type metric count/type rules from builder charts documentation",
+        actual={"backend_code": backend_code},
+        next_action="Check indicator_field_ids count and field types; for histogram use exactly one plain numeric metric, and for gauge use two non-duplicated metrics.",
+    )
+
+
 def _build_public_metric_fields(
     selectors: list[str],
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
     aggregate: str,
+    chart_type: str = "chart",
 ) -> list[dict[str, Any]]:
     normalized_aggregate = str(aggregate or "count").strip().lower()
     if normalized_aggregate == "count" or not selectors:
         return [_default_public_total_metric()]
     metrics: list[dict[str, Any]] = []
     for selector in selectors:
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(selector, chart_field_lookup=chart_field_lookup, chart_type=chart_type, role="metric")
+        field_id = _chart_field_id(qingbi_field)
+        if field_id == _QINGBI_TOTAL_FIELD_ID:
+            metrics.append(qingbi_field)
+            continue
+        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         metrics.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
+                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
                 "orderType": "default",
                 "alignType": "left",
                 "dateFormat": "yyyy-MM-dd",
@@ -12754,6 +14882,8 @@ def _build_public_metric_fields(
                 "supId": qingbi_field.get("supId"),
                 "beingTable": bool(qingbi_field.get("beingTable", False)),
                 "returnType": qingbi_field.get("returnType"),
+                "biFormulaType": qingbi_field.get("biFormulaType"),
+                "aggreFieldId": qingbi_field.get("aggreFieldId"),
             }
         )
     return metrics or [_default_public_total_metric()]
@@ -12783,7 +14913,9 @@ def _build_public_chart_filter_matrix(
     *,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
+    chart_type: str = "chart",
 ) -> list[list[dict[str, Any]]]:
     if not rules:
         return []
@@ -12799,16 +14931,21 @@ def _build_public_chart_filter_matrix(
         ViewFilterOperator.not_empty.value: 16,
     }
     for rule in rules:
-        field = _resolve_public_field(getattr(rule, "field_name", None), field_lookup=field_lookup)
-        field_id = _bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id)
-        qingbi_field = deepcopy(qingbi_fields_by_id.get(field_id, {}))
+        qingbi_field = _resolve_qingbi_chart_field(
+            getattr(rule, "field_name", None),
+            chart_field_lookup=chart_field_lookup,
+            chart_type=chart_type,
+            role="filter",
+        )
+        field_id = _chart_field_id(qingbi_field)
+        form_field = qingbi_field.get("_public_form_field") if isinstance(qingbi_field.get("_public_form_field"), dict) else {}
         operator = str(getattr(rule, "operator", ViewFilterOperator.eq.value).value if hasattr(getattr(rule, "operator", None), "value") else getattr(rule, "operator", ViewFilterOperator.eq.value))
         values = list(getattr(rule, "values", []) or [])
         group.append(
             {
                 "fieldId": field_id,
-                "fieldName": qingbi_field.get("fieldName") or field.get("name"),
-                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(field.get("type") or "")),
+                "fieldName": qingbi_field.get("fieldName") or form_field.get("name") or field_id,
+                "fieldType": qingbi_field.get("fieldType") or _qingbi_field_type_from_public_field(str(form_field.get("type") or "")),
                 "judgeType": judge_map.get(operator, 0),
                 "judgeValues": values,
                 "matchType": 1,
@@ -12822,6 +14959,7 @@ def _build_public_chart_config_payload(
     patch: ChartUpsertPatch,
     app_key: str,
     field_lookup: dict[str, dict[str, Any]],
+    chart_field_lookup: dict[str, Any],
     qingbi_fields_by_id: dict[str, dict[str, Any]],
 ) -> dict[str, Any]:
     config = deepcopy(patch.config)
@@ -12840,12 +14978,19 @@ def _build_public_chart_config_payload(
             patch.filters,
             app_key=app_key,
             field_lookup=field_lookup,
+            chart_field_lookup=chart_field_lookup,
             qingbi_fields_by_id=qingbi_fields_by_id,
+            chart_type=patch.chart_type.value,
         )
     query_condition_field_ids = []
     for selector in list(config.pop("query_condition_field_ids", []) or []):
-        field = _resolve_public_field(selector, field_lookup=field_lookup)
-        query_condition_field_ids.append(_bi_field_id_for_field(app_key=app_key, field=field, qingbi_fields_by_id=qingbi_fields_by_id))
+        field = _resolve_qingbi_chart_field(
+            selector,
+            chart_field_lookup=chart_field_lookup,
+            chart_type=patch.chart_type.value,
+            role="query_condition",
+        )
+        query_condition_field_ids.append(_chart_field_id(field))
     backend_chart_type = _map_public_chart_type_to_backend(patch.chart_type)
     if backend_chart_type == "gauge" and not patch.indicator_field_ids and "selectedMetrics" not in config:
         raise ValueError("gauge charts require at least one indicator_field_ids value; pass one metric and the CLI will pair it with 数据总量")
@@ -12853,14 +14998,18 @@ def _build_public_chart_config_payload(
         patch.dimension_field_ids,
         app_key=app_key,
         field_lookup=field_lookup,
+        chart_field_lookup=chart_field_lookup,
         qingbi_fields_by_id=qingbi_fields_by_id,
+        chart_type=patch.chart_type.value,
     )
     selected_metrics = _build_public_metric_fields(
         patch.indicator_field_ids,
         app_key=app_key,
         field_lookup=field_lookup,
+        chart_field_lookup=chart_field_lookup,
         qingbi_fields_by_id=qingbi_fields_by_id,
         aggregate=aggregate,
+        chart_type=patch.chart_type.value,
     )
     payload: dict[str, Any] = {
         "chartName": patch.name,
@@ -12914,6 +15063,7 @@ def _build_public_chart_config_payload(
         if key in config:
             payload[key] = deepcopy(config.pop(key))
     payload.update(config)
+    _validate_public_chart_payload_rules(payload)
     return payload
 
 
@@ -13089,7 +15239,9 @@ def _find_chart_by_name(items: Any, *, chart_name: str, chart_type: str | None =
     return deepcopy(candidates[-1])
 
 
-def _portal_position_payload(position: Any) -> dict[str, Any]:
+def _portal_position_payload(position: Any, *, inferred_mobile_y: int = 0) -> dict[str, Any]:
+    mobile_provided = bool(getattr(position, "mobile_provided", False))
+    mobile_rows = int(getattr(position, "mobile_h", 8)) if mobile_provided else int(getattr(position, "pc_h", 8))
     return {
         "pc": {
             "x": int(getattr(position, "pc_x", 0)),
@@ -13098,10 +15250,10 @@ def _portal_position_payload(position: Any) -> dict[str, Any]:
             "rows": int(getattr(position, "pc_h", 8)),
         },
         "mobile": {
-            "x": int(getattr(position, "mobile_x", 0)),
-            "y": int(getattr(position, "mobile_y", 0)),
-            "cols": int(getattr(position, "mobile_w", 12)),
-            "rows": int(getattr(position, "mobile_h", 8)),
+            "x": int(getattr(position, "mobile_x", 0)) if mobile_provided else 0,
+            "y": int(getattr(position, "mobile_y", 0)) if mobile_provided else int(inferred_mobile_y),
+            "cols": int(getattr(position, "mobile_w", 6)) if mobile_provided else 6,
+            "rows": mobile_rows,
         },
     }
 
@@ -13113,6 +15265,7 @@ def _portal_component_position_public(
     pc_y: int,
     pc_row_height: int,
     mobile_y: int,
+    layout_preset: str | None = None,
 ) -> tuple[dict[str, Any], int, int, int, int]:
     source_name = str(source_type or "").lower()
     if source_name == "filter":
@@ -13131,8 +15284,11 @@ def _portal_component_position_public(
         cols = 12
         rows = 2
     else:
-        cols = 8
-        rows = 4
+        if layout_preset == "dashboard_2col":
+            cols = 12
+        else:
+            cols = 8
+        rows = 6
     if cols == 24:
         if pc_x != 0:
             pc_y += pc_row_height
@@ -13155,6 +15311,73 @@ def _portal_component_position_public(
     return position, next_pc_x, next_pc_y, next_row_height, mobile_y + rows
 
 
+def _empty_portal_layout_diagnostics() -> dict[str, Any]:
+    return {
+        "pc_grid_columns": 24,
+        "mobile_grid_columns": 6,
+        "section_count": 0,
+        "explicit_position_count": 0,
+        "max_pc_right": None,
+        "safe_for_display": True,
+        "warnings": [],
+    }
+
+
+def _portal_layout_diagnostics(sections: list[PortalSectionPatch], components: list[dict[str, Any]]) -> dict[str, Any]:
+    diagnostics = _empty_portal_layout_diagnostics()
+    diagnostics["section_count"] = len(sections)
+    explicit_count = sum(1 for section in sections if section.position is not None)
+    diagnostics["explicit_position_count"] = explicit_count
+    pc_positions: list[dict[str, Any]] = []
+    warnings: list[dict[str, Any]] = []
+    for index, component in enumerate(components):
+        if not isinstance(component, dict):
+            continue
+        position = component.get("position") if isinstance(component.get("position"), dict) else {}
+        pc = position.get("pc") if isinstance(position.get("pc"), dict) else {}
+        if pc:
+            pc_positions.append(pc)
+        section = sections[index] if index < len(sections) else None
+        source_type = str(getattr(section, "source_type", "") or "").lower() if section is not None else ""
+        title = str(getattr(section, "title", "") or "").strip() if section is not None else None
+        cols = int(pc.get("cols") or 0)
+        rows = int(pc.get("rows") or 0)
+        if source_type == "chart" and (cols < 8 or rows < 5):
+            warnings.append(_warning(
+                "PORTAL_CHART_CARD_TOO_SMALL",
+                "chart portal card is too small; use at least pc.cols >= 8 and pc.rows >= 5, preferably rows >= 6",
+                section_index=index,
+                title=title,
+                pc=deepcopy(pc),
+            ))
+        if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
+            warnings.append(_warning(
+                "PORTAL_MOBILE_POSITION_MISSING",
+                "pc position was provided without mobile position; mobile layout was generated with 6-column grid",
+                section_index=index,
+                title=title,
+            ))
+    max_right = None
+    if pc_positions:
+        max_right = max(int(position.get("x") or 0) + int(position.get("cols") or 0) for position in pc_positions)
+    diagnostics["max_pc_right"] = max_right
+    if len(pc_positions) > 1 and max_right is not None and max_right <= 12:
+        warnings.append(_warning(
+            "PORTAL_LAYOUT_HALF_WIDTH",
+            "portal components only occupy the left half of the 24-column pc grid; this looks like a 12-column layout was used",
+            max_pc_right=max_right,
+            fix_hint="Use x=0/12 with cols=12 for two columns, x=0/8/16 with cols=8 for three columns, or omit position/use layout_preset.",
+        ))
+    diagnostics["warnings"] = warnings
+    diagnostics["safe_for_display"] = not any(item.get("code") in {"PORTAL_LAYOUT_HALF_WIDTH", "PORTAL_CHART_CARD_TOO_SMALL"} for item in warnings)
+    return diagnostics
+
+
+def _portal_layout_warning_items(layout_diagnostics: dict[str, Any]) -> list[dict[str, Any]]:
+    warnings = layout_diagnostics.get("warnings") if isinstance(layout_diagnostics, dict) else None
+    return [deepcopy(item) for item in warnings if isinstance(item, dict)] if isinstance(warnings, list) else []
+
+
 def _resolve_chart_reference(*, charts: QingbiReportTools, profile: str, ref: Any) -> dict[str, Any]:
     app_key = str(getattr(ref, "app_key", "") or "").strip()
     chart_id = str(getattr(ref, "chart_id", "") or "").strip()
@@ -13858,7 +16081,9 @@ def _department_scope_equal(left: Any, right: Any) -> bool:
 
 
 def _is_relation_target_metadata_read_restricted_api_error(error: QingflowApiError) -> bool:
-    return error.backend_code in {40002, 40027, 40161}
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027, 40161}
 
 
 def _relation_target_field_matches(left: dict[str, Any], right: dict[str, Any]) -> bool:
@@ -16768,13 +18993,38 @@ def _publish_verify_warnings(*, package_attached: bool | None, views_unavailable
     return warnings
 
 
-def _chart_apply_warnings(*, failed_items: list[dict[str, Any]], readback_unavailable: bool, verified: bool) -> list[dict[str, Any]]:
+def _chart_apply_warnings(
+    *,
+    failed_items: list[dict[str, Any]],
+    readback_unavailable: bool,
+    verified: bool,
+    delete_readback_issues: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
     warnings: list[dict[str, Any]] = []
+    delete_readback_issues = delete_readback_issues or []
     if failed_items:
         warnings.append(_warning("CHART_OPERATION_FAILED", "one or more chart operations failed", failed_count=len(failed_items)))
+    still_exists = [item for item in delete_readback_issues if item.get("readback_status") == "still_exists"]
+    unavailable = [item for item in delete_readback_issues if item.get("readback_status") == "unavailable"]
+    if still_exists:
+        warnings.append(
+            _warning(
+                "CHART_DELETE_READBACK_STILL_EXISTS",
+                "one or more delete requests completed, but chart_id readback still found the chart",
+                chart_ids=[item.get("chart_id") for item in still_exists if item.get("chart_id")],
+            )
+        )
+    if unavailable:
+        warnings.append(
+            _warning(
+                "CHART_DELETE_READBACK_UNAVAILABLE",
+                "one or more delete requests completed, but chart_id readback was unavailable",
+                chart_ids=[item.get("chart_id") for item in unavailable if item.get("chart_id")],
+            )
+        )
     if readback_unavailable:
         warnings.append(_warning("CHART_READBACK_PENDING", "chart readback is unavailable after apply"))
-    elif not verified and not failed_items:
+    elif not verified and not failed_items and not delete_readback_issues:
         warnings.append(_warning("CHART_VERIFICATION_INCOMPLETE", "chart apply completed but verification is incomplete"))
     return warnings
 
@@ -17273,6 +19523,56 @@ def _package_resource_signature(items: Any, *, public: bool) -> tuple[tuple[str,
     return tuple(sorted(_flatten_package_resource_identities(items, public=public)))
 
 
+def _publicize_package_list_item(item: dict[str, Any]) -> JSONObject:
+    package_id = _coerce_positive_int(item.get("package_id") or item.get("packageId") or item.get("tag_id") or item.get("tagId"))
+    raw_package_id = package_id if package_id is not None else item.get("package_id") or item.get("packageId") or item.get("tag_id") or item.get("tagId")
+    package_name = str(item.get("package_name") or item.get("packageName") or item.get("tag_name") or item.get("tagName") or "").strip()
+    raw_items = item.get("tagItems") if isinstance(item.get("tagItems"), list) else None
+    item_count = None
+    raw_item_count = item.get("item_count") if "item_count" in item else item.get("itemCount")
+    try:
+        if raw_item_count is not None:
+            coerced_count = int(raw_item_count)
+            if coerced_count >= 0:
+                item_count = coerced_count
+    except (TypeError, ValueError):
+        item_count = None
+    if item_count is None and raw_items is not None:
+        item_count = len(raw_items)
+    tag_icon = item.get("tag_icon") if "tag_icon" in item else item.get("tagIcon")
+    return {
+        "package_id": raw_package_id,
+        "package_name": package_name,
+        "tag_id": raw_package_id,
+        "tag_name": package_name,
+        "publish_status": item.get("publish_status") if "publish_status" in item else item.get("publishStatus"),
+        "being_trial": item.get("being_trial") if "being_trial" in item else item.get("beingTrial"),
+        "item_count": item_count,
+        "item_preview": deepcopy(item.get("item_preview") if "item_preview" in item else item.get("itemPreview") or []),
+        "tag_icon": tag_icon,
+        "icon_config": workspace_icon_config(str(tag_icon).strip() if tag_icon not in (None, "") else None),
+        "permissions": {
+            "can_add_app": item.get("can_add_app") if "can_add_app" in item else item.get("addAppStatus"),
+            "can_edit_app": item.get("can_edit_app") if "can_edit_app" in item else item.get("editAppStatus"),
+            "can_delete_app": item.get("can_delete_app") if "can_delete_app" in item else item.get("delAppStatus"),
+            "can_edit_package": item.get("can_edit_package") if "can_edit_package" in item else item.get("editTagStatus"),
+        },
+    }
+
+
+def _package_list_item_matches_query(item: dict[str, Any], query: str) -> bool:
+    needle = str(query or "").strip().casefold()
+    if not needle:
+        return True
+    haystacks = (
+        item.get("package_id"),
+        item.get("tag_id"),
+        item.get("package_name"),
+        item.get("tag_name"),
+    )
+    return any(needle in str(value or "").casefold() for value in haystacks)
+
+
 def _backend_package_items_from_public_items(items: list[dict[str, Any]], group_ids_by_path: dict[tuple[int, ...], int], *, path: tuple[int, ...] = ()) -> list[JSONObject]:
     backend_items: list[JSONObject] = []
     for index, item in enumerate(items):
@@ -19662,8 +21962,13 @@ def _serialize_view_button_binding(
     binding: ViewButtonBindingPatch,
     current_fields_by_name: dict[str, dict[str, Any]],
     valid_custom_button_ids: set[int],
+    allow_unverified_custom_button_id: bool = False,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
-    if binding.button_type == PublicViewButtonType.custom and binding.button_id not in valid_custom_button_ids:
+    if (
+        binding.button_type == PublicViewButtonType.custom
+        and binding.button_id not in valid_custom_button_ids
+        and not allow_unverified_custom_button_id
+    ):
         return {}, [
             {
                 "error_code": "UNKNOWN_CUSTOM_BUTTON",
@@ -19785,6 +22090,7 @@ def _normalize_portal_list_items(raw_items: Any) -> list[dict[str, Any]]:
                 "dash_key": dash_key or None,
                 "dash_name": dash_name or None,
                 "dash_icon": dash_icon,
+                "icon_config": workspace_icon_config(dash_icon),
                 "package_tag_ids": package_tag_ids,
             }
         )
@@ -20967,6 +23273,20 @@ def _associated_resource_patch_has_match_config(patch: AssociatedResourceUpsertP
     return bool(patch.match_mappings) or bool(patch.match_rules) or "match_mappings" in fields_set
 
 
+def _extract_associated_resource_id_from_result(result: Any) -> int | None:
+    if isinstance(result, dict):
+        for key in ("associated_item_id", "associatedItemId", "asosChartId", "id"):
+            item_id = _coerce_positive_int(result.get(key))
+            if item_id is not None:
+                return item_id
+        nested = result.get("result") or result.get("data")
+        if nested is not None and nested is not result:
+            return _extract_associated_resource_id_from_result(nested)
+    if isinstance(result, list) and len(result) == 1:
+        return _extract_associated_resource_id_from_result(result[0])
+    return None
+
+
 def _serialize_associated_resource_match_rules(match_rules: list[Any]) -> list[list[dict[str, Any]]]:
     if not match_rules:
         return []