@thinkingai/ae-cli 6.1.10 → 6.1.12

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, and task management. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task."
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, and operation activities. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity."
 ---
 
 # ae-engage
@@ -52,10 +52,11 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Config center** | Engage scene management / config center overview | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-config-channel.md`, `channel-mgmt.md`, `scene-strategy.md`, `scene-template.md`; L3 reports: `config-item-trigger-report.md`, `config-item-analysis-report.md`, `config-item-strategy-comparison.md` |
 | **Scene config** | Same as config center; params, groups, metrics, channels, strategies, and templates under a config item | `engage-scene` | `references/scene-config-item.md` | Same as above; params/groups/metrics: `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md` |
 | **Config item** | A single config item in the config center | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-strategy.md`, `scene-template.md` |
-| **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md`, `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
+| **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md` (**Webhook vs Client differ**: `url` = HTTP vs scene key; custom params `user:` vs `user:`/`client:`), `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
 | **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
-| **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience QP: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — **用户满足** `filts[0]` + **用户行为** `filts[1]` two-block mix QP; preflight props (stop + list if missing); examples A/B/C; template: `scene-template.md` |
+| **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — semantic `definitionRequest` (Analysis condition shape); do not pass `targetClusterQp`/`qp`; preflight props (stop + list if missing); template: `scene-template.md` |
 | **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
+| **Operation activity** | Campaign activity management and delivery trends by activity, topic, or standalone task | `engage-activity` | `references/activity-activity.md` | `activity-data-detail.md`, `activity-topic.md`, `activity-task.md`, `activity-approval.md` |
 | **Template** | Strategy templates under a config item | `engage-scene` | `references/scene-template.md` | `scene-config-param.md` (template fields reference `paramId`); enable via `template update` then `template update-status` before strategy create |
 
 **Easy to confuse:**
@@ -75,6 +76,7 @@ Naming boundary:
 
 - CLI flags use kebab-case; outer Capability input and all Capability response keys use snake_case.
 - Nested business DTOs passed through `--req` or `--payload` keep their documented native camelCase fields. Do not mechanically convert those nested DTO keys to snake_case.
+- Semantic audience, event, trigger, completion, and metric definitions are closed contracts. The CLI rejects malformed or unknown semantic fields locally; `--validate` applies the same precise Hermes capability schema without writing.
 - Successful migrated commands return their business payload under `data`; read the matching reference's Response shape before selecting fields.
 
 ## JSON Parameter Format
@@ -145,13 +147,13 @@ ae-cli engage-setting config-table delete --project-id <project_id> --info-id <i
 
 # Preset event list / update
 ae-cli engage-setting preset-event list --project-id <project_id>
-ae-cli engage-setting preset-event update --project-id <project_id> --add-event-desc <qp>
+ae-cli engage-setting preset-event update --project-id <project_id> --add-event-definition '<semantic_event_json>'
 
 # Common metric list / get / create / update / delete
 ae-cli engage-setting common-metric list --project-id <project_id>
 ae-cli engage-setting common-metric get --project-id <project_id> --metric-name <name>
