@thinkingai/ae-cli 6.0.29 → 6.0.31

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

@@ -1,74 +0,0 @@
-# analysis +drilldown_user_events (Single-User Event Sequence Drilldown)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model analysis**
-
-## Use Cases
-- Drill down to detailed event sequences for a specific user on specific dates.
-- This tool is typically used after drilldown_users.
-- Common parameters (focus on these): projectId, userId, eventNames, targetDates.
-- Advanced parameters (for special scenarios): zoneOffset, properties, timeGranularity, firstDayOfWeek, sortOrder, eventNameFilter, timeFilter, timeFilterBeforeNums, timeFilterAfterNums, entityId, entityValue, useCache, limit, offset.
-- The userId must come from drilldown_users and must not be guessed.
-- targetDates is a list of discrete dates, not a date range.
-- Constraint: drilldown positioning parameters must come from the previous query result and must not be guessed.
-- Constraint: time parameters are passed as an array of discrete time points, not a start/end interval.
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--user_id` / `--event_names` / `--target_dates`, you must first read and follow these reference documents:
-  - [`./drilldown_users.md`](./drilldown_users.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md) (only when passing `--properties`)
-- `user_id` must come from the `+drilldown_users` result; `event_names` / `target_dates` must come from the previous drilldown context or the actual result and must not be guessed.
-- Do not execute single-user event sequence drilldown until the upstream drilldown and result readback are complete.
-
-## Prerequisite call chain (required for executing single-user event drilldown)
-1. First execute `+drilldown_users` and obtain the target user and drilldown context.
-2. Confirm the `user_id`, candidate events, and target discrete time points from the previous step result.
-3. If additional property display is needed, first call `analysis_meta +list_properties --project_id <project_id>` to verify property names.
-4. Call `+drilldown_user_events` to query the event sequence.
-
-## Command
-```bash
-ae-cli analysis +drilldown_user_events --project_id <project_id> --user_id u_123 --event_names '["login"]' --target_dates '["2026-04-08 00:00:00"]'
-ae-cli analysis +drilldown_user_events --project_id <project_id> --user_id u_123 --event_names '["login"]' --target_dates '["2026-04-08 00:00:00"]' --zone_offset 8 --use_cache true --limit 20 --offset 0 --request_id mcp_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
-ae-cli analysis +drilldown_user_events --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--user_id` | Yes | User ID from drilldown_users. It must come from drilldown_users and must not be guessed. |
-| `--event_names` | Yes | JSON array of event names. Values should come from upstream drilldown context or `analysis_meta +list_events` in the same `project_id`. |
-| `--target_dates` | Yes | JSON array of discrete target dates from upstream drilldown context. Not a start/end range. |
-| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
-| `--properties` | No | Optional event properties JSON array |
-| `--time_granularity` | No | Time granularity: T0/T1/T2/T3/T4/T5/T6/T7 |
-| `--first_day_of_week` | No | First day of week: 1-7 |
-| `--sort_order` | No | Sort order: asc or desc |
-| `--event_name_filter` | No | Optional event name filter |
-| `--time_filter` | No | Optional time filter condition |
-| `--time_filter_before_nums` | No | Number of records before the time filter point |
-| `--time_filter_after_nums` | No | Number of records after the time filter point |
-| `--entity_id` | No | Optional entity ID for multi-entity scenarios |
-| `--entity_value` | No | Optional entity value for multi-entity scenarios |
-| `--use_cache` | No | Whether to use cache. Default: true |
-| `--limit` | No | Maximum rows. Default: 1000, maximum: 10000 |
-| `--offset` | No | Row offset. Default: 0 |
-| `--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, 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.
-- 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`, `--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
-- +drilldown_users -> +drilldown_user_events

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

