@thinkingai/ae-cli 6.0.34 → 6.0.36

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

@@ -6,6 +6,7 @@ Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) and firs
 
 ```bash
 ae-cli analysis drilldown-entities export \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '<same returned coordinate>' \
@@ -14,6 +15,8 @@ ae-cli analysis drilldown-entities export \
   [--timeout-seconds 21600]
 ```
 
+`--project-id` must match the project stored by `query_context_id`; a mismatch is rejected before export execution.
+
 Property support matches the synchronous preview exactly:
 
 - For the `#user_id` user subject, `--properties` accepts `[{"columnName":"<property_name>","tableType":"user"}]`. The artifact always retains `#user_id`, `#account_id`, and `#distinct_id` plus the requested user properties.

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

@@ -8,6 +8,7 @@ Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. C
 
 ```bash
 ae-cli analysis drilldown-entities run \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '<merged returned row/column/metric coordinate>' \
@@ -16,7 +17,7 @@ ae-cli analysis drilldown-entities run \
   [--timeout-seconds 120]
 ```
 
-The context, source, and coordinate must all come from the same synchronous preview. Select a visible row from `row_options`, a drillable column from `column_options`, and the relevant metric option; shallow-merge their coordinate fragments. Never send `row_index`, `column_index`, `values`, `label`, `target_id`, raw QP, or a coordinate derived from an export file.
+`--project-id` must be the project used by the synchronous preview and must match the stored query context. The context, source, and coordinate must all come from that same preview. Select a visible row from `row_options`, a drillable column from `column_options`, and the relevant metric option; shallow-merge their coordinate fragments. Never send `row_index`, `column_index`, `values`, `label`, `target_id`, raw QP, or a coordinate derived from an export file.
 
 Property support depends on the returned subject:
 

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

@@ -6,6 +6,7 @@ Use this only when the selected synchronous preview metric advertises `drilldown
 
 ```bash
 ae-cli analysis drilldown-events export \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '<same returned coordinate>' \
@@ -14,6 +15,8 @@ ae-cli analysis drilldown-events export \
   [--timeout-seconds 21600]
 ```
 
+`--project-id` must match the project stored by `query_context_id`; a mismatch is rejected before export execution.
+
 This command does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`. Common executes one full-download query and streams its result directly into the artifact; it does not repeatedly call the synchronous preview. “All” follows the platform full-download ceiling (`model_full_download_limit`), not an unbounded query.
 
 When `--properties` is present, the artifact contains required system event columns plus exactly the requested event properties. The export and synchronous preview use the same projection contract.

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

@@ -8,6 +8,7 @@ Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. C
 
 ```bash
 ae-cli analysis drilldown-events run \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '{"group_values":["Beijing"],"date":"2026-07-16","metric_index":0}' \
@@ -16,7 +17,7 @@ ae-cli analysis drilldown-events run \
   [--timeout-seconds 120]
 ```
 
-`--query-context-id` must come from the same synchronous preview that returned the selected source and options. `--source` is required only to disambiguate multiple returned sources. Assemble `--coordinate` only by merging the selected returned option fragments. Do not pass `target_id`, raw QP, display-only dates, or values from an export/download.
+`--project-id` must be the project used by that synchronous preview; Common rejects it if it does not match the stored query context. `--query-context-id` must come from the same synchronous preview that returned the selected source and options. `--source` is required only to disambiguate multiple returned sources. Assemble `--coordinate` only by merging the selected returned option fragments. Do not pass `target_id`, raw QP, display-only dates, or values from an export/download.
 
 `--properties` is an optional exact event-property projection. Omit it for default columns; string arrays such as `["#event_time"]` are invalid. Each item uses the backend field names `columnName` and `tableType`, for example `[{"columnName":"<event_property_name>","tableType":"event"}]`. `tableType` uses the documented name `event`, not a numeric enum code. Required system event columns remain present, but unrelated event properties must not be returned.
 

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

@@ -6,6 +6,7 @@ Export the complete event sequence for one user from a drilldown context. Do not
 
 ```bash
 ae-cli analysis drilldown-user-events export \
+  --project-id <project_id> \
   --drilldown-context-id <drilldown_context_id> \
   --user-id <user_id> \
   [--properties '[{"columnName":"<event_property_name>","tableType":"event"}]'] \
@@ -14,10 +15,17 @@ ae-cli analysis drilldown-user-events export \
   [--timeout-seconds 21600]
 ```
 
