@thinkingai/ae-cli 6.1.12 → 6.1.13

package/skills/ae-analysis/references/report_update.md

@@ -10,14 +10,14 @@ Command:
 
 ```bash
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --report-name "New name"
-ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}'
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>']
 ```
 
-Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided.
+Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only with that unchanged definition and is not supported with `model_type=tag`.
 
 Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
 
-When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. The report is not changed on this failure; resolve the ambiguity before retrying.
+When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. The report is not changed on this failure; follow [`../metadata_resolution.md`](../metadata_resolution.md), keep the definition unchanged, and retry with `--resolutions` only after confirmation.
 
 For the shortest safe update, read the current `version` exactly once with `analysis report get` immediately before the write; do not reuse a version from an older list or conversation turn. If a SQL dynamic parameter definition changed, query the saved default before applying an override so default persistence and override behavior are verified separately.
 

package/skills/ae-analysis/references/report_version_rollback.md

@@ -2,7 +2,7 @@
 
 Use when the user explicitly wants to rollback one report to a previous history version.
 
-Do not use without first identifying the target version from `report-change-log list` or an exact user-provided version.
+Do not use without first choosing an item with `can_rollback=true` from `report-change-log list` or receiving an exact user-provided version. Pass the selected item's `target_version`; do not infer it from `version` or `original_version`.
 
 Command:
 

package/skills/ae-analysis/references/rule_list.md

@@ -7,18 +7,20 @@ Do not use it to discover rule field syntax; use `rule-schema` for construction
 Command:
 
 ```bash
-ae-cli analysis-governance rule list --project-id <project_id>
+ae-cli analysis-governance rule list --project-id <project_id> --limit 50 --offset 0
 ae-cli analysis-governance rule list --dry-run --project-id <project_id>
 ```
 
-Capability id: analysis_meta.asset_rule.list.
+Capability id: `governance.rule.list`.
 
-Input sends project_id, payload. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends `project_id`, optional `payload`, `limit`, and `offset`. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
 
-Output `data` is the saved governance rule collection for the project. Resolve a real `rule_id` from this result before update or delete.
+Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Resolve a real `rule_id` from `items` before update or delete.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

package/skills/ae-analysis/references/run_inspect.md

@@ -4,7 +4,7 @@ Inspect an async analysis capability-gateway run returned by export commands.
 
 Use for `analysis adhoc export`, `analysis report-data export`, `analysis dashboard-report-data export`, `analysis bi-panel-page-data export`, and other analysis exports that return `run_id`.
 
-Do not use this for MCP `request_id` cancellation or status. MCP query lifecycle uses the specific MCP command contract.
+Legacy transport `request_id` values are outside this skill's execution path. This command accepts only the capability-gateway `run_id`; if the caller has only a legacy request ID, report that it cannot be inspected or canceled here.
 
 Input:
 
@@ -20,9 +20,12 @@ Input sends `run_id`.
 
 Output is the gateway run descriptor with run status, artifact status, and error fields when the run failed. Keep the `run_id` from the same export result; do not invent or reuse it across artifacts.
 
-Polling rule:
+State interpretation:
 
