@thinkingai/ae-cli 1.0.24 → 1.0.28

package/skills/ae-analysis/SKILL.md

@@ -6,7 +6,6 @@ description: "AE/TE/ThinkingEngine/ThinkingAI ae-cli manual for analysis-side ta
 
 # ae-analysis
 
-> **CRITICAL - This skill is self-contained.** Use the Global AE CLI Rules below; do not require a separate shared skill for analysis-side tasks.
 > **CRITICAL - For all commands that require `project_id`, you MUST satisfy `PROJECT_ID_GATE` first (no guessing): verify the project by ID/name with `analysis_common +list_projects` only when there is no valid project context yet, when the user switches project/host/environment, or when the supplied project is ambiguous. Reuse a project already verified in the same continuous conversation and same host/environment.**
 > **CRITICAL - For write operations in this skill, you MUST complete the post-write link loop when applicable:** after success and extractable `resource_id`, call `analysis_common +get_resource_url` and return the main result + resource link (or explicit link-failure reason).
 > **CRITICAL - Before running any `+<tool_name>` command, you MUST first read the corresponding `references/<tool_name>.md`.** The reference filename always equals the command name without the leading `+`, for example `+query_adhoc` -> `references/query_adhoc.md`.
@@ -21,6 +20,7 @@ Global parameters:
 |---|---|
 | `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli analysis +list_dashboards --host <url>`. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.

package/skills/ae-analysis/references/drilldown_user_events.md

@@ -55,7 +55,7 @@ ae-cli analysis +drilldown_user_events --dry-run
 | `--entity_value` | No | Optional entity value for multi-entity scenarios |
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--page_num` | No | Start page number, default 1 |
-| `--page_size` | No | Page size, default 20, max 50 |
+| `--page_size` | No | Page size. Default: 1000, maximum: 100000 |
 | `--timeout_minutes` | No | Query timeout in minutes |
 
 ## Decision Rules

package/skills/ae-analysis/references/drilldown_users.md

@@ -55,14 +55,14 @@ ae-cli analysis +drilldown_users --dry-run
 | `--include_total` | No | Whether to query users from the total row. Default: false |
 | `--relation_val` | No | Relation value used in relation analysis scenarios |
 | `--use_cache` | No | Whether to use cache. Default: true |
-| `--limit` | No | Optional limit. Default: 20, maximum: 50. |
+| `--limit` | No | Optional limit. Default: 1000, maximum: 100000. |
 | `--offset` | No | Optional offset. Default: 0. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. |
 
 ## Decision Rules
 - Drilldown positioning parameters must come from upstream analysis results and must not be fabricated.
 - `qp` must not be rewritten or "simplified"; it should remain consistent with the source analysis.
-- For pagination, use `--limit` and `--offset` together. Default limit is 20.
+- For pagination, use `--limit` and `--offset` together. Default limit is 1000, maximum 100000.
 - For the first run, it is recommended to pass only the required parameters (`--project_id`, `--model_type`, `--qp`) and add optional parameters after confirming the chain works.
 - Wrap JSON parameters in single quotes (for example `--qp '{}'`, `--drilldown_groups '{}'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, validate with a short range first and then expand gradually.

package/skills/ae-analysis/references/list_clusters.md

@@ -1,4 +1,4 @@
-# analysis_audience +list_clusters (Cluster Search)
+# analysis_audience +list_clusters (Audience/User Segment Cluster Search)
 
 > **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
 
@@ -8,8 +8,10 @@ Domain: **Cluster Management**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
+**Term boundary:** This command lists audience/user segment clusters only. It is not a server, region, or deployment inventory tool.
+
 ## Use Cases
-- List cluster metadata accessible to the current user in the project.
+- List audience/user segment cluster metadata accessible to the current user in the project.
 - Supports payload governance parameters: `query`, `fields`, `limit`, `offset`.
 - Returns a paginated envelope (items + total + limit + offset + hasMore), not cluster members.
 

package/skills/ae-analysis/references/query_adhoc.md

