@thinkingai/ae-cli 6.0.40 → 6.0.42

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

@@ -0,0 +1,119 @@
+# 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 with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
+
+## 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,123 @@
+# 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 with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
+
+## 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,123 @@
+# 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 with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
+
+## 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/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-task.md

@@ -221,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:
 
@@ -257,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

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-indicator-user.md

@@ -0,0 +1,104 @@
+# engage-task indicator-user
+
+Build SQL, query inline users, or export the users behind an engagement-task report indicator.
+
+> Capability ids: `engage-task.indicator-user.sql`, `engage-task.indicator-user.run`, and `engage-task.indicator-user.export` · Domain: `engage` · Risk: read-only.
+
+## Commands
+
+```bash
+# Build and validate SQL without executing it
+ae-cli engage-task indicator-user sql \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator main \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
+
+# Query a bounded inline user list
+ae-cli engage-task indicator-user run \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator secondary \
+  --secondary-index 2 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100
+
+# Export a custom metric's users
+ae-cli engage-task indicator-user export \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator metric \
+  --metric-id metric_1 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv
+```
+
+Use `sql` to obtain the generated user-detail SQL, `run` for a small inline result, and `export` for a downloadable full result.
+
+## Required input
+
+All commands require `--project-id`, `--task-id`, `--indicator`, `--start-time`, and `--end-time`.
+
+Dates use `yyyy-MM-dd`, and the start date must not be later than the end date. The task must exist under the specified project.
+
+`--indicator` maps to the report population as follows:
+
+| Value | Report population | Usage note |
+|---|---|---|
+| `original_trigger` | Original triggered users | Triggered tasks only |
+| `plan` | Planned-delivery users | Task delivery funnel |
+| `actual_trigger` | Actual-trigger/actual-delivery users | Task delivery funnel |
+| `trigger_success` | Successfully triggered/delivered users | Task delivery funnel |
+| `view` | Users who produced the configured view event | Requires view-event data |
+| `click` | Users who produced the configured click event | Requires click-event data |
+| `main` | Main conversion-indicator users | Combine with `--retention-type` for converted/lost users |
+| `secondary` | Nth secondary conversion-indicator users | Requires `--secondary-index` |
+| `metric` | Users behind a configured custom metric | Requires `--metric-id` |
+| `click_activate` | Click activation users | Used in experiment activation reports |
+| `main_activate` | Main-indicator activation users | Used in experiment activation reports |
+| `secondary_activate` | Nth secondary-indicator activation users | Requires `--secondary-index`; used in experiment activation reports |
+
+## Conditional input
+
+- `secondary` and `secondary_activate` require `--secondary-index 1..10`. Other indicators reject this flag.
+- `metric` requires `--metric-id`; obtain the ID with `ae-cli engage-task metric list`. Other indicators reject this flag.
+- `main`, `secondary`, `main_activate`, and `secondary_activate` must reference a conversion indicator configured on the task.
+- `click_activate`, `main_activate`, and `secondary_activate` use `source=experiment` and `group-by=experiment`; explicitly supplied values must also be `experiment`. The task must have an activation event configured. `click_activate` additionally requires a click-event experiment.
+- Non-metric indicators grouped by experiment use `source=experiment`, and the task must be an experiment task. Metric indicators continue to use `source=metric`.
+- Explicit `--source experiment` always requires an experiment task, even with date, batch, or trigger grouping.
+- `--group-by experiment --is-summary false` requires `--exp-group-id`. The `plan` indicator never accepts `--exp-group-id`; when grouped by experiment, it supports summary queries only.
+- `--group-by batch` is supported only by non-triggered tasks. A non-summary batch segment requires `--task-instance-id`.
+- `--group-by trigger` and `original_trigger` are supported only by triggered tasks.
+- `--retention-type lost` supports `actual_trigger`, `trigger_success`, `view`, `click`, `main`, and `secondary`; it also supports `plan` for triggered tasks. It is rejected for `original_trigger`, `metric`, all activate indicators, and `plan` on non-triggered tasks.
+
+## Optional report context
+
+- `--group-by` selects `batch`, `date`, `trigger`, or `experiment`; it defaults to `experiment` for activate indicators and `date` otherwise.
+- `--is-summary` defaults to `true`. Set it to `false` when reproducing a drilled-down batch or experiment row.
+- `--retention-type` selects `retention` or `lost`; the default is `retention`. See the supported combinations above.
+- `--source` selects `task`, `experiment`, or `metric`. It defaults to `metric` for metric indicators, `experiment` for activate indicators or experiment grouping, and `task` otherwise.
+- `--task-instance-id` narrows a non-triggered task to one execution instance.
+- `--exp-group-id` narrows an experiment report to one group.
+- `--push-language-code`, `--user-time-zone`, and `--show-time-zone` reproduce the corresponding task-report filters. Copy their values from the report context when needed.
+- `--push-language-code` accepts `all`, `default`, `ar`, `az`, `bs`, `ca`, `zh-Hans`, `zh-Hant`, `hr`, `cs`, `da`, `nl`, `en`, `et`, `fi`, `fr`, `ka`, `bg`, `de`, `el`, `hi`, `he`, `hu`, `id`, `it`, `ja`, `ko`, `lv`, `lt`, `ms`, `nb`, `fa`, `pl`, `pt`, `pa`, `ro`, `ru`, `sr`, `sk`, `es`, `sv`, `th`, `tr`, `uk`, or `vi`.
+- `--user-time-zone` accepts `all` or a decimal offset from `-12` through `14` that exists in the task's execution details. An unavailable value is rejected instead of falling back to all users.
+- `--show-time-zone` accepts offsets from `-12` through `14`. Omit it or pass `99` to use the backend server's default time zone.
+
+## Execution input and output
+
+- `sql` returns `sql` and `indicator` and does not execute the query.
+- `run` accepts `--request-id`, `--limit`, and `--timeout-seconds`. The default limit is `100` and the maximum is `1000`; the default timeout is `120` seconds and the maximum is `180` seconds. It returns `#user_id`, `#account_id`, and `#distinct_id` for each user.
+- `export` accepts `--request-id`, `--artifact-format jsonl|csv`, and `--timeout-seconds`. The default format is `jsonl`; the maximum timeout is six hours. It returns `run_id` and `artifact_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
+
+Use the query lifecycle commands to inspect and download an export:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download --artifact-id <artifact_id> --output ./task-indicator-users.csv.gz
+```
+
+`--artifact-format` controls the exported file. The global `--format json|table` only controls CLI display output.

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"]'
 ```

package/skills/ae-engage/references/task-submit-approval.md

@@ -27,6 +27,8 @@ Provide exactly one of `--task-id` or `--request`.
 
 - Prefer `task save` followed by `submit-approval --task-id`. The server loads the persisted draft, validates its
   trigger rule, and reuses the existing save-and-submit approval workflow.
+- Never put `taskId` or `task_id` inside `--request`. Existing drafts must use `--task-id`; embedded task IDs fail
+  with `REQUEST_TASK_ID_NOT_ALLOWED` so request fields are never silently discarded.
 - Do not reconstruct or pass `trigger_rule`. It is an internal persisted field.
 - The legacy `--request` mode remains available for existing callers.
 - Required body fields (server validates): `task_name`, `channel_type`, `channel_id`, `group_content_list`, `target_cluster_type`, `trigger_type`, `completion_indicator_def`, `frequency_limits`, `enable_channel_touch_limits`, `group_id`, `trigger_time_strategy`.
@@ -41,5 +43,6 @@ Provide exactly one of `--task-id` or `--request`.
 |---|---|
 | `APPROVAL_INPUT_INVALID` | neither or both of `task_id` and `request` supplied |
 | `REQUEST_REQUIRED` | `--request` missing or not an object |
+| `REQUEST_TASK_ID_NOT_ALLOWED` | `request.taskId` or `request.task_id` supplied; use `--task-id` |
 | `REQUEST_FIELDS_REQUIRED` | required body fields absent/blank |
 | `CAPABILITY_EXECUTION_FAILED` | unmapped domain failure; check `invocation_id` / Hermes logs |

package/skills/ae-engage/references/task-user-detail-export.md

@@ -0,0 +1,31 @@
+# engage-task user-detail export
+
+Export user details for one execution instance of a non-triggered engagement task.
+
+> Capability id: `engage-task.user-detail.export` · Domain: `engage` · Output: asynchronous artifact.
+
+```bash
+ae-cli engage-task user-detail export \
+  --project-id <project-id> \
+  --task-id <task-id> \
+  --task-instance-id <task-instance-id> \
+  --user-status fail \
+  --artifact-format csv
+```
+
+`--user-status` accepts English values only. The statuses below follow the task funnel from audience filtering to the final delivery result:
+
+1. `deduplicate` — users removed because the configured push ID is duplicated.
+2. `frequency_control` — users removed by the task-level frequency-control rules.
+3. `sample` — users excluded by experiment-layer sampling before planned delivery.
+4. `push_plan` — users retained in the planned-delivery population after deduplication, frequency control, and sampling.
+5. `fatigue_control` — planned users removed by channel-level fatigue-control rules.
+6. `push_actual` — users retained in the actual-delivery population after fatigue control.
+7. `exp_skip_push` — actual-delivery users intentionally not sent because their experiment control group is configured to skip delivery.
+8. `success` — users for whom delivery completed successfully.
+9. `fail` — users for whom delivery was attempted but failed. This is the default value.
+
+Use `--task-exec-detail-id` to narrow an instance to one execution detail. Triggered tasks are not supported in this version.
+Each artifact contains at most 1,000,000 rows, matching the Hermes task export safety boundary.
+
+The command returns `run_id` and `artifact_id`. Use `ae-cli engage-query run inspect` to inspect progress and `ae-cli engage-query artifact download` to download the completed artifact.

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.0
+version: 1.0.1
 description: "AE/TE metadata capability-gateway CLI: metadata data-table management and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload and event/property detail belong to ae-analysis."
 ---
 
@@ -30,6 +30,7 @@ Safety:
 - Ordinary writes (`data-table *-write`, `property-bindings-update`, dimension-table bind/create) execute without `--yes`. Delete commands are `high-risk-write`: dry-run first, summarize impact, wait for explicit confirmation, then execute with `--yes`.
 - **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata data-table list` → `metadata_data_table_list.md`).
 - Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Discover names via `ae-analysis` and data table IDs via `metadata data-table list`.
