@thinkingai/ae-cli 6.0.31 → 6.1.4

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,29 @@
 # 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 and contain the backend-supported identifier 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

@@ -28,10 +28,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

@@ -38,8 +38,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[].drilldown` 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/user_cluster_create.md

@@ -2,7 +2,9 @@
 
 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`.
 

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,7 +2,9 @@
 
 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.
 

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

@@ -2,7 +2,9 @@
 
 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`.
 

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,7 +2,9 @@
 
 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.
 

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`

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

@@ -2,11 +2,15 @@
 
 Use when the user needs to create a SQL virtual event or user property.
 
-Do not use it for physical/super properties. Use `analysis_meta +create_virtual_property` only when the gateway capability is unavailable.
+Do not use it for physical/super properties.
+
+Before building `--sql-expression` / `--related-events`, validate available properties and events with `analysis-meta property list` and `analysis-meta event list` in the same `project_id`.
 
 Command:
 
 ```bash
+ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --table-type event --select-type string --sql-expression 'event_name' --sql-event-relation-type relation_default
+ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --property-desc demo --table-type event --select-type string --sql-expression "CASE WHEN status = 1 THEN 'active' ELSE 'inactive' END" --sql-event-relation-type relation_by_setting --related-events '[{"eventName":"purchase"}]' --property-remark demo
 ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --properties '[...]'
 ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
 ```
@@ -22,10 +26,27 @@ Output is a successful gateway envelope with no business data.
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--sql-expression` | Yes | SQL expression used to calculate the virtual property. |
-| `--v-prop` | Yes | Virtual property JSON object with `property.column_name`, `table_type`, and `select_type`. |
+| `--v-prop` | No | Full virtual property JSON object with `property.column_name`, `table_type`, and `select_type`. Use typed property flags unless an exact DTO is already available. |
+| `--property-name` | No | Virtual property name. Must start with `#vp@`. Required when `--v-prop` is omitted. |
+| `--property-desc` | No | Virtual property display name. |
+| `--table-type` | No | Property table type: `event` or `user`. Required when `--v-prop` is omitted. |
+| `--select-type` | No | Property value type: `string`, `number`, `bool`, or `datetime`. Required when `--v-prop` is omitted. |
+| `--property-remark` | No | Optional virtual property remark. |
 | `--properties` | No | Dependent property JSON array. |
 | `--sql-event-relation-type` | No | `relation_default`, `relation_always`, or `relation_by_setting`. |
 | `--related-events` | No | Related events JSON array for `relation_by_setting`. |
 | `--tag-date-policies` | No | Tag date policies JSON array. |
 | `--replace-remark` | No | Replacement remark. |
 | `--replace-suggestion` | No | Replacement suggestion. |
+
+## Decision Rules
+- `sql_expression` / `related_events` cannot be written from experience alone; they must be built from real project metadata.
+- For first validation, pass only required typed parameters: `--project-id`, `--property-name`, `--table-type`, `--select-type`, `--sql-expression`, and `--sql-event-relation-type`.
+- If `--sql-event-relation-type=relation_by_setting`, `--related-events` must contain event names from `analysis-meta event list`.
+- Columns starting with `#` or containing `@` should be double-quoted in Trino SQL.
+- Use `--v-prop` only when an exact virtual property DTO is already available.
+- This is an ordinary write operation; execute it without the high-risk confirmation flag.
+
+## Recommended Chain
+- `analysis-meta property list` -> `analysis-meta virtual-property create`
+- `analysis-meta property list` -> `analysis-meta event list` -> `analysis-meta virtual-property create` when using `relation_by_setting`