@thinkingai/ae-cli 6.0.30 → 6.0.31

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

@@ -0,0 +1,13 @@
+# analysis user-cluster delete
+
+Delete a user cluster after dependency/influence review.
+
+Do not use it to clear members, stop computation, or hide a cluster. Output confirms deletion of the exact `cluster_name`; verify it is absent from `user-cluster list`.
+
+Flags: `--project-id`, `--cluster-name` required. Add `--confirmed` and `--yes` only after the user accepts the dry-run impact.
+
+```bash
+ae-cli analysis user-cluster delete --project-id <project_id> --cluster-name old_cluster --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis user-cluster delete --project-id <project_id> --cluster-name old_cluster --confirmed --yes
+```

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

@@ -0,0 +1,11 @@
+# analysis user-cluster get
+
+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.
+
+Flags: `--project-id`, `--cluster-names` JSON array.
+
+```bash
+ae-cli analysis user-cluster get --project-id <project_id> --cluster-names '["retained_users"]'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster list
+
+List accessible user clusters for discovery. Use this before any get/update/delete/member command; do not invent `cluster_name`.
+
+Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--offset` is only for stable asset browsing. It is not a member-data pagination strategy.
+When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
+
+Output is a paged cluster inventory, not cluster members or definition-build results.
+
+```bash
+ae-cli analysis user-cluster list --project-id <project_id> --query retained --limit 50
+ae-cli analysis user-cluster list --project-id <project_id> --fields '["cluster_name","display_name","users_num"]' --limit 50 --offset 0
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster-member export
+
+Export cluster members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+
+```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
+```

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

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

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

@@ -0,0 +1,87 @@
+# User cluster definition models
+
+This is the canonical `--definition-request` contract for direct user-cluster create/update. Shared operators, properties, time ranges, and filters are defined in [`audience_models.md`](audience_models.md).
+
+Top-level variants:
+
+- condition: `{"type":"condition","conditions":{"relation":"and|or","items":[...]}}`
+- SQL: `{"type":"sql","sql":"...","params":[{"name":"partdate","type":"part_date","recent_day":"1-7"}]}`
+
+For SQL clusters, quote Trino special identifiers with double quotes, for example `{"type":"sql","sql":"SELECT \"#user_id\" FROM v_user_1 WHERE vip_level >= 3"}`. This applies to identifiers containing `#`, `$`, `@`, spaces, or punctuation; single quotes are string literals.
+
+If a SQL cluster reads an event table, include a predicate on the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without it. This does not apply to the user-table example above.
+
+SQL clusters support only `${PartDate:name}` dynamic placeholders. Each placeholder requires a matching `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. General SQL parameter types (`text`, `number`, `variable`, `time`, and `selector`) are rejected for SQL clusters.
+For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
+
+Discover tables with `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then inspect columns with the same `--usage tag_cluster`. This table set is server-authorized specifically for SQL tags/clusters and differs from the default analysis SQL set.
+
+Optional `include_filter` and `exclude_filter` use the shared filter-group shape.
+
+## Event node
+
+Required: `type=event`, `event`. Defaults: `operator=eq`, `value=1`, `aggregation=count`.
+
+```json
+{
+  "type":"event",
+  "event":"pay",
+  "operator":"gte",
+  "value":2,
+  "aggregation":"count",
+  "property":"amount",
+  "time_range":{"mode":"recent","unit":"day","value":7},
+  "filters":{"relation":"and","items":[{"field":"platform","operator":"eq","values":["ios"]}]}
+}
+```
+
+## User-property node
+
+Required: `type=user`, `field`, `operator`. `values`, `time_relative`, and `time_unit` are optional.
+
+```json
+{"type":"user","field":"vip_level","operator":"gte","values":[3]}
+```
+
+## Tag or cluster membership node
+
+Required: `type=tag|cluster`, `field`. `operator` defaults to `in_cluster`; optional fields are `values`, `cluster_date_policy`, and `specified_cluster_date`.
+
+```json
+{"type":"tag","field":"user_level","operator":"eq","values":["vip"]}
+{"type":"cluster","field":"payer_users","operator":"in_cluster"}
+```
+
+## Compound node
+
+`group` is another `{relation,items}` condition group.
+
+```json
+{"type":"compound","group":{"relation":"or","items":[{"type":"user","field":"country","operator":"eq","values":["US"]},{"type":"cluster","field":"payer_users","operator":"in_cluster"}]}}
+```
+
+## Behavior-sequence node
+
+Required: `type=behavior_sequence`, `completed`, `steps`. Each step requires `event`; optional step fields are `completed`, `filters`, `relative_to_first`, and `window`. The sequence also accepts `time_range` and `window`.
+
+```json
+{
+  "type":"behavior_sequence",
+  "completed":true,
+  "steps":[{"event":"view_item","completed":true},{"event":"pay","completed":true,"window":{"value":7,"unit":"day"}}],
+  "time_range":{"mode":"recent","unit":"day","value":30},
+  "window":{"value":7,"unit":"day"}
+}
+```
+
+## Complete condition request
+
+```json
+{
+  "type":"condition",
+  "conditions":{"relation":"and","items":[
+    {"type":"event","event":"pay","operator":"gte","value":2,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":7}},
+    {"type":"user","field":"country","operator":"eq","values":["US"]}
+  ]}
+}
+```

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