-- Continue polling while status is running or pending.
-- Treat `COMPLETED` or `SUCCEEDED` as success.
-- Treat `FAILED`, `CANCELED`, or `CANCELLED` as terminal failure.
+- Continue only while run or artifact status is `RUNNING`.
+- Treat only run `SUCCEEDED` plus artifact `COMPLETED` as downloadable success.
+- Treat run or artifact `FAILED`/`CANCELED` as terminal failure.
 - After success, download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>`.
+
+For managed polling and resumability, use `ae-cli analysis run wait --run-id
+<run_id> [--output <file>]` instead of scripting an unbounded inspect loop.

package/skills/ae-analysis/references/run_wait.md

@@ -0,0 +1,37 @@
+# analysis run wait
+
+Resume client-side waiting for an asynchronous run and optionally download its
+completed artifact.
+
+Use this after an export was submitted without `--wait`, or when a previous
+wait was interrupted, detached, reached its client or server deadline, or
+stopped after persistent transient network failures. Do not use it for
+synchronous `run` results, and do not treat it as a cancellation command.
+
+```bash
+ae-cli analysis run wait --run-id <run_id> [--wait-timeout-seconds <n>] [--output <file>] [--force]
+```
+
+Input:
+
+- `--run-id`: exact run ID returned by the original async export.
+- `--wait-timeout-seconds`: optional local wait bound, `1..21600`; default
+  `600`. Expiry does not cancel the remote run.
+- `--output`: optional destination. When present, download begins only after
+  run `SUCCEEDED` and artifact `COMPLETED`.
+- `--force`: optional atomic replacement of an existing `--output`; invalid
+  without `--output`.
+
+The command polls with repeated short inspect requests and internal adaptive
+backoff. Local waiting stops at the earlier of `--wait-timeout-seconds` and the
+server lifecycle deadline, with a short artifact-materialization grace. Ctrl-C
+or a local wait failure never cancels the remote run. The error returns the
+latest lifecycle state plus `remote_run_canceled=false` and `resume_command`.
+Use `analysis query cancel --run-id <run_id>` only when cancellation is
+explicitly intended.
+
+Without `--output`, the response is the successful terminal run descriptor.
+With `--output`, success additionally guarantees a complete atomically
+published local file and returns `output_path`, `bytes`, and content headers.
+Run/artifact failure, unknown protocol states, 404, or authorization failure
+returns a non-zero structured error; do not turn those outcomes into success.

package/skills/ae-analysis/references/user_cluster_export.md

@@ -0,0 +1,13 @@
+# analysis user-cluster export
+
+Export every matching accessible user cluster without pagination.
+
+```bash
+ae-cli analysis user-cluster export \
+  --project-id <project_id> \
+  --output <temporary_path>/clusters.jsonl
+```
+
+Capability id: `analysis.user_cluster.export`.
+
+Optional filters are `--queries`, `--fields`, and `--authenticated-only`. `--limit`, `--offset`, and `--all` are not accepted. The CLI requires a `.jsonl` output path and writes an adjacent `.meta.json` completeness and identity sidecar. Search the file locally; do not load the full snapshot into model context.

package/skills/ae-analysis/references/user_cluster_list.md

@@ -2,7 +2,9 @@
 
 List accessible user clusters for discovery. Use this before any get/update/delete/member command; do not invent `cluster_name`.
 
-Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--queries` is a JSON array of 1-20 keywords and uses OR matching. Default `--limit` is 50; maximum is 200.
 
 `--offset` is only for stable asset browsing. It is not a member-data pagination strategy.
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
@@ -10,6 +12,8 @@ When `has_more=true`, continue only with the returned `next_offset`; do not calc
 Output is a paged cluster inventory, not cluster members or definition-build results.
 
 ```bash
-ae-cli analysis user-cluster list --project-id <project_id> --query retained --limit 50
+ae-cli analysis user-cluster list --project-id <project_id> --queries '["retained","retention"]' --limit 50
 ae-cli analysis user-cluster list --project-id <project_id> --fields '["cluster_name","display_name","users_num"]' --limit 50 --offset 0
 ```
+
+For a complete catalog, use [`user_cluster_export.md`](user_cluster_export.md).

package/skills/ae-analysis/references/user_cluster_member_export.md

@@ -1,12 +1,14 @@
 # analysis user-cluster-member export
 