@@ -1,80 +0,0 @@
-# analysis +drilldown_users (drill down analysis results to users)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model Analysis**
-
-## Use Cases
-- Prerequisite helper: first call `+get_analysis_query_schema` to get the structure, then call this tool.
-- Drill down to the user list for a specific data point in an existing analysis result.
-- Use this tool only after query_adhoc, query_report_data, or query_dashboard_report_data.
-- The qp must stay the same as the previous analysis.
-- Drilldown parameters such as drilldownDate, drilldownGroups, retentionDays, and funnelStep must come from actual analysis results and must not be guessed.
-- Prerequisite: it is recommended to first run query_adhoc, query_report_data, or query_dashboard_report_data, then call this tool.
-- Constraint: drilldown positioning parameters must come from the previous query result and must not be guessed.
-
-## Mandatory Prerequisites (MUST)
-- Before building `--qp` and the drilldown positioning parameters, you must first read and follow the following reference docs:
-  - [`./query_adhoc.md`](./query_adhoc.md)
-  - [`./query_report_data.md`](./query_report_data.md)
-  - [`./query_dashboard_report_data.md`](./query_dashboard_report_data.md)
-- `qp`, `drilldown_date`, `drilldown_groups`, `event_index`, `retention_days`, `funnel_step`, and other parameters must come from real analysis results and must not be guessed.
-- Do not execute user drilldown until the upstream query and result reread have been completed.
-
-## Prerequisite Call Chain (required for drilldown)
-1. Run the upstream analysis first (`+query_adhoc` / `+query_report_data` / `+query_dashboard_report_data`) and save the result.
-2. Extract `qp` and the drilldown positioning parameters from the upstream result.
-3. Verify that `--model_type` matches the upstream analysis model.
-4. Call `+drilldown_users` to execute the user drilldown.
-
-## Commands
-```bash
-ae-cli analysis +drilldown_users --project_id <project_id> --model_type event --qp '{}'
-ae-cli analysis +drilldown_users --project_id <project_id> --model_type retention --qp '{}' --drilldown_date 2026-04-08 --drilldown_groups '[]' --event_index 8 --is_lost true --retention_days 8 --is_churned_user true --funnel_step 8 --interval demo --distribution_bucket 8 --compare_index 8 --include_total true --relation_val demo --limit 10 --offset 0 --request_id mcp_cccccccccccccccccccccccccccccccc
-ae-cli analysis +drilldown_users --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--model_type` | Yes | Model type used in the source analysis. Supported values: event, retention, funnel, distribution, attribution, heat_map, interval, path, rank_list, prop_analysis, sql. |
-| `--qp` | Yes | Query parameter JSON used for drilldown. MUST be copied from the source analysis request/result and keep consistent with upstream context. |
-| `--properties` | No | Optional user properties JSON array |
-| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
-| `--drilldown_date` | No | Target drilldown date from the analysis result. Required for event and retention models. Format: yyyy-MM-dd |
-| `--drilldown_groups` | No | Drilldown group values from the analysis result as a JSON array, for example ["ios"]. Defaults to the overall group when omitted. |
-| `--event_index` | No | Event index for event-model drilldown. Use the event position from the analysis result starting from 0. |
-| `--is_lost` | No | For retention analysis, true queries lost users and false queries retained users. Default: false |
-| `--retention_days` | No | Retention interval in days from the analysis result, for example 7 for day-7 retention. If model_type is 'retention', the retention_days must not be null. |
-| `--is_churned_user` | No | For funnel analysis, true queries churned users for the step and false queries converted users. Default: false |
-| `--funnel_step` | No | Funnel step number from the analysis result starting from 1. If model_type is 'funnel', the funnel_step must not be null. |
-| `--interval` | No | Interval used for interval analysis |
-| `--distribution_bucket` | No | Distribution bucket index from the analysis result |
-| `--compare_index` | No | Comparison index used in comparison analysis scenarios |
-| `--include_total` | No | Whether to query users from the total row. Default: false |
-| `--relation_val` | No | Relation value used in relation analysis scenarios |
-| `--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` | 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.
-- 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.
-
-## Next Step After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--model_type`, `--qp`).
-- If `Invalid JSON` appears, first check the raw `qp` from the upstream query request, then verify that all necessary drilldown parameters are present.
-
-## Recommended Chaining
-- +query_adhoc -> +drilldown_users
-- +query_report_data -> +drilldown_users
-- +query_dashboard_report_data -> +drilldown_users

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

@@ -1,29 +0,0 @@
-# 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_analysis_query_schema.md