@@ -95,7 +95,7 @@ ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type>
 | `--is_sort_by_columns` | No | Whether to sort query results by columns. Default: false |
 | `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". If omitted, service auto-resolves when `qp.eventView.recentDay` exists and `startTime`/`endTime` is incomplete; otherwise defaults to false. |
 | `--fields` | No | Optional fields to return. Must match column names in result. Invalid fields cause INVALID_FIELDS error. |
-| `--limit` | No | Optional limit. Default: 20, maximum: 50. |
+| `--limit` | No | Optional limit. Default: 1000, maximum: 100000. |
 | `--offset` | No | Optional offset. Default: 0. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. |
 
@@ -103,7 +103,8 @@ ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type>
 - On the first run, start with only the required parameters (`--project_id`,`--model_type`,`--qp`), and add optional parameters after confirming the path works.
 - Do not call this command with placeholder QP such as `{}`. For builder-supported models, wait for builder `status=generated`; for non-builder models, build QP from verified schema/metadata first.
 - For builder-supported models, do not run metadata/schema lookup to "help" the builder. The builder is the metadata resolver.
-- For pagination, use `--limit` and `--offset` together. Default limit is 20.
+- For pagination, use `--limit` and `--offset` together. Default limit is 1000, maximum 100000.
+- For `model_type=sql`, use exactly one row limit: either put `LIMIT` in the SQL, or use `--limit`. If both are present they must be equal — `query_adhoc` rejects mismatched values to avoid silently sampled or duplicated results. When the SQL already has a trailing `LIMIT`, you may omit `--limit` and the SQL governs.
 - Use `--fields` to select specific columns for lighter response payloads.
 - `event`, `retention`, `funnel`, and `prop_analysis` must not manually craft QP with schema-first flow; call the builder and use the returned `qp`.
 - For non-builder models, `qp` must satisfy both schema structure and project metadata constraints.

package/skills/ae-analysis/references/query_entity_details.md

@@ -39,7 +39,7 @@ ae-cli analysis +query_entity_details --dry-run
 | `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `analysis_meta +list_properties` in the same `project_id`. |
 | `--sort_by` | No | Optional sort field                                                                                                                                                                                                                     |
 | `--sort_order` | No | Optional sort order. Supported values: asc and desc                                                                                                                                                                                     |
-| `--limit` | No | Optional result limit. Default: 20, maximum: 50                                                                                                                                                                                         |
+| `--limit` | No | Optional result limit. Default: 1000, maximum: 100000                                                                                                                                                                                         |
 | `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8                                                                                                                                                                                               |
 | `--use_cache` | No | Whether to use cache. Default: true                                                                                                                                                                                                     |
 

package/skills/ae-analysis-global/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ae-analysis-global
+version: 1.0.0
+description: "Overlay rules for AE/TE analysis global multi-cluster mode. Use only when ae-cli config cluster-mode status reports sw_cfg_enable_global_query=true. This skill supplements ae-analysis; it does not replace it."
+---
+
+# ae-analysis-global
+
+
+This is an overlay for `ae-analysis`. First use the normal `ae-analysis` rules and matching command references. Apply the rules below only when local multi-cluster mode is enabled (`ae-cli config cluster-mode status`):
+
+```bash
+ae-cli config cluster-mode status
+```
+
+The result must contain:
+
+```json
+{"sw_cfg_enable_global_query": true}
+```
+
+If the mode is not enabled, do not use this overlay.
+
+For commands added only by this overlay, read this skill's matching reference file before composing commands. Example: `+list_query_clusters` -> `references/list_query_clusters.md`.
+
+Every command accepts `--host <url>` to override the active AE host, and it may be placed after the subcommand (e.g. `ae-cli analysis +list_query_clusters --project_id <id> --host <url>`). Host selection is independent of `--cluster_query_scope`: `--host` chooses which AE instance to call, while `--cluster_query_scope` / `--slave_cluster_id` choose which cluster within global mode.
+
+## Routing Rules
+
+- In this overlay, **query cluster / service cluster / deployment cluster** means multi-cluster routing for analysis queries. **audience/user segment cluster** means audience membership assets under `analysis_audience`.
+- If the user asks for cluster inventory or cluster info, call `ae-cli analysis +list_query_clusters --project_id <project_id>`. Localized examples include "集群信息" and "有哪些集群".
+- Do not answer query-cluster inventory questions with `ae-cli analysis_audience +list_clusters` unless the user explicitly asks for audience clusters, cohorts, segments, user membership, or cluster definitions.
+- If the user mentions country, region, server, shard, site, market, or deployment area semantics, call `ae-cli analysis +list_query_clusters --project_id <project_id>` before choosing query scope.
+- Match slave cluster intent only against `slaveClusters[].clusterId`, `slaveClusters[].clusterName`, and `slaveClusters[].clusterDesc` returned by `+list_query_clusters`.
+- If a matching accessible slave cluster exists, pass `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>` to `+query_report_data`, `+query_dashboard_report_data`, or `+query_adhoc`.
+- Use `--cluster_query_scope GLOBAL` only when the user clearly asks for global, all clusters, all servers, or cross-cluster aggregated data, and `permissions.canQueryGlobal=true`.
+- If the user does not express global or slave-cluster intent, omit `--cluster_query_scope`.
+- If requested global/slave scope is not allowed, explain `permissions.allowedClusterQueryParams` instead of guessing forbidden parameters.
+- For `+query_adhoc --model_type sql`, never pass `--cluster_query_scope`; SQL model analysis only supports the current self cluster.
+
+## Response Wording
+
+- For `+list_query_clusters`, call the result "query clusters" and summarize `currentCluster`, `slaveClusters`, and `permissions.allowedClusterQueryParams`.
+- For `analysis_audience +list_clusters`, call the result "audience clusters" or "user segments"; do not call those results query clusters.
+
+## Commands Added By Multi-Cluster Mode
+
+- `ae-cli analysis +list_query_clusters --project_id <project_id>`
+- `ae-cli analysis +query_report_data ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`
+- `ae-cli analysis +query_dashboard_report_data ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`
+- `ae-cli analysis +query_adhoc ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`

package/skills/ae-analysis-global/references/list_query_clusters.md

@@ -0,0 +1,67 @@
+# analysis +list_query_clusters (Query Cluster Options)
+
+> **Prerequisite:** Use this reference only after `ae-analysis-global` confirms local multi-cluster mode is enabled. This command is added by the global overlay, not by the base `ae-analysis` skill.
+
+Domain: **Multi-Cluster Query Routing**
+
+## Use Cases
+
+- List the query cluster options accessible to the current account in the project.
+- Answer user questions such as "cluster info", "available query clusters", or "current cluster". Localized examples include "集群信息" and "有哪些集群".
+- Decide whether a later report/dashboard/ad-hoc query should use the current self cluster, global aggregated data, or one specific slave cluster.
+- Resolve country, region, game server, service shard, site, market, or deployment area wording to an accessible slave cluster before passing `cluster_query_scope=SLAVE`.
+
+This command is not for audience/user segment clusters. For cohort, audience, or segment assets, use `analysis_audience +list_clusters`.
+
+## Commands
+
+```bash
+ae-cli analysis +list_query_clusters --project_id <project_id>
+ae-cli analysis +list_query_clusters --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID used to resolve the current account's cluster query permissions. |
+
+## Output Shape
+
+The result data follows the server DTO used by `list_query_clusters`:
+
+| Field | Description |
+|---|---|
+| `globalQueryEnabled` | Whether global query is enabled by server config. |
+| `currentCluster` | The current self query cluster. Fields: `clusterId`, `clusterName`, `clusterDesc`. |
+| `slaveClusters` | Accessible slave query clusters for this account and project. Each item has `clusterId`, `clusterName`, `clusterDesc`. |
+| `permissions` | Permission summary for choosing query scope. |
+| `permissions.canQueryCurrent` | Whether the user can query the current self cluster. Usually true. |
+| `permissions.canQueryGlobal` | Whether `cluster_query_scope=GLOBAL` is allowed. |
+| `permissions.canQueryAllSlaveClusters` | Whether any enabled slave cluster may be queried. |
+| `permissions.allowedSlaveClusterIds` | Slave cluster IDs this account may use. |
+| `permissions.allowedClusterQueryParams` | Human-readable allowed query parameter combinations, e.g. `omit clusterQueryScope`, `clusterQueryScope=GLOBAL`, or `clusterQueryScope=SLAVE, slaveClusterId in [...]`. |
+
+## Decision Rules
+
+- For query-cluster inventory or cluster-info questions, call this command and answer with "query clusters", not "audience clusters".
+- Default query behavior is to omit `cluster_query_scope`, which queries the current self cluster or follows the tool-specific default.
+- Pass `--cluster_query_scope GLOBAL` only when the user clearly asks for global, all clusters, all servers, cross-cluster aggregation, or equivalent aggregate wording, and `permissions.canQueryGlobal=true`.
+- Pass `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>` only after this command confirms a requested country, region, server, site, market, or deployment maps to an accessible `slaveClusters[]` item.
+- Match slave intent only against `slaveClusters[].clusterId`, `slaveClusters[].clusterName`, and `slaveClusters[].clusterDesc`.
+- If the requested scope is not allowed, do not guess forbidden parameters. Explain `permissions.allowedClusterQueryParams`.
+- For `+query_adhoc --model_type sql`, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster.
+
+## Recommended Chains
+
+- Cluster inventory / cluster info -> `analysis +list_query_clusters`
+- Query DAU for Japan server -> `analysis +list_query_clusters` -> match JP/Japan slave cluster -> query report/dashboard/ad-hoc with `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>`
+- Query all-cluster aggregated DAU -> `analysis +list_query_clusters` -> if `permissions.canQueryGlobal=true`, query with `--cluster_query_scope GLOBAL`
+- View audience cohorts or user segments -> `analysis_audience +list_clusters` instead
+
+## Response Wording
+
+- Use "current query cluster" for `currentCluster`.
+- Use "accessible slave query clusters" for `slaveClusters`.
+- Use "allowed query-scope parameters" for `permissions.allowedClusterQueryParams`.
+- Do not call `analysis_audience +list_clusters` results query clusters; those are audience clusters or user segments.

package/skills/ae-community/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: ae-community
 version: 2.0.0
-description: "AE community analysis: post search, comment sentiment, topic trends, risky content, livestream data. Includes AE CLI authentication, global parameters, and safety rules (self-contained)."
+description: "AE community analysis: post search, comment sentiment, topic trends, risky content, livestream data."
 ---
 
 # ae-community
 
-> **CRITICAL - This skill is self-contained.** Use the Global AE CLI Rules below; do not require a separate shared skill for community-side tasks.
-
 The AE Community domain provides social data analysis: post/video search, comment analytics, sentiment and topics, risk monitoring, and livestream metrics. Commands run as **`ae-cli community +<subcommand>`** — every community subcommand uses the **`+` prefix**.
 
 | Route (MCP) | CLI service | Responsibility |
@@ -28,6 +26,7 @@ Global parameters:
 |---|---|
 | `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli community +<command> --host <url>`. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.

package/skills/ae-dataops/SKILL.md

@@ -6,8 +6,6 @@ description: "AE Data Development and Operations: Data warehouse management, flo
 
 # ae-dataops
 
-> **CRITICAL - This skill is self-contained.** Use the Global AE CLI Rules below; do not require a separate shared skill for DataOps-side tasks.
-
 The AE Data Development and Operations domain provides capabilities for data warehouse management, flow orchestration, IDE SQL queries, data integration, operations and backfill management, including the following subcommands:
 
 | Subcommand | Responsibility | Corresponding Scenario Skill |
@@ -33,6 +31,7 @@ Global parameters:
 |---|---|
 | `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli dataops_ide +<command> --host <url>`. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.

package/skills/ae-engage/SKILL.md

@@ -18,6 +18,7 @@ Global parameters:
 |---|---|
 | `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli engage +<command> --host <url>`. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.