-Export cluster members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+Stream the native full cluster-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+Do not use this command for an inline sample or filtered keyword search; use `user-cluster-member run` for preview behavior.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
-Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+Export does not accept `--offset`, `--fields`, `--query`, or `--use-cache`. Common executes the native full-download SQL once and streams result rows directly as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages. The existing full-download ceiling still applies.
 
 ```bash
 ae-cli analysis user-cluster-member export --project-id <project_id> --cluster-name retained_users --artifact-format jsonl

package/skills/ae-analysis/references/user_cluster_member_list.md

@@ -4,16 +4,16 @@ Run a bounded inline cluster member query. Read `analysis_data_retrieval.md` bef
 
 Do not use it for complete/unknown-size membership retrieval or cluster metadata. Output contains at most the requested inline limit and has no caller pagination contract.
 
-Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--preview-rows`, `--timeout-seconds`.
 
 When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, and `#distinct_id`. Cluster members do not expose tag-only fields such as `tag_value` or `tag_date`. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
-The inline member limit defaults to 50 and accepts 1..200.
+Omit `--preview-rows` to return at most 1000 rows, matching the UI member query. Explicit values must be between 1 and 100000; use a smaller preview when only a sample is needed.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
 For full or unknown-size member data, use `user-cluster-member export`; the list command has no next-page contract.
 
 ```bash
-ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --limit 100
-ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","country"]' --query US --limit 50
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --preview-rows 100
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","country"]' --query US --preview-rows 50
 ```

package/skills/ae-analysis/references/user_tag_export.md

@@ -0,0 +1,13 @@
+# analysis user-tag export
+
+Export every matching accessible user tag without pagination.
+
+```bash
+ae-cli analysis user-tag export \
+  --project-id <project_id> \
+  --output <temporary_path>/tags.jsonl
+```
+
+Capability id: `analysis.user_tag.export`.
+
+Optional filters are `--queries`, `--fields`, and `--authenticated-only`. `--limit`, `--offset`, and `--all` are not accepted. The CLI requires a `.jsonl` output path and writes an adjacent `.meta.json` completeness and identity sidecar. Search the file locally; do not load the full snapshot into model context.

package/skills/ae-analysis/references/user_tag_list.md

@@ -2,7 +2,9 @@
 
 List accessible user tags for discovery. Use this before get/update/delete/member/history-tag commands; do not invent `tag_name`.
 
-Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--queries` is a JSON array of 1-20 keywords and uses OR matching. Default `--limit` is 50; maximum is 200.
 
 `--offset` is only for stable asset browsing. It is not a tag-member pagination strategy.
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
@@ -12,6 +14,8 @@ Output is a paged tag inventory whose identifier is `tag_name`, the same field c
 Tags never accept `cluster_name`; that field belongs only to user clusters. Do not retry a tag command by substituting one identifier for the other.
 
 ```bash
-ae-cli analysis user-tag list --project-id <project_id> --query level --limit 50
+ae-cli analysis user-tag list --project-id <project_id> --queries '["level","tier"]' --limit 50
 ae-cli analysis user-tag list --project-id <project_id> --fields '["tag_name","display_name","users_num"]' --limit 50 --offset 0
 ```
+
+For a complete catalog, use [`user_tag_export.md`](user_tag_export.md).

package/skills/ae-analysis/references/user_tag_member_export.md

@@ -1,12 +1,14 @@
 # analysis user-tag-member export
 
-Export tag members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+Stream the native full tag-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+Do not use this command for an inline sample or filtered keyword search; use `user-tag-member run` for preview behavior.
+
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
-Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+Export does not accept `--offset`, `--fields`, `--query`, or `--use-cache`. Common executes the native current-tag or history-tag full-download SQL once and streams result rows directly as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages. The existing full-download ceiling still applies.
 
 ```bash
 ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl

package/skills/ae-analysis/references/user_tag_member_list.md

@@ -4,16 +4,16 @@ Run a bounded inline tag member query. Read `analysis_data_retrieval.md` before
 
 Do not use it for complete/unknown-size membership retrieval or history statistics. Output contains at most the requested inline limit and has no caller pagination contract.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--preview-rows`, `--timeout-seconds`.
 
 When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, `#distinct_id`, and the stable logical `tag_value`. Internal calculated tag column names are never part of the public response. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
