@thinkingai/ae-cli 6.0.31 → 6.0.33

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

@@ -0,0 +1,24 @@
+# analysis project role upsert
+
+Use when the user needs to create or update a project role.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project role upsert --project-id <project_id> --payload <payload>
+ae-cli analysis project role upsert --dry-run --project-id <project_id> --payload <payload>
+```
+
+Capability id: `project.role.upsert`.
+
+Input sends `project_id`, `payload`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--payload` | Yes | Role save payload matching RoleSaveRequestDTO in snake_case. |

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

@@ -0,0 +1,24 @@
+# analysis project role-user list
+
+Use when the user needs to list users bound to a role.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project role-user list --project-id <project_id> --role-name <role_name>
+ae-cli analysis project role-user list --dry-run --project-id <project_id> --role-name <role_name>
+```
+
+Capability id: `project.role_user.list`.
+
+Input sends `project_id`, `role_name`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--role-name` | Yes | Role name. |

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

@@ -0,0 +1,23 @@
+# analysis project timezone get
+
+Use when the user needs to get project time zone configuration.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project timezone get --project-id <project_id>
+ae-cli analysis project timezone get --dry-run --project-id <project_id>
+```
+
+Capability id: `project.timezone.get`.
+
+Input sends `project_id`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |

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

@@ -0,0 +1,23 @@
+# analysis project timezone overview
+
+Use when the user needs to get project time zone overview.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project timezone overview --project-id <project_id>
+ae-cli analysis project timezone overview --dry-run --project-id <project_id>
+```
+
+Capability id: `project.timezone.overview`.
+
+Input sends `project_id`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |

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

@@ -0,0 +1,25 @@
+# analysis project timezone update
+
+Use when the user needs to update one project time zone configuration item.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project timezone update --project-id <project_id> --payload <payload> --item <item>
+ae-cli analysis project timezone update --dry-run --project-id <project_id> --payload <payload> --item <item>
+```
+
+Capability id: `project.timezone.update`.
+
+Input sends `project_id`, `payload`, `item`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--payload` | Yes | Timezone update payload. Shape depends on item. |
+| `--item` | Yes | Timezone item: timezone_toggle, zone_offset, user_timezone, project_timezone_display. |

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

@@ -0,0 +1,24 @@
+# analysis project user-id-items update
+
+Use when the user needs to update project virtual user ID item configuration.
+
+Do not use it for unrelated project-management actions or for fields not present in the common-service capability schema. Do not send camelCase aliases.
+
+Command:
+
+```bash
+ae-cli analysis project user-id-items update --project-id <project_id> --payload <payload>
+ae-cli analysis project user-id-items update --dry-run --project-id <project_id> --payload <payload>
+```
+
+Capability id: `project.user_id_items.update`.
+
+Input sends `project_id`, `payload`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+
+Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--payload` | Yes | Virtual user ID item configuration payload, matching VirtualUserIdConfigSaveRequestDTO in snake_case. |

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

@@ -1,24 +1,39 @@
 # analysis-meta property list
 
-Use when the user needs to list event or user properties.
+Use when the user needs to browse or search event/user property metadata.
 
-Do not use it for property values or across mixed table types; select the event/user scope explicitly.
+Do not use it for property values. Use this command only when the user explicitly wants to inspect metadata or when a prior compiler error asks for disambiguation.
 
 Command:
 
 ```bash