+`--project-id` must match the project stored by `drilldown_context_id`; a mismatch is rejected before export execution.
+
 The nested backend keys are exactly `columnName` and `tableType`, and the table type is the named value `event`. String-name arrays, numeric enum codes, and snake_case rewrites are invalid. With an explicit projection, the artifact retains `#user_id`, account ID, visitor ID, event name, and event time and appends exactly the requested event properties. `#user_id` is internal; Agents should normally present account ID and visitor ID to customers.
 
 Use the exact `drilldown_context_id` and canonical `user_id` returned by a user-subject `analysis drilldown-entities run`. Do not use a custom entity, an entity export artifact, or a guessed identity. Export does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`; Common builds the same authorized event-sequence query without the synchronous 1000-row preview cap and streams one `csv.gz` artifact. The platform full-download ceiling (`model_full_download_limit`) still applies.
 
+For a `scope=total` source coordinate, there is no single selected date. Common
+preserves the machine date coordinates returned by the source query together
+with that query's time granularity, such as daily, weekly, or monthly. Do not
+construct dates outside that context or force a daily granularity.
+
 Inspect the returned `run_id` with `analysis run inspect`, then download the completed artifact with `analysis artifact download`.
 
 Output is an async run/artifact descriptor. The complete event rows exist only in the downloaded artifact; they cannot be used as new analysis coordinates.

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

@@ -10,6 +10,7 @@ Do not pass raw QP.
 
 ```bash
 ae-cli analysis drilldown-user-events run \
+  --project-id <project_id> \
   --drilldown-context-id <drilldown_context_id> \
   --user-id <user_id> \
   [--sort-order desc] \
@@ -20,6 +21,7 @@ ae-cli analysis drilldown-user-events run \
 ## Input
 
 - `--drilldown-context-id`: returned by the same user-subject `analysis drilldown-entities run`.
+- `--project-id`: the project used by that drilldown; it must match the project stored by `drilldown_context_id`.
 - `--user-id`: canonical `user_id` from one item in that same response. Never substitute `entity_value`, `#distinct_id`, account ID, or another identity field.
 - `--properties`: optional exact event-property projection. Omit it to use the default event columns. If present, each item uses backend keys `columnName` and `tableType`, for example `[{"columnName":"<event_property_name>","tableType":"event"}]`. `#user_id`, account ID, visitor ID, event name, and event time remain present; unrelated event properties must not be returned. `#user_id` is an internal association key, so Agents should normally display account ID and visitor ID to customers. Do not pass numeric table-type codes, string-name arrays, or snake_case nested keys.
 - `--sort-order`: `asc` or `desc`.
@@ -27,6 +29,12 @@ ae-cli analysis drilldown-user-events run \
 
 Do not use raw QP, `query_context_id`, or guessed user IDs for this command.
 
+For a `scope=total` source coordinate, there is no single selected date. Common
+preserves the machine date coordinates returned by the source query together
+with that query's time granularity, such as daily, weekly, or monthly. Do not
+invent `target_dates`, force a daily granularity, or replace the returned
+`drilldown_context_id`.
+
 Do not call this command merely because an entity row looks like a user. The explicit subject and follow-up context are the authority.
 
 ## Output

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

@@ -9,7 +9,7 @@ ae-cli analysis entity id-import-options --project-id <project_id> --entity-id <
 If the entity ID is not already known, discover it first instead of guessing:
 
 ```bash
-ae-cli analysis_meta +list_entities --project_id <project_id> --fields '["entityId","entityName","columnName","entityType"]'
+ae-cli analysis project entity list --project-id <project_id> --fields '["entityId","entityName","columnName","entityType"]'
 ```
 
 - `match_mode=user_property`: `--association-property` is required and must be copied from `association_properties`; `#user_id` is forbidden.

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

