@thinkingai/ae-cli 6.1.19 → 6.1.21

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

@@ -2,7 +2,7 @@
 
 Execute bounded inline data from one or more saved reports.
 
-Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings -> use the returned synchronous query context for drilldown.
+Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings. Use query context only for a requested, supported follow-up action.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `report-data export`.
 
@@ -10,7 +10,7 @@ Do not use this command for full, unknown-size, larger than the current runtime
 
 This gateway report-data capability executes saved reports with model-specific overrides. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
-Before adding any query-condition override, call `analysis report get` for every `report_id` and branch on `data.model_type`:
+Before adding any query-condition override, reuse each report definition already read or call `analysis report get` for the missing `report_id` and branch on `data.model_type`:
 
 | Saved report model | Valid query-condition overrides |
 |---|---|
@@ -24,8 +24,8 @@ Command:
 # Non-SQL analysis report
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --start-time 2026-07-01 --end-time 2026-07-09 --preview-rows 20
 
-# SQL report, after analysis report get confirms definition.params contains platform
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --preview-rows 20
+# SQL report, after analysis report get confirms a selector option has options[].name=Production
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"environment","value":"Production"}]' --preview-rows 20
 
 # Explicit local-time mode (not UTC+99)
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --preview-rows 20
@@ -47,14 +47,21 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"environment","value":"Production"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
+
+Selector runtime contract:
+
+- Find the matching selector in the live `data.definition.params` returned by `analysis report get`.
+- The override object still uses the field named `value`, but its content must be the exact UI label from that selector's `options[].name`, including case and punctuation.
+- Never put `options[].value` in the runtime override. That field is the saved SQL expansion fragment, not the runtime selector name. For example, if an option is `{"name":"Production","value":"AND is_dev = false"}`, send `{"name":"environment","value":"Production"}`, not the SQL fragment.
+- Do not guess from a stale knowledge-base snapshot and do not automatically translate ambiguous labels. Re-read the live report definition. If execution returns `INVALID_REPORT_DEFINITION` with `selectorName invalid`, correct the override from `options[].name`; do not repeat the unchanged request.
 
 A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `end_time`, or `time_granularity` fails with `INVALID_OVERRIDE_FOR_MODEL`. A homogeneous non-SQL request with `sql_params` also fails. Mixed-model batches are best-effort: data still returns and `meta.warnings[]` uses `OVERRIDE_IGNORED_FOR_MODEL`, `model_type`, `report_ids`, and `ignored_fields` to identify fields that did not apply. Do not discard these warnings.
 
-For a newly created or updated dynamic SQL report, omit `--sql-params` to execute the saved default first. After that succeeds, then make one second call with `--sql-params` to change only the requested value. This separates a broken saved default from a broken override and avoids repeating the same query.
+For a SQL report query, pass the requested value overrides directly through `--sql-params`; omit it when the saved defaults are requested.
 
 Output is the gateway envelope. When at least one report exposes a follow-up action, `data` contains bounded inline report result items plus `query_context_id` and compact `sources[]` summaries. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. SQL-only and otherwise non-drillable results omit query context entirely. Use `analysis query-context get` to read the selected source's full coordinate options.
 
 `meta.actual_cluster_query_scope`, optional `meta.actual_slave_cluster_id`, and `meta.cluster_query_scope_source` describe the actual physical route. Verify them before comparing or drilling down. An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Call `analysis query-context get`, select only its returned row/column/metric options, and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.
+Only when the user requests a supported follow-up action, read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Call `analysis query-context get`, select only its returned row/column/metric options, and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.

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

@@ -2,7 +2,7 @@
 
 Use when the user needs one saved report definition as AI QP without executing the report.
 
-Do not use as a workaround after a builder-supported ad-hoc QP builder fails. For builder failure, stop and handle the structured error or ask for clarification.
+Do not use it to execute report data; use `report-data run/export` for the result. Reuse a definition already read when preparing supported overrides or an ad-hoc query.
 
 Command:
 
