@thinkingai/ae-cli 6.0.37 → 6.0.39

package/skills/ae-dataops/references/dataops-flow-create.md

@@ -41,7 +41,7 @@ ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
 # Create task with upstream dependency
 ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --taskName "Export Results" \
-  --preTaskCode ${upstreamTaskCode} \
+  --preTasks "[${upstreamTaskCode},${anotherUpstreamTaskCode}]" \
   --sql "INSERT INTO ads_user SELECT * FROM dwd_user"
 ```
 
@@ -63,23 +63,40 @@ ae-cli dataops_flow +update_integration_task --spaceCode "${spaceCode}" \
 
 Use `dataops_integration +list_sync_solutions` or `+get_sync_detail` to find the `syncId` first. These commands expose workflow `OFFLINE_SYNC` tasks only; app sync tasks are not part of this flow.
 
-### Step 4: Modify SQL Task Content
+### Step 4: Create or Modify Workflow Instance Check Task
+
+`checkItems` is a flat JSON array. Every item contains only `flowCode`, `left`, `right`, and `checkTimeUnit` (`DAY`, `HOUR`, or `MINUTE`). One `AND` or `OR` relation applies to the entire array; nested groups are not supported. For the current workflow, `left` and `right` are at least `1`; for another workflow they may be `0`; `right` must not exceed `left`.
+
+```bash
+ae-cli dataops_flow +create_workflow_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskName "Wait for upstream workflows" \
+  --checkItems '[{"flowCode":10037355068544,"left":1,"right":1,"checkTimeUnit":"DAY"},{"flowCode":10037355068545,"left":2,"right":0,"checkTimeUnit":"HOUR"}]' \
+  --relation OR
+
+ae-cli dataops_flow +update_workflow_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} \
+  --checkItems '[{"flowCode":10037355068544,"left":1,"right":1,"checkTimeUnit":"DAY"}]'
+```
+
+Create defaults are `relation=AND`, `checkInterval=5`, `checkTime=3`, `failRetryTimes=3`, `failRetryInterval=5`, and `failRetryUnit=MINUTE`. On update, omitted check scalars, dependencies, and retry fields keep their current values.
+
+### Step 5: Modify SQL Task Content
 
 ```bash
-# Update SQL task content without changing owner, remark, dependencies, retry, or timeout
+# Update SQL task content and keep dependencies and retry policy
 ae-cli dataops_flow +update_sql_task --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --taskCode ${taskCode} \
   --sql "SELECT * FROM dwd_user"
 ```
 
-### Step 5: Add Task Dependencies (DAG connections)
+### Step 6: Add Task Dependencies (DAG connections)
 
 ```bash
 ae-cli dataops_flow +add_task_relation --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --preTaskCode ${upstreamTaskCode} --taskCode ${downstreamTaskCode}
 ```
 
-### Step 6: Configure Schedule
+### Step 7: Configure Schedule
 
 ```bash
 # CRON expression for scheduled execution
@@ -93,7 +110,7 @@ ae-cli dataops_flow +save_schedule_config --spaceCode "${spaceCode}" \
 - `0 0 */4 * * ?` — Every 4 hours
 - `0 30 8 * * 1-5` — Weekdays at 8:30
 
-### Step 7: Preview Release
+### Step 8: Preview Release
 
 ```bash
 # Preview pending DEV-to-PROD release changes before publishing
@@ -101,7 +118,7 @@ ae-cli dataops_flow +preview_release_flow --spaceCode "${spaceCode}" \
   --flowCode ${flowCode}
 ```
 