-ae-cli analysis-meta property list --project-id <project_id> --table-type <table_type>
+ae-cli analysis-meta property list --project-id <project_id>
+ae-cli analysis-meta property list --project-id <project_id> --scope event --event-name purchase --query demo
+ae-cli analysis-meta property list --project-id <project_id> --query demo --fields '["prop_id","prop_name","prop_desc","prop_remark","select_type","table_type","authentication_status"]' --limit 20 --offset 0
 ae-cli analysis-meta property list --dry-run
 ```
 
 Capability id: `metadata.property.list`.
 
-Input sends `project_id`, `table_type`.
+Input sends `project_id` and optional `table_type`, `scope`, `event_name`, `query`, `fields`, `limit`, `offset`, `authenticated_only`.
 
-Output `data.properties[]` contains property metadata for the selected table type.
+Output `data.properties[]` contains property metadata. When `limit` or `offset` is provided, output also includes `total`, `limit`, `offset`, and `has_more`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--table-type` | Yes | Property table type. |
+| `--table-type` | No | Optional property table type: `event` or `user`. |
+| `--scope` | No | Optional property scope: `event` or `user`. If omitted, all scopes are queried. |
+| `--event-name` | No | Optional event name filter for event properties. |
+| `--query` | No | Optional keyword filter. Fuzzy match is applied to property name, description, and remark. |
+| `--fields` | No | Optional fields to return as a JSON array. Supported fields: `prop_id`, `prop_name`, `prop_desc`, `prop_remark`, `select_type`, `table_type`, `sub_table_type`, `authentication_status`. |
+| `--limit` | No | Optional page size. |
+| `--offset` | No | Optional zero-based page offset. |
+| `--authenticated-only` | No | When true, return only authenticated properties. |
+
+## Decision Rules
+
+- Prefer `--scope event` or `--scope user` when the user needs a specific table type.
+- Use `--authenticated-only true` only when the user explicitly asks for authenticated assets.
+- For ad-hoc analysis, pass the user's property wording in the AI-facing `definition` instead of pre-querying property metadata.

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

@@ -2,7 +2,7 @@
 
 Use when the user explicitly wants to generate a public link for a dashboard or BI panel.
 
-Do not use for internal resource URLs. Use `analysis_common +get_resource_url` when applicable.
+Do not use for internal resource URLs. Use `analysis-meta asset url-get` when applicable.
 
 Command:
 

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

@@ -1,47 +1,30 @@
 # analysis query create-result-cluster
 
-Precondition: the upstream response must have `result_cluster_available=true` and the selected source must contain `target_contract`. If either is absent, do not call this command or reconstruct a target from display text.
+Save the user or custom-entity population behind one selected synchronous-preview cell as that subject's reusable result cluster.
 
-Save users matched by a previous analysis result target as a reusable result cluster.
-
-Use this after any analysis data command that returns `query_context_id`:
-
-- `analysis adhoc run`
-- `analysis adhoc export`
-- `analysis report-data run`
-- `analysis report-data export`
-- `analysis dashboard-report-data run`
-- `analysis dashboard-report-data export`
-
-Do not pass raw QP.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. The selected metric/action must advertise `create_result_cluster`. `EVENT_LIST` and `NONE` analysis angles cannot be saved as a result cluster.
 
 ## Command
 
 ```bash
 ae-cli analysis query create-result-cluster \
-  --query-context-id <query_context_id> \
-  --target '<json>' \
-  --cluster-name <cluster_name> \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '<merged returned row/column/metric coordinate>' \
+  --cluster-name <unique_name> \
   [--display-name <display_name>] \
   [--zone-offset 8] \
-  [--timeout-seconds 60]
+  [--timeout-seconds 180]
 ```
 
-## Input
-
-- `--query-context-id`: returned by an analysis data run/export submit response, or by the first metadata line of a JSONL artifact.
-- `--target`: pass the selected source's `target_contract.default_target` directly, or copy it and replace only fields named by `target_contract.copy_from_selected_result` for a specific row or cell.
-- `--cluster-name`: result cluster name.
-- `--display-name`: optional display name.
-
-Do not use raw QP or reconstruct the first query request. The server resolves the source QP from Redis by `query_context_id`.
-
-## Target
-
-`--target` uses the same machine-readable `sources[].target_contract` contract as [`drilldown_users_run.md`](drilldown_users_run.md).
+## Input rules
 
