@thinkingai/ae-cli 6.0.39 → 6.0.41

package/skills/ae-engage/references/flow-metric-update.md

@@ -0,0 +1,77 @@
+# Flow metric update
+
+Use this reference when the user asks to configure, replace, or save effect metric settings for a flow canvas.
+
+Mapped CLI command:
+
+- `ae-cli engage-flow metric update`
+
+Mapped capability:
+
+- `engage-flow.metric.update`
+
+## Safety
+
+This is a write command. Only run it when the user explicitly asks to change a flow's metric configuration. Use `--dry-run` first when the final `metric_map` was assembled by an agent.
+
+The backend uses a clean-and-insert update model: omitted existing metric settings may be deleted. Treat `metric_map` as the complete desired metric configuration for the flow, not a partial patch.
+
+## Required input
+
+- `--project-id`
+- `--flow-id`
+- `--metric-map '<metric_map_json>'`
+
+## Parameter guidance
+
+- `flow_id` is the logical flow ID used by the flow canvas APIs.
+- `metric_map` is a JSON object keyed by metric target-user group. Valid first-level keys are exactly:
+  - `trigger`
+  - `view`
+  - `click`
+  - `ab_test`
+- Preserve first-level group keys exactly. Do not convert `ab_test` to `abTest`.
+- Each group value is an array of Hermes metric DTO objects.
+- Use DTO field names from `HermesMetricReqDTO`: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `displayName`, `orderId`, `note`, and `metricParams`.
+- The CLI boundary accepts snake_case nested DTO fields too, but prefer the native camelCase names above in examples and generated payloads.
+- For existing bindings, include `metricSettingId` so Hermes updates that binding instead of treating it as a new binding.
+- For preset metrics, use `metricType: 1` and a real `metricName` discovered from `engage-setting common-metric list/get`.
+- For custom metrics, use `metricType: 2` plus a complete `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, and `displayName`; Hermes creates the custom metric name.
+- Do not invent metric names, event names, property names, QP structures, or metric-setting IDs. Read the existing flow detail and available metric definitions first, then update the complete desired metric map.
+
+## Examples
+
+Dry-run updating an existing binding:
+
+```bash
+ae-cli --dry-run engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Apply the same update:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Add a custom metric to the `view` group:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"view":[{"metricType":2,"metricQp":"{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}","metricWindowNum":1,"metricWindowTimeUnit":"day","displayName":"Purchase after view","orderId":1}]}'
+```
+
+## Common mistakes
+
+- Do not pass `flow_uuid`; this command requires `flow_id`.
+- Do not pass `metricId`; `HermesMetricReqDTO` has no `metricId` field. Use `metricSettingId` for an existing binding or `metricName` for a preset metric.
+- Do not use arbitrary first-level keys such as `custom`, `ACTION`, or `channel`; use only `trigger`, `view`, `click`, or `ab_test`.
+- Do not submit only the group you want to change unless deleting omitted groups is intended.
+- Do not use this command to query report data. For report metric details, use `references/flow-metric-detail-report.md`.

package/skills/ae-engage/references/flow-metric-user.md

@@ -0,0 +1,118 @@
+# Flow metric-user
+
+Use this reference when the user asks for users behind a process-level flow metric segment, such as a cell in the flow process report.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow metric-user run`
+- `ae-cli engage-flow metric-user export`
+
+Mapped capabilities:
+
+- `engage-flow.metric-user.run`
+- `engage-flow.metric-user.export`
+
+Hermes SQL source: `FlowReportDataService#buildClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of matched users.
+- Use `export` for the full user-detail artifact.
+- This command does not require `--node-uuid`; use `node-user` or `node-metric-user` for node-level cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the process report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected report segment; do not invent or hand-minify partial JSON.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+ae-cli engage-flow metric-user run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100 \
+  --timeout-seconds 120
+```
+
+Export all matched users:
+
+```bash
+ae-cli engage-flow metric-user export \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv \
+  --timeout-seconds 21600
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download \
+  --run-id <run_id> \
+  --artifact-id <artifact_id> \
+  --output ./flow-metric-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- Do not pass `--node-uuid` unless the process-level report segment actually needs branch/node context; for normal node cells use `node-user`.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.
+- If `cluster_def` is missing the date pair implied by `isSummary`, Hermes rejects it before SQL execution.

package/skills/ae-engage/references/flow-node-metric-user.md

@@ -0,0 +1,122 @@
+# Flow node-metric-user
+
+Use this reference when the user asks for users behind a node-level metric segment on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow node-metric-user run`
+- `ae-cli engage-flow node-metric-user export`
+
+Mapped capabilities:
+
+- `engage-flow.node-metric-user.run`
+- `engage-flow.node-metric-user.export`
+
+Hermes SQL source: `FlowNodeReportDataService#buildMetricClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of users behind the selected node metric segment.
+- Use `export` for the full user-detail artifact.
+- Use `node-user` for node data segments that are not metric-detail segments.
+- Use `metric-user` for process-level flow metric cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the node metric report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected node metric report segment; do not invent it.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+ae-cli engage-flow node-metric-user run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name metric_setting_id_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100 \
+  --timeout-seconds 120
+```
+
+Export all matched users:
+
+```bash
+ae-cli engage-flow node-metric-user export \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name metric_setting_id_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv \
+  --timeout-seconds 21600
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download \
+  --run-id <run_id> \
+  --artifact-id <artifact_id> \
+  --output ./flow-node-metric-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- `--node-uuid` is required and must be the canvas node UUID.
+- Do not use this for node data cells; use `node-user` so Hermes routes to the non-metric SQL builder.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.

package/skills/ae-engage/references/flow-node-user.md

@@ -0,0 +1,122 @@
+# Flow node-user
+
+Use this reference when the user asks for users behind a node-level data segment on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow node-user run`
+- `ae-cli engage-flow node-user export`
+
+Mapped capabilities:
+
+- `engage-flow.node-user.run`
+- `engage-flow.node-user.export`
+
+Hermes SQL source: `FlowNodeReportDataService#buildClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of users in the selected node data segment.
+- Use `export` for the full user-detail artifact.
+- Use `metric-user` for process-level flow metric cells.
+- Use `node-metric-user` for node metric cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the node report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected node report segment; do not invent it.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+ae-cli engage-flow node-user run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100 \
+  --timeout-seconds 120
+```
+
+Export all matched users:
+
+```bash
+ae-cli engage-flow node-user export \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv \
+  --timeout-seconds 21600
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download \
+  --run-id <run_id> \
+  --artifact-id <artifact_id> \
+  --output ./flow-node-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- `--node-uuid` is required and must be the canvas node UUID.
+- Do not use this for node metric cells; use `node-metric-user` so Hermes routes to the metric SQL builder.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.

package/skills/ae-engage/references/preset-event.md

@@ -12,6 +12,8 @@ ae-cli engage-setting preset-event update --project-id <project_id> \
 ```
 
 At least one definition is required for update. Event filters use semantic `field`, `operator`, `values`, and `and`/`or`; Hermes resolves project metadata and compiles the stored event object.
