@josephyan/qingflow-cli 0.2.0-beta.77 → 0.2.0-beta.78

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.77
+npm install @josephyan/qingflow-cli@0.2.0-beta.78
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.77 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.78 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.77",
+  "version": "0.2.0-beta.78",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b48"
+__version__ = "0.2.0b78"

package/src/qingflow_mcp/builder_facade/models.py

@@ -291,7 +291,7 @@ class FieldSelector(StrictModel):
 
     @model_validator(mode="after")
     def validate_selector(self) -> "FieldSelector":
-        if not any((self.field_id, self.que_id, self.name)):
+        if self.field_id is None and self.que_id is None and self.name is None:
             raise ValueError("selector must include field_id, que_id, or name")
         return self
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -8503,6 +8503,8 @@ def _hydrate_relation_field_configs(
     for field in resolved_fields:
         if not isinstance(field, dict) or field.get("type") != FieldType.relation.value:
             continue
+        if not bool(field.get("_relation_config_explicit")) and isinstance(field.get("_reference_config_template"), dict):
+            continue
         target_app_key = str(field.get("target_app_key") or "").strip()
         if not target_app_key:
             continue
@@ -8661,13 +8663,13 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         field["relation_mode"] = _relation_mode_from_optional_data_num(reference.get("optionalDataNum"))
         refer_questions = reference.get("referQuestions") if isinstance(reference.get("referQuestions"), list) else []
         visible_fields: list[dict[str, Any]] = []
-        display_field_que_id = _coerce_positive_int(reference.get("referQueId"))
+        display_field_que_id = _coerce_nonnegative_int(reference.get("referQueId"))
         display_field_name: str | None = None
         for item in refer_questions:
             if not isinstance(item, dict):
                 continue
             selector = {
-                "que_id": _coerce_positive_int(item.get("queId")),
+                "que_id": _coerce_nonnegative_int(item.get("queId")),
                 "name": str(item.get("queTitle") or "").strip() or None,
             }
             visible_fields.append(selector)
@@ -8682,6 +8684,8 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         }
         field["visible_fields"] = visible_fields
         field["field_name_show"] = bool(reference.get("fieldNameShow", True))
+        field["_reference_config_template"] = deepcopy(reference)
+        field["_relation_config_explicit"] = False
     if field_type == FieldType.department:
         department_scope = _normalize_department_scope_from_question(question)
         if department_scope is not None:
@@ -9341,7 +9345,7 @@ def _build_selector_map(fields: list[dict[str, Any]]) -> dict[str, int]:
     for index, field in enumerate(fields):
         field_id = str(field.get("field_id") or "")
         field_name = str(field.get("name") or "")
-        que_id = _coerce_positive_int(field.get("que_id"))
+        que_id = _coerce_nonnegative_int(field.get("que_id"))
         if field_id:
             mapping[f"field_id:{field_id}"] = index
         if field_name:
@@ -9356,7 +9360,7 @@ def _resolve_selector(selector_map: dict[str, int], selector: FieldSelector) ->
         value = selector_map.get(f"field_id:{selector.field_id}")
         if value is not None:
             return value
-    if selector.que_id:
+    if selector.que_id is not None:
         value = selector_map.get(f"que_id:{selector.que_id}")
         if value is not None:
             return value
@@ -9404,6 +9408,7 @@ def _field_patch_to_internal(patch: FieldPatch) -> dict[str, Any]:
         "que_id": None,
         "default_type": 1,
         "default_value": None,
+        "_relation_config_explicit": patch.type == PublicFieldType.relation,
     }
 
 
@@ -9474,7 +9479,7 @@ def _field_selector_payload_equal(left: Any, right: Any) -> bool:
         return False
     return (
         str(left.get("field_id") or "") == str(right.get("field_id") or "")
-        and _coerce_positive_int(left.get("que_id")) == _coerce_positive_int(right.get("que_id"))
+        and _coerce_nonnegative_int(left.get("que_id")) == _coerce_nonnegative_int(right.get("que_id"))
         and str(left.get("name") or "") == str(right.get("name") or "")
     )
 
