@thinkingai/ae-cli 6.1.20 → 6.1.23

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_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`.
 

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

@@ -2,7 +2,7 @@
 
 Stream the native full tag-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-tag-member run` for preview behavior.
+Do not use this command for an inline sample or filtered keyword search; use `user-tag-member list` 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`.
 
@@ -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 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
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output tag-members.jsonl.gz
+ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl --output tag-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/virtual_event_create.md

@@ -4,15 +4,15 @@ Use when the user needs to create a virtual event from events and filters.
 
 Do not use it for super-event creation.
 
-Before constructing `--events` / `--filter`, validate the available events and properties with `analysis-meta event list` and `analysis-meta property list` in the same `project_id`.
+Before constructing `--events` / `--filter`, validate the available events and properties with `analysis-meta event list` and `analysis-meta property list` in the same `project_id`. Resolve tag and cluster names with `analysis user-tag list` / `analysis user-cluster list`; for a fixed tag snapshot, resolve a real date with `analysis history-tag list`.
 
 Command:
 
 ```bash
 ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"event_name":"purchase"}]'
 ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"event_name":"add_to_cart","filter":{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}]' --override true
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@vip_purchase --event-desc 'VIP purchase' --events '[{"event_name":"purchase","filter":{"relation":"and","items":[{"field":{"name":"vip_users","type":"tag"},"operator":"is_true","cluster_date_policy":"SPECIFIED","specified_cluster_date":"2026-09-15"}]}}]'
 ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"ta@qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
-ae-cli analysis-meta virtual-event create --dry-run
 ```
 
 Capability id: `metadata.virtual_event.create`.
@@ -30,16 +30,21 @@ Output data contains `v_event_id` and `event_name`. Use the returned `v_event_id
 | `--event-name` | No | Virtual event name. Must start with `ta@`. Required when `--payload` is omitted. |
 | `--event-desc` | No | Virtual event display name. Required when `--payload` is omitted. |
 | `--remark` | No | Optional virtual event remark. |
-| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:'and|or',items:[{field:{name,type?},operator,values?}]}`. Required when `--payload` is omitted. |
-| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Referenced properties must come from `analysis-meta property list`. |
+| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:"and|or",items:[{field:{name,type?},operator,values?,cluster_date_policy?,specified_cluster_date?}]}`. Required when `--payload` is omitted. |
+| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Normal properties must come from `analysis-meta property list`; tags/clusters must come from their dedicated list commands. |
 
 ## Decision Rules
 - `events` / `filter` must not be handwritten by intuition alone; they must match real metadata in the same project.
 - Use snake_case `event_name`; do not pass the legacy `eventName` spelling.
+- `cluster_date_policy` is valid only when `field.type` is `tag` or `cluster`: `LATEST` uses the latest computed result, `AUTO` matches each analysis date dynamically, and `SPECIFIED` selects one fixed snapshot.
+- `SPECIFIED` requires `specified_cluster_date` in `yyyy-MM-dd` format. Do not send `specified_cluster_date` with `LATEST` or `AUTO`.
+- For tag `SPECIFIED`, choose a date returned by `analysis history-tag list`; do not invent a snapshot date. For a cluster, verify that the chosen fixed date exists in the target environment before creation.
 - Before calling `event list` / `property list`, read the corresponding reference documents.
 - For first validation, pass only required typed parameters: `--project-id`, `--event-name`, `--event-desc`, and `--events`.
 - Use `--payload` only when an exact virtual-event rule DTO is already available.
 - This is an ordinary write operation; execute it without the high-risk confirmation flag.
 
 ## Recommended Chain
-- `analysis-meta event list` -> `analysis-meta property list` -> `analysis-meta virtual-event create`
+- Ordinary properties: `analysis-meta event list` -> `analysis-meta property list` -> `analysis-meta virtual-event create`
+- Tag snapshot: `analysis-meta event list` -> `analysis user-tag list` -> `analysis history-tag list` -> `analysis-meta virtual-event create`
+- Cluster snapshot: `analysis-meta event list` -> `analysis user-cluster list` -> verify the fixed result date -> `analysis-meta virtual-event create`

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta virtual-event get --project-id <project_id> --v-event-id <v_event_id>
-ae-cli analysis-meta virtual-event get --dry-run
 ```
 
 Capability id: `metadata.virtual_event.get`.

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

@@ -12,7 +12,6 @@ Command:
 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 '{"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
 ```
 
 Capability id: `metadata.virtual_property.create`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --properties '[...]'
-ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --dry-run
 ```
 
 Capability id: `metadata.virtual_property.sql_rule_update`.