@thinkingai/ae-cli 6.0.30 → 6.0.32

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,13 @@
+# analysis user-tag refresh
+
+Explicitly recompute an existing user tag by exact `tag_name` without changing its definition.
+
+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.
+
+```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,15 @@
+# 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. 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.
+
+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,24 +2,43 @@
 
 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.
+
+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> --override true --payload '{}'
+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 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` | 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_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,51 @@
 
 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.
+
+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> --payload '{}'
-ae-cli analysis-meta virtual-property create --dry-run
+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
 ```
 
 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` | 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`

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

package/skills/ae-analysis-global/SKILL.md

@@ -29,25 +29,23 @@ Every command accepts `--host <url>` to override the active AE host, and it may
 
 ## Routing Rules
 
-- In this overlay, **query cluster / service cluster / deployment cluster** means multi-cluster routing for analysis queries. **audience/user segment cluster** means audience membership assets under `analysis_audience`.
+- In this overlay, **query cluster / service cluster / deployment cluster** means multi-cluster routing for analysis queries. **audience/user segment cluster** means user membership assets under `analysis user-cluster`.
 - If the user asks for cluster inventory or cluster info, call `ae-cli analysis +list_query_clusters --project_id <project_id>`. Localized examples include "集群信息" and "有哪些集群".
-- Do not answer query-cluster inventory questions with `ae-cli analysis_audience +list_clusters` unless the user explicitly asks for audience clusters, cohorts, segments, user membership, or cluster definitions.
+- Do not answer query-cluster inventory questions with `ae-cli analysis user-cluster list` unless the user explicitly asks for audience clusters, cohorts, segments, user membership, or cluster definitions.
 - If the user mentions country, region, server, shard, site, market, or deployment area semantics, call `ae-cli analysis +list_query_clusters --project_id <project_id>` before choosing query scope.
 - Match slave cluster intent only against `slaveClusters[].clusterId`, `slaveClusters[].clusterName`, and `slaveClusters[].clusterDesc` returned by `+list_query_clusters`.
-- If a matching accessible slave cluster exists, pass `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>` to `+query_report_data`, `+query_dashboard_report_data`, or `+query_adhoc`.
+- Unified ad-hoc gateway commands (`analysis adhoc run/export`) do not expose `cluster_query_scope`. If the user explicitly needs global/slave ad-hoc analysis, state that the new ad-hoc gateway contract does not support cluster routing yet and stop instead of adding hidden flags or removed ad-hoc commands.
+- Report/dashboard data gateway commands (`analysis report-data run/export`, `analysis dashboard-report-data run/export`) also do not expose `cluster_query_scope`; do not add hidden cluster flags to them.
 - Use `--cluster_query_scope GLOBAL` only when the user clearly asks for global, all clusters, all servers, or cross-cluster aggregated data, and `permissions.canQueryGlobal=true`.
 - If the user does not express global or slave-cluster intent, omit `--cluster_query_scope`.
 - If requested global/slave scope is not allowed, explain `permissions.allowedClusterQueryParams` instead of guessing forbidden parameters.
-- For `+query_adhoc --model_type sql`, never pass `--cluster_query_scope`; SQL model analysis only supports the current self cluster.
+- For SQL model analysis, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster in the current gateway contract.
 
 ## Response Wording
 
 - For `+list_query_clusters`, call the result "query clusters" and summarize `currentCluster`, `slaveClusters`, and `permissions.allowedClusterQueryParams`.
-- For `analysis_audience +list_clusters`, call the result "audience clusters" or "user segments"; do not call those results query clusters.
+- For `analysis user-cluster list`, call the result "audience clusters" or "user segments"; do not call those results query clusters.
 
 ## Commands Added By Multi-Cluster Mode
 
 - `ae-cli analysis +list_query_clusters --project_id <project_id>`
-- `ae-cli analysis +query_report_data ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`
-- `ae-cli analysis +query_dashboard_report_data ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`
-- `ae-cli analysis +query_adhoc ... --cluster_query_scope <GLOBAL|SLAVE> [--slave_cluster_id <id>]`

package/skills/ae-analysis-global/references/list_query_clusters.md

@@ -11,7 +11,7 @@ Domain: **Multi-Cluster Query Routing**
 - Decide whether a later report/dashboard/ad-hoc query should use the current self cluster, global aggregated data, or one specific slave cluster.
 - Resolve country, region, game server, service shard, site, market, or deployment area wording to an accessible slave cluster before passing `cluster_query_scope=SLAVE`.
 
-This command is not for audience/user segment clusters. For cohort, audience, or segment assets, use `analysis_audience +list_clusters`.
+This command is not for audience/user segment clusters. For cohort, audience, or segment assets, use `analysis user-cluster list`.
 
 ## Commands
 
@@ -50,18 +50,19 @@ The result data follows the server DTO used by `list_query_clusters`:
 - Pass `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>` only after this command confirms a requested country, region, server, site, market, or deployment maps to an accessible `slaveClusters[]` item.
 - Match slave intent only against `slaveClusters[].clusterId`, `slaveClusters[].clusterName`, and `slaveClusters[].clusterDesc`.
 - If the requested scope is not allowed, do not guess forbidden parameters. Explain `permissions.allowedClusterQueryParams`.
-- For `+query_adhoc --model_type sql`, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster.
+- Unified ad-hoc gateway commands (`analysis adhoc run/export`) do not expose `cluster_query_scope`; if a global/slave ad-hoc query is requested, report that the gateway contract does not support it yet instead of using removed ad-hoc commands or hidden flags.
+- For SQL model analysis, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster in the current gateway contract.
 
 ## Recommended Chains
 
 - Cluster inventory / cluster info -> `analysis +list_query_clusters`
-- Query DAU for Japan server -> `analysis +list_query_clusters` -> match JP/Japan slave cluster -> query report/dashboard/ad-hoc with `--cluster_query_scope SLAVE --slave_cluster_id <clusterId>`
-- Query all-cluster aggregated DAU -> `analysis +list_query_clusters` -> if `permissions.canQueryGlobal=true`, query with `--cluster_query_scope GLOBAL`
-- View audience cohorts or user segments -> `analysis_audience +list_clusters` instead
+- Query DAU for Japan server -> `analysis +list_query_clusters` -> match JP/Japan slave cluster -> use only commands that explicitly expose cluster routing; the current report/dashboard/ad-hoc gateway data commands do not.
+- Query all-cluster aggregated DAU -> `analysis +list_query_clusters` -> if `permissions.canQueryGlobal=true`, use only commands that explicitly expose cluster routing; otherwise stop and report the capability gap.
+- View audience cohorts or user segments -> `analysis user-cluster list` instead
 
 ## Response Wording
 
 - Use "current query cluster" for `currentCluster`.
 - Use "accessible slave query clusters" for `slaveClusters`.
 - Use "allowed query-scope parameters" for `permissions.allowedClusterQueryParams`.
-- Do not call `analysis_audience +list_clusters` results query clusters; those are audience clusters or user segments.
+- Do not call `analysis user-cluster list` results query clusters; those are audience clusters or user segments.

package/skills/ae-capability/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-capability
-version: 1.2.0
-description: "AE/TE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, dry-run a capability, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields."
+version: 1.3.1
+description: "AE/TE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, optionally validate complex input or dry-run before execute, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields. Prefer on-demand validate OR dry-run — do not stack both by default."
 ---
 
 # ae-capability
@@ -13,14 +13,28 @@ Use this skill for progressive capability discovery and generic gateway invocati
 1. Use a domain skill and its curated command when it directly covers the task.
 2. Otherwise search the capability catalog.
 3. Inspect the selected capability before constructing input.
-4. Dry-run with real input when helpful.
-5. Run after dry-run succeeds; obtain chat confirmation only for delete capabilities.
+4. **Optionally** pre-check — pick **at most one** path from the table below (do not stack validate + dry-run by default).
+5. Execute (`capability run` / curated command). Chat confirmation only for delete (`high-risk-write`).
 
 Never guess a capability ID, input field, enum value, resource ID, or project ID.
 
+### On-demand pre-check (pick one)
+
+Motto: **validate = fix params; dry-run = confirm ready to run.**
+Hard rule: **for the same final input, do not run both validate and dry-run by default.** `dry-run` already includes parameter validation.
+
+| Situation | What to call | Then |
+| --- | --- | --- |
+| Simple / familiar input (typical `read`, few scalar fields) | **Neither** — skip pre-check | `run` directly |
+| Complex `qp` / nested `payload` / share maps; still iterating shape | **`--validate` / `capability validate` only** (may repeat while fixing) | After `valid=true`, **`run` directly** — skip dry-run unless below applies |
+| Need risk / `output_mode` / `supports_cancel`, or `high-risk-write` delete gate | **`--dry-run` / `capability dry-run` only** (once on final input) | Then confirm (delete) / `run`. Do **not** validate first on the same final payload |
+| Rare exception: many validate iterations, then still need delete confirmation | validate while drafting → **one** dry-run on the **final** input | Then chat confirm → `run --yes` |
+
+Do **not** treat `validate → dry-run → run` as the normal path. That stack is the rare exception in the last row only.
+
 ## Skill references
 
-Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → `dry-run` → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.
+Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → (**optional** validate *or* dry-run) → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.
 
 Create or keep a standalone reference only when at least one applies: L2 hard bar, easily confused with neighbors, `high-risk-write` delete workflow, or multi-step orchestration. Domain skills may inline one-line summaries in overview matrices (e.g. `analysis_gateway_assets.md`). See [`capability-command-admission` §10](../../docs/capability-command-admission.md).
 
@@ -36,10 +50,15 @@ ae-cli capability search "<terms>" --domain <domain>
 # Read input_schema, risk, auth, output, and dry-run support.
 ae-cli capability inspect <capability-id>
 
-# Validate and preview input without execution.
+# Optional — fix params only (gateway /validate). Curated: global --validate.
+ae-cli capability validate <capability-id> --input '<json-object>'
+ae-cli metadata data-table sql-write --project-id 1 ... --validate
+
+# Optional — confirm ready to run (gateway /dry-run). Curated: global --dry-run.
 ae-cli capability dry-run <capability-id> --input '<json-object>'
+ae-cli metadata data-table sql-write --project-id 1 ... --dry-run
 
-# Execute after inspection (and dry-run when input is non-trivial).
+# Execute (after inspect; add at most one pre-check when needed).
 ae-cli capability run <capability-id> --input '<json-object>'
 ```
 