@@ -9629,6 +9634,10 @@ def _code_block_binding_equal(left: Any, right: Any) -> bool:
 
 def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
     payload = mutation.model_dump(mode="json", exclude_none=True)
+    relation_config_explicit = (
+        payload.get("type") == FieldType.relation.value
+        or any(key in payload for key in ("target_app_key", "display_field", "visible_fields", "relation_mode"))
+    )
     if "name" in payload:
         field["name"] = payload["name"]
     if "type" in payload:
@@ -9671,6 +9680,11 @@ def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
         field["custom_button_text"] = payload["custom_button_text"]
     if "subfields" in payload:
         field["subfields"] = [_field_patch_to_internal(item) for item in payload["subfields"]]
+    if relation_config_explicit:
+        field["_relation_config_explicit"] = True
+    elif payload.get("type") and payload.get("type") != FieldType.relation.value:
+        field.pop("_relation_config_explicit", None)
+        field.pop("_reference_config_template", None)
 
 
 def _resolve_field_selector_with_uniqueness(
@@ -9682,8 +9696,8 @@ def _resolve_field_selector_with_uniqueness(
     selector = FieldSelector.model_validate(selector_payload)
     if selector.field_id:
         matched = [field for field in fields if str(field.get("field_id") or "") == str(selector.field_id)]
-    elif selector.que_id:
-        matched = [field for field in fields if _coerce_positive_int(field.get("que_id")) == _coerce_positive_int(selector.que_id)]
+    elif selector.que_id is not None:
+        matched = [field for field in fields if _coerce_nonnegative_int(field.get("que_id")) == _coerce_nonnegative_int(selector.que_id)]
     elif selector.name:
         name = str(selector.name or "").strip()
         matched = [field for field in fields if str(field.get("name") or "").strip() == name]
@@ -11142,7 +11156,7 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
         },
         temp_id,
     )
-    if field.get("que_id"):
+    if _coerce_nonnegative_int(field.get("que_id")) is not None:
         question["queId"] = field["que_id"]
     else:
         question["queTempId"] = temp_id
@@ -11152,13 +11166,23 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
     if "default_value" in field:
         question["queDefaultValue"] = field.get("default_value")
     if field.get("type") == FieldType.relation.value:
-        reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
-        reference["referAppKey"] = field.get("target_app_key")
-        reference["_targetEntityId"] = field.get("target_app_key")
-        if field.get("target_field_que_id"):
-            reference["referQueId"] = field.get("target_field_que_id")
-        reference["optionalDataNum"] = _relation_mode_to_optional_data_num(field.get("relation_mode"))
-        question["referenceConfig"] = reference
+        preserved_reference = (
+            deepcopy(field.get("_reference_config_template"))
+            if not bool(field.get("_relation_config_explicit")) and isinstance(field.get("_reference_config_template"), dict)
+            else None
+        )
+        if preserved_reference is not None:
+            preserved_reference["referAppKey"] = field.get("target_app_key")
+            preserved_reference["_targetEntityId"] = field.get("target_app_key")
+            question["referenceConfig"] = preserved_reference
+        else:
+            reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
+            reference["referAppKey"] = field.get("target_app_key")
+            reference["_targetEntityId"] = field.get("target_app_key")
+            if field.get("target_field_que_id") is not None:
+                reference["referQueId"] = field.get("target_field_que_id")
+            reference["optionalDataNum"] = _relation_mode_to_optional_data_num(field.get("relation_mode"))
+            question["referenceConfig"] = reference
     if field.get("type") == FieldType.department.value:
         scope_type, scope_payload = _serialize_department_scope_for_question(field.get("department_scope"))
         question["deptSelectScopeType"] = scope_type

package/src/qingflow_mcp/cli/main.py