-The inline member limit defaults to 50 and accepts 1..200.
+Omit `--preview-rows` to return at most 1000 rows, matching the UI member query. Explicit values must be between 1 and 100000; use a smaller preview when only a sample is needed.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
 For full or unknown-size member data, use `user-tag-member export`; the list command has no next-page contract.
 
 ```bash
-ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --limit 100
-ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","tag_value","country"]' --limit 50
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --preview-rows 100
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","tag_value","country"]' --preview-rows 50
 ```

package/skills/ae-analysis/references/virtual_property_create.md

@@ -11,7 +11,7 @@ Command:
 ```bash
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --table-type event --select-type string --sql-expression 'event_name' --sql-event-relation-type relation_default
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --property-desc demo --table-type event --select-type string --sql-expression "CASE WHEN status = 1 THEN 'active' ELSE 'inactive' END" --sql-event-relation-type relation_by_setting --related-events '[{"eventName":"purchase"}]' --property-remark demo
-ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --properties '[...]'
+ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{"property":{"column_name":"#vp@demo","table_type":"event","select_type":"string"}}' --properties '[...]'
 ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
 ```
 
@@ -26,7 +26,7 @@ Output is a successful gateway envelope with no business data.
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--sql-expression` | Yes | SQL expression used to calculate the virtual property. |
-| `--v-prop` | No | Full virtual property JSON object with `property.column_name`, `table_type`, and `select_type`. Use typed property flags unless an exact DTO is already available. |
+| `--v-prop` | No | Full virtual property JSON object with `property.column_name`, `property.table_type`, and `property.select_type`. All three fields belong inside `property`; use typed property flags unless an exact DTO is already available. |
 | `--property-name` | No | Virtual property name. Must start with `#vp@`. Required when `--v-prop` is omitted. |
 | `--property-desc` | No | Virtual property display name. |
 | `--table-type` | No | Property table type: `event` or `user`. Required when `--v-prop` is omitted. |

package/skills/ae-community/SKILL.md

@@ -42,7 +42,7 @@ Safety constraints:
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
-**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), and `operation` (operations).
+**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis-meta` (metadata), and `operation` (operations).
 
 ---
 
@@ -262,7 +262,7 @@ Commands below are shown **without** the `ae-cli community` prefix; all use the
 
 ## Composite scenario skills
 
-Structured multi-step reports (MCP tool chains) — open the linked reference for full workflows.
+Structured multi-step report workflows — open the linked reference for the complete ae-cli command sequence.
 
 | Skill | Purpose |
 |-------|---------|

package/skills/ae-dataops/SKILL.md

@@ -17,7 +17,7 @@ The AE Data Development and Operations domain provides capabilities for data war
 |------------|----------------|------------------------------|
 | `dataops_repo` | Space discovery | — |
 | `dataops_datatable` | Data table and view management | `dataops-table` |
-| `dataops_flow` | Flow creation and orchestration | `dataops-flow-create` |
+| `dataops_flow` | Flow creation, node deletion, and orchestration | `dataops-flow-create` |
 | `dataops_flow` | Flow execution and monitoring | `dataops-flow-monitor` |
 | `dataops_operations` | Operations instance search, details, and task logs | `dataops-flow-monitor` |
 | `dataops_ide` | Data exploration and SQL queries | `dataops-query` |
@@ -89,7 +89,7 @@ You must understand the following key concepts before use, otherwise errors are
 ### Flow Lifecycle
 
 ```
-Create DEV Flow → Create/Update DEV SQL, Integration, or Workflow Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
+Create DEV Flow → Create/Update DEV SQL, Integration, Workflow Instance Check, or Task Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
 ### CRON Format (6 fields)
@@ -112,7 +112,7 @@ Choose the appropriate scenario skill based on user intent to get complete step-
 
 | User Intent | Trigger Skill | Keywords |
 |-------------|---------------|----------|