+- `metadata data-table download` is an async artifact command: plain invocation submits, `--wait` waits, and `--output <file>` waits then streams atomically. Resume with `analysis run wait`; local interruption never cancels the remote run.
 
 ## When to Use
 

package/skills/ae-metadata/references/metadata_data_table_download.md

@@ -5,6 +5,7 @@
 ```bash
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 120
+ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --output <file>
 ```
 
 | Parameter | Required | Description |
@@ -12,6 +13,13 @@ ae-cli metadata data-table download --project-id <project_id> --data-table-id <i
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--data-table-id` | Yes | Data table ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
-| `--timeout-seconds` | No | Timeout in seconds, 1 to 7200. |
+| `--timeout-seconds` | No | Remote runtime in seconds, 1 to 21600. |
+| `--wait` | No | Wait for run `SUCCEEDED` and artifact `COMPLETED`. |
+| `--output` | No | Wait, then stream and atomically publish the artifact to this file. |
+| `--force` | No | Replace an existing `--output` file atomically; invalid without `--output`. |
 
-Use this command when the user needs an exported data-table artifact.
+Use this command when the user needs an exported data-table artifact. Plain
+invocation submits only. `--output` implies `--wait`; resume an interrupted
+wait with `ae-cli analysis run wait --run-id <run_id> [--output <file>]`.
+Local interruption never cancels the remote run. Do not use this command for
+inline data-table metadata; use `metadata data-table get` instead.