-ae-cli engage-setting common-metric create --project-id <project_id> --metric-type 1 --metric-name <name> --metric-qp '<qp_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
-ae-cli engage-setting common-metric update --project-id <project_id> --metric-type 1 --metric-name <name> --metric-qp '<qp_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
+ae-cli engage-setting common-metric create --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
+ae-cli engage-setting common-metric update --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
 ae-cli engage-setting common-metric delete --project-id <project_id> --metric-name <name> --yes
 ```
 
@@ -170,6 +172,9 @@ ae-cli engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo
 # Query task details
 ae-cli engage-task task get --project-id 1 --task-id task_123
 
+# Submit a saved draft task for approval
+ae-cli engage-task task submit-approval --project-id 1 --task-id task_123
+
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
@@ -210,6 +215,7 @@ 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 task delete --project-id 1 --task-id task_id_123 --yes
+ae-cli engage-task task submit-approval --project-id 1 --task-id task_id_123
 
 # Query the node schema
 ae-cli engage-flow node-config schema --project-id 1 --node-type message_push
@@ -241,7 +247,7 @@ ae-cli engage-scene config-group batch-delete --project-id <project_id> --group-
 
 # Preset metric get / set
 ae-cli engage-scene preset-metric get --project-id <project_id> --config-id <config_id>
-ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> --impression-event-qp '<qp>'
+ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> --impression-event-definition '<semantic_event_json>'
 
 # Config metric list / get / batch-add / update-rule / batch-delete
 ae-cli engage-scene config-metric list --project-id <project_id> --config-id <config_id>
@@ -252,7 +258,7 @@ ae-cli engage-scene config-metric batch-delete --project-id <project_id> --confi
 
 # Config channel list / get / create / update / update-status / delete / query-log
 # User params: verify each customsParamList columnName via ae-analysis property list/get first; then use user:<prop_name>
-# Strategy custom audience: scene-strategy-audience.md — mix QP filts[0]=用户满足, filts[1]=用户行为; strategy predict for 预估人数
+# Strategy custom audience: scene-strategy-audience.md — semantic definitionRequest; strategy predict for 预估人数
 # Workflows: references/channel-mgmt.md · schema: references/scene-config-channel.md
 ae-cli engage-scene config-channel list --project-id <project_id> [--channel-type 0|1]
 ae-cli engage-scene config-channel get --project-id <project_id> --channel-id <channel_id>
@@ -266,7 +272,7 @@ ae-cli engage-scene config-channel query-log --project-id <project_id> --channel
 ae-cli engage-scene strategy create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","strategyName":"s1"}'
 ae-cli engage-scene strategy update --project-id <project_id> --payload '{"strategyUuid":"uuid-1"}'
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
-ae-cli engage-scene strategy predict --project-id <project_id> --qp '<mix QP string>' --zone-offset 8 [--strategy-uuid <uuid>]
+ae-cli engage-scene strategy predict --project-id <project_id> --definition-request '{"type":"condition","conditions":{...}}' --zone-offset 8 [--strategy-uuid <uuid>]
 ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> --strategy-ids '["s1"]'
 
 # Template list / get / create / update / update-status / delete
@@ -282,6 +288,18 @@ ae-cli engage-scene template delete --project-id <project_id> --config-id <confi
 
 New capability-gateway command group `engage-activity` covers campaign activities: activities, approval workflow, topics, activity types, and standalone tasks. Complex DTOs are passed with `--payload` (native camelCase JSON).
 
+### Activity payload guardrails
+
+Before generating any activity topic or standalone-task payload, enforce the same subset exposed by the Hermes activity UI:
+
+- `triggerType` must be `0` (schedule single) or `1` (schedule repeat). Activity tasks do not support manual (`2`) or triggered (`3`-`6`) task types.
+- Do not configure A/B or horse-race experiments. Omit `expConfig` or use only `{"enableExp":false}`, and provide exactly one non-experiment `groupContentList` group.
+- Standalone activity tasks must use `triggerTimeStrategy: "fixed_time_zone"` and the parent activity `tzOffset`. Schedule times must remain inside the activity period.
+- A topic root supports audience types `1` (custom) and `2` (existing cluster), not `3` (all users). A standalone activity task may use `1`, `2`, or `3`.
+- Topic tasks inherit schedule, timezone, channel, frequency limits, channel touch limits, whitelist, and experiment settings from the topic. They may only add an inclusion-only custom `definitionRequest`; never generate task-level `clusterKey`, trigger rules, or shared-setting overrides. `topic get` may return the canonical task marker `targetClusterType=1`; preserve it for update if present, but never use another task-level value.
+- Resolve the parent activity first and confirm it is editable (`mappingStatus` `0`, `2`, or `5`). Limits for topics, tasks, and languages are project configuration values; do not hardcode defaults.
+- `approval submit` and `approval approve` validate every persisted activity task. Approval does not normalize unsupported task data. On `ACTIVITY_TASK_COMPATIBILITY_VIOLATION`, cancel/withdraw approval as needed, correct or recreate each reported task, and submit again.
+
 ```bash
 # Activity create / update / delete / list / get / pause / end / stats / info-list
 ae-cli engage-activity activity create --project-id <project_id> --payload '{"activityName":"a1","activityType":"other_type","tzOffset":8,"periodType":0}'
@@ -294,8 +312,8 @@ ae-cli engage-activity activity end --project-id <project_id> --activity-id <act
 ae-cli engage-activity activity stats --project-id <project_id>
 ae-cli engage-activity activity info-list --project-id <project_id> --activity-id <activity_id>
 
-# Approval approve / reject / cancel
-# Note: engage-activity.approval.submit is temporarily disabled (testing issues); do not call it.
+# Approval submit / approve / reject / cancel
+ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id> [--reason <reason>]
 ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
 ae-cli engage-activity approval reject --project-id <project_id> --activity-id <activity_id> --reason <reason>
 ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <activity_id>
@@ -346,12 +364,9 @@ 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 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 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>"]'
-```
+3. Build condition-related nodes with semantic `targetDefinitionRequest` and
+   `triggerDefinition` objects. Resolve real event and property names through Analysis metadata;
+   do not create an intermediate cluster merely to obtain persisted QP.
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
 
@@ -361,7 +376,10 @@ ae-cli engage-setting channel list --project-id <projectId>
 
 5. `engage-flow flow save` is **operation-based** (protocol v2). The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — use `nodes` / `edges` with `operation=build`. A legacy `nodeList`/`edgeList` payload (or a missing `operation`) is rejected with `Unsupported save_flow operation: null`.
 6. Run the lifecycle: `build` (returns `data.result.status = ready_to_preview` or `need_input`) → resolve any `data.result.next_slot` → `preview` (re-issues response fields `data.result.draft_version` + `data.result.confirm_token`) → `commit` (maps those values to request fields `draftVersion` + `confirmToken`) → reads the final ID from `data.result.result.flow_uuid`.
-7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. If `targetClusterQp` appears inside a node `config`, its value is usually a `JSON.stringify`'d string, not a raw object.
+7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. Custom audience nodes and branches use semantic `targetDefinitionRequest`; Hermes compiles it to the node's stored execution format.
+   Never send `targetClusterQp`. Each audience `event` and `behavior_sequence` must include
+   its own `time_range`; Flow entry dates do not replace that range. Use only properties that
+   resolve through the Flow editor's current project, timezone, and user-entity metadata scope.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -437,13 +455,14 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/scene-config-channel.md` (`engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}`)
 - `references/channel-mgmt.md` (config channel management workflows)
 - `references/scene-strategy.md` (`engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}`)
