@thinkingai/ae-cli 1.0.1

package/skills/te-analysis/references/build-entity-details-sql.md

@@ -0,0 +1,58 @@
+# te_analysis +build_entity_details_sql (Generate Entity Details SQL)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Entity details SQL queries**
+
+## Use Cases
+- When constructing `definition`, you must first obtain the cluster schema and fill in the project event/property metadata.
+- Build the SQL for an entity details query. The parameters are the same as `+query_entity_details`, but the tool returns SQL instead of query results.
+- Build the SQL for an entity details query.
+
+## Mandatory prerequisites (MUST)
+- Before constructing `--definition` / `--properties`, you must first read and follow these reference documents:
+  - [`../../te-audience/references/get-cluster-definition-schema.md`](../../te-audience/references/get-cluster-definition-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate the final `definition` / `properties` until the documentation review and prerequisite command calls are complete.
+
+## Prerequisite call chain (required for constructing definition/properties)
+1. First confirm the cluster type (condition / sql).
+2. Read `get-cluster-definition-schema.md`, then call `te-cli te_audience +get_cluster_definition_schema --cluster_type <condition|sql>` to get the structure.
+3. Read `list-events.md`, then call `te-cli te_meta +list_events --project_id 1`.
+4. Read `list-properties.md`, then call `te-cli te_meta +list_properties --project_id 1`.
+5. Build `definition` (and optional `properties`) from the schema + metadata, then call `+build_entity_details_sql`.
+
+## Command
+```bash
+te-cli te_analysis +build_entity_details_sql --project_id 1 --definition '{}'
+te-cli te_analysis +build_entity_details_sql --project_id 1 --entity_id 1001 --definition '{}' --properties '{}' --sort_by time --sort_order desc --limit 100 --zone_offset 8
+te-cli te_analysis +build_entity_details_sql --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--entity_id` | No | Optional entity ID used in multi-entity scenarios. If omitted, the default user entity is used. |
+| `--definition` | Yes | Cluster definition JSON. MUST call `+get_cluster_definition_schema` first, then fill valid event/property names from `te_meta +list_events` / `te_meta +list_properties` in the same `project_id`. |
+| `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `te_meta +list_properties` in the same `project_id`. |
+| `--sort_by` | No | Optional sort field |
+| `--sort_order` | No | Optional sort order. Supported values: asc and desc |
+| `--limit` | No | Optional result limit. Default: 1000, maximum: 10000 |
+| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
+
+## Decision Rules
+- `definition` / `properties` cannot be written from experience alone: they must satisfy both the schema structure and the project metadata constraints.
+- Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
+- On the first run, start with only the required parameters (`--project_id`, `--definition`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--definition '{}'`, `--properties '{}'`) to avoid shell escaping issues.
+- 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` and `--definition`).
+- If `Invalid JSON` appears, first check the schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
+
+## Recommended chaining
+- +get_cluster_definition_schema -> te_meta +list_events -> te_meta +list_properties -> +build_entity_details_sql
+- +query_entity_details -> +query_event_details -> +build_event_details_sql

package/skills/te-analysis/references/build-event-details-sql.md

@@ -0,0 +1,61 @@
+# te_analysis +build_event_details_sql (generate event detail SQL)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Event Detail SQL Queries**
+
+## Use Cases
+- When building `filters` / `properties`, first obtain the filter schema and the project's real event/property metadata.
+- Build the SQL for an event details query. The parameters are the same as `+query_event_details`, but the tool returns SQL instead of query results.
+- Build the SQL for an event details query.
+
+## Mandatory Prerequisites (MUST)
+- Before building `--filters` / `--properties`, you must first read and follow the following reference docs:
+  - [`./get-filter-schema.md`](./get-filter-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate final `filters` / `properties` until the above docs have been read and the prerequisite commands have been called.
+
+## Prerequisite Call Chain (required for filters/properties)
+1. Read `get-filter-schema.md`, then call `te-cli te_analysis +get_filter_schema` to get the filter structure.
+2. Read `list-events.md`, then call `te-cli te_meta +list_events --project_id 1` to confirm available event names.
+3. Read `list-properties.md`, then call `te-cli te_meta +list_properties --project_id 1` to get available properties.
+4. Build `filters` / `properties` based on the schema and metadata, then call `+build_event_details_sql`.
+
+## Commands
+```bash
+te-cli te_analysis +build_event_details_sql --project_id 1 --event_name login --start_time '2026-04-08 00:00:00' --end_time '2026-04-08 23:59:59'
+te-cli te_analysis +build_event_details_sql --project_id 1 --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 100 --zone_offset 8
+te-cli te_analysis +build_event_details_sql --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--event_name` | Yes | Event name |
+| `--start_time` | No | Start time. Format: yyyy-MM-dd HH:mm:ss |
+| `--end_time` | No | End time. Format: yyyy-MM-dd HH:mm:ss |
+| `--relative_date_range` | No | Optional relative date range in m-n format. For example, 0-7 means the most recent 7 days including today. Use either this field or start_time/end_time. |
+| `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `te_meta +list_properties` in the same `project_id`. |
+| `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `te_meta +list_properties` in the same `project_id`. |
+| `--sort_by` | No | Optional sort field |
+| `--sort_order` | No | Optional sort order. Supported values: asc and desc |
+| `--limit` | No | Optional result limit. Default: 100 |
+| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
+
+## Decision Rules
+- `filters` / `properties` cannot be written by hand based on experience alone: they must satisfy both the schema structure and the project's real metadata.
+- `list_events` / `list_properties` must be learned from the corresponding reference docs before calling them.
+- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--event_name`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--properties '{}'`) 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`, `--event_name`).
+- If `Invalid JSON` appears, first check the required filter schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
+
+## Recommended Chaining
+- +get_filter_schema -> te_meta +list_events -> te_meta +list_properties -> +build_event_details_sql
+- +query_entity_details -> +query_event_details -> +build_event_details_sql