@@ -16,10 +16,12 @@ This command reads saved definition metadata and deliberately has no `--use-cach
 
 Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
 
+For saved tag/cluster filters, `data.definition` preserves `field.type` and the persisted `cluster_date_policy`: `AUTO` means dynamic matching by analysis date, `LATEST` means the latest computed result, and `SPECIFIED` requires `specified_cluster_date`. Do not infer dynamic matching from the tag name or `field.type` alone; if a legacy report has no readable policy, state that the saved date semantics are unknown rather than claiming `AUTO`.
+
 For a saved non-SQL report with a time granularity, `data.definition` returns the agent-facing `time_particle_size` spelling, such as `day`, `hour`, or `total`; internal `T0` through `T9` codes must never leak. If `time_particle_size` is absent, the saved definition has no readable granularity. Do not infer a granularity from the number of result rows; execute the saved report as-is or use an explicit ad-hoc definition when the user requires a specific granularity.
 
-This read is mandatory before applying report-data overrides. Branch on `data.model_type`:
+Reuse this definition when already read; otherwise get it before applying report-data overrides. Branch on `data.model_type`:
 
-- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter. A saved PartDate definition exposes boolean `use_timezone` (default `false`); it is definition metadata and cannot be overridden by report-data.
+- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter. For a selector runtime override, copy the exact UI label from `data.definition.params[].options[].name` into the override's `value`; never send `options[].value`, which is the saved SQL expansion fragment. A saved PartDate definition exposes boolean `use_timezone` (default `false`); it is definition metadata and cannot be overridden by report-data.
 - non-SQL analysis models: use `--filters`, `--group-by`, `--start-time`, `--end-time`, or `--time-granularity`; do not send `--sql-params`.
 - `tag`: report-data executes the saved tag definition. For a different tag view, use `analysis history-tag-data run/export`.

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

@@ -15,3 +15,5 @@ Input sends `project_id`, optional `queries`, `model_types`, `fields`, `limit`,
 Output is the gateway envelope. `data` contains report summaries, `total`, effective `limit`, `offset`, `has_more`, and nullable `next_offset`. When `has_more` is true, use exactly `next_offset` for the next call; stop when it is false. Include `version` in `--fields` when the next step is `analysis report update`.
 
 When locating reports, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.
+
+Search matches report names and descriptions, not events inside definitions. Inspect a suitable candidate with `report get` when its definition is not already available; use [metadata resolution](metadata_resolution.md) for a business-measure lookup.

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

@@ -13,13 +13,15 @@ ae-cli analysis report update --project-id <project_id> --report-id <report_id>
 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; `resolutions` is allowed only with that unchanged definition and is not supported with `model_type=tag`.
+When the caller supplies an existing snapshot, optional `--intent-snapshot` accepts `schema_version: 1`, non-empty `requirement`, `definition` and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway. Metadata-only updates use no definition snapshot.
+
+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 when a definition is provided 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 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.
+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 each bound field's path and original wording, fill confirmed model parameters, 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.
+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 the user also requests report data, query directly with the requested value-only `--sql-params` overrides, or omit that flag to use saved defaults.
 
 For a SQL `part_date` parameter, `use_timezone` is a boolean saved definition field with default `false`. Change it only by submitting the complete updated `definition`; report-data `--sql-params` is value-only and must not contain `use_timezone`.
 

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

@@ -2,18 +2,17 @@
 
 Use when the user needs to create an asset governance rule through the capability gateway.
 
-Do not use it when a matching saved rule already exists; list rules first and use `rule-update` for an existing `rule_id`.
+Do not use it when a matching saved rule already exists; list rules first and use `rule update` for an existing `rule_id`.
 
 Command:
 
 ```bash
-ae-cli analysis-governance rule create --project-id <project_id> --payload '{}'
-ae-cli analysis-governance rule create --dry-run --project-id <project_id>
+ae-cli analysis-governance rule create --project-id <project_id> --rule-name <rule_name> --rule '<verified_rule_json>'
 ```
 
-Capability id: analysis_meta.asset_rule.create.
+Capability id: governance.rule.create.
 
-Input sends project_id, payload, rule_name, comment, rule. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, rule_name, comment, rule. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data.rule_id` is the created governance rule identity. Preserve it for later update/delete operations.
 
@@ -24,4 +23,4 @@ Output `data.rule_id` is the created governance rule identity. Preserve it for l
 | --rule-name | No | Rule name; required unless provided inside payload. |
 | --comment | No | Rule comment. |
 | --rule | No | Governance Filter JSON; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -7,14 +7,14 @@ Do not use it to disable a rule or with a guessed ID; resolve the saved rule, dr
 Command:
 
 ```bash
-ae-cli analysis-governance rule delete --project-id <project_id> --payload '{}' --dry-run
+ae-cli analysis-governance rule delete --project-id <project_id> --rule-id <rule_id> --dry-run
 # Summarize the target and impact, then wait for explicit user confirmation.
-ae-cli analysis-governance rule delete --project-id <project_id> --payload '{}' --yes
+ae-cli analysis-governance rule delete --project-id <project_id> --rule-id <rule_id> --yes
 ```
 
