@thinkingai/ae-cli 6.0.18 → 6.0.20

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

@@ -0,0 +1,61 @@
+# analysis +build_rank_list_analysis_qp (Build Rank List Analysis QP)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated rank-list-analysis QP from structured rank list intent.
+- Rank list analysis ranks entities (users, items, etc.) by a metric value.
+- Use in the mandatory builder flow before `+query_adhoc --model_type rank_list`.
+- This command builds QP only and does not execute the analysis query.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase.
+- `--rank_list` is a JSON object. Required fields: `rankDimension` (with `field`), `rankEvent`, `rankAggregation`.
+- `rankType` values: `rank`=standard (1,2,2,4), `dense_rank`=dense (1,2,2,3), `row_rank`=unique (1,2,3,4). Defaults to `row_rank`.
+- `orderBy`: `DESC`=highest first (default), `ASC`=lowest first.
+- Wrap JSON in single quotes in shell commands.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_rank_list_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --rank_list '<rank_list_json>'
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--time_range` | Yes | Time range JSON |
+| `--rank_list` | Yes | Rank list intent JSON |
+
+## JSON Shape
+`--rank_list` object:
+```json
+{
+  "rankDimension": {"field": {"name": "#account_id", "type": "user_property"}},
+  "rankEvent": "purchase",
+  "rankAggregation": "A103",
+  "rankProperty": "amount",
+  "orderBy": "DESC"
+}
+```
+
+Optional fields in `--rank_list`:
+- `rankProperty`: required when rankAggregation is property-based (A103/A104/A106/A107/A108 etc.)
+- `rankType`: rank / dense_rank / row_rank (default)
+- `orderBy`: DESC (default) / ASC
+- `filters`: global filters array
+- `relation`: filter relation (and / or)
+
+## Examples
+```bash
+ae-cli analysis +build_rank_list_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --rank_list '{"rankDimension":{"field":{"name":"#account_id","type":"user_property"}},"rankEvent":"purchase","rankAggregation":"A101","orderBy":"DESC"}'
+```
+
+## Decision Rules
+- After successful build (`status=generated`), call `+query_adhoc --model_type rank_list --qp '<response.qp>'`.
+- If non-generated status, stop and ask user to clarify.
+
+## Recommended Chain
+- `+build_rank_list_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type rank_list --qp '<response.qp>'`

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

@@ -0,0 +1,63 @@
+# analysis_audience +build_tag_definition (Build Tag Definition)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Tag Management**
+
+## Use Cases
+
+- Build a tag definition JSON from structured intent. Call this before `+create_tag` or `+update_tag` to generate the `definition` field.
+- Supported types: `condition` (multi-value), `metric` (event metric), `first_last` (first/last occurrence), `sql`.
+- For condition/metric/first_last types, event and property names are resolved from project metadata — do not guess.
+- On success, pass the returned definition to `+create_tag` or `+update_tag`.
+
+## Required Prerequisites (MUST)
+
+- Before calling this command, you must first read and follow these reference docs:
+  - [`./get_tag_definition_schema.md`](./get_tag_definition_schema.md)
+  - [`./list_events.md`](./list_events.md)
+  - [`./list_properties.md`](./list_properties.md)
+- Do not construct `--condition_values` / `--metric` / `--first_last` until the schema has been read and metadata has been verified for the same `project_id`.
+
+## Commands
+
+```bash
+ae-cli analysis_audience +build_tag_definition --project_id <project_id> --type condition --condition_values '[]'
+ae-cli analysis_audience +build_tag_definition --project_id <project_id> --type metric --metric '{}'
+ae-cli analysis_audience +build_tag_definition --project_id <project_id> --type first_last --first_last '{}'
+ae-cli analysis_audience +build_tag_definition --project_id <project_id> --type sql --sql 'SELECT "#user_id", tag_value FROM ...'
+ae-cli analysis_audience +build_tag_definition --dry-run
+```
+
+## Parameters
+
+| Parameter             | Required | Description                                                                                                                                                                       |
+| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project_id` / `-p` | Yes      | Project ID                                                                                                                                                                        |
+| `--type`              | Yes      | Tag type. Supported values: `condition`, `metric`, `first_last`, `sql`                                                                                                            |
+| `--condition_values`  | No       | For type=condition: list of tag value definitions JSON array. Each item defines a segment label and its conditions. See `+get_tag_definition_schema` for the structure.            |
+| `--metric`            | No       | For type=metric: metric definition JSON. Fields: `eventName`, `analysis`, `quota` (property name), `recentDay`/`startTime`/`endTime`.                                             |
+| `--first_last`        | No       | For type=first_last: first/last occurrence definition JSON. Fields: `eventName`, `firstEvent` (true=first, false=last), `calcPropType`, `property`, `recentDay`/`startTime`/`endTime`. |
+| `--sql`               | No       | For type=sql: SQL query returning two columns: `#user_id` and the tag value.                                                                                                      |
+
+## Decision Rules
+
+- Determine `--type` first, then pass only the corresponding parameter.
+- For type=condition, `--condition_values` is effectively required.
+- For type=metric, `--metric` is effectively required.
+- For type=first_last, `--first_last` is effectively required.
+- For type=sql, only `--sql` is needed; other type-specific parameters are ignored.
+- Event and property names must come from session-verified metadata (`analysis_meta +list_events` / `+list_properties` for the same `project_id`).
+- Do not guess event or property names — always verify against real metadata first.
+- Wrap JSON parameters in single quotes (e.g. `--condition_values '[]'`) to avoid shell escaping issues.
+- Run `--dry-run` first to inspect the request mapping before making the actual call.
+
+## Next Step on Failure
+
+- If required parameters are missing, check that `--project_id` and `--type` are provided.
+- If the returned definition is rejected by `+create_tag` or `+update_tag`, re-read `+get_tag_definition_schema` with `--response_mode examples` and verify metadata names again.
+
+## Recommended Chain
+
+- `+get_tag_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_tag_definition` → `+create_tag`
+- `+get_tag_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_tag_definition` → `+update_tag`

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