-If one `query_context_id` contains multiple report sources, include `report_id`. If it contains multiple BI chart sources, include `chart_id`. BI SQL chart contexts normally return `result_cluster_available=false`; do not create a result cluster unless the first response explicitly says `result_cluster_available=true`.
+- `--query-context-id`, `--source`, and all coordinate fragments must come from the same synchronous `adhoc run`, `report-data run`, or `dashboard-report-data run` response.
+- Match the desired visible row and column in `source.drilldown.row_options`/`column_options`, select the correct metric option, and shallow-merge only their `coordinate` fragments.
+- Never pass `target_id`, raw QP, display-only dates, option presentation fields, or data from an export/download. Exports do not create query contexts.
+- `--cluster-name` must be unique in the project, start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be at most 24 characters. This legacy result-cluster path is stricter than ordinary cluster creation.
+- `--display-name`, when provided, must be at most 80 characters.
 
-## Output
+The saved cluster subject is `source.drilldown.subject` or the selected event metric's `subject`. `USER_LIST` creates a user result cluster. `ENTITY_LIST` creates a result cluster for that custom entity; do not relabel it as a user cluster.
 
-The response contains the result cluster creation result from the analysis service.
+The response must contain the backend cluster creation result. A successful capability envelope without a created cluster identifier/result is not sufficient evidence of completion.

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

@@ -26,4 +26,4 @@ ae-cli analysis report create --project-id <project_id> --report-name "Recent SQ
 
 After creation, keep the `report_id` returned by this exact create response. To verify the report, query the saved default first with `analysis report-data run` and omit `--sql-params`; then make one second query with a value-only `--sql-params` override. Do not rebuild internal `sqlViewParams` or guess an ID.
 
-After any successful report create, call `analysis_common +get_resource_url` with that returned `report_id` and output its `markdown_link`.
+After any successful report create, call `analysis-meta asset url-get` with that returned `report_id` and output its `markdown_link`.

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

@@ -18,7 +18,9 @@ ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001
 ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --artifact-format jsonl
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `use_cache`, artifact `format`, and `timeout_seconds`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, artifact `format`, and `timeout_seconds`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+Timezone contract is identical to `report-data run`: omit `--zone-offset` to match the current user's report UI timezone (falling back to the project default); use an enabled integer from `-12` through `14` for a fixed UTC offset; use `--zone-offset 99` for local-time mode, where rows are not converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`, and the option is not persisted.
 
 Override model:
 
@@ -28,10 +30,10 @@ Override model:
 
 Mixed-model export batches are best-effort rather than rejected only for being mixed. Prefer one model per overridden export because artifact formats cannot surface submission-time warnings as prominently as inline `meta.warnings`.
 
-Output is the gateway envelope. `data` contains opaque `run_id` and `artifact_id`, lifecycle status and expiration, effective timeout/deadline fields, plus `query_context_id` and `query_context_expires_at` when Redis context creation succeeds. Inspect/download through the dedicated CLI commands using the IDs.
+Output is the gateway envelope. `data` contains opaque `run_id` and `artifact_id`, lifecycle status and expiration, and effective timeout/deadline fields. Exports do not create `query_context_id`. Inspect/download through the dedicated CLI commands using the IDs.
 
 Keep `run_id` and `artifact_id` from the same export response. Inspect that exact `run_id`, then download only that paired `artifact_id`; never combine IDs from different exports.
 
 An empty artifact is a successful query and means the requested time range has no data. If every requested report explicitly fails, the run reaches `FAILED` instead of completing an error-only artifact. Mixed exports may contain explicit per-report error markers alongside successful report data.
 
-Use the submit response `query_context_id` immediately with `analysis drilldown-users run` or `analysis query create-result-cluster` when present. JSONL artifacts repeat `query_context_id` and `query_context_expires_at` in the first metadata line; CSV remains pure CSV and carries context only in the submit descriptor. Do not pass raw QP.
+Never use the export response or downloaded rows as a drilldown/result-cluster source. Run a bounded synchronous preview containing the desired cell first.

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

@@ -24,9 +24,19 @@ ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]'
 
 # 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"}]' --limit 20