@@ -6,6 +6,7 @@ import sys
 from typing import Any, Callable, TextIO
 
 from ..errors import QingflowApiError
+from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
@@ -49,6 +50,8 @@ def run(
         return 2
     context = context_factory()
     try:
+        if not bool(args.json):
+            _emit_cli_effective_context_notice(args, context, stream=err)
         result = handler(args, context)
     except RuntimeError as exc:
         payload = trim_error_response(_parse_error_payload(exc))
@@ -145,5 +148,31 @@ def _result_exit_code(result: dict[str, Any]) -> int:
     return 0
 
 
+def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliContext, *, stream: TextIO) -> None:
+    spec = cli_public_tool_spec_from_namespace(args)
+    if spec is None or not spec.cli_show_effective_context:
+        return
+    sessions = getattr(context, "sessions", None)
+    if sessions is None or not hasattr(sessions, "get_profile"):
+        return
+    profile_name = str(getattr(args, "profile", "default") or "default")
+    try:
+        session_profile = sessions.get_profile(profile_name)
+    except Exception:
+        session_profile = None
+    workspace_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
+    workspace_name = getattr(session_profile, "selected_ws_name", None) if session_profile is not None else None
+    if workspace_id is None:
+        workspace_label = "(not selected)"
+    elif workspace_name:
+        workspace_label = f"{workspace_name} ({workspace_id})"
+    else:
+        workspace_label = str(workspace_id)
+    lines = [f"Context: profile={profile_name} workspace={workspace_label}"]
+    if spec.cli_context_write and profile_name == "default":
+        lines.append("Warning: using default profile for a workspace-sensitive write command")
+    stream.write("\n".join(lines) + "\n")
+
+
 if __name__ == "__main__":
     main()

package/src/qingflow_mcp/public_surface.py

@@ -17,6 +17,8 @@ class PublicToolSpec:
     mcp_public: bool = True
     cli_public: bool = True
     has_contract: bool = False
+    cli_show_effective_context: bool = False
+    cli_context_write: bool = False
 
     @property
     def trim_key(self) -> str:
@@ -34,13 +36,13 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "auth_logout", ("auth_logout",), ("auth", "logout")),
     PublicToolSpec(USER_DOMAIN, "workspace_list", ("workspace_list",), ("workspace", "list")),
     PublicToolSpec(USER_DOMAIN, "workspace_select", ("workspace_select",), ("workspace", "select")),