@@ -10,7 +10,7 @@ Domain: **Query lifecycle**
 - Cancel a query by the same `requestId` that was supplied to or returned by a previous query command.
 - For proactive cancellation, pass `requestId` to the query tool before starting it, then call `cancel_query` with the same value if you stop waiting.
 - If a query returns `fetch failed`, hits an HTTP timeout, or the caller stops waiting, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset `requestId`.
-- auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` before any query that may exceed the CLI/MCP HTTP timeout.
+- MCP query tools require caller-supplied `requestId`; generate and pass it before starting any cancelable query, then reuse the same value if cleanup is needed.
 
 ## Command
 ```bash
@@ -30,9 +30,8 @@ ae-cli analysis +cancel_query --request_id mcp_0123456789abcdef0123456789abcdef
 - The request must belong to the current MCP user. Otherwise the service returns `REQUEST_NOT_FOUND_OR_NOT_OWNED`.
 - Do not invent a request ID. Use the ID from the query response or the ID explicitly supplied to the original query.
 - This command cancels by request ID only. It does not cancel by SQL text, report ID, dashboard ID, BI panel ID, run ID, or tool call ID.
-- For query commands that expose `--request_id`, prefer supplying a stable ID before execution using `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`, so proactive cancellation does not depend on waiting for the response metadata.
+- For query commands that expose `--request_id`, supplying a stable ID before execution is required. Use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`, so proactive cancellation does not depend on waiting for the response metadata.
 - For query commands that may exceed the CLI/MCP HTTP timeout, preset `--request_id`; if `fetch failed`, HTTP timeout, or caller timeout happens, immediately call `+cancel_query --request_id <same value> --yes`.
-- For commands that do not expose caller-supplied `request_id`, cancel only if the response includes a request ID.
 
 ## Next Steps on Failure
 - If `REQUEST_NOT_FOUND_OR_NOT_OWNED` appears, verify the request ID, user identity, host, and whether the original query already finished.

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

@@ -0,0 +1,33 @@
+# analysis +copy_dashboard (Copy Dashboard)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Copy a dashboard to a new dashboard, optionally copying its associated reports.
+- To place the copy in a specific space or folder, provide `--to_space_id` or `--to_folder_id`. Use `+list_spaces` to resolve these IDs.
+
+## Commands
+```bash
+ae-cli analysis_audience +copy_dashboard --project_id <project_id> --dashboard_id <dashboard_id> --dashboard_name "Copy of Dashboard"
+ae-cli analysis_audience +copy_dashboard --project_id <project_id> --dashboard_id <dashboard_id> --dashboard_name "Copy of Dashboard" --report_copy true --to_space_id <space_id>
+ae-cli analysis_audience +copy_dashboard --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_id` | Yes | Source dashboard ID to copy |
+| `--dashboard_name` | Yes | Name for the new copied dashboard |
+| `--report_copy` | No | Whether to also copy associated reports. Defaults to false. |
+| `--to_space_id` | No | Target space ID. Omit to use the default location. |
+| `--to_folder_id` | No | Target folder ID inside the target space. Omit to place at the space root. |
+
+## Decision Rules
+- Call `+list_spaces` first when the user wants to place the copy in a specific space or folder.
+- Returns the new dashboard ID and name on success.
+
+## Recommended Chain
+- `+list_dashboards` -> `+list_spaces` -> `+copy_dashboard` -> `analysis_common +get_resource_url`

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

@@ -0,0 +1,40 @@
+# analysis_audience +create_id_cluster (Create ID Cluster)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Cluster Management**
+
+## Use Cases
+- Create a new ID cluster by uploading a CSV of user IDs as plain text.
+- The CSV should contain a single column of user IDs (no header row required).
+- The operation is asynchronous — the cluster enters computing state after creation.
+
+## Commands
+```bash
+ae-cli analysis_audience +create_id_cluster --project_id <project_id> --display_name "My ID Cluster" --file_content "user_001
+user_002
+user_003" --entity_id <entity_id>
+ae-cli analysis_audience +create_id_cluster --project_id <project_id> --display_name "My ID Cluster" --file_content "user_001" --entity_id <entity_id> --cluster_name my_id_cluster --remarks "Created by script"
+ae-cli analysis_audience +create_id_cluster --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--display_name` | Yes | Cluster display name (1-80 characters) |
+| `--file_content` | Yes | CSV file content as plain text. No header row, UTF-8 encoding. Each row contains one user ID. Max 100MB. |
+| `--entity_id` | Yes | Entity ID to associate the cluster with. Use `analysis_meta +list_entities` to query. |
+| `--cluster_name` | No | Cluster name (lowercase letters, digits, underscores, starts with a letter, max 80 chars). Auto-generated if omitted. |
+| `--remarks` | No | Optional remarks (max 200 characters) |
+| `--main_column_name` | No | Optional main column name for ID matching |
+
+## Return Value
+Returns `clusterId`, `uploadNum` (rows uploaded), `userNum` (matched users), `unmatchedNum` (unmatched rows), and `clusterName`.
+
+## Decision Rules
+- Call `analysis_meta +list_entities` to resolve `entity_id` before creating.
+- If file size exceeds 100MB, inform the user to upload directly via the web interface.
+
+## Recommended Chain
+- `analysis_meta +list_entities` -> `+create_id_cluster` -> `+refresh_cluster`

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

@@ -0,0 +1,39 @@
+# analysis_audience +create_id_tag (Create ID Tag)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Tag Management**
+
+## Use Cases
+- Create a new ID tag by uploading a CSV of user IDs and tag values as plain text.
+- The CSV should contain two columns: user ID and tag value (tag value is optional).
+- The operation is asynchronous — the tag enters computing state after creation.
+
+## Commands
+```bash
+ae-cli analysis_audience +create_id_tag --project_id <project_id> --display_name "VIP Tag" --file_content "user_001,gold
+user_002,silver" --entity_id <entity_id>
+ae-cli analysis_audience +create_id_tag --project_id <project_id> --display_name "VIP Tag" --file_content "user_001,gold" --entity_id <entity_id> --tag_name vip_tag --remarks "ID-based tag"
+ae-cli analysis_audience +create_id_tag --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--display_name` | Yes | Tag display name (1-80 characters) |
+| `--file_content` | Yes | CSV file content as plain text. No header row, UTF-8 encoding. Column 1: user ID. Column 2: tag value (optional). Example: user_001,gold_member. Max 100MB. |
+| `--entity_id` | Yes | Entity ID to associate the tag with. Use `analysis_meta +list_entities` to query. |
+| `--tag_name` | No | Tag name (letters/digits/underscores, starts with a letter, max 80 chars). Auto-generated if omitted. |
+| `--remarks` | No | Optional remarks (max 200 characters) |
+| `--main_column_name` | No | Optional main column name for ID matching |
+
+## Return Value
+Returns `clusterId`, `uploadNum` (rows uploaded), `userNum` (matched users), `unmatchedNum` (unmatched rows), and `clusterName` (tag name).
+
+## Decision Rules
+- Call `analysis_meta +list_entities` to resolve `entity_id` before creating.
+- If file size exceeds 100MB, inform the user to upload directly via the web interface.
+
+## Recommended Chain
+- `analysis_meta +list_entities` -> `+create_id_tag` -> `+refresh_tag`

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

@@ -0,0 +1,27 @@
+# analysis +delete_alert (Delete Alert)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Alert Management**
+
+## Use Cases
+- Permanently delete an alert by its ID.
+
+## Commands
+```bash
+ae-cli analysis +delete_alert --project_id <project_id> --alert_id <alert_id>
+ae-cli analysis +delete_alert --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--alert_id` | Yes | Alert ID to delete |
+
+## Decision Rules
+- Use `+list_alerts` first to confirm the alert ID before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `+list_alerts` -> `+delete_alert`

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

@@ -0,0 +1,27 @@
+# analysis_audience +delete_cluster (Delete Cluster)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Cluster Management**
+
+## Use Cases
+- Permanently delete a cluster by its name.
+
+## Commands
+```bash
+ae-cli analysis_audience +delete_cluster --project_id <project_id> --cluster_name my_cluster
+ae-cli analysis_audience +delete_cluster --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--cluster_name` | Yes | Cluster name to delete |
+
+## Decision Rules
+- Use `+list_clusters` first to confirm the cluster name before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `+list_clusters` -> `+delete_cluster`

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

@@ -0,0 +1,30 @@
+# analysis +delete_dashboard (Delete Dashboard)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Permanently delete a dashboard by its ID.
+
+## Commands
+```bash
+ae-cli analysis +delete_dashboard --project_id <project_id> --dashboard_id <dashboard_id>
+ae-cli analysis +delete_dashboard --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_id` | Yes | Dashboard ID to delete |
+
+## Decision Rules
+- Use `+list_dashboards` first to confirm the dashboard ID before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Next Step on Failure
+- If the dashboard is not found, use `+list_dashboards` to verify the ID.
+
+## Recommended Chain
+- `+list_dashboards` -> `+delete_dashboard`

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

@@ -0,0 +1,27 @@
+# analysis_meta +delete_metric (Delete Metric)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Metric Management**
+
+## Use Cases
+- Permanently delete a metric by its ID.
+
+## Commands
+```bash
+ae-cli analysis_meta +delete_metric --project_id <project_id> --metric_id <metric_id>
+ae-cli analysis_meta +delete_metric --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--metric_id` | Yes | Metric ID to delete |
+
+## Decision Rules
+- Use `+list_metrics` first to confirm the metric ID before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `+list_metrics` -> `+delete_metric`

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

@@ -0,0 +1,27 @@
+# analysis +delete_report (Delete Report)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Report Management**
+
+## Use Cases
+- Permanently delete a report by its ID.
+
+## Commands
+```bash
+ae-cli analysis +delete_report --project_id <project_id> --report_id <report_id>
+ae-cli analysis +delete_report --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--report_id` | Yes | Report ID to delete |
+
+## Decision Rules
+- Use `+list_reports` first to confirm the report ID before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `+list_reports` -> `+delete_report`

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

@@ -0,0 +1,27 @@
+# analysis_audience +delete_tag (Delete Tag)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Tag Management**
+
+## Use Cases
+- Permanently delete a tag by its name.
+
+## Commands
+```bash
+ae-cli analysis_audience +delete_tag --project_id <project_id> --tag_name my_tag
+ae-cli analysis_audience +delete_tag --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--tag_name` | Yes | Tag name to delete |
+
+## Decision Rules
+- Use `+list_tags` first to confirm the tag name before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `+list_tags` -> `+delete_tag`

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

@@ -56,18 +56,18 @@ ae-cli analysis +drilldown_user_events --dry-run
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--page_num` | No | Start page number, default 1 |
 | `--page_size` | No | Page size. Default: 1000, maximum: 10000 |
-| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
 | `--timeout_minutes` | No | Query timeout in minutes |
 
 ## Decision Rules
 - `user_id` / `event_names` / `target_dates` must come from the previous step result and must not be constructed out of thin air.
-- On the first run, start with only the required parameters (`--project_id`,`--user_id`,`--event_names`,`--target_dates`), and add optional parameters after confirming the path works.
+- On the first run, include all required parameters (`--project_id`,`--user_id`,`--event_names`,`--target_dates`,`--request_id`), and add optional parameters after confirming the path works.
 - Wrap JSON parameters in single quotes (for example `--event_names '[]'`, `--target_dates '[]'`) to avoid shell escaping issues.
-- For long-running or cancelable drilldowns, supply your own `--request_id` before starting so `+cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
+- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--user_id`, `--event_names`, `--target_dates`).
+- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--user_id`, `--event_names`, `--target_dates`, `--request_id`).
 - If `Invalid JSON` appears, first verify the array structure, then compare it with the previous drilldown result to confirm the values are complete and valid.
 
 ## Recommended chaining

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

@@ -57,15 +57,15 @@ ae-cli analysis +drilldown_users --dry-run
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--limit` | No | Optional limit. Default: 1000, maximum: 10000. |
 | `--offset` | No | Optional offset. Default: 0. |
-| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
 | `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. |
 
 ## Decision Rules
 - Drilldown positioning parameters must come from upstream analysis results and must not be fabricated.
 - `qp` must not be rewritten or "simplified"; it should remain consistent with the source analysis.
 - For pagination, use `--limit` and `--offset` together. Default limit is 1000, maximum 100000.
-- For long-running or cancelable drilldowns, supply your own `--request_id` before starting so `+cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--model_type`, `--qp`) and add optional parameters after confirming the chain works.
+- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
+- For the first run, include all required parameters (`--project_id`, `--model_type`, `--qp`, `--request_id`) and add optional parameters after confirming the chain works.
 - Wrap JSON parameters in single quotes (for example `--qp '{}'`, `--drilldown_groups '{}'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, validate with a short range first and then expand gradually.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.

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

@@ -0,0 +1,29 @@
+# analysis +freeze_dashboards (Freeze / Unfreeze Dashboards)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Freeze one or more dashboards to take their scheduled refresh jobs offline.
+- Unfreeze dashboards to bring scheduled jobs back online (for dashboards that have a schedule configured).
+
+## Commands
+```bash
+ae-cli analysis_audience +freeze_dashboards --project_id <project_id> --dashboard_ids '[123, 456]' --freeze true
+ae-cli analysis_audience +freeze_dashboards --project_id <project_id> --dashboard_ids '[123]' --freeze false
+ae-cli analysis_audience +freeze_dashboards --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_ids` | Yes | JSON array of dashboard IDs to freeze or unfreeze |
+| `--freeze` | Yes | true to freeze, false to unfreeze |
+
+## Decision Rules
+- Use `+list_dashboards` to confirm dashboard IDs before freezing.
+
+## Recommended Chain
+- `+list_dashboards` -> `+freeze_dashboards`

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

