@thinkingai/ae-cli 6.0.41 → 6.0.42

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-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/references/metadata_property_dimension_table_bind_existing.md

@@ -18,7 +18,7 @@ ae-cli metadata property bind-existing-dimension-table --project-id <project_id>
 | `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
 | `--data-table-id` | Yes | Existing dimension data table ID. |
 | `--timestamp-join-format` | No | Timestamp join format. |
-| `--dict-columns` | No | Dictionary column names JSON array. |
+| `--dict-columns` | No | Dictionary column names JSON array. The CLI converts each string to the canonical `{"column_name":"..."}` object required by the capability. |
 
 ## Decision Rules