-Capability id: analysis_meta.asset_rule.delete.
+Capability id: governance.rule.delete.
 
-Input sends project_id, payload, rule_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, rule_id. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data.deleted` reports whether the identified rule was deleted; `false` must not be presented as a successful deletion.
 
@@ -23,4 +23,4 @@ Output `data.deleted` reports whether the identified rule was deleted; `false` m
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --rule-id | No | Rule ID; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -2,18 +2,17 @@
 
 Use when the user needs to list asset governance rules through the capability gateway.
 
-Do not use it to discover rule field syntax; use `rule-schema` for construction metadata and this command for existing rule IDs and definitions.
+Do not use it to discover rule field syntax; use `rule schema` for construction metadata and this command for existing rule IDs and definitions.
 
 Command:
 
 ```bash
 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: `governance.rule.list`.
 
-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.
+Input sends `project_id`, optional `limit`, and `offset`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 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.
 
@@ -21,6 +20,6 @@ Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `of
 | 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. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |
 | `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
 | `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

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

@@ -8,12 +8,11 @@ Command:
 
 ```bash
 ae-cli analysis-governance rule schema --project-id <project_id>
-ae-cli analysis-governance rule schema --dry-run --project-id <project_id>
 ```
 
-Capability id: analysis_meta.asset_rule.schema.
+Capability id: governance.rule.schema.
 
-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. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is the project-specific rule column/operator schema consumed by the `rule` object in rule create and update commands.
 
@@ -21,4 +20,4 @@ Output `data` is the project-specific rule column/operator schema consumed by th
 | 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. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -2,18 +2,17 @@
 
 Use when the user needs to update an asset governance rule through the capability gateway.
 
-Do not use it to create a new rule or guess a rule ID; resolve the existing rule with `rule-list` before updating its full definition.
+Do not use it to create a new rule or guess a rule ID; resolve the existing rule with `rule list` before updating its full definition.
 
 Command:
 
 ```bash
-ae-cli analysis-governance rule update --project-id <project_id> --payload '{}'
-ae-cli analysis-governance rule update --dry-run --project-id <project_id>
+ae-cli analysis-governance rule update --project-id <project_id> --rule-id <rule_id> --rule-name <rule_name> --rule '<verified_rule_json>'
 ```
 
-Capability id: analysis_meta.asset_rule.update.
+Capability id: governance.rule.update.
 
-Input sends project_id, payload, rule_id, rule_name, comment, rule. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, rule_id, rule_name, comment, rule. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` returns the updated `rule_id` and `updated=true`; a missing rule is an operation failure, not a create fallback.
 
@@ -25,4 +24,4 @@ Output `data` returns the updated `rule_id` and `updated=true`; a missing rule i
 | --rule-name | No | Rule name; required unless provided inside payload. |
 | --comment | No | Rule comment. |
 | --rule | No | Governance Filter JSON; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -1,8 +1,6 @@
 # tracking sdk-sample generate
 
-Use when submit an AI SDK sample generation task.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to submit an AI SDK sample generation task.
 
 Command:
 
@@ -14,7 +12,7 @@ Capability id: `tracking.sdk_sample.generate`
 
 Input sends `project_id` and `sdk_types`. The backend resolves company ID, app ID, and receiver URL from the authorized project. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 

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

@@ -2,7 +2,7 @@
 
 List queryable columns for one server-authorized SQL table.
 
-First call `analysis sql-table list --project-id <project_id>`, then copy an exact returned `table_ref`. Do not guess table or column names.
+For an unknown table, first call `analysis sql-table list --project-id <project_id>`, then copy an exact returned `table_ref`. Reuse an already verified authorized table reference in the same scope. Do not guess table or column names.
 
 ```bash
 ae-cli analysis sql-table columns \

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

@@ -7,7 +7,7 @@ Do not use it for ordinary event/property CRUD, metadata import from XLSX, or as
 Command:
 
 ```bash
-ae-cli analysis-meta super-metadata batch-create --project-id <project_id> --events '[{"event_name":"purchase","event_desc":"Purchase"}]' --event-properties '[{"prop_name":"amount","select_type":"number","super_event_names":["purchase"]}]' --dry-run
+ae-cli analysis-meta super-metadata batch-create --project-id <project_id> --events '[{"event_name":"purchase","event_desc":"Purchase"}]' --event-properties '[{"prop_name":"amount","select_type":"number","super_event_names":["purchase"]}]'
 ```
 
 Capability id: `metadata.super_metadata.batch_create`.

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

@@ -7,7 +7,7 @@ Do not use it to create metadata, delete metadata, hide metadata, update event/p
 Command:
 
 ```bash