@@ -5,16 +5,16 @@
 Domain: **Model analysis**
 
 ## Use Cases
-- Query the field list of a project table. Returns all column names and types under the specified catalog, schema, and table so the table schema can be understood before SQL analysis.
+- Query the field list of a project table. Returns all column names and types for `tableRef` so the table schema can be understood before SQL analysis.
 - Table guide:
-- default.public.ta_event_1: catalog is default, schema is public, table is ta_event_1
-- public.ta_event_1: catalog is hive(default value), schema is public, table is ta_event_1
-- ta_event_1: catalog is hive(default value), schema is ta(default value), table is ta_event_1
-- Query the field list of a project table.
+- `hive.ta_dim.datatable_1`: catalog is hive, schema is ta_dim, table is datatable_1.
+- `ta_dim.datatable_1`: catalog defaults to hive, schema is ta_dim, table is datatable_1.
+- `ta_event_1`: table only; resolved against project available tables and fails if ambiguous.
+- The only common catalog is `hive`. Common hive schemas are `ta` (default analysis tables), `ta_dim` (dimension/datatable/exchange tables), `temp` (SQL temporary tables), and `ta_ext` (external datatable/API tables). Do not replace an explicit schema such as `ta_dim` with default `ta`.
 
 ## Command
 ```bash
-ae-cli analysis +get_table_columns --project_id <project_id> --catalog demo --schema demo --table demo
+ae-cli analysis +get_table_columns --project_id <project_id> --table_ref hive.ta_dim.datatable_1
 ae-cli analysis +get_table_columns --dry-run
 ```
 