-    PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list")),
-    PublicToolSpec(USER_DOMAIN, "app_search", ("app_search",), ("app", "search")),
-    PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get")),
-    PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list")),
-    PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get")),
-    PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get")),
-    PublicToolSpec(USER_DOMAIN, "chart_get", ("chart_get",), ("chart", "get")),
+    PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "app_search", ("app_search",), ("app", "search"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "chart_get", ("chart_get",), ("chart", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "file_get_upload_info", ("file_get_upload_info",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "file_upload_local", ("file_upload_local",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "feedback_submit", ("feedback_submit",), cli_public=False),
@@ -78,22 +80,22 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze")),
-    PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list")),
-    PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get")),
-    PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert")),
-    PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update")),
-    PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete")),
+    PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_import_template_get", ("record_import_template_get",), ("import", "template")),
     PublicToolSpec(USER_DOMAIN, "record_import_verify", ("record_import_verify",), ("import", "verify")),
     PublicToolSpec(USER_DOMAIN, "record_import_repair_local", ("record_import_repair_local",), ("import", "repair")),
     PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start")),
     PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status")),
-    PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run")),
-    PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list")),
-    PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get")),
-    PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action")),
-    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log")),
+    PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False, cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "directory_search", ("directory_search",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), cli_public=False),
     PublicToolSpec(USER_DOMAIN, "directory_list_all_internal_users", ("directory_list_all_internal_users",), cli_public=False),
@@ -111,42 +113,42 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), ("builder", "auth", "logout"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), ("builder", "workspace", "list"), cli_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "workspace_select", ("workspace_select",), ("builder", "workspace", "select"), cli_public=False),
-    PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "package_list", ("package_list",), ("builder", "package", "list"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "package_resolve", ("package_resolve",), ("builder", "package", "resolve"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_list", ("package_list",), ("builder", "package", "list"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_resolve", ("package_resolve",), ("builder", "package", "resolve"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
-    PublicToolSpec(BUILDER_DOMAIN, "package_create", ("package_create",), ("builder", "package", "create"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "solution_install", ("solution_install",), ("builder", "solution", "install"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "member_search", ("member_search",), ("builder", "member", "search"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "role_search", ("role_search",), ("builder", "role", "search"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "package_attach_app", ("package_attach_app",), ("builder", "package", "attach-app"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_update", ("app_custom_button_update",), ("builder", "button", "update"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_delete", ("app_custom_button_delete",), ("builder", "button", "delete"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get", ("app_get",), ("builder", "app", "get", "summary"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get_fields", ("app_get_fields",), ("builder", "app", "get", "fields"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_repair_code_blocks", ("app_repair_code_blocks",), ("builder", "app", "repair-code-blocks"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get_layout", ("app_get_layout",), ("builder", "app", "get", "layout"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get_views", ("app_get_views",), ("builder", "app", "get", "views"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get_flow", ("app_get_flow",), ("builder", "app", "get", "flow"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_get_charts", ("app_get_charts",), ("builder", "app", "get", "charts"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "portal_list", ("portal_list",), ("builder", "portal", "list"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "portal_get", ("portal_get",), ("builder", "portal", "get"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "view_get", ("view_get",), ("builder", "view", "get"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "chart_get", ("chart_get",), ("builder", "chart", "get"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_schema_apply", ("app_schema_apply",), ("builder", "schema", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_layout_apply", ("app_layout_apply",), ("builder", "layout", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_flow_apply", ("app_flow_apply",), ("builder", "flow", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_create", ("package_create",), ("builder", "package", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "solution_install", ("solution_install",), ("builder", "solution", "install"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "member_search", ("member_search",), ("builder", "member", "search"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_search", ("role_search",), ("builder", "role", "search"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_attach_app", ("package_attach_app",), ("builder", "package", "attach-app"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_update", ("app_custom_button_update",), ("builder", "button", "update"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_delete", ("app_custom_button_delete",), ("builder", "button", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get", ("app_get",), ("builder", "app", "get", "summary"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_fields", ("app_get_fields",), ("builder", "app", "get", "fields"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_repair_code_blocks", ("app_repair_code_blocks",), ("builder", "app", "repair-code-blocks"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_layout", ("app_get_layout",), ("builder", "app", "get", "layout"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_views", ("app_get_views",), ("builder", "app", "get", "views"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_flow", ("app_get_flow",), ("builder", "app", "get", "flow"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_charts", ("app_get_charts",), ("builder", "app", "get", "charts"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_list", ("portal_list",), ("builder", "portal", "list"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_get", ("portal_get",), ("builder", "portal", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "view_get", ("view_get",), ("builder", "view", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "chart_get", ("chart_get",), ("builder", "chart", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_schema_apply", ("app_schema_apply",), ("builder", "schema", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_layout_apply", ("app_layout_apply",), ("builder", "layout", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_flow_apply", ("app_flow_apply",), ("builder", "flow", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True, cli_show_effective_context=True),
 )
 
 
@@ -195,6 +197,13 @@ def cli_trim_key_from_namespace(args: Namespace) -> str | None:
     return spec.trim_key if spec is not None else None
 
 
+def cli_public_tool_spec_from_namespace(args: Namespace) -> PublicToolSpec | None:
+    route = cli_route_from_namespace(args)
+    if route is None:
+        return None
+    return PUBLIC_TOOL_BY_CLI_ROUTE.get(route)
+
+
 def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
     command = getattr(args, "command", None)
     if not isinstance(command, str) or not command: