@thinkingai/ae-cli 6.0.29 → 6.0.31

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

@@ -29,25 +29,23 @@ Every command accepts `--host <url>` to override the active AE host, and it may
 
 ## 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`.
+- In this overlay, **query cluster / service cluster / deployment cluster** means multi-cluster routing for analysis queries. **audience/user segment cluster** means user membership assets under `analysis user-cluster`.
 - 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.
+- Do not answer query-cluster inventory questions with `ae-cli analysis user-cluster list` 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`.
+- Unified ad-hoc gateway commands (`analysis adhoc run/export`) do not expose `cluster_query_scope`. If the user explicitly needs global/slave ad-hoc analysis, state that the new ad-hoc gateway contract does not support cluster routing yet and stop instead of adding hidden flags or removed ad-hoc commands.
+- Report/dashboard data gateway commands (`analysis report-data run/export`, `analysis dashboard-report-data run/export`) also do not expose `cluster_query_scope`; do not add hidden cluster flags to them.
 - 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.
+- For SQL model analysis, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster in the current gateway contract.
 
 ## 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.
+- For `analysis user-cluster list`, 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

@@ -11,7 +11,7 @@ Domain: **Multi-Cluster Query Routing**
 - 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`.
+This command is not for audience/user segment clusters. For cohort, audience, or segment assets, use `analysis user-cluster list`.
 
 ## Commands
 
@@ -50,18 +50,19 @@ The result data follows the server DTO used by `list_query_clusters`:
 - 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.
+- Unified ad-hoc gateway commands (`analysis adhoc run/export`) do not expose `cluster_query_scope`; if a global/slave ad-hoc query is requested, report that the gateway contract does not support it yet instead of using removed ad-hoc commands or hidden flags.
+- For SQL model analysis, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster in the current gateway contract.
 
 ## 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
+- Query DAU for Japan server -> `analysis +list_query_clusters` -> match JP/Japan slave cluster -> use only commands that explicitly expose cluster routing; the current report/dashboard/ad-hoc gateway data commands do not.
+- Query all-cluster aggregated DAU -> `analysis +list_query_clusters` -> if `permissions.canQueryGlobal=true`, use only commands that explicitly expose cluster routing; otherwise stop and report the capability gap.
+- View audience cohorts or user segments -> `analysis user-cluster list` 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.
+- Do not call `analysis user-cluster list` results query clusters; those are audience clusters or user segments.

package/skills/ae-capability/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-capability
-version: 1.2.0
-description: "AE/TE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, dry-run a capability, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields."
+version: 1.3.1
+description: "AE/TE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, optionally validate complex input or dry-run before execute, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields. Prefer on-demand validate OR dry-run — do not stack both by default."
 ---
 
 # ae-capability
@@ -13,14 +13,28 @@ Use this skill for progressive capability discovery and generic gateway invocati
 1. Use a domain skill and its curated command when it directly covers the task.
 2. Otherwise search the capability catalog.
 3. Inspect the selected capability before constructing input.
-4. Dry-run with real input when helpful.
-5. Run after dry-run succeeds; obtain chat confirmation only for delete capabilities.
+4. **Optionally** pre-check — pick **at most one** path from the table below (do not stack validate + dry-run by default).
+5. Execute (`capability run` / curated command). Chat confirmation only for delete (`high-risk-write`).
 
 Never guess a capability ID, input field, enum value, resource ID, or project ID.
 
+### On-demand pre-check (pick one)
+
+Motto: **validate = fix params; dry-run = confirm ready to run.**
+Hard rule: **for the same final input, do not run both validate and dry-run by default.** `dry-run` already includes parameter validation.
+
+| Situation | What to call | Then |
+| --- | --- | --- |
+| Simple / familiar input (typical `read`, few scalar fields) | **Neither** — skip pre-check | `run` directly |
+| Complex `qp` / nested `payload` / share maps; still iterating shape | **`--validate` / `capability validate` only** (may repeat while fixing) | After `valid=true`, **`run` directly** — skip dry-run unless below applies |
+| Need risk / `output_mode` / `supports_cancel`, or `high-risk-write` delete gate | **`--dry-run` / `capability dry-run` only** (once on final input) | Then confirm (delete) / `run`. Do **not** validate first on the same final payload |
+| Rare exception: many validate iterations, then still need delete confirmation | validate while drafting → **one** dry-run on the **final** input | Then chat confirm → `run --yes` |
+
+Do **not** treat `validate → dry-run → run` as the normal path. That stack is the rare exception in the last row only.
+
 ## Skill references
 
-Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → `dry-run` → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.
+Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → (**optional** validate *or* dry-run) → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.
 
 Create or keep a standalone reference only when at least one applies: L2 hard bar, easily confused with neighbors, `high-risk-write` delete workflow, or multi-step orchestration. Domain skills may inline one-line summaries in overview matrices (e.g. `analysis_gateway_assets.md`). See [`capability-command-admission` §10](../../docs/capability-command-admission.md).
 
@@ -36,10 +50,15 @@ ae-cli capability search "<terms>" --domain <domain>
 # Read input_schema, risk, auth, output, and dry-run support.
 ae-cli capability inspect <capability-id>
 
-# Validate and preview input without execution.
+# Optional — fix params only (gateway /validate). Curated: global --validate.
+ae-cli capability validate <capability-id> --input '<json-object>'
+ae-cli metadata data-table sql-write --project-id 1 ... --validate
+
+# Optional — confirm ready to run (gateway /dry-run). Curated: global --dry-run.
 ae-cli capability dry-run <capability-id> --input '<json-object>'
+ae-cli metadata data-table sql-write --project-id 1 ... --dry-run
 
-# Execute after inspection (and dry-run when input is non-trivial).
+# Execute (after inspect; add at most one pre-check when needed).
 ae-cli capability run <capability-id> --input '<json-object>'
 ```
 
@@ -50,7 +69,37 @@ ae-cli capability run <capability-id> --input '<json-object>'
 - `@<path>`.
 - `-` to read JSON from stdin.
 
-The capability namespace is inferred from `<capability-id>` for `inspect`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing.
+The capability namespace is inferred from `<capability-id>` for `inspect`, `validate`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing.
+
+## validate vs dry-run
+
+| | `validate` / `--validate` | `dry-run` / `--dry-run` |
+| --- | --- | --- |
+| Purpose | Check **input shape** while composing complex payloads | **Pre-execution confirmation** (params + risk/output/cancel) |
+| Does it mutate business data? | No | No |
+| Primary success fields | `valid`, `capability_id`, `normalized_input` | `dry_run`, `capability_id`, `risk`, `output_mode`, `supports_cancel`, `normalized_input` |
+| When to prefer | Iterating nested `payload` / `qp` / multi-field JSON | Final input; need risk/output contract or delete gate |
+| Typical failure focus | Missing/invalid fields, type mismatches, bad `qp` structure | Same param errors, plus readiness signals for actual run |
+| Curated commands | Global `--validate` on gateway-backed curated commands | Global `--dry-run` |
+
+Server may still authenticate the caller for both endpoints. Neither executes the capability business handler. Do not combine `--validate` and `--dry-run` on one invocation.
+
+**Complex input:** prefer **`--validate` only** while assembling `qp` / nested payload; after `valid=true`, go to `run`. Use dry-run instead of validate when you need the risk/output preview or a delete confirmation gate — not both.
+
+Example (param risk only — no stacked dry-run):
+
+```bash
+ae-cli metadata data-table sql-write ... --validate   # iterate until valid
+ae-cli metadata data-table sql-write ...              # execute ordinary write
+```
+
+Example (delete gate — dry-run only on final input):
+
+```bash
+ae-cli capability dry-run analysis.folder.delete --input '...'
+# stop, ask user, then:
+ae-cli capability run analysis.folder.delete --input '...' --yes
+```
 
 ## Risk Levels (aligned with lark-cli)
 
@@ -64,12 +113,15 @@ Legacy values such as `create`, `update`, or `delete` are normalized to this thr
 
 ## Safety
 
-- `list`, `search`, `inspect`, and `dry-run` never execute business mutations.
+- `list`, `search`, `inspect`, `validate`, and `dry-run` never execute business mutations.
+- Curated gateway commands: `--validate` → `/validate`; `--dry-run` → `/dry-run`; do not combine them.
+- Do not stack validate + dry-run on the same final input by default (efficiency).
 - `capability run` inspects metadata before execution when `--yes` is absent.
 - Only `high-risk-write` requires chat confirmation before `capability run ... --yes`.
-- `read` and `write` may run directly after inspect/dry-run.
+- `read` and ordinary `write` may run after inspect; add validate **or** dry-run only when the on-demand table says so.
 - Use `--yes` on delete runs only after the user explicitly authorizes execution in chat.
-- Global `--dry-run` on `capability run` calls the gateway dry-run endpoint instead of execute.
+- Global `--dry-run` on `capability run` / curated commands calls the gateway dry-run endpoint instead of execute.
+- Global `--validate` on `capability run` / curated commands calls the gateway validate endpoint instead of execute.
 
 ## High-Risk Confirmation Workflow (Agent)
 
@@ -77,13 +129,13 @@ Applies only when `inspect` shows `risk=high-risk-write`.
 
 User intent (for example "delete this space") is **not** execution authorization. Do not pass `--yes` just because the user stated the desired action.
 
-1. Run `capability inspect` and `capability dry-run` with the final input.
+1. `capability inspect`. For complex delete input only, you may iterate with `validate` while drafting; for the **final** payload use **`dry-run` once** (skip a redundant validate on that same final JSON — dry-run already validates params).
 2. **Stop in the same turn.** Do not call `capability run` in the same turn as dry-run.
 3. Summarize in chat: capability ID, `project_id`, key input fields, and `risk=high-risk-write`.
 4. Ask the user to confirm execution. Prefer `AskUserQuestion` when that tool is available; otherwise ask in plain text and wait for the user's **next message**.
 5. Only after the user replies with explicit authorization (for example `confirm`, `execute`, or `yes`) run `capability run ... --yes` with the same input as dry-run.
 
-For `risk=write`, run directly after a successful dry-run; no chat confirmation gate.
+For `risk=write`: no chat confirmation gate. Prefer direct `run` after inspect; use `--validate` alone when the payload is complex and you are fixing shape; use `--dry-run` alone only if you need the risk/output preview — **not** validate then dry-run as a habit.
 
 Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do not work in Agent Bash; chat confirmation is the real gate for `high-risk-write`.
 
@@ -91,13 +143,14 @@ Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do
 
 - `list` returns `{ domain, count, capabilities }`.
 - `search` returns `{ domain, query, count, capabilities }`.
-- `inspect`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.
+- `inspect`, `validate`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.
 
 ## Examples
 
 ```bash
 ae-cli capability search "dashboard list" --domain analysis
 ae-cli capability inspect analysis.dashboard.list
-ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
+ae-cli capability validate metadata.data_table.sql_write --input input.json
+ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
 ae-cli capability run analysis.dashboard.list --input input.json
 ```

package/skills/ae-community/SKILL.md

@@ -34,11 +34,11 @@ Output and errors:
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
-- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Ordinary `write` commands require explicit user intent but no CLI confirmation. Only `high-risk-write` commands use the confirmation gate.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
-**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis), `analysis_audience` (audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
+**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
 
 ---
 

package/skills/ae-data-integration-helper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-data-integration-helper
-description: Answers questions about ThinkingData SDK integration and usage, including the LogBus2 data import tool. Trigger words: 怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus / tracking / integration / how to integrate / data import / データ連携 / インテグレーション / 트래킹 / 연동.
+description: "Answers questions about ThinkingData SDK integration and usage, including the LogBus2 data import tool. Trigger words: 怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus / tracking / integration / how to integrate / data import / データ連携 / インテグレーション / 트래킹 / 연동."
 ---
 
 # ae-data-integration-helper

package/skills/ae-dataops/SKILL.md

@@ -44,7 +44,7 @@ Output and errors:
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
-- Write-command examples omit `--yes`; add `--yes` only when the user explicitly wants to skip the confirmation prompt.
+- Ordinary `write` commands execute without `--yes`; use `--yes` only for a `high-risk-write` command after explicit user confirmation.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 

package/skills/ae-engage/SKILL.md

@@ -26,17 +26,18 @@ Output and errors:
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
-- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Write commands require explicit user intent. Ordinary `write` commands execute without CLI confirmation; only `high-risk-write` commands use the confirmation gate.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
 ## Overview
 
-The `ae-engage` package provides Hermes Engage MCP capabilities across config items, flows, channel settings, and task data. Commands are invoked through `ae-cli engage <command>`.
+The `ae-engage` package provides Hermes Engage MCP capabilities across config items, flows, channel settings, and task data. Legacy MCP tools use `ae-cli engage +<command>`; new capability-gateway commands use `ae-cli engage-flow|engage-task|engage-setting <resource> <action>`.
 
 Typical use cases include:
 
 - Querying and managing channels, config channels, approvers, and whitelists
+- Querying project channel touch-limit or fatigue-control rules
 - Querying task lists, task details, experiment reports, and metric reports
 - Querying config items and strategies, copying templates, and managing strategy status
 - Querying flow lists, node schemas, and flow reports, and saving or managing flows
@@ -72,6 +73,9 @@ ae-cli engage +channel_list --project_id 1 --provider_list '["webhook","fcm"]'
 
 # Query config channels
 ae-cli engage +config_channel_list --project_id 1
+
+# Query project channel touch-limit rules
+ae-cli engage-setting channel-touch-limits list --project-id <project_id>
 ```
 
 ### 2. task
@@ -117,6 +121,19 @@ ae-cli engage +flow_list --project_id 1
 # Query flow details
 ae-cli engage +flow_detail --project_id 1 --flow_uuid flow_uuid_123
 
+# Query flow operation records and application logs
+ae-cli engage-flow operation-log query --project-id 1 --flow-uuid flow_uuid_123
+
+# Query flow versions and task push records
+ae-cli engage-flow version list --project-id 1 --flow-id flow_id_123
+ae-cli engage-task operation-log query --project-id 1 --task-id task_id_123
+ae-cli engage-task push-record query --project-id 1 --task-id task_id_123 --page-num 1 --page-size 20
+ae-cli engage-task segment-list query --project-id 1 --task-id task_id_123
+ae-cli engage-task group list --project-id 1
+ae-cli engage-task metric list --project-id 1 --task-id task_id_123
+ae-cli engage-task channel-ref stats --project-id 1 --channel-id channel_123
+ae-cli engage-task ops delete --project-id 1 --task-id task_id_123 --yes
+
 # Query the node schema
 ae-cli engage +flow_node_config_schema --node_type message_push
 ```
@@ -133,10 +150,11 @@ When the user wants to "create a flow / generate a flow canvas / save a flow", d
    - The touchpoint or delivery method
    - Whether branching is needed, and the branching conditions
 2. Do not jump directly from natural language to `--req`. You must first organize a stable intermediate intent structure, then map it to the final `req`.
-3. Before building any condition-related nodes, you must call:
+3. Before building condition-related nodes, create the reusable audience directly from its semantic definition, then read back the server-authored definition only if the Engage schema explicitly needs QP-derived fields:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
@@ -167,7 +185,7 @@ ae-cli engage +channel_list --project_id <projectId>
 ```text
 User request
 -> Organize intent
--> analysis_audience +get_cluster_definition_schema --cluster_type condition
+-> analysis user-cluster create/get
 -> +channel_list --project_id <projectId>
 -> Build nodes / edges
 -> Self-check
@@ -196,11 +214,19 @@ 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/channel_touch_limits_list.md` (`engage-setting.channel-touch-limits.list`)
 - `references/build-task-save-guide.md`
 - `references/save-task.md`
 - `references/task-list.md`
 - `references/config-item-list.md`
 - `references/flow-list.md`
+- `references/operation-log-query.md` (`engage-flow.operation-log.query`)
+- `references/task-operation-log-query.md` (`engage-task.operation-log.query`)
+- `references/version-list.md` (`engage-flow.version.list`)
+- `references/push-record-query.md` (`engage-task.push-record.query`)
+- `references/segment-list-query.md` (`engage-task.segment-list.query`)
+- `references/group-list.md` (`engage-task.group.list`)
+- `references/ops-delete.md` (`engage-task.ops.delete`)
 
 This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the `references/` root directory.
 
@@ -208,11 +234,13 @@ This split documentation structure is easier to extend later, because commands w
 
 ### setting
 
-`+channel_list`, `+channel_detail`, `+update_channel_status`, `+delete_channel`, `+add_channel`, `+whitelist_list`, `+add_approver`, `+approver_list`, `+cancel_query_by_request_id`, `+config_channel_detail`, `+config_channel_list`, `+delete_config_channel`, `+update_config_channel_status`
+`channel-touch-limits list` (via `engage-setting`), `+channel_list`, `+channel_detail`, `+update_channel_status`, `+delete_channel`, `+add_channel`, `+whitelist_list`, `+add_approver`, `+approver_list`, `+cancel_query_by_request_id`, `+config_channel_detail`, `+config_channel_list`, `+delete_config_channel`, `+update_config_channel_status`
 
 ### 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`
+`operation-log query` / `push-record query` / `segment-list query|get|rename` / `ops delete|modify-group` / `metric list|update` / `channel-ref stats` / `group list|create|update` (via `engage-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`
+
+> Temporarily disabled engage-task commands (do not use): `group delete`, `segment-list set-visibility`, `ops submit-approval`, `race release`.
 
 ### config
 
@@ -220,7 +248,7 @@ This split documentation structure is easier to extend later, because commands w
 
 ### flow
 
-`+save_flow`, `+flow_node_config_schema`, `+flow_detail`, `+flow_list`, `+flow_node_overview_report`, `+manage_flow`, `+flow_ab_split_node_report`, `+flow_process_report`, `+validate_flow_node_config`, `+flow_node_detail_report`, `+delete_flow`, `+modify_flow_base_info`
+`operation-log query` / `version list` (via `engage-flow`), `+save_flow`, `+flow_node_config_schema`, `+flow_detail`, `+flow_list`, `+flow_node_overview_report`, `+manage_flow`, `+flow_ab_split_node_report`, `+flow_process_report`, `+validate_flow_node_config`, `+flow_node_detail_report`, `+delete_flow`, `+modify_flow_base_info`
 
 ## Date Format
 
@@ -239,11 +267,11 @@ 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`
+3. If the guide says QP-derived fields are needed, create the audience with `analysis user-cluster create`, then read its server-authored definition with `analysis user-cluster get`
 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`.
+Audience creation is not a fixed preflight step. Use direct `analysis user-cluster create` only when the guide requires a condition audience, and prefer the returned `cluster_name`/`clusterKey`. If the Engage schema explicitly requires QP-derived fields such as `targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`, read the saved server-authored definition with `analysis user-cluster get`; never assemble raw QP manually.

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

@@ -14,10 +14,11 @@ 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:
+3. If the guide says an audience or QP-derived fields are required, create the audience directly and read it back:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 4. Build the final grouped `save_task.req`.
@@ -25,8 +26,8 @@ ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
 
 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:
+- Do not treat audience creation as a fixed preflight step.
+- Create/read the audience only when the guide indicates that you need to construct:
   - `targetConfig.qp`
   - `triggerConfig.triggerRule`
   - `clientConfig.clientQp`
@@ -175,7 +176,7 @@ 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`
+- QP-derived fields require a server-authored audience: direct `analysis user-cluster create`, followed by `analysis user-cluster get`
 - `save_task.req` must be a grouped JSON object
 
 ### 4.6 `scenario`
@@ -263,13 +264,14 @@ Recommended usage pattern:
 3. read `fieldRules.channelContentSchema`
 4. read `handoff.reqTemplate`
 5. fix everything in `blockingPlaceholders`
-6. if the guide points to QP-derived fields, call:
+6. if the guide points to an audience or QP-derived fields, call:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
-7. fill those fields using the real condition schema
+7. prefer the created cluster reference; only copy server-authored fields from `user-cluster get` when the guide explicitly requires QP-derived fields
 8. call `+save_task`
 
 ---
@@ -278,6 +280,6 @@ ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
 
 - `+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 treat the semantic cluster definition builder 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/channel_touch_limits_list.md

@@ -0,0 +1,29 @@
+# engage-setting channel-touch-limits list
+
+> Capability id: `engage-setting.channel-touch-limits.list` · Domain: `engage`.
+
+## Command
+
+```bash
+ae-cli engage-setting channel-touch-limits list --project-id <project_id>
+ae-cli engage-setting channel-touch-limits list --project-id <project_id> --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` / `-p` | Yes | Numeric project ID. |
+
+## Output
+
+- `data.items`: complete touch-limit rule list for the project.
+- `data.total`: number of returned rules.
+- Each item can contain `project_id`, `rule_id`, `channel_biz_type`, `enable`, `rule_def`, `channel_name`, `channel_type`, and `channel_list`.
+- Each `channel_list` item contains `channel_id` and `channel_name`.
+
+## Decision Rules
+
+- Use this command when the user asks for project channel touch-limit, delivery-cap, or fatigue-control rules.
+- Use `+channel_list` to list channels and `+channel_detail` to inspect one channel; neither returns the project touch-limit rule list.
+- If `items` is empty, do not invent rule IDs or channel IDs; report that no touch-limit rules were returned for the project.

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

@@ -0,0 +1,13 @@
+# engage-task group list
+
+List task groups in a project.
+
+> Capability id: `engage-task.group.list` · Domain: `engage`.
+
+```bash
+ae-cli engage-task group list --project-id <project-id>
+```
+
+## Parameters
+
+- `--project-id` / `-p`: Numeric project ID.

package/skills/ae-engage/references/operation-log-query.md

@@ -0,0 +1,11 @@
+# engage-flow operation-log query
+
+Use this command to query aggregated operation records and application logs for a flow canvas.
+
+> Capability id: `engage-flow.operation-log.query` · Domain: `engage`.
+
+```bash
+ae-cli engage-flow operation-log query --project-id <project-id> --flow-uuid <flow-uuid>
+```
+
+The result contains `operation_record_list` and `app_log_list`, grouped by flow version.

package/skills/ae-engage/references/ops-delete.md

@@ -0,0 +1,14 @@
+# engage-task ops delete
+
+Delete an engagement task. High-risk write; requires `--yes` to skip confirmation.
+
+> Capability id: `engage-task.ops.delete` · Domain: `engage`.
+
+```bash
+ae-cli engage-task ops delete --project-id <project-id> --task-id <task-id> --yes
+```
+
+## Parameters
+
+- `--project-id` / `-p`: Numeric project ID.
+- `--task-id`: Engagement task ID.

package/skills/ae-engage/references/push-record-query.md

@@ -0,0 +1,26 @@
+# engage-task push-record query
+
+Query delivery and push records for an engagement task. Hermes automatically selects scheduled, user-time-zone, or triggered record data based on the task configuration.
+
+> Capability id: `engage-task.push-record.query` · Domain: `engage`.
+
+```bash
+ae-cli engage-task push-record query \
+  --project-id <project-id> \
+  --task-id <task-id> \
+  --page-num 1 \
+  --page-size 20
+```
+
+## Parameters
+
+- `--project-id`, `-p`: Numeric project ID.
+- `--task-id`: Engagement task ID.
+- `--page-num`: Optional page number for scheduled tasks. Defaults to `1`.
+- `--page-size`: Optional page size for scheduled tasks. Defaults to `20`.
+- `--start-date`: Optional start date in `yyyy-MM-dd` format. Must not be after `--end-date`.
+- `--end-date`: Optional end date in `yyyy-MM-dd` format. Must not be before `--start-date`.
+
+## Output
+
+Returns `record_type`, `items`, `total`, and pagination metadata when the selected backend record type is paginated. Records include available trigger, planned-send, actual-send, success, channel-exception, status, and failure-reason fields.

package/skills/ae-engage/references/save-flow.md

@@ -33,7 +33,7 @@ You still organize user requirements into an intermediate intent first, then map
 ## 2. Workflow
 
 1. Identify the flow intent from the user input and produce a unified intent JSON.
-2. Run `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition` to obtain the condition cluster definition schema for assembling condition-related fields later.
+2. Build a semantic condition request from `ae-analysis/references/user_cluster_models.md`, create the audience directly with `analysis user-cluster create`, and prefer its `cluster_name`/`clusterKey`. Read the saved server-authored definition with `analysis user-cluster get` only when an Engage node schema explicitly requires QP-derived fields; never assemble raw QP.
 3. Run `ae-cli engage +channel_list --project_id <projectId>` to get the available channels and match real `channelId` values for touchpoint nodes. For `webhook_push`, also run `ae-cli engage +channel_detail` and use `data.config.paramsList` to build `contentList`.
 4. Query `ae-cli engage +flow_node_config_schema --node_type <type>` before constructing each non-trivial node config, then run `ae-cli engage +validate_flow_node_config --node_type <type> --operation_mode save_flow --config '<config-json-string>'` before placing the config into `nodes` or `nodeConfigs`.
 5. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
@@ -167,13 +167,14 @@ Organize the user requirement into an intermediate intent JSON (not the final `r
 
 ## 5. Step Two: Required CLI Queries
 
-### 5.1 Cluster Definition Schema
+### 5.1 Semantic Audience
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
-Provides the basis for `targetClusterQp` and `triggerRule.events`.
+Prefer the created cluster reference. Only when the node schema requires `targetClusterQp` or `triggerRule.events`, copy the corresponding server-authored fields returned by `user-cluster get`.
 
 ### 5.2 Project Channels