@@ -0,0 +1,11 @@
+# analysis user-cluster refresh
+
+Refresh a user cluster by exact `cluster_name`.
+
+Do not use it to change a definition or upload ID members. Output means recomputation was submitted; inspect cluster state before reporting completion.
+
+Flags: `--project-id`, `--cluster-name` required.
+
+```bash
+ae-cli analysis user-cluster refresh --project-id <project_id> --cluster-name retained_users
+```

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

@@ -0,0 +1,13 @@
+# analysis user-cluster update
+
+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.
+
+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.
+
+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
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --display-name "Retained Users v2"
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster update-id
+
+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.
+
+Flags: `--project-id`, `--cluster-name` required. Provide exactly one of local `--input-file`, reusable `--input-file-id`, or small-test `--file-content`. Optional: `--display-name`, `--remarks`, conditional `--association-property`.
+
+Use `analysis entity id-import-options` for the bound entity. CSV is headerless UTF-8 with exactly one non-empty column per row. Pass `--association-property` only for the primary user entity.
+
+```bash
+ae-cli analysis user-cluster update-id --project-id <project_id> --cluster-name vip_ids --input-file-id <input_file_id>
+```
+
+The response reports `operation_status=PROCESSING` and a pending match summary. Read the cluster again until processing completes to obtain final uploaded, matched, and unmatched counts.

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

@@ -0,0 +1,15 @@
+# analysis user-tag create
+
+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.
+
+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`.
+
+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.
+
+```bash
+ae-cli analysis user-tag create --project-id <project_id> --tag-name high_value --display-name "High Value" --definition-request '{"type":"condition","condition_values":[{"value":"high","events":[{"event":"pay","operator":"gte","value":3,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":30}}]}]}'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag create-id
+
+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`.
+
+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.
+
+Create returns `operation_status=PROCESSING` and `match_summary_status=PENDING`; poll `user-tag get` until progress is 100 for the final `match_summary`.
+
+```bash
+ae-cli analysis user-tag create-id --project-id <project_id> --display-name "VIP Tag" --entity-id <entity_id> --association-property email --input-file /tmp/id-tag.csv --tag-name vip_tag
+```

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

@@ -0,0 +1,13 @@
+# analysis user-tag delete
+
+Delete a user tag after dependency/influence review.
+
+Do not use it to clear history snapshots or hide a tag. Output confirms deletion of the exact `tag_name`; verify it is absent from `user-tag list`.
+
+Flags: `--project-id`, `--tag-name` required. Add `--confirmed` and `--yes` only after the user accepts the dry-run impact.
+
+```bash
+ae-cli analysis user-tag delete --project-id <project_id> --tag-name old_tag --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis user-tag delete --project-id <project_id> --tag-name old_tag --confirmed --yes
+```

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

@@ -0,0 +1,11 @@
+# analysis user-tag get
+
+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.
+
+Flags: `--project-id`, `--tag-names` JSON array.
+
+```bash
+ae-cli analysis user-tag get --project-id <project_id> --tag-names '["user_level"]'
+```

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

@@ -0,0 +1,17 @@
+# 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`.
+
+Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--offset` is only for stable asset browsing. It is not a tag-member pagination strategy.
+When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
+
+Output is a paged tag inventory whose identifier is `tag_name`, the same field consumed by get/update/delete/member/history-tag commands. It is not tag members, history snapshots, or definition-build results.
+
+Tags never accept `cluster_name`; that field belongs only to user clusters. Do not retry a tag command by substituting one identifier for the other.
+
+```bash
+ae-cli analysis user-tag list --project-id <project_id> --query level --limit 50
+ae-cli analysis user-tag list --project-id <project_id> --fields '["tag_name","display_name","users_num"]' --limit 50 --offset 0
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag-member export
+
+Export tag members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+
+```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
+```

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

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

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