@@ -0,0 +1,47 @@
+# analysis filter-value list
+
+List stored candidate values for one event property, user property, user tag, or user cluster whose identifier is already known.
+
+## Purpose
+
+Use this capability when an analysis filter needs an exact stored value but the caller knows only the business wording. Typical examples are checking whether a channel is stored as `iOS`, `ios`, or `Apple`, or narrowing a high-cardinality property with a prefix before constructing a report or ad-hoc filter.
+
+Do not use it to discover property names, calculate value frequencies, enumerate all raw rows, or replace an analysis aggregation. Resolve the property through metadata or compiler clarification first. The result is a candidate-value aid, not proof of frequency or completeness.
+
+## Command
+
+```bash
+ae-cli analysis filter-value list \
+  --project-id <project_id> \
+  --property-name <property_name> \
+  --table-type event|user \
+  [--event-name <event_name>] \
+  [--search-prefix <text>] \
+  [--zone-offset <offset>] \
+  [--cluster-date-policy LATEST|AUTO|SPECIFIED] \
+  [--specified-cluster-date yyyy-MM-dd] \
+  [--report-mode true|false]
+```
+
+`--event-name` narrows an event-property lookup. `--specified-cluster-date` is required only with `--cluster-date-policy SPECIFIED` and is rejected otherwise. Here “cluster date” means a 用户分群/人群包 snapshot date; it is unrelated to the physical 查询集群 returned by `analysis query-cluster list`.
+
+Output `data.items` contains permission-filtered candidate values. An empty array is successful: no visible candidate matched the selected property and prefix.
+
+## Tag and cluster snapshot semantics
+
+For user tags and user clusters, `LATEST` means the latest available computed result snapshot. It is not a tag definition or configuration release, and it does not require a version list, version ID, draft state, or publish state.
+
+Natural-language routing:
+
+- “查询标签 X 最新版本/最新结果有哪些值” → resolve `X` with `analysis user-tag list`, then call `analysis filter-value list` with the returned exact `tag_name`, `--table-type user`, and `--cluster-date-policy LATEST`.
+- “查询分群 X 最新结果的候选值” → resolve `X` with `analysis user-cluster list`, then use the same candidate-value command with `--cluster-date-policy LATEST`.
+
+Do not route either request to a definition-version workflow. `LATEST`, `AUTO`, and `SPECIFIED` select computed data snapshots only.
+
+## Typical workflow
+
+1. Resolve the exact event/property identifier or tag/cluster machine name from the matching metadata or asset list.
+2. Call `analysis filter-value list`, using `--search-prefix` when the value space is large.
+3. Select only a returned exact value; do not normalize spelling or invent a synonym.
+4. Put that value into `report-data run`, `dashboard-report-data run`, or `adhoc run`.
+5. Verify the result scope and, when needed, follow the returned synchronous query context into drilldown.

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

@@ -7,12 +7,12 @@ Do not use to list all spaces. Use `project-space list`.
 Command:
 
 ```bash
-ae-cli analysis project-space get --project-id <project_id> --space-id <space_id> [--fields '["spaceId","spaceName"]']
+ae-cli analysis project-space get --project-id <project_id> --space-id <space_id> [--fields '["space_id","space_name"]']
 ```
 
 Input sends `project_id`, `space_id`, and optional `fields`.
 
-Supported fields are `spaceId`, `spaceName`, `spaceDesc`, `avatarType`, `colorKey`, `avatar`,
-`allAuthUserAuthority`, `createTime`, `updateTime`, and `owner`.
+Supported fields are `space_id`, `space_name`, `space_desc`, `avatar_type`, `color_key`, `avatar`,
+`all_auth_user_authority`, `create_time`, `update_time`, and `owner`.
 
 Output is the gateway envelope. `data` contains project-space detail with snake_case field names.

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

@@ -2,12 +2,12 @@
 
 Use when the user needs project spaces they can access.
 
-Do not use for project lookup or project ID verification. Use `analysis_common +list_projects`.
+Do not use for project lookup or project ID verification. Use `analysis project info list`.
 
 Command:
 
 ```bash
-ae-cli analysis project-space list --project-id <project_id> [--query <keyword>] [--fields '["id","name"]'] [--limit 50] [--offset 0]
+ae-cli analysis project-space list --project-id <project_id> [--query <keyword>] [--fields '["space_id","name","space_desc"]'] [--limit 50] [--offset 0]
 ```
 
 Input sends `project_id` and optional `query`, `fields`, `limit`, `offset`.
@@ -15,3 +15,7 @@ Input sends `project_id` and optional `query`, `fields`, `limit`, `offset`.
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
 
 Output is the gateway envelope. `data` contains project-space summaries.
+
+Supported projection fields are `space_id`, `name`, `space_desc`, `creator`, `user_id`, `origin`,
+`authority_type`, `avatar_type`, `color_key`, `avatar`, `is_favorite`, and `permissions`.
+Use only these snake_case names; camelCase projection names are rejected.

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

@@ -2,7 +2,7 @@
 
 Use to cancel an async capability-gateway query or export by `run_id`.
 