-| Create flow, add nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, release, cron, scheduled execution |
+| Create flow, add or delete nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, delete task node, release, cron, scheduled execution |
 | View execution status, troubleshoot failures, view logs | `dataops-flow-monitor` | execute flow, running instance, monitor, logs, stop, DAG, troubleshoot |
 | Search operation instances across a space | `dataops-flow-monitor` | operations instance, flow instance search, status statistics, owner statistics |
 | Create datasource, configure sync solution, execute sync | `dataops-integration` | datasource, sync, integration, field mapping, data ingestion, MySQL, ClickHouse, DatabricksJdbc |
@@ -159,6 +159,7 @@ Detailed creation/configuration commands live in [`references/dataops-flow-creat
 
 Key constraints:
 - Create and update tasks in DEV, preview/release before PROD execution.
+- Treat `+delete_task` as high-risk: verify the target with `+get_flow_overview`, preview with `--dry-run`, and use `--yes` only after explicit user confirmation. Deletion affects DEV; release the flow to apply it to PROD.
 - `+execute_flow` always runs PROD; it returns `executeId` for early stop.
 - Prefer `flowInstanceId` from operations search for stable inspection and troubleshooting.
 - Reference workspace parameters in task SQL as `${paramKey}`.

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

@@ -63,7 +63,9 @@ 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: Create or Modify Workflow Instance Check Task
+### Step 4: Create or Modify Instance Check Tasks
+
+#### Workflow instance check
 
 `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`.
 
@@ -80,6 +82,23 @@ ae-cli dataops_flow +update_workflow_instance_check_task --spaceCode "${spaceCod
 
 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.
 
+#### Task instance check
+
+Each task instance `checkItems` entry contains only `flowCode`, `taskCode`, `left`, `right`, and `checkTimeUnit`. The nested `checkItems[].taskCode` identifies a target task inside that item's `flowCode`. On update, the top-level `--taskCode` identifies the TASK_CHECK node to update; it is not a target task code. Use `+get_flow_overview` to discover target task codes. Checking the TASK_CHECK node itself is supported.
+
+```bash
+ae-cli dataops_flow +create_task_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskName "Wait for target tasks" \
+  --checkItems '[{"flowCode":10037355068544,"taskCode":10380350567040,"left":1,"right":1,"checkTimeUnit":"DAY"},{"flowCode":10037355068545,"taskCode":10380350567041,"left":0,"right":0,"checkTimeUnit":"HOUR"}]' \
+  --relation OR
+
+ae-cli dataops_flow +update_task_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCheckNodeCode} \
+  --checkItems '[{"flowCode":10037355068544,"taskCode":10380350567040,"left":1,"right":1,"checkTimeUnit":"DAY"}]'
+```
+
+Task instance check create defaults are `relation=AND`, `checkInterval=10`, and `checkTime=3`; retry defaults are `3`, `5`, and `MINUTE`. `checkItems` is required and replaces the complete target list. On update, omitted check scalars, dependencies, and retry fields keep their current values.
+
 ### Step 5: Modify SQL Task Content
 
 ```bash
@@ -89,6 +108,24 @@ ae-cli dataops_flow +update_sql_task --spaceCode "${spaceCode}" \
   --sql "SELECT * FROM dwd_user"
 ```
 
+### Delete a Task Node
+
+Verify the target with `+get_flow_overview` before any deletion. Preview the request first, then execute it only after explicit user confirmation:
+
+```bash
+ae-cli dataops_flow +get_flow_overview --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode}
+
+ae-cli dataops_flow +delete_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} --dry-run
+
+# Run only after explicit user confirmation
+ae-cli dataops_flow +delete_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} --yes
+```
+
+`+delete_task` deletes exactly one non-placeholder task node in DEV. It removes attached DAG edges but does not reconnect upstream and downstream nodes. It may terminate running DEV debug executions that include the node and does not repair cross-flow `TASK_CHECK` references. A published PROD node remains until the flow is released again. Repeated deletion, a task from another flow, or an internal placeholder returns an error.
+
 ### Step 6: Add Task Dependencies (DAG connections)
 
 ```bash