+
+# Explicit local-time mode (not UTC+99)
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --limit 20
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `use_cache`, `limit`, and `timeout_seconds`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, `limit`, and `timeout_seconds`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+Timezone contract:
+
+- Omit `--zone-offset` to match the report UI for the current user. The backend uses that user's selected timezone when it is available for the project, otherwise the project default.
+- Pass an integer from `-12` through `14` for a fixed UTC offset that is enabled in the project.
+- Pass `--zone-offset 99` for local-time mode: event timestamps retain their reported local time instead of being converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`.
+- The option changes only this execution. It does not update the saved report or the user's UI preference.
 
 Override model:
 
@@ -38,8 +48,8 @@ A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `en
 
 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.
 
-Output is the gateway envelope. `data` contains bounded inline report result items plus `query_context_id`, `drilldown_available`, and `result_cluster_available` when a context can be created.
+Output is the gateway envelope. `data` contains bounded inline report result items plus `query_context_id` and `sources[]`. 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. `sources[].drilldown` is present when the returned preview exposes follow-up actions. Each source is evaluated independently; SQL and other unsupported models have no actions.
 
 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. Mixed batches keep successful items and return `meta.partial`, counts, and per-report `meta.failures` for partial-result handling.
 
-Use `query_context_id` with `analysis drilldown-users run` or `analysis query create-result-cluster`. Do not pass raw QP.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Select only 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

@@ -14,6 +14,8 @@ Input sends `project_id` and `report_id`.
 
 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 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`:
 
 - `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.

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

@@ -19,4 +19,4 @@ Output is the gateway envelope. `data` contains update status, `report_id`, and
 
 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.
 
-After a successful update, call `analysis_common +get_resource_url` with the updated `report_id` and output its `markdown_link`.
+After a successful update, call `analysis-meta asset url-get` with the updated `report_id` and output its `markdown_link`.

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

@@ -0,0 +1,24 @@
+# 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.
+
+Command:
+
+```bash
+ae-cli tracking sdk-sample generate --project-id <project_id> --sdk-types '<json_array>'
+```
+
+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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | Numeric project ID. | Yes |
+| `--sdk-types` | SDK type array. Supported values include `android-java`, `ios-swift`, `web-js`, `server-java`, `server-python`, `server-nodejs`, `unity-csharp`, and the other values listed by command help/schema. | Yes |

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

@@ -2,10 +2,14 @@
 
 Create a condition or SQL user cluster directly from an AI-facing definition request.
 
-Do not use it for uploaded-ID clusters or result-derived clusters; use `user-cluster create-id` or `query create-result-cluster`. A successful create automatically starts the initial computation. Do not immediately call `user-cluster refresh`; use `user-cluster get` to observe the initial refresh/computation status and refresh only for a later explicit recomputation.
+Do not use it for uploaded-ID clusters or result-derived clusters; use `user-cluster create-id` or `query create-result-cluster`. A successful create automatically starts the initial computation; it does not mean the result is already complete. Do not call `user-cluster refresh` afterward. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
+
+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`, `--cluster-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The cluster type comes from `definition_request.type`.
 
+`cluster_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.
+
 Read `user_cluster_models.md` before constructing `--definition-request`. Create does not accept `--remark`; set it later with `user-cluster update` when needed.
 
 The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the cluster. Condition clusters are saved as mixed-condition clusters (`clusterType=CONDITION`, `clusterSubType=MIX_CONDITION`).

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

@@ -4,6 +4,8 @@ Create a cluster by mapping imported values to an analysis entity.
 
 Flags: `--project-id`, `--display-name`, and `--entity-id` are required. Prefer `--input-file <local_csv>`; the CLI uploads it automatically. `--input-file-id` resumes from an existing upload, while `--file-content` is only for small local tests. Exactly one of the three is allowed. Optional: `--cluster-name`, `--remarks`, and conditional `--association-property`.
 
+When supplied, `cluster_name` follows the same 1-80 character machine-name rule as condition/SQL clusters. `display_name` is 1-80 characters and `remarks` is at most 400 characters.
+
 Use `--input-file` for real local files; use `--input-file-id` only when resuming from an existing upload. Do not inline large ID lists.
 
 Run `analysis entity id-import-options` first. For the primary user entity, pass an allowed `--association-property` and put its real values in the single CSV column; `#user_id` is forbidden. For a non-primary entity, omit the flag and put that entity's own IDs in the single column. Every row must be non-empty.

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