package/skills/te-analysis/references/create-alert.md

@@ -0,0 +1,47 @@
+# te_analysis +create_alert (Create Alert)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Metadata queries**
+
+## Use Cases
+- Precondition helper: call `+get_alert_definition_schema` to get the structure before using this tool.
+- Create a new alert. After creation, use list_alerts or get_alert to retrieve the created alert. See get_alert_definition_schema for the parameter structure.
+- Create a new alert.
+
+## Mandatory prerequisites (MUST)
+- Before constructing `--definition`, you must first read and follow:
+  - [`./get-alert-definition-schema.md`](./get-alert-definition-schema.md)
+- Do not generate the final `definition` until the documentation review and schema call are complete.
+
+## Prerequisite call chain (required for constructing definition)
+1. Read `get-alert-definition-schema.md` to understand the return structure of `+get_alert_definition_schema`.
+2. Call `ae-cli te_analysis +get_alert_definition_schema` to get the schema.
+3. Build `definition` from the schema, then call `+create_alert`.
+
+## Command
+```bash
+ae-cli te_analysis +create_alert --project_id 1 --definition '{}'
+ae-cli te_analysis +create_alert --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--definition` | Yes | Alert definition JSON. MUST call `+get_alert_definition_schema` first and strictly follow the returned structure. |
+
+## Decision Rules
+- `definition` cannot be written from experience alone: it must satisfy the alert schema structure constraints.
+- On the first run, start with only the required parameters (`--project_id`, `--definition`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--definition '{}'`) to avoid shell escaping issues.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` for automated scenarios.
+
+## 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` and `--definition`).
+- If `Invalid JSON` appears, first check the schema required fields and enumeration values, then add fields incrementally.
+- If the result after writing does not match expectations, immediately read back the corresponding list/get interface to compare before and after.
+
+## Recommended chaining
+- +get_alert_definition_schema -> +create_alert

package/skills/te-analysis/references/create-dashboard.md

@@ -0,0 +1,49 @@
+# te_analysis +create_dashboard (create dashboard)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Create a new dashboard.
+- Can automatically associate an initial report after creation.
+- Can optionally create an initial dashboard note at the same time.
+- Returns basic dashboard information (such as ID and name), not the full dashboard configuration.
+
+## Commands
+```bash
+ae-cli te_analysis +create_dashboard --project_id 1 --dashboard_name demo
+ae-cli te_analysis +create_dashboard --project_id 1 --dashboard_name demo --space_id 1 --folder_id 1 --initial_report_id 1 --note_title demo --note_content demo --note_style '{}'
+ae-cli te_analysis +create_dashboard --project_id 1 --dashboard_name demo --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_name` | Yes | Dashboard name |
+| `--space_id` | No | Optional space ID. If provided, the dashboard is created in that space. |
+| `--folder_id` | No | Optional folder ID. If provided, the dashboard is created in that folder. |
+| `--initial_report_id` | No | Optional initial report ID. If provided, the report is automatically associated with the new dashboard after creation. |
+| `--note_title` | No | Optional note title for an initial dashboard note. |
+| `--note_content` | No | Optional note content for an initial dashboard note. |
+| `--note_style` | No | Optional note style configuration JSON for an initial dashboard note. |
+
+## Decision Rules
+- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--dashboard_name`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--note_style '{}'`) to avoid shell escaping issues.
+- Only pass `--space_id` and `--folder_id` when you clearly know the target location; if unsure, create it in the default location first.
+- Dashboard note-related parameters are best passed as a group to avoid incomplete results caused by specifying only the title or only the content.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` only for automation scenarios.
+
+## Next Step After Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--dashboard_name`).
+- If `Invalid JSON` appears, first validate with the smallest JSON structure (for example `{}`), then add fields gradually.
+- If the result after writing is not as expected, immediately reread the corresponding list/get interface and compare before and after.
+
+## Recommended Chaining
+- +create_dashboard -> +list_dashboards
+- +create_dashboard -> +query_dashboard_detail
+- +create_dashboard -> +update_dashboard
+- +create_dashboard -> +query_adhoc -> +create_report -> +update_dashboard