-- `references/scene-strategy-audience.md` (custom audience mix QP: 用户满足/用户行为 two-block layout, preflight, worked examples A/B/C)
+- `references/scene-strategy-audience.md` (custom audience semantic `definitionRequest`, preflight, predict)
 - `references/scene-template.md` (`engage-scene.template.{list,get,copy,create,update,update-status,delete}`)
 - `references/config-item-trigger-report.md` (`engage-scene.report.config-item-trigger`, L3)
 - `references/config-item-analysis-report.md` (`engage-scene.report.config-item-analysis`, L3)
 - `references/config-item-strategy-comparison.md` (`engage-scene.report.strategy-comparison`, L3)
 - `references/activity-activity.md` (`engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`)
-- `references/activity-approval.md` (`engage-activity.approval.{approve,reject,cancel}`; `submit` temporarily disabled)
+- `references/activity-data-detail.md` (`engage-activity.activity-data.detail`, L3)
+- `references/activity-approval.md` (`engage-activity.approval.{submit,approve,reject,cancel}`)
 - `references/activity-topic.md` (`engage-activity.topic.{create,update,remove-task,delete,get,copy}`)
 - `references/activity-activity-type.md` (`engage-activity.activity-type.{list,batch-add,update,batch-delete}`)
 - `references/activity-task.md` (`engage-activity.task.{get,create,update,copy}`)
@@ -460,6 +479,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/segment-list-query.md` (`engage-task.segment-list.query`)
 - `references/group-list.md` (`engage-task.group.list`)
 - `references/task-delete.md` (`engage-task.task.delete`)
+- `references/task-submit-approval.md` (`engage-task.task.submit-approval`)
 
 This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the `references/` root directory.
 
@@ -471,7 +491,7 @@ This split documentation structure is easier to extend later, because commands w
 
 ### task
 
-`operation-log query` / `push-record query` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
+`operation-log query` / `push-record query` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task submit-approval` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
 
 ### config
 
@@ -483,7 +503,7 @@ Legacy config MCP commands are migrated into the `scene` L2 group and the three
 
 ### activity
 
-`activity create` / `activity update` / `activity delete` / `activity list` / `activity get` / `activity pause` / `activity end` / `activity stats` / `activity info-list` / `approval approve` / `approval reject` / `approval cancel` / `topic create` / `topic update` / `topic remove-task` / `topic delete` / `topic get` / `topic copy` / `activity-type list` / `activity-type batch-add` / `activity-type update` / `activity-type batch-delete` / `task get` / `task create` / `task update` / `task copy` (via `engage-activity`), capability ids `engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`, `engage-activity.approval.{approve,reject,cancel}`, `engage-activity.topic.{create,update,remove-task,delete,get,copy}`, `engage-activity.activity-type.{list,batch-add,update,batch-delete}`, `engage-activity.task.{get,create,update,copy}`
+`activity create` / `activity update` / `activity delete` / `activity list` / `activity get` / `activity pause` / `activity end` / `activity stats` / `activity info-list` / `approval submit` / `approval approve` / `approval reject` / `approval cancel` / `topic create` / `topic update` / `topic remove-task` / `topic delete` / `topic get` / `topic copy` / `activity-type list` / `activity-type batch-add` / `activity-type update` / `activity-type batch-delete` / `task get` / `task create` / `task update` / `task copy` (via `engage-activity`), capability ids `engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`, `engage-activity.approval.{submit,approve,reject,cancel}`, `engage-activity.topic.{create,update,remove-task,delete,get,copy}`, `engage-activity.activity-type.{list,batch-add,update,batch-delete}`, `engage-activity.task.{get,create,update,copy}`
 
 ### workbench
 
@@ -505,19 +525,39 @@ High-risk delete commands (`risk: high-risk-write`) require explicit user author
 - Config channels (config center channel management): `engage-scene config-channel create|update|update-status` (write), `engage-scene config-channel delete` (high-risk-write)
 - Strategies and config items: `engage-scene config-item delete` (high-risk-write), `engage-scene template copy` and `engage-scene strategy manage` (write)
 - Flows: `engage-flow flow update-remark` (write), `engage-flow flow save` (write), `engage-flow flow modify-base-info` (write), `engage-flow flow manage` (write), `engage-flow flow delete` (high-risk-write)
-- Tasks: `engage-task task save` (write), `engage-task task manage` (write)
+- Tasks: `engage-task task save` (write), `engage-task task submit-approval` (write), `engage-task task manage` (write)
 
 For task draft creation or update, use this workflow:
 
 1. `ae-cli engage-setting channel list --project-id <projectId>`
 2. `ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`