-ae-cli analysis-meta super-metadata batch-edit --project-id <project_id> --type event_property --items '[{"prop_name":"amount","prop_desc":"Amount","prop_remark":"Revenue amount"}]' --dry-run
+ae-cli analysis-meta super-metadata batch-edit --project-id <project_id> --type event_property --items '[{"prop_name":"amount","prop_desc":"Amount","prop_remark":"Revenue amount"}]'
 ```
 
 Capability id: `metadata.super_metadata.batch_edit`.

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

@@ -7,8 +7,7 @@ Do not use it to add existing company members to a project; use the project memb
 Command:
 
 ```bash
-ae-cli system member add --dry-run --company-id <company_id> --members @members.json
-ae-cli system member add --company-id <company_id> --members @members.json
+ae-cli system member add --company-id <company_id> --members '[{"login_name":"<login_name>","user_name":"<user_name>"}]'
 ```
 
 Capability id: `system.member.add`.

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

@@ -23,4 +23,4 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
 | `--target-open-id` | Yes | Target member open ID. |
-| `--status` | Yes | Target status. |
+| `--status` | Yes | `locked` or `active`. |

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

@@ -19,5 +19,5 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--limit` | No | Page size. Default: 50, max: 200. |
+| `--limit` | No | Page size. Default: 50, range: 1..100. |
 | `--offset` | No | Zero-based result offset. |

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

@@ -7,7 +7,6 @@ Do not use it for bulk delivery, repeated probing, or an unconstrained HTTP dest
 Command:
 
 ```bash
-ae-cli system ops-alert-contact test --dry-run --company-id <company_id> --channel <channel> --target-file <chmod_600_file>
 ae-cli system ops-alert-contact test --company-id <company_id> --channel <channel> --target-file <chmod_600_file>
 ```
 

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

@@ -7,7 +7,7 @@ Do not use it outside the system query-monitor operation or with fields absent f
 Command:
 
 ```bash
-ae-cli system query-monitor overview --company-id <company-id> --cluster-names <cluster-names_json>
+ae-cli system query-monitor overview --company-id <company-id> --cluster-names '["<cluster_name>"]' --project-ids '[<project_id>]'
 ```
 
 Capability id: `system.query_monitor.overview`.
@@ -20,7 +20,7 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
 | `--duration-minutes` | No | Monitoring duration in minutes. Default: 60. |
-| `--project-ids` | No | Project ID JSON array. |
-| `--space-codes` | No | Project space-code JSON array. |
+| `--project-ids` | Conditional | Non-empty project IDs or space codes are required. |
+| `--space-codes` | Conditional | Non-empty space codes or project IDs are required. |
 | `--cluster-names` | Yes | Query cluster-name JSON array. |
 | `--point-interval-seconds` | No | Chart sample interval seconds. Default: 5. |

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

@@ -7,25 +7,14 @@ Do not use it for an inline page; use `ae-cli system query-task list` instead.
 Command:
 
 ```bash
-ae-cli system query-task options --company-id <company_id>
-ae-cli system query-task export --company-id <company_id> --start-time '2026-07-24 00:00:00' --end-time '2026-07-24 23:59:59' --status-codes '[4]' --content-codes '[101]' --task-type-codes '[6]' --project-ids '[123]'
+ae-cli system query-task export --company-id <company_id> --start-time '2026-07-24 00:00:00' --end-time '2026-07-24 23:59:59' --status-codes '[4]' --content-codes '[101]' --task-type-codes '[6]' --project-ids '[123]' --output <file>
 ```
 
 Capability id: `system.query_task.export`.
 
-Always run `query-task options` first and select codes from its returned mappings. Do not guess numeric filter codes or cluster names.
+If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
-Preserve the `run_id` from this exact submit response and poll:
-
-```bash
-ae-cli analysis run inspect --run-id <run_id>
-```
-
-After success, preserve the same run's `artifact_id` and download:
-
-```bash
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <output_path>
-```
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).
 
 The artifact is CSV and this command intentionally has no `--artifact-format`. Cancel an unfinished export with `ae-cli analysis query cancel --run-id <run_id>`.
 