@@ -79,6 +80,12 @@ ae-cli engage +config_channel_list --project_id 1
 # Query the task list
 ae-cli engage +task_list --project_id 1 --req '{"pageNum":1,"pageSize":20}'
 
+# Build a save_task guide before composing the final req
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+
+# Save a task draft (create when req.taskId is omitted)
+ae-cli engage +save_task --project_id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
+
 # Query task details
 ae-cli engage +task_detail --project_id 1 --task_id task_123
 
@@ -182,6 +189,8 @@ For more detailed generation rules, consult these references first:
 ```bash
 ae-cli --dry-run engage +channel_list --project_id 1
 ae-cli --dry-run engage +task_list --project_id 1 --req '{"pageNum":1,"pageSize":20}'
+ae-cli --dry-run engage +build_task_save_guide --project_id 1 --req '{}'
+ae-cli --dry-run engage +save_task --project_id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
 ae-cli --dry-run engage +flow_list --project_id 1
 ```
 
@@ -190,6 +199,8 @@ ae-cli --dry-run engage +flow_list --project_id 1
 More detailed single-command guidance is available in the business-oriented `references/` directory:
 
 - `references/channel-list.md`
+- `references/build-task-save-guide.md`
+- `references/save-task.md`
 - `references/task-list.md`
 - `references/config-item-list.md`
 - `references/flow-list.md`
@@ -204,7 +215,7 @@ This split documentation structure is easier to extend later, because commands w
 
 ### task
 
-`+task_data_overview`, `+task_data_detail`, `+task_metric_detail`, `+task_experiment_report`, `+task_detail`, `+task_list`, `+task_stats`, `+manage_task`
+`+task_data_overview`, `+task_data_detail`, `+task_metric_detail`, `+task_experiment_report`, `+task_detail`, `+task_list`, `+task_stats`, `+build_task_save_guide`, `+save_task`, `+manage_task`
 
 ### config
 
@@ -225,4 +236,17 @@ The following commands are write operations. Confirm that the user intent is exp
 - Channels and config channels: `+add_channel`, `+delete_channel`, `+update_channel_status`, `+delete_config_channel`, `+update_config_channel_status`
 - Strategies and config items: `+delete_config_item`, `+copy_config_template`, `+manage_strategy`
 - Flows: `+save_flow`, `+modify_flow_base_info`, `+manage_flow`, `+delete_flow`
-- Tasks: `+manage_task`
+- Tasks: `+save_task`, `+manage_task`
+
+For task draft creation or update, use this workflow:
+
+1. `ae-cli engage +channel_list --project_id <projectId>`
+2. `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`
+3. If the guide says QP-derived fields are needed, call `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`
+4. `ae-cli engage +save_task --project_id <projectId> --req '{...}'`
+
+`+build_task_save_guide` is a read-only helper. It returns scenario-specific required fields, channel content schema, unsupported combinations, examples, and a handoff template for `save_task`.
+
+`+save_task` only saves a draft. It does not submit approval, does not start sending, and does not trigger task execution. If `req.taskId` is omitted it creates a new draft; if `req.taskId` is present it updates an existing draft. Update mode only supports draft tasks, and omitted fields can inherit from the existing draft before validation.
+
+The audience schema query `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition` is not a fixed preflight step. Call it only when the guide indicates that you must construct `targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`.

package/skills/ae-engage/references/add-approver.md

@@ -1,6 +1,5 @@
 # ae-engage +add_approver
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Batch add approvers.
 

package/skills/ae-engage/references/add-channel.md

@@ -1,6 +1,5 @@
 # ae-engage +add_channel
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Create a new Engage channel.
 

package/skills/ae-engage/references/approver-list.md

@@ -1,6 +1,5 @@
 # ae-engage +approver_list
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Query the project approver list.
 

package/skills/ae-engage/references/build-task-save-guide.md