@@ -0,0 +1,54 @@
+# User tag definition models
+
+This is the canonical `--definition-request` contract for direct user-tag create/update. Shared operators, properties, time ranges, and filters are defined in [`audience_models.md`](audience_models.md).
+
+Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`.
+
+## Condition tag
+
+`condition_values` is a non-empty array. Each item requires `value`; optional fields are `remark`, `events`, `event_relation`, `filters`, `relation`, `event_user_relation`, and `behavior_sequences`.
+
+```json
+{
+  "type":"condition",
+  "condition_values":[{
+    "value":"payer",
+    "remark":"Paid in the last 30 days",
+    "events":[{"event":"pay","operator":"gte","value":1,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":30}}],
+    "event_relation":"and",
+    "filters":{"relation":"and","items":[{"field":"country","operator":"eq","values":["US"]}]},
+    "event_user_relation":"and"
+  }]
+}
+```
+
+## Metric tag
+
+Required: `event`, `aggregation`. `property` and `time_range` are optional.
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}
+```
+
+## First/last tag
+
+Required: `event`, `occurrence=first|last`, and exactly one value source: `calculation` or `property`. `time_range` and `filters` are optional. Supplying neither or both value sources is rejected before execution.
+
+```json
+{"type":"first_last","first_last":{"event":"login","occurrence":"last","property":"platform","time_range":{"mode":"recent","unit":"day","value":30}}}
+```
+
+## SQL tag
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\", 'payer' AS tag_value FROM hive.ta.v_event_1 WHERE ${PartDate:partdate} AND \"$part_event\"='pay'","params":[{"name":"partdate","type":"part_date","recent_day":"1-7"}]}
+```
+
+SQL tags support only `${PartDate:name}` dynamic placeholders. Every placeholder requires one `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. `Text`, `Number`, `Variable`, `Time`, and `Selector` parameters are valid for general SQL analysis but are not valid for SQL tags.
+For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
+
+Before writing a SQL tag, use `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then call `analysis sql-table columns --project-id <project_id> --table-ref <table_ref> --usage tag_cluster`. The `tag_cluster` authorized table set is intentionally different from the general analysis SQL table set; do not reuse a table discovered with the default `usage=analysis`.
+
+`#user_id`, `$part_event`, and any other Trino identifier containing `#`, `$`, `@`, spaces, or punctuation must be delimited with double quotes. Single quotes are only for values.
+
+When the SQL reads an event table, it must also filter the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without that predicate.

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

@@ -0,0 +1,11 @@
+# analysis user-tag refresh
+
+Refresh a user tag by exact `tag_name`.
+
+Do not use it to change the definition or refresh one history snapshot. Output means recomputation was submitted; inspect tag state before reporting completion.
+
+Flags: `--project-id`, `--tag-name` required.
+
+```bash
+ae-cli analysis user-tag refresh --project-id <project_id> --tag-name user_level
+```

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

@@ -0,0 +1,13 @@
+# analysis user-tag update
+
+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.
+
+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.
+
+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
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --display-name "User Level v2"
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag update-id
+
+Update a tag by remapping imported values to its analysis entity.
+
+Do not use it for condition/metric/first-last/SQL definition changes.
+
+Flags: `--project-id`, `--tag-name` required. Provide exactly one of local `--input-file`, reusable `--input-file-id`, or small-test `--file-content`. Optional: `--display-name`, `--entity-id`, `--remarks`, conditional `--association-property`.
+
+Use `analysis entity id-import-options` for the effective entity. CSV is headerless UTF-8 with exactly two non-empty columns: association value or entity ID, then `tag_value`.
+
+```bash
+ae-cli analysis user-tag update-id --project-id <project_id> --tag-name vip_tag --input-file-id <input_file_id>
+```
+
+The response reports `operation_status=PROCESSING` and a pending match summary. Read the tag again until processing completes to obtain final uploaded, matched, and unmatched counts.

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to create a virtual event from events and filters.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+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.
 
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-event create --project-id <project_id> --override true --payload '{}'
+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
 ```
 
@@ -15,11 +15,11 @@ Capability id: `metadata.virtual_event.create`.
 
 Input sends `project_id`, `override`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Read back with `virtual-event get` when the created event ID is known.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--override` | No | Whether to override an existing virtual event rule. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--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. |

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

@@ -2,20 +2,21 @@
 
 Use when the user needs to delete a virtual event rule.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for super events or by guessed ID; resolve and inspect the virtual event first.
 
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-event delete --project-id <project_id> --v-event-id <v_event_id>
-ae-cli analysis-meta virtual-event delete --dry-run
+ae-cli analysis-meta virtual-event delete --project-id <project_id> --v-event-id <v_event_id> --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-meta virtual-event delete --project-id <project_id> --v-event-id <v_event_id> --yes
 ```
 
 Capability id: `metadata.virtual_event.delete`.
 
 Input sends `project_id`, `v_event_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to get virtual event rule.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for super-event-by-name detail or event result data; this resolves one virtual event by numeric ID.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.virtual_event.get`.
 
 Input sends `project_id`, `v_event_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.virtual_event` contains the virtual-event metadata and rule.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,23 +2,30 @@
 
 Use when the user needs to create a SQL virtual event or user property.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for physical/super properties. Use `analysis_meta +create_virtual_property` only when the gateway capability is unavailable.
 
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-property create --project-id <project_id> --payload '{}'
-ae-cli analysis-meta virtual-property create --dry-run
+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
 ```
 
 Capability id: `metadata.virtual_property.create`.
 
-Input sends `project_id`, `payload`.
+Input sends typed snake_case fields.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--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`. |
+| `--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. |

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

@@ -2,20 +2,21 @@
 
 Use when the user needs to delete or revoke SQL virtual property rule.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for physical/super properties. Omit `--operation` for permanent deletion; pass `revoke` only when the user explicitly wants revocation instead.
 
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-property sql-rule-delete --project-id <project_id> --v-prop-id <v_prop_id> --operation <operation>
-ae-cli analysis-meta virtual-property sql-rule-delete --dry-run
+ae-cli analysis-meta virtual-property sql-rule-delete --project-id <project_id> --v-prop-id <v_prop_id> --operation <operation> --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-meta virtual-property sql-rule-delete --project-id <project_id> --v-prop-id <v_prop_id> --operation <operation> --yes
 ```
 
 Capability id: `metadata.virtual_property.sql_rule_delete`.
 
 Input sends `project_id`, `v_prop_id`, `operation`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,23 +2,30 @@
 
 Use when the user needs to update SQL virtual property rule.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for renaming a physical property. Use only when replacing the complete SQL rule for an existing virtual property and an exact DTO is available.
 
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --payload '{}'
-ae-cli analysis-meta virtual-property sql-rule-update --dry-run
+ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --properties '[...]'
+ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
 ```
 
 Capability id: `metadata.virtual_property.sql_rule_update`.
 
-Input sends `project_id`, `payload`.
+Input sends typed snake_case fields.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--sql-expression` | Yes | Replacement SQL expression. |
+| `--v-prop` | Yes | Existing virtual property JSON object, including its ID and property fields. |
+| `--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. |