@@ -50,7 +69,37 @@ ae-cli capability run <capability-id> --input '<json-object>'
 - `@<path>`.
 - `-` to read JSON from stdin.
 
-The capability namespace is inferred from `<capability-id>` for `inspect`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing.
+The capability namespace is inferred from `<capability-id>` for `inspect`, `validate`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing.
+
+## validate vs dry-run
+
+| | `validate` / `--validate` | `dry-run` / `--dry-run` |
+| --- | --- | --- |
+| Purpose | Check **input shape** while composing complex payloads | **Pre-execution confirmation** (params + risk/output/cancel) |
+| Does it mutate business data? | No | No |
+| Primary success fields | `valid`, `capability_id`, `normalized_input` | `dry_run`, `capability_id`, `risk`, `output_mode`, `supports_cancel`, `normalized_input` |
+| When to prefer | Iterating nested `payload` / `qp` / multi-field JSON | Final input; need risk/output contract or delete gate |
+| Typical failure focus | Missing/invalid fields, type mismatches, bad `qp` structure | Same param errors, plus readiness signals for actual run |
+| Curated commands | Global `--validate` on gateway-backed curated commands | Global `--dry-run` |
+
+Server may still authenticate the caller for both endpoints. Neither executes the capability business handler. Do not combine `--validate` and `--dry-run` on one invocation.
+
+**Complex input:** prefer **`--validate` only** while assembling `qp` / nested payload; after `valid=true`, go to `run`. Use dry-run instead of validate when you need the risk/output preview or a delete confirmation gate — not both.
+
+Example (param risk only — no stacked dry-run):
+
+```bash
+ae-cli metadata data-table sql-write ... --validate   # iterate until valid
+ae-cli metadata data-table sql-write ...              # execute ordinary write
+```
+
+Example (delete gate — dry-run only on final input):
+
+```bash
+ae-cli capability dry-run analysis.folder.delete --input '...'
+# stop, ask user, then:
+ae-cli capability run analysis.folder.delete --input '...' --yes
+```
 
 ## Risk Levels (aligned with lark-cli)
 