-Do not use for MCP query cancellation by `request_id`; use `analysis +cancel_query`.
+This is the only analysis-query cancellation command exposed by ae-cli. Cancellation is bound to the capability-gateway `run_id`; ae-cli does not expose MCP `request_id` cancellation.
 
 Command:
 
@@ -13,3 +13,5 @@ ae-cli analysis query cancel --run-id <run_id> [--reason <reason>]
 Input sends `run_id` and optional `reason`.
 
 Output is the gateway envelope. `data` contains the cancellation result.
+
+Typical workflow: submit an async export, preserve its `run_id`, inspect that run, and call this command only when that same run no longer needs to continue. Do not substitute a lifecycle `request_id` for `run_id`.

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

@@ -0,0 +1,34 @@
+# analysis query-cluster list
+
+List physical query-routing clusters accessible to the current account in one project.
+
+## Terminology boundary
+
+Both product concepts contain the English word `cluster`, but they are different:
+
+- 查询集群 / 数据集群 / 部署集群: physical data-routing locations used by `GLOBAL` and `SLAVE`. This command lists these.
+- 用户分群 / 人群包: saved user-membership assets. Use `analysis user-cluster list` for these.
+
+Never use a 用户分群 ID as `--slave-cluster-id`, and never answer a user-segment inventory question with this command.
+
+## Purpose
+
+Use this capability before routing a report, dashboard, or ad-hoc query when the request mentions all clusters, a country/region, a game server, shard, site, market, or deployment. Do not call it for ordinary queries with no physical routing intent; omission preserves the query surface's documented default.
+
+## Command
+
+```bash
+ae-cli analysis query-cluster list --project-id <project_id>
+```
+
+The snake_case output contains `current_cluster`, accessible `slave_clusters`, and `permissions.allowed_cluster_query_params`. `permissions.can_query_global` is authoritative for `GLOBAL`; only returned `slave_clusters[].cluster_id` values may be used for `SLAVE`.
+
+## Typical workflow
+
+1. Resolve the project and call `analysis query-cluster list`.
+2. Match an explicit region/server request only against returned cluster ID, name, and description.
+3. Use `--cluster-query-scope GLOBAL` only for explicit cross-cluster aggregation, or use `--cluster-query-scope SLAVE --slave-cluster-id <id>` for one matched physical slave cluster.
+4. Run/export through `report-data`, `dashboard-report-data`, or `adhoc`.
+5. For synchronous runs, verify `actual_cluster_query_scope`, `actual_slave_cluster_id`, and `cluster_query_scope_source` in the result. For exports, verify the submitted route and successful run before consuming the artifact; report-data artifacts contain report rows rather than route metadata. If permissions reject the route, report `allowed_cluster_query_params`; do not fall back silently.
+
+Surface defaults differ: report-data and ad-hoc omit scope to query the current self cluster; dashboard-report-data omits scope to follow the saved dashboard configuration.

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

@@ -8,6 +8,7 @@ Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. T
 
 ```bash
 ae-cli analysis query create-result-cluster \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '<merged returned row/column/metric coordinate>' \
@@ -19,6 +20,7 @@ ae-cli analysis query create-result-cluster \
 
 ## Input rules
 
+- `--project-id` must be the project used by the synchronous preview and must match the project stored by `query_context_id`.
 - `--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.

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

@@ -16,14 +16,18 @@ Input sends `project_id`, `report_name`, `model_type`, `definition`, optional `r
 
 Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
 
+Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. No report is created on this failure; select an exact returned candidate or ask the user before retrying.
+
 ## SQL dynamic parameter shortest path
 
 When a SQL report contains a `${...}` placeholder, define its saved default in the same AI-facing `definition`. Example:
 
 ```bash
-ae-cli analysis report create --project-id <project_id> --report-name "Recent SQL" --model-type sql --definition '{"sql":"select * from events where ${PartDate:ds} limit 100","params":[{"name":"ds","type":"part_date","recent_day":"1-7"}]}'
+ae-cli analysis report create --project-id <project_id> --report-name "Recent SQL" --model-type sql --definition '{"sql":"select * from events where ${PartDate:ds} limit 100","params":[{"name":"ds","type":"part_date","recent_day":"1-7","use_timezone":true}]}'
 ```
 
+`use_timezone` is an optional boolean definition field only for `part_date`; it defaults to `false`. `true` makes that parameter use the query's effective timezone. It is a saved definition field, so change it through report create/update `--definition`, never through report-data `--sql-params`.
+
 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-meta asset url-get` with that returned `report_id` and output its `markdown_link`.

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