@@ -0,0 +1,283 @@
+# ae-engage `+build_task_save_guide`
+
+Build a scenario-specific guide for constructing `save_task.req`.
+
+Mapped command: `ae-cli engage +build_task_save_guide`
+
+This is a read-only helper. It does not save tasks, submit approvals, or trigger execution. Its job is to tell you how to build a valid `save_task` request for the current scenario.
+
+---
+
+## 1. Recommended Workflow
+
+Use this sequence when creating or updating a task draft:
+
+1. Query channels with `ae-cli engage +channel_list --project_id <projectId>`.
+2. Call `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`.
+3. If the guide says QP-derived fields are required, call:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+4. Build the final grouped `save_task.req`.
+5. Submit with `ae-cli engage +save_task --project_id <projectId> --req '{...}'`.
+
+Important:
+
+- Do not treat the audience schema query as a fixed preflight step.
+- Call it only when the guide indicates that you need to construct:
+  - `targetConfig.qp`
+  - `triggerConfig.triggerRule`
+  - `clientConfig.clientQp`
+  - `completionIndicatorDef.event`
+
+---
+
+## 2. CLI Shape
+
+The CLI call shape is:
+
+```bash
+ae-cli engage +build_task_save_guide --project_id <projectId> --req '<req-json>'
+```
+
+This CLI requires `--req`, but `{}` is valid when you want a generic guide without scenario context.
+
+Common request patterns:
+
+```bash
+ae-cli engage +build_task_save_guide --project_id 1 --req '{}'
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+ae-cli engage +build_task_save_guide --project_id 1 --req '{"draft":{"baseInfo":{"taskName":"Demo Task"}}}'
+```
+
+Supported request fields:
+
+- `context`
+  - a lightweight scenario selector
+  - use it when you know key dimensions such as trigger type, audience type, channel, or experiment mode
+- `draft`
+  - a partial `save_task` request
+  - use it when you already have part of the final payload and want missing fields, examples, or corrections
+- `reqDraft`
+  - alias of `draft`
+- `detailLevel`
+  - `brief`: core requirements only
+  - `full`: includes enums, unsupported cases, examples, and self-check information
+
+---
+
+## 3. `context` and `draft`
+
+### 3.1 `context`
+
+Use `context` when you want scenario-specific guidance without writing a partial `save_task.req`.
+
+Typical fields:
+
+- `triggerType`
+- `targetClusterType`
+- `channelType`
+- `channelId`
+- `channelTemplateId`
+- `enableExp`
+- `expIndicatorBizType`
+
+Example:
+
+```json
+{
+  "context": {
+    "triggerType": 2,
+    "targetClusterType": 2,
+    "channelId": "channel_123"
+  }
+}
+```
+
+### 3.2 `draft`
+
+Use `draft` when you already have a partial `save_task.req` and want the guide to tell you:
+
+- what is still missing
+- what is invalid
+- whether the payload is already close to submit-ready
+- what template or schema to use to finish it
+
+Example:
+
+```json
+{
+  "draft": {
+    "baseInfo": {
+      "taskName": "Demo Task"
+    },
+    "triggerConfig": {
+      "triggerType": 2
+    }
+  }
+}
+```
+
+---
+
+## 4. Output Structure
+
+The guide returns structured metadata rather than free-form prose. The top-level sections are:
+
+- `valid`
+- `errors`
+- `warnings`
+- `missingInputs`
+- `saveTaskContract`
+- `scenario`
+- `requiredInput`
+- `fieldRules`
+- `handoff`
+
+### 4.1 `valid`
+
+- `true` means the current scenario or draft has no structural blocking errors
+- `false` means you should inspect `errors`, `missingInputs`, and `handoff.blockingPlaceholders`
+
+### 4.2 `errors`
+
+Use `errors` for hard blockers such as:
+
+- invalid enum values
+- unsupported combinations
+- unsupported trigger types
+
+The guide may expose invalid values separately so you can correct them instead of silently dropping them.
+
+### 4.3 `warnings`
+
+Use `warnings` for non-fatal guidance, for example:
+
+- channel content schema is unavailable because no `channelId` was provided
+- click-rate experiment setup still needs a channel context
+
+### 4.4 `missingInputs`
+
+Use `missingInputs` as the to-do list for fields you still need before you can submit `save_task`.
+
+Typical examples:
+
+- missing `baseInfo.taskName`
+- missing `channelConfig.channelId`
+- missing `channelConfig.groupContentList`
+- missing `triggerConfig.triggerTime` for scheduled single tasks
+
+### 4.5 `saveTaskContract`
+
+This section describes the high-level contract:
+
+- final tool is `save_task`
+- required preflight is `query_channel_list -> build_task_save_guide`
+- QP-derived fields may require `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`
+- `save_task.req` must be a grouped JSON object
+
+### 4.6 `scenario`
+
+This section shows the resolved scenario, such as:
+
+- create vs update draft
+- trigger type
+- audience type
+- channel type / channel id
+- whether the scenario is unsupported
+
+### 4.7 `requiredInput`
+
+This section tells you which grouped blocks and fields are required in the current scenario.
+
+Use it to understand what must appear in:
+
+- `baseInfo`
+- `channelConfig`
+- `targetConfig`
+- `triggerConfig`
+- `controlConfig`
+- `expConfig` when experiment mode is enabled
+
+### 4.8 `fieldRules`
+
+This is the most important construction section.
+
+It includes:
+
+- grouped block rules
+- structured conditional rules
+- related-parameter rules
+- unsupported fields / values / combinations
+- `channelContentSchema`
+- enum values and wrong examples when `detailLevel=full`
+
+#### `fieldRules.channelContentSchema`
+
+Treat this as the source of truth for channel content construction.
+
+Use it to get:
+
+- valid keys
+- expected item shape
+- channel-specific examples
+- params that must be copied exactly, such as `paramType`
+
+Do not invent free-form content items such as:
+
+```json
+[{"text":"hello"}]
+```
+
+Instead, use the valid item structure and put message text into `value`.
+
+### 4.9 `handoff`
+
+This is the final section before `save_task`.
+
+Important fields:
+
+- `reqTemplate`
+  - a scenario-aware grouped request template
+  - use it as a starting point, not as unquestioned final truth
+- `readyToSubmit`
+  - `true` means the current scenario or draft has no blocking placeholders
+- `blockingPlaceholders`
+  - unresolved placeholders that still block submission
+- `selfCheckList`
+  - a final checklist before calling `save_task`
+- `successUrlRule`
+  - after `save_task` succeeds, build the task detail URL from current page origin plus the relative hash
+  - do not hardcode host, IP, or port
+
+---
+
+## 5. How to Use the Guide in Practice
+
+Recommended usage pattern:
+
+1. resolve a real `channelId` with `+channel_list`
+2. call `+build_task_save_guide`
+3. read `fieldRules.channelContentSchema`
+4. read `handoff.reqTemplate`
+5. fix everything in `blockingPlaceholders`
+6. if the guide points to QP-derived fields, call:
+
+```bash
+ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+```
+
+7. fill those fields using the real condition schema
+8. call `+save_task`
+
+---
+
+## 6. Safety Notes
+
+- `+build_task_save_guide` is read-only; it does not save a draft
+- do not skip the guide and build `save_task.req` from memory alone
+- do not treat the audience schema query as mandatory for every task
+- do not invent `channelId`, `clusterKey`, content keys, or QP structures
+- if the guide exposes an unsupported scenario, correct it before calling `save_task`

package/skills/ae-engage/references/cancel-query-by-request-id.md

@@ -1,6 +1,5 @@
 # ae-engage +cancel_query_by_request_id
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Cancel a running data query by requestId.
 

package/skills/ae-engage/references/channel-detail.md

@@ -1,6 +1,5 @@
 # ae-engage +channel_detail
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Query the details of a single Engage channel.
 

package/skills/ae-engage/references/channel-list.md

@@ -1,6 +1,5 @@
 # ae-engage +channel_list
 
-> **Prerequisite:** Read [`../../ae-shared/SKILL.md`](../../ae-shared/SKILL.md)
 
 Query the list of Engage channels in a project.