@@ -64,12 +113,15 @@ Legacy values such as `create`, `update`, or `delete` are normalized to this thr
 
 ## Safety
 
-- `list`, `search`, `inspect`, and `dry-run` never execute business mutations.
+- `list`, `search`, `inspect`, `validate`, and `dry-run` never execute business mutations.
+- Curated gateway commands: `--validate` → `/validate`; `--dry-run` → `/dry-run`; do not combine them.
+- Do not stack validate + dry-run on the same final input by default (efficiency).
 - `capability run` inspects metadata before execution when `--yes` is absent.
 - Only `high-risk-write` requires chat confirmation before `capability run ... --yes`.
-- `read` and `write` may run directly after inspect/dry-run.
+- `read` and ordinary `write` may run after inspect; add validate **or** dry-run only when the on-demand table says so.
 - Use `--yes` on delete runs only after the user explicitly authorizes execution in chat.
-- Global `--dry-run` on `capability run` calls the gateway dry-run endpoint instead of execute.
+- Global `--dry-run` on `capability run` / curated commands calls the gateway dry-run endpoint instead of execute.
+- Global `--validate` on `capability run` / curated commands calls the gateway validate endpoint instead of execute.
 
 ## High-Risk Confirmation Workflow (Agent)
 
@@ -77,13 +129,13 @@ Applies only when `inspect` shows `risk=high-risk-write`.
 
 User intent (for example "delete this space") is **not** execution authorization. Do not pass `--yes` just because the user stated the desired action.
 