@@ -153,6 +190,9 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 | `+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]` |
+| `+create_task_instance_check_task` | Create DEV task instance check task | `--spaceCode` `--flowCode` `--taskName` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` `[--remark]` |
+| `+update_task_instance_check_task` | Update DEV task instance check task | `--spaceCode` `--flowCode` `--taskCode` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` |
+| `+delete_task` | Delete one DEV task node after confirmation | `--spaceCode` `--flowCode` `--taskCode` `--yes` |
 | `+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` |
@@ -169,14 +209,16 @@ 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`.
-- **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.
+- **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, workflow instance check, and task 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**: All four 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`; 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`.
+- **Task instance check tasks**: `checkItems` is required and replaces the complete check item list. Each item identifies a target using `flowCode` and `taskCode`. Create defaults `relation/checkInterval/checkTime` to `AND/10/3`; update preserves omitted scalar values. This command creates `TASK_CHECK`.
+- **Task deletion**: `+delete_task` requires `--spaceCode`, `--flowCode`, and `--taskCode`. It is a `high-risk-write`: inspect the node with `+get_flow_overview`, run `--dry-run`, obtain explicit confirmation, and then pass `--yes`. It changes DEV only; release the flow to apply deletion to PROD.
 
 ## Transport Status
 
@@ -186,6 +228,8 @@ Owning module: gaia-mcp workflow
 
 Current transport: DataOps CLI REST
 
+Covered workflow tools: `flow_create_workflow_instance_check_task`, `flow_update_workflow_instance_check_task`, `flow_create_task_instance_check_task`, `flow_update_task_instance_check_task`, and `flow_delete_task`
+
 Gateway target: TBD after DataOps workflow Gateway schema review
 
 Review after: 2026-10-27

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, and operation activities. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity."
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, operation activities, and query lifecycle. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, query lifecycle, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity, engage-query."
 ---
 
 # ae-engage
@@ -33,7 +33,7 @@ Safety constraints:
 
 ## Overview
 
-The `ae-engage` package provides Hermes Engage capabilities across config items, flows, channel settings, and task data. Use capability-gateway commands through `ae-cli engage-flow|engage-task|engage-setting|engage-scene <resource> <action>`; low-frequency reports use the L3 references below.
+The `ae-engage` package provides Hermes Engage capabilities across config items, flows, channel settings, task data, and query lifecycle. Use capability-gateway commands through `ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action>`; low-frequency reports use the L3 references below.
 
 Typical use cases include:
 
@@ -175,6 +175,10 @@ 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
 
+# Query task reports through the Hermes inline task-data capabilities
+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"]'
+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
+
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
@@ -219,8 +223,29 @@ 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
+ae-cli engage-flow metric update --project-id 1 --flow-id flow_id_123 --metric-map '<metric_map_json>'
+
+# Query or export newly exposed flow report surfaces
+ae-cli engage-flow report metric-detail run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
+ae-cli engage-flow report metric-detail export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
+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
+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
+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
+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
+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
+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
 ```
 
+User-detail `run` commands are for bounded inline rows and accept `--request-id`, `--limit`, and `--timeout-seconds`; metric-detail `run` returns the report object. Export commands accept `--request-id`, `--artifact-format csv|jsonl` (default `jsonl`), and `--timeout-seconds`, then return `run_id` and `artifact_id`; poll with `ae-cli engage-query run inspect --run-id RUN_ID`, then download with `ae-cli engage-query artifact download --run-id RUN_ID --artifact-id ARTIFACT_ID --output ./artifact.jsonl.gz`. Cancel running async work with `ae-cli engage-query query cancel --run-id RUN_ID`.
+
+For flow report/user-detail commands, read the matching reference before composing non-trivial input:
+
+- Flow canvas custom metric configuration: `references/flow-metric-update.md`
+- Metric-detail report object or flattened report export: `references/flow-metric-detail-report.md`
+- Users behind a process-level metric segment: `references/flow-metric-user.md`
+- Users behind a node-level data segment: `references/flow-node-user.md`
+- Users behind a node-level metric segment: `references/flow-node-metric-user.md`
+
 ### 5. scene (scene management / config center)
 
 New capability-gateway command group `engage-scene` covers the config center: config items, params, groups, preset/related metrics, config channels, strategies, and templates. Complex DTOs are passed with `--payload` (native camelCase JSON).