@@ -1,71 +0,0 @@
-# analysis +get_analysis_query_schema (Get Analysis Query Schema)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model schema queries**
-
-> **CRITICAL - Builder-supported ad hoc models**
->
-> Do **not** use this tool for natural-language non-SQL ad hoc requests.
-> All ten non-SQL models have matching QP builders; use the builder first, then `+query_adhoc`.
->
-> If a builder returns `need_clarification`, `invalid_argument`, `unsupported_feature`, or `validation_error`, stop and ask the user or report the structured error. Do not fall back to this schema tool.
-
-> **CRITICAL - Step-by-Step Execution (BLOCKING)**
->
-> This blocking sequence applies only to the SQL manual path.
-> **You MUST execute these steps in order. Do NOT skip any step.**
->
-> | Step | Command | When to proceed |
-> |------|---------|-----------------|
-> | **Step 1 (MANUAL PATH ONLY)** | `--model_type sql` **without `--segments`** | Execute first only for SQL. Review result. |
-> | **Step 2 (OPTIONAL)** | Add `--segments 'filter_group'` | Only if Step 1 result lacks filter/groupBy structures AND you need them |
-> | **Step 3 (OPTIONAL)** | Add `--segments 'examples'` | Only if Step 1+2 insufficient for multi-metric, time comparison, formulas |
->
-> **WRONG:** `ae-cli analysis +get_analysis_query_schema --model_type sql --segments 'examples'` ← **Never start here!**
-> **RIGHT:** `ae-cli analysis +get_analysis_query_schema --model_type sql` → review → add segments if needed
-
-## Pre-call Checklist (Execute in Order)
-
-0. ✓ **Builder-supported model?** → If non-SQL, stop using this tool and use the matching builder.
-1. ✓ **Step 1 completed?** → Review core schema
-2. ✓ **Gap identified?** → Justify need (e.g., "need filter_group structure")
-3. ✓ **Justified?** → Call again with specific segment
-
-**Rule**: For SQL, uncertain → execute Step 1 first. For non-SQL models, uncertain → read the matching builder reference first.
-
-## Command (Execute in Order)
-
-```bash
-# Step 1: start here only for SQL (no segments)
-ae-cli analysis +get_analysis_query_schema --model_type sql
-
-# Step 2: Only after Step 1, if filter/groupBy needed
-ae-cli analysis +get_analysis_query_schema --model_type sql --segments 'filter_group' --include_core false
-
-# Step 3: Only after Step 1/2, for complex scenarios
-ae-cli analysis +get_analysis_query_schema --model_type sql --segments 'examples' --include_core false
-
-# Follow-up request (already have core from earlier step in same session)
-ae-cli analysis +get_analysis_query_schema --model_type sql --segments 'examples' --include_core false
-```
-
-## Parameters
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--model_type` | Yes | Model type: event, retention, funnel, distribution, sql, interval, path, attribution, prop_analysis, rank_list, heat_map |
-| `--segments` | No | `core` (default), `filter_group`, `calctype`, `aggregatetype`, `examples`, `full`. Empty → core only. |
-| `--include_core` | No | Default: true. Set false for follow-up requests when core already retrieved. |
-
-## 场景分级
-
-| 场景 | 参数 | 执行顺序 |
-|---|---|---|
-| Builder 支持模型 | 不适用 | 所有非 SQL 模型禁止用此工具作为 QP 准备步骤，改用 builder |
-| 简单 | 不传 `--segments` | **Step 1** - SQL manual path |
-| 中等 | `--segments 'filter_group'` | **Step 2** - SQL manual path，有过滤或分组，需先完成 Step 1 |
-| 复杂 | `--segments 'examples'` | **Step 3** - SQL manual path，需先完成 Step 1 |
-
-## Next Steps on Failure
-- Verify model type and segment compatibility (e.g., aggregatetype not for funnel/path/interval/sql)

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

@@ -1,35 +0,0 @@
-# analysis +get_bi_panel_detail (read BI panel structure)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **BI panel management**
-
-## Use Cases
-- Read a BI panel's released structure without querying data.
-- Inspect pages, queryable charts, summary page metadata, dashboard-level parameter controls, dashboard-level permission controls, and page chart filter controls.
-- Get `pageKey`, `chartId`, `defaultColumns`, and control schemas needed by `+query_bi_panel_data`.
-
-## Command
-```bash
-ae-cli analysis +get_bi_panel_detail --project_id <project_id> --panel_id <panel_id>
-ae-cli analysis +get_bi_panel_detail --project_id <project_id> --panel_id <panel_id> --fields '["basic","pages","charts","parameterControls","permissionControls","chartFilterControls","summary"]'
-ae-cli analysis +get_bi_panel_detail --project_id <project_id> --panel_id <panel_id> --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--panel_id` | Yes | BI panel ID returned by `+list_bi_panels` |
-| `--fields` / `-f` | No | Optional detail sections. Supported values: `basic`, `pages`, `charts`, `parameterControls`, `permissionControls`, `chartFilterControls`, `summary`. |
-
-## Decision Rules
-- This command reads the released BI panel version only. It does not expose version selection.
-- Use `charts` and the three control sections when preparing `+query_bi_panel_data`.
-- `parameterControls` are dashboard-level parameter controls and keep single-value semantics.
-- `permissionControls` are dashboard-level permission control values. Their `allowedValues` are hints, not an MCP-side whitelist.
-- `chartFilterControls` are page-level filter controls and apply only to their `boundChartIds`. Some filters are stored as `pageCharts` components and are returned as non-queryable filter controls.
-- Do not infer internal fields such as `paramList`, `permissionFilters`, `visualCfg`, `whereList`, `field`, `columnName`, `userId`, or `openId`.
-
-## Recommended Chaining
-- `+list_bi_panels` -> `+get_bi_panel_detail` -> `+query_bi_panel_data`

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

@@ -1,53 +0,0 @@
-# analysis_audience +get_cluster_definition_schema (Get Cluster Definition Schema)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Schema Query**
-
-## Use Cases
-- Support tool positioning: the current command provides the structure definition (schema) and should be used as a prerequisite step.
-- Recommended sequence: first call this schema tool to get the structure, then verify metadata in the same session and `project_id` (first build/update calls `analysis_meta +list_events` / `analysis_meta +list_properties`; later calls should reuse session-verified results first), and finally create or update clusters.
-- Get the cluster definition schema. Supports cluster type + response mode + condition subtype.
-
-## Commands
-```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type sql
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition --response_mode base
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition --response_mode examples --condition_subtype behavior_seq
-ae-cli analysis_audience +get_cluster_definition_schema --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--cluster_type` | Yes | Cluster type. Supported values: condition and sql |
-| `--response_mode` | No | Schema response mode. Supported values: `base`, `examples`, `full`. Default: `base`. |
-| `--condition_subtype` | No | Only effective when `--cluster_type condition`. Supported values: `core`, `behavior_seq`, `all`. Default: `core`. |
-
-## Progressive Loading Strategy
-- Use the smallest response that can solve the current task. Large schemas consume context and can make the follow-up definition construction less reliable.
-- Start with `--response_mode base` or omit `--response_mode` for simple condition clusters and SQL clusters.
-- Request `--response_mode examples` only when the base schema is not enough to build or validate the target `definition`.
-- Request `--response_mode full` only for complex, ambiguous, or repeatedly failing definition construction. Do not use `full` by default.
-- For normal condition clusters, use the default `--condition_subtype core`.
-- Use `--condition_subtype behavior_seq` only when the user specifically needs behavior sequence conditions.
-- Use `--condition_subtype all` only when comparing condition subtypes or when the exact subtype cannot be determined after reading the user request. Avoid `all` for simple creation/update tasks.
-- For clear SQL cluster requests, call `--cluster_type sql` with base mode first.
-
-## Decision Rules
-- `--cluster_type` must be explicitly set to `condition` or `sql`.
-- Prefer `--response_mode base` first; request `examples` only when needed; request `full` only as a last resort.
-- `--condition_subtype` should only be passed for `condition` schemas.
-- It is recommended to run `--dry-run` first to inspect the request mapping before making the actual call.
-- The current command returns only structure constraints; it does not guarantee that the field values are available in the target project. Event names and property names must be confirmed again with `analysis_meta` metadata interfaces.
-- Before calling `analysis_meta +list_events` / `analysis_meta +list_properties`, first read their reference docs to confirm the parameter and return-field meanings. Query metadata on the first build/update in this session for the same `project_id`; after that, prefer reusing session-verified metadata.
-
-## Next Step on Failure
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-- If the schema does not match expectations, confirm whether the correct schema interface was used (filter/groupby/query/tag/cluster).
-
-## Recommended Chain
-- First read: [`./get_cluster_definition_schema.md`](./get_cluster_definition_schema.md) -> [`./list_events.md`](./list_events.md) -> [`./list_properties.md`](./list_properties.md)
-- +get_cluster_definition_schema -> (first build/update in session or refresh) analysis_meta +list_events -> analysis_meta +list_properties -> +create_cluster
-- +get_cluster_definition_schema -> (first build/update in session or refresh) analysis_meta +list_events -> analysis_meta +list_properties -> +update_cluster

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

@@ -1,69 +0,0 @@
-# analysis_audience +get_clusters_by_name (Locate Clusters by Name)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Cluster Management**
-
-## Use Cases
-- Get cluster definition details in batch by cluster name. Returns complete cluster information for matched clusters, including IDs, names, display names, types, status, user counts, and refresh status.
-
-## Commands
-```bash
-ae-cli analysis_audience +get_clusters_by_name --project_id <project_id> --names '["demo"]'
-ae-cli analysis_audience +get_clusters_by_name --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--names` | Yes | List of cluster names (JSON array). Exact-name matching is used; unmatched clusters are ignored automatically. |
-
-## Decision Rules
-- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--names`) and add optional parameters after confirming the path works.
-- `--names` must be passed as a JSON array (e.g. `--names '["cluster_a","cluster_b"]'`).
-- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
-
-## Enum Codebook (Asset Definition Interpretation Only)
-
-When interpreting cluster `definition` for users, if operator enum codes appear, use the following complete `calcuSymbol` mapping instead of outputting raw codes only.
-
-| Code | Meaning | Applicable Types |
-|---|---|---|
-| `C00` | equals | all |
-| `C000` | equals empty string | string |
-| `C01` | not equals | all |
-| `C010` | not equals empty string | string |
-| `C02` | less than | number |
-| `C020` | less than or equal | number |
-| `C03` | greater than | number |
-| `C030` | greater than or equal | number |
-| `C04` | has value | all |
-| `C05` | no value | all |
-| `C06` | range | number/date |
-| `C060` | date range | date |
-| `C07` | contains | string |
-| `C08` | does not contain | string |
-| `C09` | true | bool |
-| `C10` | false | bool |
-| `C11` | regex match | string |
-| `C12` | regex does not match | string |
-| `C13` | relative to current time | date/datetime |
-| `C14` | relative to event time | date/datetime |
-| `C15` | element exists | array |
-| `C16` | element does not exist | array |
-| `C17` | element position | array |
-| `C18` | no value | array |
-| `C19` | has value | array |
-| `C20` | belongs to cluster | cluster/tag (`tableType="2"`) |
-| `C21` | does not belong to cluster | cluster/tag (`tableType="2"`) |
-| `C22` | object exists that satisfies condition | array |
-| `C23` | no object satisfies condition | array |
-| `C24` | all objects satisfy condition | array |
-
-## Next Step on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--names`).
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-
-## Recommended Chain
-- +list_clusters -> +get_clusters_by_name -> +update_cluster

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