-1. Run `capability inspect` and `capability dry-run` with the final input.
+1. `capability inspect`. For complex delete input only, you may iterate with `validate` while drafting; for the **final** payload use **`dry-run` once** (skip a redundant validate on that same final JSON — dry-run already validates params).
 2. **Stop in the same turn.** Do not call `capability run` in the same turn as dry-run.
 3. Summarize in chat: capability ID, `project_id`, key input fields, and `risk=high-risk-write`.
 4. Ask the user to confirm execution. Prefer `AskUserQuestion` when that tool is available; otherwise ask in plain text and wait for the user's **next message**.
 5. Only after the user replies with explicit authorization (for example `confirm`, `execute`, or `yes`) run `capability run ... --yes` with the same input as dry-run.
 
-For `risk=write`, run directly after a successful dry-run; no chat confirmation gate.
+For `risk=write`: no chat confirmation gate. Prefer direct `run` after inspect; use `--validate` alone when the payload is complex and you are fixing shape; use `--dry-run` alone only if you need the risk/output preview — **not** validate then dry-run as a habit.
 
 Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do not work in Agent Bash; chat confirmation is the real gate for `high-risk-write`.
 
@@ -91,13 +143,14 @@ Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do
 
 - `list` returns `{ domain, count, capabilities }`.
 - `search` returns `{ domain, query, count, capabilities }`.
-- `inspect`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.
+- `inspect`, `validate`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.
 
 ## Examples
 
 ```bash
 ae-cli capability search "dashboard list" --domain analysis
 ae-cli capability inspect analysis.dashboard.list
-ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
+ae-cli capability validate metadata.data_table.sql_write --input input.json
+ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
 ae-cli capability run analysis.dashboard.list --input input.json
 ```

package/skills/ae-community/SKILL.md

@@ -34,11 +34,11 @@ Output and errors:
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
-- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Ordinary `write` commands require explicit user intent but no CLI confirmation. Only `high-risk-write` commands use the confirmation gate.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
-**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis), `analysis_audience` (audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
+**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
 
 ---
 

package/skills/ae-dataops/SKILL.md

@@ -44,7 +44,7 @@ Output and errors:
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
-- Write-command examples omit `--yes`; add `--yes` only when the user explicitly wants to skip the confirmation prompt.
+- Ordinary `write` commands execute without `--yes`; use `--yes` only for a `high-risk-write` command after explicit user confirmation.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.