@@ -22,17 +22,16 @@ ae-cli analysis +get_table_columns --dry-run
 | Parameter | Required | Description |
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID |
-| `--catalog` | Yes | Catalog name, default hive |
-| `--schema` | Yes | Schema name, default ta |
-| `--table` | Yes | Table name |
+| `--table_ref` | Yes | Table reference. Supports `hive.schema.table`, `schema.table`, or `table`. If only `table` is provided, the backend resolves it against project available tables and fails on ambiguity. |
 
 ## Decision Rules
-- On the first run, start with only the required parameters (`--project_id`,`--catalog`,`--schema`), and add optional parameters after confirming the path works.
+- Prefer a fully qualified `--table_ref` when the schema is known, especially for `ta_dim`, `temp`, or `ta_ext` tables.
+- Use table-only `--table_ref <table>` only when you expect the table name to be unique in the project; if the backend returns ambiguity, retry with one of the returned fully qualified `tableRef` values.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--catalog`, `--schema`).
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
+- If required parameters are missing, fill in `--project_id` and `--table_ref` first.
+- If reading fails, first verify whether the `tableRef` exists, is unambiguous, and belongs to the current project permissions.
 
 ## Recommended chaining
 - +get_table_columns

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

@@ -28,17 +28,17 @@ ae-cli analysis_audience +list_cluster_members --dry-run
 | `--fields` | No | Optional return field list (JSON array). Invalid fields will fail with `INVALID_FIELDS`. |
 | `--limit` | No | Optional page size. Default: 20, max: 50. |
 | `--offset` | No | Optional page offset. Default: 0. |
-| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
 | `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
 
 ## Decision Rules
-- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`) and add optional parameters after confirming the path works.
+- For the first execution, include all required parameters (`--project_id`, `--cluster_name`, `--request_id`) and add optional parameters after confirming the path works.
 - `--property_names` must be passed as a JSON array (e.g. `--property_names '["#user_id"]'`).
-- For long-running or cancelable member queries, supply your own `--request_id` before starting so `analysis +cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
+- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
 - When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Step on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`).
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`, `--request_id`).
 - If the result is empty, first confirm the project ID/keyword, then try broadening the filter conditions.
 
 ## Recommended Chain

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

@@ -19,7 +19,7 @@ Domain: **Cluster Management**
 ```bash
 ae-cli analysis_audience +list_clusters --project_id <project_id>
 ae-cli analysis_audience +list_clusters --project_id <project_id> --query demo
-ae-cli analysis_audience +list_clusters --project_id <project_id> --fields '["id","clusterName","usersNum"]' --limit 20 --offset 0
+ae-cli analysis_audience +list_clusters --project_id <project_id> --fields '["id","clusterName","displayName","remarks","clusterType","progress","usersNum"]' --limit 20 --offset 0
 ae-cli analysis_audience +list_clusters --dry-run
 ```
 
@@ -27,8 +27,8 @@ ae-cli analysis_audience +list_clusters --dry-run
 | Parameter | Required | Description |
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID |
-| `--query` / `-q` | No | Optional keyword filter. Performs fuzzy matching against cluster names, display names, and remarks; if omitted, all clusters are returned. |
-| `--fields` | No | Optional return field list (JSON array). Invalid fields will fail with `INVALID_FIELDS`. |
+| `--query` / `-q` | No | Optional keyword filter. Performs fuzzy matching against clusterName, displayName, and remarks; if omitted, all clusters are returned. |
+| `--fields` | No | Optional return field list (JSON array). Supported fields: `id`, `clusterName`, `displayName`, `clusterType`, `progress`, `usersNum`, `refreshStatus`, `remarks`. Default fields when omitted: `id`, `clusterName`, `displayName`, `remarks`, `clusterType`, `progress`, `usersNum`. Invalid fields will fail with `INVALID_FIELDS`. |
 | `--limit` | No | Optional page size. Default: 20, max: 50. |
 | `--offset` | No | Optional page offset. Default: 0. |