@@ -4,6 +4,10 @@ Get exact user cluster details after discovery.
 
 Do not use it for fuzzy discovery or member data. Output contains saved cluster metadata/definition for the requested names.
 
+After `user-cluster create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-cluster refresh`. Until `progress=100` and `refresh_end_time` is not older than `update_time`, `users_num` and member queries may still reflect the previous successful computation. Treat that state as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+
+The raw backend value is returned under `result`. The response also provides aggregate and per-cluster `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_end_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
+
 Flags: `--project-id`, `--cluster-names` JSON array.
 
 ```bash

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

@@ -1,8 +1,10 @@
 # analysis user-cluster refresh
 
-Refresh a user cluster by exact `cluster_name`.
+Explicitly recompute an existing user cluster by exact `cluster_name` without changing its definition.
 
-Do not use it to change a definition or upload ID members. Output means recomputation was submitted; inspect cluster state before reporting completion.
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-cluster create` or an update containing `--definition-request`; those commands already start computation automatically. Output means recomputation was submitted, not completed. Poll `user-cluster get` and verify the new computation before using `users_num` or querying members.
+
+The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
 
 Flags: `--project-id`, `--cluster-name` required.
 

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

@@ -2,10 +2,14 @@
 
 Update a condition or SQL user cluster. Discover the exact `cluster_name` first.
 
-Do not use it for ID-file membership replacement or to create a missing cluster. Output is the updated cluster result; a submitted recomputation may still be in progress.
+Do not use it for ID-file membership replacement or to create a missing cluster. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-cluster refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A successful update means the definition was saved, not that the new result is complete. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
+
+The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
 Flags: `--project-id`, `--cluster-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`. The cluster type comes from `definition_request.type` when the definition changes.
 
+`display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `cluster_name` is an existing exact identifier and cannot be renamed by update.
+
 Read `user_cluster_models.md` before changing the definition. The backend validates and compiles `definition_request` inside update and refuses to modify the cluster if clarification is required. Condition definitions are saved as mixed-condition clusters.
 
 ```bash

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

@@ -1,5 +1,7 @@
 # analysis user-cluster update-id
 
+`display_name` is at most 80 characters and `remarks` is at most 400 characters. The CLI rejects violations before uploading or dispatching the replacement file.
+
 Update a cluster by remapping imported values to its analysis entity.
 
 Do not use it for a condition/SQL cluster. The existing entity binding cannot be changed by this command.

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

@@ -2,10 +2,14 @@
 
 Create a user tag directly from an AI-facing definition request.
 
-Do not use it for uploaded-ID tags; use `user-tag create-id`. Output identifies the created tag and initial state; computation completion is a later state.
+Do not use it for uploaded-ID tags; use `user-tag create-id`. A successful create automatically starts the initial computation; it does not mean the result is already complete. Do not call `user-tag refresh` afterward. Poll `user-tag get` until `progress=100` and `refresh_time` is present before using `users_num` or querying members.
+
+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`.
 