@@ -47,3 +36,4 @@ The response uses `ok`, `data`, and `meta`. Empty task data is a successful expo
 | `--download-columns` | No | Optional allowlisted CSV column JSON array. |
 | `--request-id` | No | Caller-supplied `cli_<32 lowercase hex>` lifecycle ID; generated when omitted. |
 | `--timeout-seconds` | No | Maximum runtime, `1..21600`; default `21600`. |
+| `--output` | No | Wait and download to this local file. |

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

@@ -20,4 +20,4 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
 | `--task-id` | Yes | Query-monitor task ID. |
-| `--sql-max-chars` | No | Maximum returned SQL characters. |
+| `--sql-max-chars` | No | Maximum returned SQL characters, range: 0..20000. |

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

@@ -7,13 +7,12 @@ Do not use it outside the system query-task operation or with fields absent from
 Command:
 
 ```bash
-ae-cli system query-task options --company-id <company_id>
 ae-cli system query-task list --company-id <company_id> --start-time '2026-07-24 00:00:00' --end-time '2026-07-24 23:59:59' --status-codes '[4]' --content-codes '[101]' --task-type-codes '[6]' --project-ids '[123]'
 ```
 
 Capability id: `system.query_task.list`.
 
-Always run `query-task options` first and select codes from its returned status, content type, task type, project/workspace, and cluster mappings. Do not guess numeric codes.
+If the required filter mappings are unknown, call `ae-cli system query-task options --company-id <company_id>` once. Reuse verified mappings within the same company/project scope; do not guess filter codes or cluster names.
 
 The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
 
@@ -22,10 +21,10 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--start-time` | Yes | Inclusive ISO date/time lower bound. |
-| `--end-time` | Yes | Inclusive ISO date/time upper bound. |
-| `--project-ids` | No | Project ID JSON array. |
-| `--space-codes` | No | Project space-code JSON array. |
+| `--start-time` | Yes | Inclusive lower bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--end-time` | Yes | Inclusive upper bound in `yyyy-MM-dd HH:mm:ss`. |
+| `--project-ids` | Conditional | Non-empty project IDs or space codes are required. |
+| `--space-codes` | Conditional | Non-empty space codes or project IDs are required. |
 | `--status-codes` | Yes | Task status-code JSON array. |
 | `--content-codes` | Yes | Query content-code JSON array. |
 | `--task-type-codes` | Yes | Query task-type-code JSON array. |

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

@@ -19,9 +19,9 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--scope` | Yes | Receiver scope. |
+| `--scope` | Yes | `global` or `project`; project scope requires `--project-ids`. |
 | `--address-url` | Yes | Receiver address URL. |
-| `--address-type` | Yes | Receiver address type. |
+| `--address-type` | Yes | `public` or `private`. |
 | `--project-ids` | No | Project ID JSON array; required for project scope. |
 | `--original-address-url` | No | Original URL when changing an existing address. |
-| `--original-address-type` | No | Original address type. |
+| `--original-address-type` | No | Original `public` or `private` type. |

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

@@ -1,6 +1,6 @@
 # system receiver-detection get
 
-Use when the user needs to get receiver-address detection configuration.
+Use when the user authorizes retrieving receiver-address detection configuration, including initialization. This capability has `risk=write` and requires `system:write`: it may initialize a default task and trigger detection. Keep it out of read-only discovery and audit paths.
 
 Do not use it outside the system receiver-detection operation or with fields absent from the inspected capability schema.
 

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

@@ -22,4 +22,4 @@ The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `
 | Parameter | Required | Description |
 |---|---|---|
 | `--company-id` | Yes | Company ID. |
-| `--login-type` | Yes | Third-party login type. |
+| `--login-type` | Yes | `wecom`, `dingtalk`, or `feishu`. |

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

@@ -7,22 +7,12 @@ Do not use it for a small inline result; use `ae-cli system usage-trend query` i
 Command:
 
 ```bash
-ae-cli system usage-trend export --company-id <company_id> --metric <metric> --start-time <yyyy-MM-dd> --end-time <yyyy-MM-dd> --time-granularity <day_or_week_or_month>
+ae-cli system usage-trend export --company-id <company_id> --metric <metric> --start-time <yyyy-MM-dd> --end-time <yyyy-MM-dd> --time-granularity <day_or_week_or_month> --output <file>
 ```
 
 Capability id: `system.usage_trend.export`.
 