package/skills/te-analysis/references/create-or-update-dashboard-note.md

@@ -0,0 +1,39 @@
+# te_analysis +create_or_update_dashboard_note (Maintain Dashboard Note)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Dashboard management**
+
+## Use Cases
+- Create a new dashboard note or update an existing one. If noteId is provided, updates the existing note; otherwise creates a new note. Returns the created or updated note information.
+- Create a new dashboard note or update an existing one.
+
+## Command
+```bash
+te-cli te_analysis +create_or_update_dashboard_note --project_id 1 --dashboard_id 1 --note_title demo
+te-cli te_analysis +create_or_update_dashboard_note --project_id 1 --dashboard_id 1 --note_id 1 --note_title demo --description demo --ui_config '{}'
+te-cli te_analysis +create_or_update_dashboard_note --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_id` / `-d` | Yes | Dashboard ID |
+| `--note_id` | No | Optional note ID. If provided, updates the existing note; otherwise creates a new note. |
+| `--note_title` | Yes | Note title |
+| `--description` | No | Optional note description content. |
+| `--ui_config` | No | Optional UI configuration JSON string for the note style. |
+
+## Decision Rules
+- On the first run, start with only the required parameters (`--project_id`, `--dashboard_id`, `--note_title`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--ui_config '{}'`) to avoid shell escaping issues.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` for automated scenarios.
+
+## 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`, `--dashboard_id`, `--note_title`).
+- If `Invalid JSON` appears, first verify with the smallest JSON structure (for example `{}` or `[]`), then add fields incrementally.
+- If the result after writing does not match expectations, immediately read back the corresponding list/get interface to compare before and after.
+
+## Recommended chaining

package/skills/te-analysis/references/create-public-access-link.md

@@ -0,0 +1,43 @@
+# te_analysis +create_public_access_link (create public access link)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Create a public access link for the project.
+- Creates a public link that allows unauthenticated users to access a specified dashboard or BI panel.
+- Returns the created link ID and short-link identifier.
+
+## Commands
+```bash
+te-cli te_analysis +create_public_access_link --project_id 1 --resource_type dashboard --resource_id 1 --access_controls '{}' --effective_at "2026-04-09 10:00:00" --expires_at "2026-04-10 10:00:00"
+te-cli te_analysis +create_public_access_link --project_id 1 --company_id 1 --resource_type dashboard --resource_id 1 --access_controls '{}' --remark demo --effective_at "2026-04-09 10:00:00" --expires_at "2026-04-10 10:00:00"
+te-cli te_analysis +create_public_access_link --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--company_id` | No | Optional company ID. If omitted, the company ID of the project is used. |
+| `--resource_type` | Yes | Access target type. Supported values: dashboard (dashboard) and bi_panel (BI panel). |
+| `--resource_id` | Yes | Access target ID. Use a dashboard ID when resourceType is dashboard, and a BI panel ID when resourceType is bi_panel. |
+| `--access_controls` | Yes | Public access control JSON. Effective when resourceType is dashboard. DN controls whether the dashboard title is shown (1: shown, 2: hidden); GF controls whether filters are shown (1: shown and editable, 2: hidden, 3: shown but not editable); UA controls whether refresh is allowed (1: shown, 2: hidden). Pass JSON format. The default for dashboard is {"DN":"1","GF":"3","UA":"2"}; the default for bi_panel is {}. |
+| `--remark` | No | Optional remark. Maximum length: 200 characters. |
+| `--effective_at` | Yes | Effective time. Format: yyyy-MM-dd HH:mm:ss |
+| `--expires_at` | Yes | Expiration time. Format: yyyy-MM-dd HH:mm:ss |
+
+## Decision Rules
+- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--resource_type`, `--resource_id`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--access_controls '{}'`) 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`, `--resource_type`, `--resource_id`).
+- If `Invalid JSON` appears, first validate with the smallest JSON structure (for example `{}` or `[]`), then add fields gradually.
+- If the result after writing is not as expected, immediately reread the corresponding list/get interface and compare before and after.
+
+## Recommended Chaining
+- +create_public_access_link -> +list_public_access_links

package/skills/te-analysis/references/create-report.md

@@ -0,0 +1,60 @@
+# te_analysis +create_report (Create Report)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Report management**
+
+## Use Cases
+- Precondition helper: call `+get_analysis_query_schema` to get the structure before using this tool.
+- When constructing a real `analysis_query`, you must supplement it with real project metadata; first call `te_meta +list_events` and `te_meta +list_properties`.
+- Create and persist a new report definition. Returns the new report ID and name without querying data or modifying existing reports.
+
+## Mandatory prerequisites (MUST)
+- Before constructing `--analysis_query`, you must first read and follow these reference documents:
+  - [`./get-analysis-query-schema.md`](./get-analysis-query-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate the final `analysis_query` until the documentation review and prerequisite command calls are complete.
+
+## Prerequisite call chain (required for constructing analysis_query)
+1. First determine `--model_type`.
+2. Read `get-analysis-query-schema.md`, then call `te-cli te_analysis +get_analysis_query_schema --model_type <model_type>` to get the structure.
+3. Read `list-events.md`, then call `te-cli te_meta +list_events --project_id 1`.
+4. Read `list-properties.md`, then call `te-cli te_meta +list_properties --project_id 1`.
+5. Build `analysis_query` from the schema + metadata, then call `+create_report`.
+
+## Command
+```bash
+te-cli te_analysis +create_report --project_id 1 --report_name demo --model_type event --analysis_query '{}'
+te-cli te_analysis +create_report --project_id 1 --report_name demo --model_type event --analysis_query '{}' --description demo --cache_seconds 8 --query_duration_ms 8 --dashboard_ids '[]'
+te-cli te_analysis +create_report --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--report_name` | Yes | Report name. Length: 1-80 characters |
+| `--model_type` | Yes | Report model type. Supported values: event, retention, funnel, prop_analysis, path, distribution, sql, interval, attribution |
+| `--analysis_query` | Yes | Report analysis query JSON. MUST call `+get_analysis_query_schema` first, and use event/property metadata from `te_meta +list_events` / `te_meta +list_properties` in the same `project_id`. |
+| `--description` | No | Optional report description |
+| `--cache_seconds` | No | Optional cache duration in seconds |
+| `--query_duration_ms` | No | Optional query duration in milliseconds |
+| `--dashboard_ids` | No | Optional list of dashboard IDs to associate |
+
+## Decision Rules
+- `analysis_query` cannot be written from experience alone: it must satisfy both the schema structure and the project metadata constraints.
+- Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
+- On the first run, start with only the required parameters (`--project_id`,`--report_name`,`--model_type`), and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--analysis_query '{}'`, `--dashboard_ids '{}'`) to avoid shell escaping issues.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` for automated scenarios.
+
+## 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`, `--report_name`, `--model_type`).
+- If `Invalid JSON` appears, first check the schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
+- If the result after writing does not match expectations, immediately read back the corresponding list/get interface to compare before and after.
+
+## Recommended chaining
+- +get_analysis_query_schema -> te_meta +list_events -> te_meta +list_properties -> +create_report
+- +list_reports -> +get_report_definition -> +query_report_data