@@ -2,6 +2,8 @@
 
 Submit saved report data as a downloadable async artifact. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
+Typical closed loop: verify saved report definition -> resolve exact filter values and physical query route when needed -> submit export -> preserve the returned run/artifact pair -> inspect to a successful terminal state -> download and verify artifact content.
+
 Before adding overrides, call `analysis report get` for every report. The model matrix is the same as `report-data run`: SQL accepts only saved `definition.params` names through `--sql-params`; non-SQL analysis models accept filters/group/time overrides; tag executes its saved definition. Never put generic overrides and `--sql-params` in one homogeneous-model request.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `report-data run`.
@@ -16,9 +18,14 @@ ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001
 
 # SQL report
 ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --artifact-format jsonl
+
+# Global cross-cluster export for a supported non-SQL report
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --cluster-query-scope GLOBAL --artifact-format jsonl
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, artifact `format`, and `timeout_seconds`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Resolve allowed physical routes with `analysis query-cluster list`; SQL reports reject `GLOBAL`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`.
+
+The downloaded report-data artifact contains report rows and per-report markers, not `actual_cluster_query_scope` metadata. Therefore resolve an allowed route first, keep the submitted scope/ID with the run record, and do not infer route from row contents.
 
 Timezone contract is identical to `report-data run`: omit `--zone-offset` to match the current user's report UI timezone (falling back to the project default); use an enabled integer from `-12` through `14` for a fixed UTC offset; use `--zone-offset 99` for local-time mode, where rows are not converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`, and the option is not persisted.
 
@@ -26,7 +33,7 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields such as `type`, `options`, or `use_timezone`.
 
 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`.
 

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

@@ -2,6 +2,8 @@
 
 Execute bounded inline data from one or more saved reports.
 
+Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings -> use the returned synchronous query context for drilldown.
+
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `report-data export`.
 
 Do not use this command for full, unknown-size, larger than 1000-row, or long-running report data; use `report-data export`.
@@ -27,9 +29,12 @@ ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]'
 
 # Explicit local-time mode (not UTC+99)
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --limit 20
+
+# One physical slave query cluster
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --cluster-query-scope SLAVE --slave-cluster-id jp --limit 20
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, `limit`, and `timeout_seconds`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Use `GLOBAL` only for explicit cross-cluster aggregation; use `SLAVE` with exactly one ID returned by `analysis query-cluster list`. SQL reports reject `GLOBAL`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180.
 
 Timezone contract:
 
@@ -42,7 +47,7 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
 
 A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `end_time`, or `time_granularity` fails with `INVALID_OVERRIDE_FOR_MODEL`. A homogeneous non-SQL request with `sql_params` also fails. Mixed-model batches are best-effort: data still returns and `meta.warnings[]` uses `OVERRIDE_IGNORED_FOR_MODEL`, `model_type`, `report_ids`, and `ignored_fields` to identify fields that did not apply. Do not discard these warnings.
 
@@ -50,6 +55,6 @@ For a newly created or updated dynamic SQL report, omit `--sql-params` to execut
 
 Output is the gateway envelope. `data` contains bounded inline report result items plus `query_context_id` and `sources[]`. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. `sources[].drilldown` is present when the returned preview exposes follow-up actions. Each source is evaluated independently; SQL and other unsupported models have no actions.
 
-An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error. Mixed batches keep successful items and return `meta.partial`, counts, and per-report `meta.failures` for partial-result handling.
+`meta.actual_cluster_query_scope`, optional `meta.actual_slave_cluster_id`, and `meta.cluster_query_scope_source` describe the actual physical route. Verify them before comparing or drilling down. 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.
 
 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

@@ -12,12 +12,14 @@ ae-cli analysis report get --project-id <project_id> --report-id <report_id>
 
 Input sends `project_id` and `report_id`.
 
+This command reads saved definition metadata and deliberately has no `--use-cache` option. Cache selection applies to `report-data run/export`, not to definition reads.
+
 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.
+- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter. A saved PartDate definition exposes boolean `use_timezone` (default `false`); it is definition metadata and cannot be overridden by report-data.
 - non-SQL analysis models: use `--filters`, `--group-by`, `--start-time`, `--end-time`, or `--time-granularity`; do not send `--sql-params`.
 - `tag`: report-data executes the saved tag definition. For a different tag view, use `analysis history-tag-data run/export`.

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

@@ -17,6 +17,10 @@ Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, an
 
 Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
 
+When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. The report is not changed on this failure; resolve the ambiguity before retrying.
+
 For the shortest safe update, read the current `version` exactly once with `analysis report get` immediately before the write; do not reuse a version from an older list or conversation turn. If a SQL dynamic parameter definition changed, query the saved default before applying an override so default persistence and override behavior are verified separately.
 
+For a SQL `part_date` parameter, `use_timezone` is a boolean saved definition field with default `false`. Change it only by submitting the complete updated `definition`; report-data `--sql-params` is value-only and must not contain `use_timezone`.
+
 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/super_metadata_batch_create.md

@@ -0,0 +1,29 @@
+# analysis-meta super-metadata batch-create
+
+Use this command to create effective system metadata in batch through the capability gateway: super events, event properties, and user properties.
+
+Do not use it for ordinary event/property CRUD, metadata import from XLSX, or asset governance. Use the dedicated event/property commands, event-property-bundle import, or governance commands instead.
+
+Command:
+
+```bash
+ae-cli analysis-meta super-metadata batch-create --project-id <project_id> --events '[{"event_name":"purchase","event_desc":"Purchase"}]' --event-properties '[{"prop_name":"amount","select_type":"number","super_event_names":["purchase"]}]' --dry-run
+```
+
+Capability id: `metadata.super_metadata.batch_create`.
+
+Input sends `project_id` plus any non-empty JSON arrays among `events`, `event_properties`, and `user_properties`. Use snake_case object fields exactly as documented by the common-service schema:
+
+- Event items: `event_name`, optional `event_desc`, optional `remark`, optional `super_event_prop_names`.
+- Event property items: `prop_name`, `select_type`, optional `prop_desc`, optional `prop_remark`, optional `common_prop`, optional `super_event_names`.
+- User property items: `prop_name`, `select_type`, optional `prop_desc`, optional `prop_remark`.
+
+Output returns `created.events`, `created.event_properties`, and `created.user_properties` with created names and IDs, plus count metadata. If common-service rejects a duplicate, bad reference, or invalid type, preserve the gateway error code and message.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--events` | No | Super event JSON array. |
+| `--event-properties` | No | Event property JSON array. |
+| `--user-properties` | No | User property JSON array. |

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