-3. If the guide says QP-derived fields are needed (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`), call:
-   `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>`
-   Use the returned skill text to build those fields. For existing-cluster audiences (`targetClusterType=2`), use `analysis user-cluster get` instead of hand-writing QP.
+3. For a custom audience, pass the Analysis semantic contract as
+   `targetConfig.definitionRequest`. Use semantic `triggerConfig.triggerDefinition` and
+   `completionIndicatorDef.completionIndicators[].eventDefinition`. Build shapes from
+   `ae-analysis` user-cluster / audience models. For existing-cluster audiences
+   (`targetClusterType=2`), use `analysis user-cluster get`. For event-triggered tasks, pass
+   `channelType`, `triggerType`, and `eventTriggerType` to `build-save-guide`, then use its
+   type-specific semantic event shape. Accumulated events are aggregate conditions, continuous
+   events use count/eq with a value of at least 2, ordered events use sequence-step envelopes,
+   and every-completion events use count/eq/1. Completion target and experiment main-goal event
+   filters must not use properties whose metadata `select_type` is `datetime`. Never construct
+   persisted QP fields.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
+5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 
 `engage-task task build-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`.
 
 `engage-task task save` creates or updates a task configuration. 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 or paused** task. Update mode rejects running/ended tasks with `invalid_status`. Omitted fields inherit from the existing task before validation (partial rename/update is supported).
 
-Audience creation is not a fixed preflight step. When the guide requires QP-derived fields (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, `completionIndicatorDef.event`), call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` first and follow the returned skill definition; do not assemble raw QP manually. For existing-cluster audiences, use `analysis user-cluster get` to copy server-authored definitions when appropriate.
+`engage-task task submit-approval --task-id` is the recommended approval path after `task save`.
+It submits the persisted draft without requiring the Agent to reconstruct internal `trigger_rule`.
+The legacy `--request` mode remains available for compatibility; provide exactly one of
+`--task-id` or `--request`.
+
+Audience creation is not a fixed preflight step. For custom task audiences, use semantic
+`targetConfig.definitionRequest`; `task get` returns the same contract as
+`definition_request`. `clientConfig.clientQp` is server-authored and must be omitted from
+Capability requests; partial updates preserve existing server state. Do not assemble raw QP
+manually.
+For a `behavior_sequence`, omit second-step `relative_to_first` or set it to `false`; reserve
+`true` for step 3 or later when the window is measured from step 1.

package/skills/ae-engage/references/activity-activity.md

@@ -56,6 +56,9 @@ ae-cli engage-activity activity info-list --project-id <project_id> --activity-i
 - `get`: `data.activity`.
 - `stats`: `data.status_count`.
 - `info-list`: `data.info` with `taskList` (standalone tasks) and `topicList` (topics under the activity).
+  This summary intentionally omits stored QP-bearing detail fields such as `qp`,
+  `triggerRule`, `completionIndicatorDef`, and `clientQp`. Use the corresponding task
+  or topic detail command to obtain the semantic definitions before editing.
 - `delete` / `pause` / `end`: `data.success`.
 
 ## Timezone (`tzOffset`)

package/skills/ae-engage/references/activity-approval.md

@@ -1,14 +1,15 @@
 # engage-activity approval
 
-> Capability ids: `engage-activity.approval.{approve,reject,cancel}` · Domain: `engage`.
->
-> **Temporarily disabled:** `engage-activity.approval.submit` — do not call until re-enabled.
+> Capability ids: `engage-activity.approval.{submit,approve,reject,cancel}` · Domain: `engage`.
 
 Campaign activities — activity approval workflow. Current actions target an activity (`ApprovalActivityIdDealDTO`: `projectId` + `activityId` + `reason`); each is a state-changing `write` and does not support dry-run. `reject` requires `reason`; other actions treat `reason` as optional.
 
 ## Commands
 
 ```bash
+# Submit an activity for approval
+ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id> [--reason <reason>]
+
 # Approve an activity
 ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
 
@@ -23,6 +24,7 @@ ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <
 
 | Command | Required flags | Notes |
 |---|---|---|
+| submit | `--project-id`, `--activity-id` | `--reason` optional. Activity must have draft/pending standalone or topic tasks. |
 | approve | `--project-id`, `--activity-id` | `--reason` optional. |
 | reject | `--project-id`, `--activity-id`, `--reason` | `--reason` required, max 72 characters. |
 | cancel | `--project-id`, `--activity-id` | `--reason` optional. |
@@ -35,13 +37,19 @@ ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <
 
 - All approval actions are `write` (real state changes) and do not support dry-run; they do not require `--yes` (only `high-risk-write` does).
 - Approve/reject require the caller to be a valid approver of the activity (enforced server-side).
-- Do **not** call `engage-activity.approval.submit`; it is temporarily unavailable.
+- Submit requires at least one standalone or topic task under the activity that can enter approval.
+- Submit and approve load complete task details and scan both standalone tasks and topic tasks before invoking the product approval service.
+- Approval does not repair or normalize unsupported activity task configurations.
+- If preflight returns `ACTIVITY_TASK_COMPATIBILITY_VIOLATION`, inspect `error.meta.violations`, withdraw/cancel approval when necessary, and update or recreate each reported task as scheduled, fixed-timezone, and non-experiment before resubmitting.
 
 ## Common Errors
 
 | code | when |
 |---|---|
 | `ACTIVITY_NOT_FOUND` | activity id missing in project |
+| `ACTIVITY_NO_APPROVAL_TASK` | activity has no standalone/topic tasks to submit |
+| `ACTIVITY_TASK_COMPATIBILITY_VIOLATION` | one or more persisted activity tasks use unsupported trigger, timezone, experiment, or content-group configuration; details are in `error.meta.violations` |
+| `ACTIVITY_TRIGGER_TYPE_REQUIRED` | a persisted activity task is missing its trigger type; reported inside the compatibility violation list |
 | `ACTIVITY_STATUS_INVALID` | activity not in draft/pending |
 | `APPROVAL_NOT_PENDING` | no under-approval record |
 | `NOT_APPROVER` | caller is not a project approver |

package/skills/ae-engage/references/activity-data-detail.md

@@ -0,0 +1,61 @@
+# engage-activity.activity-data.detail
+
+Query activity delivery trends through the L3 Capability Gateway.
+
+Mapped command:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input '<json>'
+```
+
+## Input
+
+Required fields:
+
+- `project_id`: project that owns the activity.
+- `activity_id`: activity to query.
+- `start_time`: inclusive start date in `yyyy-MM-dd` format.
+- `end_time`: inclusive end date in `yyyy-MM-dd` format.
+
+Optional fields:
+
+- `time_particle_size`: `T1` (day), `T2` (week), `T3` (month), or `T5` (total). Defaults to `T1`.
+- `source`: `activity` or `topic_and_task`. Defaults to `activity`.
+- `topic_id_list`: selected topic IDs.
+- `task_id_list`: selected standalone task IDs.
+- `request_id`: cancelable query ID. A UUID is generated when omitted.
+
+When `source=topic_and_task` and both ID lists are omitted or empty, the capability selects every topic and standalone task in the activity. When either list is provided, only the explicitly selected resources are queried. Selected resources must belong to the activity and project.
+
+## Recent seven-day topic trend
+
+Use an inclusive seven-day range, `T1`, and `topic_and_task`:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input \
+  '{"project_id":1,"activity_id":"act-1","start_time":"2026-07-25","end_time":"2026-07-31","time_particle_size":"T1","source":"topic_and_task","request_id":"<uuid>"}'
+```
+
+The report exposes the existing activity-page indicators:
+
+- `plan`: planned trigger users.
+- `actualTrigger`: actual push users.
+- `trigger`: successful push users.
+
+It does not expose `view` (actual arrival) or `click`. Use the returned header values instead of treating `trigger` as an actual-arrival metric.
+
+## Output
+
+Successful output contains:
+
+- `data.request_id`: the request ID used by the query.
+- `data.result_generate_time`: ISO-8601 generation time.
+- `data.data.x`: summary/date axis.
+- `data.data.headers`: indicator keys.
+- `data.data.total`: activity totals aligned with `headers`.
+- `data.data.values`: topic or standalone-task rows aligned with `x` and `headers`.
+- `data.data.topic_list`: selected source IDs and names using `topic_id` and `topic_name`.
+
+The first `x`/`total` row is the overall summary. For non-total time grains, subsequent rows are the requested date buckets.
+
+Use `engage-setting.query.cancel` with the same `request_id` to cancel a running query.

package/skills/ae-engage/references/activity-task.md

@@ -26,9 +26,9 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 
 | Command | Required flags | Notes |
 |---|---|---|
-| get | `--project-id`, `--task-id` | read. |
-| create | `--project-id`, `--payload` | payload = `OperationTaskOpDTO`; set `activityId`, leave `topicId` empty. Missing `expConfig` is auto-filled as `{"enableExp":false}`. |
-| update | `--project-id`, `--payload` | payload = `OperationTaskOpDTO` including `taskId`. Prefer get detail as base. Missing `expConfig` is auto-filled as `{"enableExp":false}`. |
+| get | `--project-id`, `--task-id` | Only standalone tasks with an `activityId`; ordinary tasks use `engage-task task get`. |
+| create | `--project-id`, `--payload` | payload = `OperationTaskOpDTO`; set `activityId`, leave `topicId` empty. Only scheduled `triggerType` `0/1` is supported. |
+| update | `--project-id`, `--payload` | payload = `OperationTaskOpDTO` including `taskId`. Prefer get detail as base. Only scheduled `triggerType` `0/1` is supported. |
 | copy | `--project-id`, `--task-id` | `--new-name` optional (default source name + `_copy`). |
 
 ## Output
@@ -47,20 +47,28 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 - **TEXT (rich text) params** must include both `value` and `config` (Slate.js JSON **string**). If `config` is missing, Hermes copy auto-fills  
   `config = [{"type":"paragraph","children":[{"text":"<value>"}]}]` as a JSON string.
 - Missing `expConfig` on create/update is auto-filled as `{"enableExp":false}` (same shape as task `get`).
+- A/B and horse-race experiments are not supported. Do not pass experiment fields or multiple content groups.
+- `groupContentList` must contain exactly one non-experiment group. Put language variants in that group's `contentList`.
 
 ### Audience (`targetClusterType`)
 
 | Value | Required | Notes |
 |---|---|---|
 | `2` (existed) | `clusterKey` | From `analysis user-cluster list/get`. |
-| `1` (custom) | `qp` | JSON object string. |
-| `3` (all) | — | Do not pass `clusterKey` or `qp`. |
+| `1` (custom) | `definitionRequest` | Analysis-compatible semantic condition object. |
+| `3` (all) | — | Do not pass `clusterKey` or `definitionRequest`. |
+
+`get` returns `definition_request`, `definition_status`, and optional `definition_unavailable_reason`, while hiding the stored execution QP. Reuse `definition_request` as payload `definitionRequest` for an update. `copy` converts the source internally and does not require an audience field from the caller.
 
 ## Decision Rules
 
+- `triggerType` must be `0` (schedule single) or `1` (schedule repeat). Manual (`2`) and triggered (`3`-`6`) tasks belong under `engage-task`, not `engage-activity`.
+- Set `triggerTimeStrategy` to `fixed_time_zone` and `tzOffset` to the parent activity timezone. User timezone and user active time are not supported.
+- Keep `triggerTime`, or repeat `startDate`/`endDate`, inside the parent activity period.
+- Create/update/copy is limited to editable parent activity states: draft (`0`), paused (`2`), or denied (`5`). Project-configured count and language limits remain authoritative.
 - Discover a real `task_id` via `get`/activity `info-list` first; never invent IDs.
 - `copy` duplicates the editable task config (not runtime/trigger state).
-- `copy` saves via **draft** add (`draft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval (`engage-activity.approval.submit` is temporarily unavailable).
+- `copy` saves via **draft** add (`draft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval.
 - Standalone tasks must **not** include `topicId`; topic tasks use `engage-activity topic create` / `topic copy`.
 
 ## Copy errors
@@ -73,6 +81,13 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 | `TASK_PROJECT_MISMATCH` | task exists but not in `--project-id` |
 | `TOPIC_TASK_FORBIDDEN` | source has `topicId` (use `topic copy`) |
 | `ACTIVITY_ID_REQUIRED` | source has no `activityId` (not a standalone activity task) |
+| `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED` | task uses manual or a triggered task type |
+| `ACTIVITY_TRIGGER_TIME_STRATEGY_UNSUPPORTED` | task does not use `fixed_time_zone` |
+| `ACTIVITY_TIMEZONE_REQUIRED` | standalone task omits `tzOffset` |
+| `ACTIVITY_EXPERIMENT_UNSUPPORTED` | task enables or configures an experiment |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | task has more than one experiment-style content group |
+| `ACTIVITY_TIMEZONE_MISMATCH` | task timezone differs from the parent activity |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | task schedule is outside the activity period |
 | `TRIGGER_TIME_REQUIRED` | schedule-single missing `triggerTime` |
 | `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
 | `TASK_COUNT_LIMIT` | project task count limit exceeded |

package/skills/ae-engage/references/activity-topic.md

@@ -30,7 +30,7 @@ ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id
 
 | Command | Required flags | Notes |
 |---|---|---|
-| create | `--project-id`, `--payload` | payload = `TopicAddDTO` (camelCase). Prefer `triggerType` `0` (schedule single) or `1` (schedule repeat); activity topics do not use manual (`2`). |
+| create | `--project-id`, `--payload` | payload = `TopicAddDTO` (camelCase). `triggerType` must be `0` (schedule single) or `1` (schedule repeat). |
 | update | `--project-id`, `--payload` | payload = `TopicModifyReq` (`topicId` + fields + task lists). |
 | remove-task | `--project-id`, `--task-id` | high-risk; requires `--yes`; no dry-run. Only tasks with a non-empty `topicId`. |
 | delete | `--project-id`, `--topic-id` | high-risk; requires `--yes`; no dry-run. |
@@ -42,19 +42,19 @@ ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id
 TEXT (rich text) params inside `groupContentList[].contentList[].content` need both `value` and Slate `config` (JSON string). If `config` is omitted, Hermes copy/create auto-fills  
 `[{"type":"paragraph","children":[{"text":"<value>"}]}]`. See `activity-task.md` Channel content.
 
-Topic-level audience uses `topicClusterKey` / `topicQp`; do **not** pass task-level `clusterKey` at topic root.
+Topic-level audience uses `topicClusterKey` / `topicDefinitionRequest`; do **not** pass task-level `clusterKey` at topic root.
 
 ### Audience (`targetClusterType`)
 
 | Value | Required | Notes |
 |---|---|---|
-| `1` (custom) | `topicQp` | Valid condition JSON object string (not `{}`). Use mix QP with `totalCFilter` (and optional `totalOutCFilter`). |
+| `1` (custom) | `topicDefinitionRequest` | Analysis-compatible semantic condition object. |
 | `2` (existed) | `topicClusterKey` | From an existing user cluster. |
 | `3` (all) | — | **Not supported for activity topics** → `TOPIC_TARGET_CLUSTER_TYPE_UNSUPPORTED`. Use standalone `engage-activity task create` for all-users. |
 
-**`triggerMixQpVersion`:** For custom audience (`targetClusterType=1`) with mix QP (`totalCFilter` / `totalInCFilter`), set `"4.4"`. UI theme edit parses conditions only when this is `4.4`; missing/blank values make target-user filters render empty. Capability create/update/copy default blank to `"4.4"` (same as UI and standalone task MCP).
+**`triggerMixQpVersion`:** Capability create/update/copy defaults a blank value to `"4.4"` while compiling the semantic definition.
 
-Task-level extra conditions go in `taskQp` as mix QP under **`totalCFilter` only** (user attrs and/or events). Do not put task-owned conditions in `totalInCFilter` — that key is reserved for topic→task merge (topic `totalCFilter` is copied into task cluster `totalInCFilter` on save).
+Task-level extra conditions go in each task's inclusion-only `definitionRequest`. Keep shared conditions in `topicDefinitionRequest`; Hermes performs the topic-to-task merge through the existing domain service. Topic tasks do not have an independent audience mode. `topic get` returns the canonical task marker `targetClusterType=1`; it may be retained when mapping `taskList` into `modifyTaskList`, but no other value is accepted. Do not pass task-level `clusterKey`, all-users selection, or exclusion filters.
 
 ### Trigger (`triggerType`)
 
@@ -62,7 +62,16 @@ Task-level extra conditions go in `taskQp` as mix QP under **`totalCFilter` only
 |---|---|---|
 | `0` (schedule single) | `triggerTime` (`yyyy-MM-dd HH:mm`, future) | Preferred for CLI create. |
 | `1` (schedule repeat) | `startDate`, `endDate`, `triggerCrontab` | |
-| `2` (manual) | — | **Not supported for activity topics** (UI only offers 0/1). Using it without `endDate` causes `CAPABILITY_EXECUTION_FAILED`. |
+
+Manual (`2`) and every triggered type (`3`-`6`) are rejected with `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED`.
+
+### Shared topic configuration
+
+- A/B and horse-race experiments are not supported. Omit `expConfig` and use exactly one content group per topic task.
+- The topic owns schedule, activity timezone, channel, frequency limits, channel touch limits, and whitelist.
+- A topic task only owns its name, optional inclusion-only custom audience refinement, one content group, completion indicators, metrics, and description.
+- Do not put schedule, trigger rules, channel, frequency, whitelist, experiment, or `clusterKey` on a topic task. The only accepted task-level `targetClusterType` is the canonical get response value `1`.
+- Keep the topic schedule inside the parent activity period. Create/update/copy requires parent activity `mappingStatus` `0`, `2`, or `5`.
 
 ## Create Topic Orchestration
 
@@ -72,11 +81,11 @@ Use this workflow when a topic has a shared audience plus one or more task-level
 2. **Resolve the parent activity.** Use `activity list|get` to verify the exact `activityId`, editable status, activity dates, and timezone. For a repeated topic, keep `startDate` and `endDate` inside the activity period and interpret the cron in the activity timezone.
 3. **Resolve a real channel.** Query `engage-setting channel list`, then inspect the selected channel before composing content. If several enabled channels match and the user has not specified a provider or an already-confirmed project default, ask which one to use instead of choosing an arbitrary ID.
 4. **Read the channel content contract.** Call `engage-task task build-save-guide` with the known trigger, audience, channel type, and `channelId`. Build every `groupContentList[].contentList[].content` item from `fieldRules.channelContentSchema`; do not infer App Push keys or parameter types from memory.
-5. **Prepare audience and completion inputs.** Resolve real event/property metadata and categorical values through the applicable Analysis workflow. Put the shared condition in `topicQp` or `topicClusterKey`, and only task-specific conditions in each `taskQp`. For a rolling condition such as "recent N days" that must be evaluated for future repeated sends, prefer a custom QP; use an existing cluster only after confirming that its refresh semantics match the send cadence. Build the completion goal separately in `completionIndicatorDef`.
-6. **Build one native `TopicAddDTO`.** Keep nested payload keys in camelCase. Ensure `tasks` is non-empty, `frequencyLimits` and QP fields are JSON strings where documented, each task has channel content, and Android/iOS or other variants map to the correct task audience and message.
+5. **Prepare audience and completion inputs.** Resolve real event/property metadata and categorical values through the applicable Analysis workflow. Put the shared condition in `topicDefinitionRequest` or `topicClusterKey`, and only task-specific conditions in each task's `definitionRequest`. For a rolling condition such as "recent N days" that must be evaluated for future repeated sends, prefer a semantic custom definition; use an existing cluster only after confirming that its refresh semantics match the send cadence. Build the completion goal separately in `completionIndicatorDef`.
+6. **Build one native `TopicAddDTO`.** Keep nested payload keys in camelCase. Ensure `tasks` is non-empty, each semantic definition is a JSON object, each task has channel content, and Android/iOS or other variants map to the correct task audience and message.
 7. **Validate the complex payload.** Run `topic create ... --validate` while correcting the nested payload. Inspect `normalized_input` and confirm that the schedule, audience boundaries, message variants, and completion window retain the intended semantics. After `valid=true`, execute the same payload directly; do not add a redundant dry-run by default.
 8. **Create exactly once.** Run `topic create` with the validated payload. A successful response only reports `data.success`; it does not provide enough evidence to declare the whole orchestration complete.
-9. **Resolve IDs and verify the saved topic.** Call `activity info-list` for the parent activity, match the new topic and tasks by their names, then call `topic get` with the returned `topicId`. Verify the channel, dates, cron, topic audience, each task audience, content, completion goal, and draft status. For custom audiences, confirm that the saved task QP keeps task-owned conditions in `totalCFilter` and the shared topic condition appears only through the topic-to-task merge.
+9. **Resolve IDs and verify the saved topic.** Call `activity info-list` for the parent activity, match the new topic and tasks by their names, then call `topic get` with the returned `topicId`. Verify the channel, dates, cron, semantic topic audience, each semantic task audience, content, completion goal, and draft status.
 10. **Verify generated audiences before reporting completion.** Read the generated topic/task cluster keys with the applicable cluster query and wait for terminal computation state. Require `refresh_status=success`, `progress=100`, `real_available=1`, and `cluster_valid=1`. A zero-user result may be valid, but reconcile it with the discovered categorical values and business expectation. If computation fails, correct only the verified cause and re-check; do not retry an unchanged request or report the topic as fully ready.
 
 Recommended command order:
@@ -95,7 +104,7 @@ activity list/get
 
 ## Output
 
-- `get`: `data.topic` (includes `topicClusterKey` for topic audience).
+- `get`: `data.topic` (includes `topicClusterKey` for an existing audience or `topic_definition_request` plus conversion status for a custom audience).
 - `create` / `update` / `remove-task` / `delete` / `copy`: `data.success`.
 - `copy` may include `data.trigger_time_stale=true` when source schedule-single time is already past.
 
@@ -104,7 +113,7 @@ activity list/get
 - `remove-task` and `delete` are `high-risk-write` — require `--yes`, no dry-run.
 - `remove-task` only deletes **topic tasks** (`topicId` present). Standalone tasks → use `engage-task task delete`.
 - `copy` duplicates the editable topic config and its tasks (not runtime/approval state).
-- `copy` saves via **draft** add (`isDraft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval (`engage-activity.approval.submit` is temporarily unavailable).
+- `copy` saves via **draft** add (`isDraft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval.
 - Prefer `topic get` as a template when inspecting channel/content fields.
 
 ## Create / update audience errors
@@ -113,9 +122,16 @@ activity list/get
 |---|---|
 | `TOPIC_TARGET_CLUSTER_TYPE_UNSUPPORTED` | `targetClusterType=3` (all); topics only allow 1/2 |
 | `TOPIC_CLUSTER_KEY_REQUIRED` | `targetClusterType=2` missing `topicClusterKey`, or topic-root `clusterKey` alias |
-| `TOPIC_QP_REQUIRED` | `targetClusterType=1` missing `topicQp` |
-| `TOPIC_QP_INVALID` | `topicQp` is not a JSON object string |
+| `TOPIC_DEFINITION_REQUIRED` | `targetClusterType=1` missing `topicDefinitionRequest` |
+| `TOPIC_DEFINITION_INVALID` | `topicDefinitionRequest` is not a semantic condition object |
 | `TARGET_CLUSTER_TYPE_INVALID` | `targetClusterType` not a known enum value |
+| `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED` | topic uses manual or a triggered task type |
+| `ACTIVITY_EXPERIMENT_UNSUPPORTED` | topic or a topic task configures an experiment |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | a topic task has multiple experiment-style content groups |
+| `TOPIC_TASK_OVERRIDE_UNSUPPORTED` | a topic task overrides shared topic settings or selects an independent cluster |
+| `TOPIC_TASK_AUDIENCE_EXCLUSION_UNSUPPORTED` | a topic task definition contains exclusion filters |
+| `ACTIVITY_STATUS_INVALID` | parent activity is not editable |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | topic schedule is outside the parent activity period |
 
 ## Copy errors
 
@@ -129,6 +145,8 @@ activity list/get
 | `ACTIVITY_NOT_FOUND` | parent activity missing / deleted / wrong project |
 | `TOPIC_TASKS_REQUIRED` | source topic has no tasks |
 | `ACTIVITY_STATUS_INVALID` | parent activity is approving/working/complete |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | source topic schedule is outside the parent activity period |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | a source topic task has multiple content groups |
 | `TOPIC_COUNT_LIMIT` | activity topic count limit exceeded |
 | `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
 | `TASK_COUNT_LIMIT` | project task count limit exceeded |