@@ -1,33 +0,0 @@
-# analysis +get_filter_schema (get filter schema)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Schema Queries**
-
-## Use Cases
-- Helper tool positioning: this command provides structure definitions (schema) and should be used as a prerequisite step.
-- Recommended order: call the schema tool first to get the structure, then call the specific business tool.
-- Typical downstream tools: `+create_virtual_event`, `+get_analysis_query_schema`, `+get_cluster_definition_schema`, `+get_groupby_schema`, `+get_tag_definition_schema`, `+query_dashboard_report_data`, `+query_report_data`
-- Get the filter schema. Returns field definitions, operator enums, data type descriptions, and examples.
-- Get the filter schema.
-
-## Commands
-```bash
-ae-cli analysis +get_filter_schema
-ae-cli analysis +get_filter_schema --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| None | - | This command has no business parameters; call it directly. |
-
-## Decision Rules
-- It is recommended to run `--dry-run` first to observe the request-body mapping before making the formal call.
-
-## Next Step After Failure
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-- If the schema does not match expectations, confirm whether the correct schema interface was called (filter/groupby/query/tag/cluster).
-
-## Recommended Chaining
-- +get_analysis_query_schema -> +get_filter_schema -> +get_groupby_schema

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

@@ -1,33 +0,0 @@
-# analysis +get_groupby_schema (Get Group-By Schema)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Schema queries**
-
-## Use Cases
-- Helper tool positioning: this command provides structural definitions (schema) and should be used as a prerequisite step.
-- Recommended order: first use the current schema tool to get the structure, then call the specific business tool.
-- Typical follow-up tools: `+get_analysis_query_schema`, `+get_cluster_definition_schema`, `+get_filter_schema`, `+get_tag_definition_schema`, `+query_report_data`
-- Get the group-by schema. Returns field definitions and examples for group-by configuration.
-- Get the group-by schema.
-
-## Command
-```bash
-ae-cli analysis +get_groupby_schema
-ae-cli analysis +get_groupby_schema --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| None | - | This command has no business parameters; call it directly. |
-
-## Decision Rules
-- It is recommended to run `--dry-run` first to inspect the request body mapping before making the formal call.
-
-## Next Steps on Failure
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-- If the schema does not match expectations, confirm whether the correct schema interface was called (filter/groupby/query/tag/cluster).
-
-## Recommended chaining
-- +get_analysis_query_schema -> +get_filter_schema -> +get_groupby_schema

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