-### Step 8: Release to Production and Verify
+### Step 9: Release to Production and Verify
 
 ```bash
 ae-cli dataops_flow +release_flow --spaceCode "${spaceCode}" \
@@ -130,10 +147,12 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 | Command | Purpose | Key Flags |
 |---------|---------|-----------|
 | `+create_flow` | Create DEV flow | `--spaceCode` `--flowName` `[--remark]` |
-| `+create_sql_task` | Create DEV Trino SQL task and save SQL | `--spaceCode` `--flowCode` `--taskName` `--sql` `[--preSql]` `[--postSql]` `[--preTaskCode]` `[--remark]` |
-| `+update_sql_task` | Update DEV Trino SQL task content | `--spaceCode` `--flowCode` `--taskCode` `--sql` `[--preSql]` `[--postSql]` |
-| `+create_integration_task` | Create DEV integration sync task from an existing sync solution | `--spaceCode` `--flowCode` `--taskName` `--syncId` `[--preTaskCode]` `[--remark]` |
-| `+update_integration_task` | Rebind DEV integration sync task to a sync solution | `--spaceCode` `--flowCode` `--taskCode` `--syncId` |
+| `+create_sql_task` | Create DEV Trino SQL task and save SQL | `--spaceCode` `--flowCode` `--taskName` `--sql` `[--preSql]` `[--postSql]` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` `[--remark]` |
+| `+update_sql_task` | Update DEV Trino SQL task content | `--spaceCode` `--flowCode` `--taskCode` `--sql` `[--preSql]` `[--postSql]` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` |
+| `+create_integration_task` | Create DEV integration sync task from an existing sync solution | `--spaceCode` `--flowCode` `--taskName` `--syncId` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` `[--remark]` |
+| `+update_integration_task` | Rebind DEV integration sync task to a sync solution | `--spaceCode` `--flowCode` `--taskCode` `--syncId` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` |
+| `+create_workflow_instance_check_task` | Create DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskName` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` `[--remark]` |
+| `+update_workflow_instance_check_task` | Update DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskCode` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` |
 | `+add_task_relation` | Add DEV dependency | `--spaceCode` `--flowCode` `--preTaskCode` `--taskCode` |
 | `+save_schedule_config` | Save DEV schedule config | `--spaceCode` `--flowCode` `--enabled` `[--cron]` |
 | `+get_task_params` | View DEV task parameter list | `--spaceCode` `--flowCode` `--taskCode` |
@@ -150,17 +169,33 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 - **Schedule config**: `+save_schedule_config` requires `--spaceCode`, `--flowCode`, and `--enabled`. `--cron` is required only when `--enabled true`; omit it when disabling scheduling. It returns `action/result/status`; `result` includes `enabled`, `flow`, `message`, and `cron` only when enabled.
 - **Release preview**: `+preview_release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `flowCode`, `releaseStatus`, `message`, and `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries may include `changed`, `contentCompare`, and `targetTable`.
 - **Release**: `+release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `action/result/status`; `result` includes `flowCode`, `releaseStatus`, `message`, optional `packageCode`, and optional `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries include `changed`.
-- **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; `--preSql`, `--postSql`, `--preTaskCode`, and `--remark` are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
-- **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; `--preSql` and `--postSql` are optional and keep existing values when omitted. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
+- **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, and workflow instance check create/update commands. Omit `--preTasks` on update to preserve existing dependencies; pass `--preTasks '[]'` to clear them; pass a non-empty array to replace them.
+- **Retry policy**: The three task types accept `--failRetryTimes`, `--failRetryInterval`, and `--failRetryUnit`. Create defaults to `3`, `5`, and `MINUTE`. Update preserves every omitted retry field. `MINUTE` is the only supported unit.
+- **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; SQL hooks, dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
+- **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; omitted SQL hooks, dependencies, and retry fields keep existing values. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
 - **Task dependency**: `+add_task_relation` requires `--spaceCode`, `--flowCode`, `--preTaskCode`, and `--taskCode`. `preTaskCode` is upstream and `taskCode` is downstream. It returns `action/result/status`; `result` includes `status`, `flowCode`, `preTaskCode`, `taskCode`, and `message`.
 - **Task parameters**: `+get_task_params` requires `--spaceCode`, `--flowCode`, and `--taskCode`; it has no optional flags. It queries DEV and returns `data` as an array. Items include fields such as `paramKey`, `paramType`, `paramDataType`, `paramFrom`, and built-in flags like `isBd`.
-- **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; `--preTaskCode` and `--remark` are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
-- **SQL task dependencies**: Use optional `--preTaskCode` to create one upstream dependency with the task. Use `+add_task_relation` for additional DAG dependencies.
+- **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
+- **Workflow instance check tasks**: `checkItems` is required and replaces the complete check item list. Create defaults `relation/checkInterval/checkTime` to `AND/5/3`; update preserves omitted scalar values. This command creates `FLOW_CHECK`, not task-instance `TASK_CHECK`.
+
+## Transport Status
+
+Transition status: transitional
+
+Owning module: gaia-mcp workflow
+
+Current transport: DataOps CLI REST
+
+Gateway target: TBD after DataOps workflow Gateway schema review
+
+Review after: 2026-10-27
+
+Exit condition: Migrate or remove these one-to-one commands after equivalent Capability Gateway actions are available.
 
 ## Important Notes
 
 1. **Getting flowCode**: Use `+list_flows` (see `dataops-flow-monitor` Skill)
-2. **Getting taskCode**: Returned by `+create_sql_task` / `+create_integration_task` or query via `+get_flow_overview`
+2. **Getting taskCode**: Returned by a task create command or query via `+get_flow_overview`
 3. **Release Impact**: Submits current DEV changes to PROD; released schedule/config applies to future PROD runs
 4. **SQL Validation**: Recommended to validate before saving TRINO_SQL tasks
 5. **Cannot create circular dependencies**

package/skills/ae-engage/SKILL.md

@@ -52,9 +52,9 @@ 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` |
 | **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 |
 
@@ -145,13 +145,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 +170,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 +213,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 +245,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 +256,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 +270,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 +286,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 +310,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 +362,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 +374,7 @@ 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.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -437,13 +450,13 @@ 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-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 +473,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 +485,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 +497,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 +519,35 @@ 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. 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.

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-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 |