+`field` accepts a technical-name string or `{"name":"...","type":"event_property"}`. Unknown
+semantic fields, unsupported relations/operators, and invalid time ranges are rejected.
 
 List hides the stored event QP and returns each semantic field plus its conversion status:
 

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

@@ -23,4 +23,35 @@ ae-cli engage-task push-record query \
 
 ## Output
 
-Returns `record_type`, `items`, `total`, and pagination metadata when the selected backend record type is paginated. Records include available trigger, planned-send, actual-send, success, channel-exception, status, and failure-reason fields.
+Returns `record_type`, `items`, `total`, and pagination metadata when the selected backend record type is paginated.
+
+The count fields depend on `record_type`:
+
+| `record_type` | Actual push field | Successful push field |
+| --- | --- | --- |
+| `scheduled` | `actual_trigger_num` | `trigger_num` |
+| `user_time_zone` | `actual_trigger_num` | `trigger_num` |
+| `triggered` | `actual_push_num` | `push_success_num` |
+
+Scheduled records and nested user-time-zone execution records use stable English `status_name`
+values:
+
+| `status` | `status_name` |
+| --- | --- |
+| `0` | `Waiting` |
+| `1` | `Ready` |
+| `2` | `Pushing` |
+| `3` | `Sent` |
+| `4` | `Retrying` |
+| `5` | `Failed` |
+
+Top-level user-time-zone task instances use a separate status enum:
+
+| `status` | `status_name` |
+| --- | --- |
+| `0` | `Sending` |
+| `1` | `Sent` |
+| `2` | `Finished` |
+
+Use `status` and the count fields for automated assertions. `status_name` never returns an internal
+`hermes.*` localization key.

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