+`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.
+
 Read `user_tag_models.md` before constructing `--definition-request`. Create does not accept `--remark`; set it later with `user-tag update` when needed.
 
 The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the tag.

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

@@ -4,6 +4,8 @@ Create a tag by mapping imported values to an analysis entity.
 
 Flags: `--project-id`, `--display-name`, and `--entity-id` are required. Prefer `--input-file <local_csv>`; the CLI uploads it automatically. `--input-file-id` resumes from an existing upload, while `--file-content` is only for small local tests. Exactly one of the three is allowed. Optional: `--tag-name`, `--remarks`, and conditional `--association-property`.
 
+When supplied, `tag_name` follows the same 1-80 character machine-name rule as calculated tags. `display_name` is 1-80 characters and `remarks` is at most 400 characters.
+
 Use `--input-file` for real local files; use `--input-file-id` only when resuming from an existing upload. Do not inline large ID lists.
 
 Run `analysis entity id-import-options` first. For the primary user entity, column 1 is a real value of the selected `--association-property`; for a non-primary entity, it is that entity's own ID. Column 2 is `tag_value`. The headerless UTF-8 CSV must contain exactly two non-empty columns in every row.

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

@@ -4,6 +4,10 @@ Get exact user tag details after discovery.
 
 Do not use it for fuzzy discovery, member data, or history statistics. Output contains saved tag metadata/definition for the requested names.
 
+After `user-tag create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a definition update, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+
+The raw backend value is returned under `result`. The response also provides aggregate and per-tag `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
+
 Flags: `--project-id`, `--tag-names` JSON array.
 
 ```bash

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

@@ -1,8 +1,10 @@
 # analysis user-tag refresh
 
-Refresh a user tag by exact `tag_name`.
+Explicitly recompute an existing user tag by exact `tag_name` without changing its definition.
 
-Do not use it to change the definition or refresh one history snapshot. Output means recomputation was submitted; inspect tag state before reporting completion.
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update containing `--definition-request`; those commands already start computation automatically. Do not use it to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
+
+The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
 
 Flags: `--project-id`, `--tag-name` required.
 

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

@@ -2,10 +2,14 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Output is the updated tag result; a submitted recomputation may still be in progress.
+Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+
+The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
 Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`. The tag type comes from `definition_request.type` when the definition changes.
 
+`display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `tag_name` is an existing exact identifier and cannot be renamed by update.
+
 Read `user_tag_models.md` before changing the definition. The backend validates and compiles `definition_request` inside update and refuses to modify the tag if clarification is required.
 
 ```bash

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

@@ -1,5 +1,7 @@
 # analysis user-tag update-id
 
+`display_name` is at most 80 characters and `remarks` is at most 400 characters. The CLI rejects violations before uploading or dispatching the replacement file.
+
 Update a tag by remapping imported values to its analysis entity.
 
 Do not use it for condition/metric/first-last/SQL definition changes.

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

@@ -2,18 +2,22 @@
 
 Use when the user needs to create a virtual event from events and filters.
 
-Do not use it for super-event creation. Prefer typed `analysis_meta +create_virtual_event` unless an exact virtual-event rule DTO is already available.
+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`.
 
 Command:
 
 ```bash
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"eventName":"purchase"}]'
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"eventName":"add_to_cart"}]' --filter '{}' --override true
 ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
 ae-cli analysis-meta virtual-event create --dry-run
 ```
 
 Capability id: `metadata.virtual_event.create`.
 
-Input sends `project_id`, `override`, `payload`.
+Input sends `project_id`, `override`, and `payload`. When typed flags are used, ae-cli builds `payload` from `event_name`, `event_desc`, `remark`, and `rule.events/filter`.
 
 Output is a successful gateway envelope with no business data. Read back with `virtual-event get` when the created event ID is known.
 
@@ -22,4 +26,19 @@ Output is a successful gateway envelope with no business data. Read back with `v
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--override` | No | Whether to override an existing virtual event rule. |
-| `--payload` | Yes | Virtual-event DTO: `event_id?`, `event_name`, `event_desc?`, `remark?`, `rule` (`events` plus optional common `filter`), `replace_remark?`, `replace_suggestion?`. Common header fields are server-owned and must be omitted. |
+| `--payload` | No | Full virtual-event DTO: `event_id?`, `event_name`, `event_desc?`, `remark?`, `rule` (`events` plus optional common `filter`), `replace_remark?`, `replace_suggestion?`. Common header fields are server-owned and must be omitted. |
+| `--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 events to combine. Required when `--payload` is omitted. |
+| `--filter` | No | Optional global filter JSON. Referenced properties must come from `analysis-meta property list`. |
+
+## Decision Rules
+- `events` / `filter` must not be handwritten by intuition alone; they must match real metadata in the same project.
+- 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`