@@ -1,37 +0,0 @@
-# analysis +get_report_definition (read report definition)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Report Management**
-
-## Constraints
-
-**Not a builder fallback:** Do not call `+get_report_definition` to repair or replace a failed non-SQL QP builder call. Builder failure means stop and ask for clarification or report the structured error.
-
-## Use Cases
-- Get the definition details of a single report. Returns model type, event configuration, display configuration, and other definition data without executing a data query.
-- Get the definition details of a single report.
-- When interpreting report information, remember that for recent-day ranges, 1-N means the last N days (past N days), which is actually N+1 days ago through yesterday, while 0-N means the most recent N days, which is actually N days ago through today.
-
-## Commands
-```bash
-ae-cli analysis +get_report_definition --project_id <project_id> --report_id 1
-ae-cli analysis +get_report_definition --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--report_id` / `-r` | Yes | Report ID |
-
-## Decision Rules
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--report_id`) and add optional parameters after confirming the chain works.
-- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-
-## Next Step After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--report_id`).
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-
-## Recommended Chaining
-- +list_reports -> +get_report_definition -> +query_report_data

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

@@ -1,37 +0,0 @@
-# analysis +get_table_columns (Read Underlying Table Columns)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model analysis**
-
-## Use Cases
-- 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:
-- `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> --table_ref hive.ta_dim.datatable_1
-ae-cli analysis +get_table_columns --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--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
-- 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, 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/get_tag_definition_schema.md

@@ -1,49 +0,0 @@
-# analysis_audience +get_tag_definition_schema (Get Tag Definition Schema)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Schema Query**
-
-## Use Cases
-- Support tool positioning: the current command provides the structure definition (schema) and should be used as a prerequisite step.
-- Recommended sequence: first call this schema tool to get the structure, then call specific business tools.
-- Typical downstream tools: `+create_tag`, `+update_tag`
-- Get the tag definition schema. Supports tag type + response mode + condition subtype.
-
-## Commands
-```bash
-ae-cli analysis_audience +get_tag_definition_schema --type condition
-ae-cli analysis_audience +get_tag_definition_schema --type metric
-ae-cli analysis_audience +get_tag_definition_schema --type condition --response_mode examples --condition_subtype behavior_seq
-ae-cli analysis_audience +get_tag_definition_schema --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--type` | Yes | Tag type. Supported values: `condition`, `metric`, `first_last`, `sql`. |
-| `--response_mode` | No | Schema response mode. Supported values: `base`, `examples`, `full`. Default: `base`. |
-| `--condition_subtype` | No | Only effective when `--type condition`. Supported values: `core`, `behavior_seq`, `all`. Default: `core`. |
-
-## Progressive Loading Strategy
-- Use the smallest response that can solve the current task. Large schemas consume context and can make the follow-up definition construction less reliable.
-- Start with `--response_mode base` or omit `--response_mode` for simple `condition`, `metric`, and `sql` tags.
-- Request `--response_mode examples` only when the base schema is not enough to build or validate the target `definition`.
-- `first_last` tags have a more specialized structure; use base first when the requested shape is simple, and escalate to `examples` when the field mapping or event/property role is unclear.
-- Request `--response_mode full` only for complex, ambiguous, or repeatedly failing definition construction. Do not use `full` by default.
-- For normal condition tags, use the default `--condition_subtype core`.
-- Use `--condition_subtype behavior_seq` only when the user specifically needs behavior sequence conditions.
-- Use `--condition_subtype all` only when comparing condition subtypes or when the exact subtype cannot be determined after reading the user request. Avoid `all` for simple creation/update tasks.
-
-## Decision Rules
-- `--type` is required and must match the target tag type.
-- It is recommended to run `--dry-run` first to inspect the request mapping before making the actual call.
-- Prefer `--response_mode base` first; request `examples` only when needed; request `full` only as a last resort.
-
-## Next Step on Failure
-- If reading fails, first verify whether the object ID exists and belongs to the current project.
-- If the schema does not match expectations, confirm whether the correct schema interface was used (filter/groupby/query/tag/cluster).
-
-## Recommended Chain
-- +get_tag_definition_schema -> (first build/update in session or refresh) analysis_meta +list_events -> analysis_meta +list_properties -> +create_tag
-- +get_tag_definition_schema -> (first build/update in session or refresh) analysis_meta +list_events -> analysis_meta +list_properties -> +update_tag