@@ -177,6 +177,14 @@ ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<co
 ```
 
 Prefer the created cluster reference for an existing-cluster audience. For a custom audience, pass the semantic definition as `targetDefinitionRequest`; do not copy or construct stored execution QP.
+Use only the documented semantic fields. Unknown fields are rejected, and property `field` values
+may be technical-name strings or `{name,type}` references.
+
+Custom flow audiences support `behavior_sequence`. When `flow get` returns relation-preserving
+top-level `compound` nodes, retain them unchanged in subsequent saves; they preserve distinct
+member-group, event-group, and outer relations.
+For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
+from the third step onward when its window must be measured from step 1.
 
 ### 5.2 Project Channels
 
@@ -239,6 +247,12 @@ Inside action nodes: `channel_name` → real `channelId`; `content` → `content
 3. Every path must eventually end at `exit_flow`.
 4. `config` may be a JSON object or a JSON string. `targetDefinitionRequest` itself is a JSON object.
 5. Hermes compiles `targetDefinitionRequest` and Flow-specific `triggerDefinition` fields (including branch definitions) on `nodes[]`, `nodeConfigs[]`, and `slotAnswer.nodeConfig.config` before legacy node validation. `node-config validate` uses the same compile path. Other compatible input normalization remains unchanged.
+6. Never send `targetClusterQp`; it is a server-authored execution field. Every `event` and
+   `behavior_sequence` inside `targetDefinitionRequest` must include its own `time_range`.
+   Entry-node `startDate` / `endDate` values do not provide an audience-event time range.
+7. Audience fields must resolve through the current Flow editor metadata scope. If Hermes
+   rejects a field, choose another property returned for the same project, timezone, and user
+   entity instead of constructing persisted metadata manually.
 
 ### 7.2 Common Node Types
 

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

@@ -120,6 +120,39 @@ Task aggregate and completion event definitions support:
 - `aggregation`: `count`, `sum`, or `distinct_count`
 - `operator`: `gt`, `gte`, or `eq`
 
+Completion target and experiment main-goal event filters must not use properties whose metadata
+`select_type` is `datetime`. The supported filter-property select types are `string`, `number`,
+`bool`, `bool-s`, `date`, `array`, `array_string`, `row`, and `array_row`. This restriction applies
+to `completionIndicatorDef.completionIndicators[].eventDefinition.filters`; it does not apply to
+trigger-event filters.
+
+For an event property whose metadata `select_type` is `array_row`, never submit it as a flat
+property filter. Use an object-group filter and place only that parent's child properties inside
+`conditions`:
+
+```json
+{
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
+  }
+}
+```
+
+Object-group operators are `any_satisfy`, `none_satisfy`, and `all_satisfy`. Resolve the parent
+and child fields from current metadata. Hermes validates the metadata type, child-parent
+relationship, and supported operators before saving, so do not flatten `array_row` or invent child
+field names.
+
 Trigger events have an additional envelope contract selected by `eventTriggerType`. Do not apply
 one aggregate event shape to every trigger type. Use the matrix and examples in section 4.4.
 
@@ -188,6 +221,13 @@ Rules:
 - do not guess template IDs
 - `groupContentList` maximum size is `5`
 - `occasionKeys` are parsed from content automatically and are not accepted as input
+- when `expConfig.enableExp=true`, each `groupContentList` item must include
+  `expGroupName`, `expGroupType`, `percentageInExperiment`, and `order`, and the list must
+  mirror `expConfig.expGroupList` one-to-one by `expGroupName`
+- capability `engage-task.task.save` rejects misaligned experiment `groupContentList`
+  (`TASK_EXPERIMENT_GROUP_CONTENT_INVALID`) before the inner save service runs
+- do not submit experiment content as content-only objects such as
+  `{"contentList":[...]}` without the group association fields
 
 Content guidance:
 