-The submit response returns the `run_id` for this exact export. Preserve it and poll:
-
-```bash
-ae-cli analysis run inspect --run-id <run_id>
-```
-
-When the run succeeds, preserve its `artifact_id` and download the same run-scoped artifact:
-
-```bash
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <output_path>
-```
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).
 
 The artifact format is fixed gzip-compressed JSONL (`.jsonl.gz`); this command intentionally has no `--artifact-format`. Cancel an unfinished export with `ae-cli analysis query cancel --run-id <run_id>`.
 
@@ -42,3 +32,4 @@ The response uses `ok`, `data`, and `meta`. Empty exported data is success when
 | `--data-type` | No | `all`, `event`, or `user` for project-scoped total event volume. |
 | `--request-id` | No | Caller-supplied `cli_<32 lowercase hex>` lifecycle ID; generated when omitted. |
 | `--timeout-seconds` | No | Maximum runtime, `1..21600`; default `21600`. |
+| `--output` | No | Wait and download to this local file. |

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

@@ -1,6 +1,6 @@
 # analysis user-cluster list
 
-List accessible user clusters for discovery. Use this before any get/update/delete/member command; do not invent `cluster_name`.
+List accessible user clusters for discovery. Use this when the target `cluster_name` is unknown; reuse a verified name from the current task and do not invent `cluster_name`.
 
 Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
 

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

@@ -2,7 +2,7 @@
 
 Stream the native full cluster-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Do not use this command for an inline sample or filtered keyword search; use `user-cluster-member run` for preview behavior.
+Do not use this command for an inline sample or filtered keyword search; use `user-cluster-member list` 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`.
 
@@ -11,7 +11,7 @@ If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you
 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
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output members.jsonl.gz
+ae-cli analysis user-cluster-member export --project-id <project_id> --cluster-name retained_users --artifact-format jsonl --output members.jsonl.gz
 ```
+
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).

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

@@ -6,7 +6,7 @@ Do not use it for uploaded-ID tags; use `user-tag create-id`. A successful creat
 
 The response reports this directly: `computation.triggered_automatically=true`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow `next_action`; when it is `poll_get`, invoke `next_capability_id` with the exact `next_input` returned by the command.
 
-Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The tag type comes from `definition_request.type`.
+Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type`.
 
 `tag_name` is a machine identifier: 1-80 characters, starts with a letter, and contains only letters, digits, or underscores. `display_name` is 1-80 characters. The CLI rejects violations before dispatch.
 
@@ -23,3 +23,25 @@ First/last tag for this month:
 ```bash
 ae-cli analysis user-tag create --project-id <project_id> --tag-name latest_platform_this_month --display-name "Latest Platform This Month" --definition-request '{"type":"first_last","first_last":{"event":"login","occurrence":"last","property":"platform","time_range":{"mode":"recent","unit":"month","value":1}}}'
 ```
+
+Periodic refresh can be configured in this same create operation. It is separate from the initial computation. Omitted scheduling flags leave periodic refresh disabled; supplying a schedule enables it. `--enable-auto-refresh true` requires a schedule on create. Do not combine `--enable-auto-refresh false` with a schedule, or pass both schedule forms.
+
+Append one of these options to the create command:
+
+```bash
+# Every day at 02:30 in the tag timezone
+--auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Monday and Sunday at 09:00 (ISO weekdays: 1=Monday, 7=Sunday)
+--auto-refresh-schedule '{"frequency":"weekly","time":"09:00","weekdays":[1,7]}'
+
+# The 1st and 15th of each month at 06:00
+--auto-refresh-schedule '{"frequency":"monthly","time":"06:00","month_days":[1,15]}'
+
+# Custom Quartz schedule, including multiple executions per day
+--auto-refresh-cron '0 0/30 8-18 * * ? *'
+```
+
+`time` uses 24-hour `HH:mm`. `month_days` accepts 1-31; dates absent from a month are skipped. Weekly/monthly schedules require their respective day array; other frequencies reject those fields. The structured form preserves the page's daily/weekly/monthly frequency selection. Cron uses the page's custom schedule mode and preserves every cron field.
+
+Schedules use the tag timezone. Use the existing `--zone-offset` only with an offset supported by the project; omit it to use the project's default behavior. Inspect `user-tag get` for `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset` after creation.

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

@@ -1,6 +1,6 @@
 # analysis user-tag list
 
-List accessible user tags for discovery. Use this before get/update/delete/member/history-tag commands; do not invent `tag_name`.
+List accessible user tags for discovery. Use this when the target `tag_name` is unknown; reuse a verified name from the current task and do not invent `tag_name`.
 
 Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.