@@ -442,6 +467,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/add-approver.md` / `references/approver-list.md` (`engage-setting.approval-approver.{add,list}`)
 - `references/whitelist-list.md` / `references/whitelist.md` (`engage-setting.whitelist.{list,add,update,delete,verify}`)
 - `references/cancel-query-by-request-id.md` (`engage-setting.query.cancel`, L3)
+- `references/cancel-query-run.md` (`engage-query.query.cancel`)
 - `references/push-language.md` (`engage-setting.push-language.{get,set}`)
 - `references/client-param.md` (`engage-setting.client-param.{create,update,delete,list}`)
 - `references/config-table.md` (`engage-setting.config-table.{upload,save,list,query-data,update-data,delete}`)
@@ -480,6 +506,9 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `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`)
+- `references/task-data-detail.md` (`engage-task data-detail query`; capability `engage-task.task-data.detail`)
+- `references/task-metric-detail.md` (`engage-task effect query`; capability `engage-task.task-data.metric-detail`)
+- `references/flow-metric-update.md` (`engage-flow metric update`; capability `engage-flow.metric.update`)
 
 This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the `references/` root directory.
 
@@ -491,7 +520,11 @@ 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 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}`
+`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` / `effect query` / `data-detail query` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
+
+### query
+
+`run inspect` / `artifact download` / `query cancel` (via `engage-query`), capability ID `engage-query.query.cancel`
 
 ### config
 
@@ -511,7 +544,7 @@ Legacy config MCP commands are migrated into the `scene` L2 group and the three
 
 ### flow
 
-`operation-log query` / `version list` / `flow update-remark` / `flow save` / `node-config schema` / `flow get` / `flow list` / `flow manage` / `node-config validate` / `flow delete` / `flow modify-base-info` (via `engage-flow`), plus L3 capabilities `engage-flow.report.{node-overview,process,node-detail,ab-split-node}`
+`operation-log query` / `version list` / `flow update-remark` / `flow save` / `node-config schema` / `flow get` / `flow list` / `flow manage` / `node-config validate` / `flow delete` / `flow modify-base-info` / `metric update` / `report metric-detail run` / `report metric-detail export` / `metric-user run` / `metric-user export` / `node-user run` / `node-user export` / `node-metric-user run` / `node-metric-user export` (via `engage-flow`), plus L3 capabilities `engage-flow.report.{node-overview,process,node-detail,ab-split-node}`
 
 ## Date Format
 
@@ -532,8 +565,10 @@ 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. For a custom audience, pass the Analysis semantic contract as
-   `targetConfig.definitionRequest`. Use semantic `triggerConfig.triggerDefinition` and
-   `completionIndicatorDef.completionIndicators[].eventDefinition`. Build shapes from
+   `targetConfig.definitionRequest`. For an event-triggered task, use semantic
+   `triggerConfig.triggerDefinition` and
+   always include `periodTimeSymbol` (`TS01`, `TS02`, `TS03`, or `TS04`) on its primary A rule.
+   Use semantic `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
@@ -546,6 +581,11 @@ For task draft creation or update, use this workflow:
 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`.
+When `enableExp=true`, capability `engage-task.task.build-save-guide` enriches the handoff so
+`groupContentList` association fields
+(`expGroupName`/`expGroupType`/`percentageInExperiment`/`order`) stay aligned with
+`expConfig.expGroupList`; only replace `contentList[].content`. Capability `engage-task.task.save`
+rejects misaligned experiment content with `TASK_EXPERIMENT_GROUP_CONTENT_INVALID`.
 
 `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).