@@ -224,6 +264,8 @@ Rules:
 - if `triggerDefinition` is needed, build it from semantic event definitions and resolve real
   event/property names through Analysis metadata
 - always set the A rule's `eventTriggerType` explicitly
+- always set the A rule's `periodTimeSymbol` to `TS01`, `TS02`, `TS03`, or `TS04`; it is
+  required even when `periodStart` and `periodEnd` are present
 - Hermes compiles the semantic event and then validates the final persisted trigger-rule envelope
 - for semantic event-trigger tasks, Hermes backfills missing task-level `startDate` / `endDate`
   from the A rule's `periodStart` / `periodEnd`; explicit task-level dates remain authoritative
@@ -381,6 +423,8 @@ Minimum required field:
 
 When the guide points to event-based completion or experiment-driven main-goal rules, build
 `completionIndicatorDef.completionIndicators[].eventDefinition` from the semantic event contract.
+Read `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes` and exclude
+every property type listed under `excluded` before constructing its `filters`.
 
 Important constraints that still apply:
 

package/skills/ae-engage/references/scene-strategy-audience.md

@@ -25,19 +25,19 @@ Use the same condition definition accepted by Analysis user-cluster commands:
     "relation": "and",
     "items": [
       {
-        "type": "user_property",
-        "property": "vip_level",
+        "type": "user",
+        "field": "vip_level",
         "operator": "eq",
-        "value": "gold"
+        "values": ["gold"]
       },
       {
-        "type": "event_behavior",
+        "type": "event",
         "event": "purchase",
         "aggregation": "count",
         "operator": "gte",
         "value": 2,
-        "time": {
-          "type": "relative",
+        "time_range": {
+          "mode": "recent",
           "unit": "day",
           "value": 7
         }
@@ -48,8 +48,13 @@ Use the same condition definition accepted by Analysis user-cluster commands:
 ```
 
 Before writing, resolve real event and property names through Analysis metadata commands. Never invent names or copy internal calculation codes from historical output.
+Use only the documented semantic fields. Unknown fields are rejected; property `field` accepts a
+technical-name string or a `{name,type}` reference.
 
-Nested `and`/`or`, user properties, event behavior, include/exclude existing clusters, relative time, and custom time use the Analysis semantic shape documented by `ae-analysis`.
+Nested `and`/`or`, user properties, event behavior, `behavior_sequence`, include/exclude existing
+clusters, relative time, and custom time use the Analysis semantic shape documented by
+`ae-analysis`. A `get` response may contain top-level `compound` nodes when stored member,
+event, and outer relations differ. Preserve those compounds when updating the strategy.
 
 ## Create or update
 

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

@@ -2,10 +2,17 @@
 
 Query a task detail report through the L3 Capability Gateway.
 
-Mapped command: `ae-cli capability run engage-task.task-data.detail --input '<json>'`
+Mapped command: `ae-cli engage-task data-detail query`
+
+Capability ID: `engage-task.task-data.detail`
 
 Required input: `project_id`, `task_id`, `detail_type`, `start_time`, `end_time`. `detail_type` is `time`, `instance`, or `instance_daily`; the last form also requires `task_instance_id`.
 
 ```bash
-ae-cli capability run engage-task.task-data.detail --input '{"project_id":1,"task_id":"task_123","detail_type":"time","start_time":"2026-04-01","end_time":"2026-04-07"}'
+ae-cli engage-task data-detail query \
+  --project-id 1 \
+  --task-id task_123 \
+  --detail-type time \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
 ```

package/skills/ae-engage/references/task-metric-detail.md

@@ -2,10 +2,17 @@
 
 Query a task metric detail report through the L3 Capability Gateway.
 
-Mapped command: `ae-cli capability run engage-task.task-data.metric-detail --input '<json>'`
+Mapped command: `ae-cli engage-task effect query`
+
+Capability ID: `engage-task.task-data.metric-detail`
 
 Required input: `project_id`, `task_id`, `start_time`, `end_time`. Optional input includes `request_id`, `push_language_code`, `metric_id_list`, `group_type`, and `show_time_zone`.
 
 ```bash
-ae-cli capability run engage-task.task-data.metric-detail --input '{"project_id":1,"task_id":"task_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+ae-cli engage-task effect query \
+  --project-id 1 \
+  --task-id task_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --metric-id-list '["metric_1"]'
 ```