package/skills/te-analysis/references/create-result-cluster.md

@@ -0,0 +1,73 @@
+# te_analysis +create_result_cluster (create result cluster)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Create a reusable result cluster from users matched by a drilldown condition in an existing analysis result.
+- Use this tool only after query_adhoc, query_report_data, or query_dashboard_report_data.
+- Keep the qp consistent with the source analysis.
+- Drilldown parameters such as drilldownDate, funnelStep, and retentionDays must come from real analysis results.
+- Prerequisite: it is recommended to first run query_adhoc, query_report_data, or query_dashboard_report_data, then call this tool.
+
+## Mandatory Prerequisites (MUST)
+- Before building `--qp` and the various drilldown 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 create a result cluster until the upstream query and result reread have been completed.
+
+## Prerequisite Call Chain (required for creating a result cluster)
+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 (date, group, step, interval, and so on) from the upstream result.
+3. Verify that `--model_type` matches the upstream analysis model.
+4. Call `+create_result_cluster` to create the cluster.
+
+## Commands
+```bash
+te-cli te_analysis +create_result_cluster --project_id 1 --cluster_name demo --model_type event --qp '{}'
+te-cli te_analysis +create_result_cluster --project_id 1 --cluster_name demo --display_name demo --model_type event --qp '{}' --zone_offset 8 --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
+te-cli te_analysis +create_result_cluster --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--cluster_name` | Yes | Cluster name. Must start with a letter and contain only letters, digits, and underscores. It must be unique within the project. |
+| `--display_name` | No | Optional cluster display name. If omitted, clusterName is used. |
+| `--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. MUST be copied from the source analysis request/result and keep fully consistent with the upstream analysis context. |
+| `--zone_offset` | No | Optional time zone offset. If omitted, the project default time zone is used. |
+| `--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 saves lost users and false saves retained users. Default: false |
+| `--retention_days` | No | Retention interval in days from the analysis result, for example 7 for day-7 retention |
+| `--is_churned_user` | No | For funnel analysis, true saves churned users for the step and false saves converted users. Default: false |
+| `--funnel_step` | No | Funnel step number from the analysis result starting from 1 |
+| `--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 save users from the total row. Default: false |
+| `--relation_val` | No | Relation value used in relation analysis scenarios |
+
+## 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 the first run, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`, `--model_type`, `--qp`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--qp '{}'`) 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`, `--cluster_name`, `--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.
+- If the result after writing is not as expected, immediately reread the corresponding list/get interface and compare before and after.
+
+## Recommended Chaining
+- +query_adhoc -> +create_result_cluster
+- +query_report_data -> +create_result_cluster
+- +query_dashboard_report_data -> +create_result_cluster

package/skills/te-analysis/references/drilldown-user-events.md

@@ -0,0 +1,72 @@
+# te_analysis +drilldown_user_events (Single-User Event Sequence Drilldown)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/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, pageNum, pageSize.
+- 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)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/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 `te_meta +list_properties --project_id 1` to verify property names.
+4. Call `+drilldown_user_events` to query the event sequence.
+
+## Command
+```bash
+te-cli te_analysis +drilldown_user_events --project_id 1 --user_id u_123 --event_names '["login"]' --target_dates '["2026-04-08 00:00:00"]'
+te-cli te_analysis +drilldown_user_events --project_id 1 --user_id u_123 --event_names '["login"]' --target_dates '["2026-04-08 00:00:00"]' --zone_offset 8 --use_cache true --page_num 1 --page_size 100
+te-cli te_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 `te_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 |
+| `--page_num` | No | Start page number, default 1 |
+| `--page_size` | No | Page size, default 100 |
+| `--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.
+- Wrap JSON parameters in single quotes (for example `--event_names '[]'`, `--target_dates '[]'`) to avoid shell escaping issues.
+- 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 `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/te-analysis/references/drilldown-users.md

@@ -0,0 +1,75 @@
+# te_analysis +drilldown_users (drill down analysis results to users)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/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 te_analysis +drilldown_users --project_id 1 --model_type event --qp '{}'
+ae-cli te_analysis +drilldown_users --project_id 1 --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
+ae-cli te_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 |
+| `--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 |
+| `--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 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.
+- 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/te-analysis/references/get-alert-definition-schema.md

@@ -0,0 +1,32 @@
+# te_analysis +get_alert_definition_schema (Get Alert Definition Schema)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Metadata 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: `+create_alert`, `+update_alert`
+- Get the alert definition schema. Returns field definitions, enum descriptions, and examples for creating or updating alerts.
+- Use this to understand the alert definition structure before calling create_alert or update_alert.
+
+## Command
+```bash
+te-cli te_analysis +get_alert_definition_schema
+te-cli te_analysis +get_alert_definition_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.
+
+## Recommended chaining
+- +get_alert_definition_schema