@@ -0,0 +1,24 @@
+# analysis-meta super-metadata batch-edit
+
+Use this command to batch edit descriptions and remarks for effective system metadata through the capability gateway.
+
+Do not use it to create metadata, delete metadata, hide metadata, update event/property relations, or edit governance assets. Use batch-create or the dedicated metadata commands instead.
+
+Command:
+
+```bash
+ae-cli analysis-meta super-metadata batch-edit --project-id <project_id> --type event_property --items '[{"prop_name":"amount","prop_desc":"Amount","prop_remark":"Revenue amount"}]' --dry-run
+```
+
+Capability id: `metadata.super_metadata.batch_edit`.
+
+Input sends `project_id`, `type`, and `items`. For `type=event`, each item identifies the target with `event_name` and may set `event_desc` or `remark`. For `type=event_property` or `type=user_property`, each item identifies the target with `prop_name` and may set `prop_desc` or `prop_remark`.
+
+Output returns `type` and `updated_count`. Preserve validation errors from common-service, especially missing names, unsupported `type`, or empty `items`.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--type` | Yes | Metadata type to edit: `event`, `event_property`, or `user_property`. |
+| `--items` | Yes | Batch edit item JSON array. |

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

@@ -9,9 +9,9 @@ Before constructing `--events` / `--filter`, validate the available events and p
 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 --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"event_name":"purchase"}]'
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"event_name":"add_to_cart","filter":{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}]' --override true
+ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"ta@qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
 ae-cli analysis-meta virtual-event create --dry-run
 ```
 
@@ -19,7 +19,7 @@ Capability id: `metadata.virtual_event.create`.
 
 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.
+Output data contains `v_event_id` and `event_name`. Use the returned `v_event_id` for `virtual-event get` or `virtual-event delete`.
 
 ## Parameters
 | Parameter | Required | Description |
@@ -30,11 +30,12 @@ Output is a successful gateway envelope with no business data. Read back with `v
 | `--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`. |
+| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:'and|or',items:[{field:{name,type?},operator,values?}]}`. Required when `--payload` is omitted. |
+| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Referenced properties must come from `analysis-meta property list`. |
 
 ## Decision Rules
 - `events` / `filter` must not be handwritten by intuition alone; they must match real metadata in the same project.
+- Use snake_case `event_name`; do not pass the legacy `eventName` spelling.
 - 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.