@thinkingai/ae-cli 6.0.18 → 6.0.22

package/skills/ae-analysis/SKILL.md

@@ -17,17 +17,19 @@ AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine anal
 
 Global parameters:
 
-| Parameter | Description |
-|---|---|
-| `--format <json\|table>` | Output format. Default is JSON. |
-| `--jq <expr>` | jq filter expression for JSON output. |
-| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli analysis +list_dashboards --host <url>`. |
+| Parameter                | Description                                                                                                                                           |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format <json\|table>` | Output format. Default is JSON.                                                                                                                       |
+| `--jq <expr>`            | jq filter expression for JSON output.                                                                                                                 |
+| `--host <url>`           | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli analysis +list_dashboards --host <url>`. |
 
 Output and errors:
+
 - Successful commands return machine-readable JSON by default.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
 Safety constraints:
+
 - Read commands can execute directly after required IDs and references are verified.
 - Write commands require explicit user intent and normally keep the confirmation prompt.
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. For builder-supported ad-hoc models (`event`, `retention`, `funnel`, `prop_analysis`), do not pre-discover metadata; pass the user's event/property/metric wording to the matching QP builder and let the builder resolve metadata or return clarification. For non-builder/manual workflows, read the matching command reference and discover real project metadata first.
@@ -39,10 +41,10 @@ Use `ae-analysis` for all AE analysis-side work below:
 
 - Domain `analysis`: alerts, reports/dashboards, ad-hoc model analysis, drilldown, entity/event details, schema helpers.
 - Domain `analysis_audience`: clusters/tags and definition schemas.
-- Domain `analysis_meta`: metadata governance, metrics, virtual metadata, project config, tracking plans, mark times, entity catalog.
+- Domain `analysis_meta`: metadata governance, metrics, virtual metadata, project config, tracking plans, mark times, entity catalog (MCP). For **single** super-event / super-property **detail** on the capability gateway, switch to **`ae-metadata`** skill (`metadata event get`, `metadata property get`).
 - Domain `analysis_common`: project listing and post-write resource links.
 
-If user intent is Engage/DataOps/Community, switch to `ae-engage` / `ae-dataops` / `ae-community`.
+If user intent is Engage/DataOps/Community/metadata gateway detail, switch to `ae-engage` / `ae-dataops` / `ae-community` / **`ae-metadata`**.
 
 ## Command Format
 
@@ -52,6 +54,7 @@ If user intent is Engage/DataOps/Community, switch to `ae-engage` / `ae-dataops`
 - `ae-cli analysis_common +<tool_name> [options]`
 
 Conventions:
+
 - CLI flags use underscores, e.g. `--project_id`.
 - MCP params map automatically to camelCase.
 - JSON args pass as JSON string literals.
@@ -62,6 +65,7 @@ Conventions:
 ### A. PROJECT_ID_GATE
 
 For any command requiring `project_id`:
+
 1. If the same continuous conversation already has a verified project context (`project_id`, project name when known, and host/environment), reuse it directly for follow-up commands.
 2. Call `analysis_common +list_projects` only when no verified project context exists, the user provides a new project ID/name, the user switches host/environment, the user asks to list projects, or the current project is ambiguous.
 3. Verify any new user-provided ID or name against returned projects before using it.
@@ -73,6 +77,7 @@ For any command requiring `project_id`:
 ### B. Write-operation Post-link Completion
 
 When these writes succeed and `resource_id` is extractable, call `analysis_common +get_resource_url` and append link output:
+
 - `dashboard`: `+create_dashboard`, `+update_dashboard`
 - `report`: `+create_report`
 - `metric`: `+create_metric`, `+update_metric`
@@ -84,6 +89,7 @@ When these writes succeed and `resource_id` is extractable, call `analysis_commo
 - `super_event` / `super_prop_event` / `super_prop_user`: `+batch_create_metadata`, `+batch_edit_metadata`
 
 Closed-loop check (must be explicit in result):
+
 - Write result
 - `resource_id` checked
 - `+get_resource_url` called or skipped (no ID)
@@ -102,6 +108,7 @@ For list commands with `--query` parameter (list_reports, list_dashboards, list_
 5. **Never proceed** with operations on non-existent resources
 
 **Example workflow:**
+
 - User asks: "Find active user report"
 - Attempt 1: `--query "active user"` → no results
 - Attempt 2: `--query "active"` → no results
@@ -121,18 +128,21 @@ Before executing ad-hoc queries (`query_adhoc`), MUST check for existing reports
 5. **If not found** - For QP builder-supported models (`event`, `retention`, `funnel`, `prop_analysis`), call the matching builder first and then call `query_adhoc` with builder `qp`; do not call schema or metadata tools between the report/dashboard miss and the builder. For all other `query_adhoc` models, use the legacy schema/metadata path.
 
 **Rationale:**
+
 - **Performance**: Existing reports are pre-computed and faster
 - **Consistency**: Reports have business-defined metrics and calibrated logic
 - **Resource efficiency**: Avoid redundant computation
 - **Permissions**: Users may have report access but not ad-hoc query permissions
 
 **Example:**
+
 - User: "Query active users in last 7 days"
 - Step 1: `list_reports --query "active user"` → found "DAU Active Users Report"
 - Step 2: `query_report_data --report_id <id>` → return data
 - ❌ WRONG: Directly use `query_adhoc` without checking existing reports
 
 **Exceptions (when ad-hoc is acceptable):**
+
 - User explicitly requests "ad-hoc query" or "ad-hoc analysis"
 - User wants custom filters/groupings not available in existing reports
 - User is exploring data for new insights (exploratory analysis)
@@ -150,6 +160,7 @@ For these four model types, QP builder is mandatory before `query_adhoc`. Do not
 4. `prop_analysis` -> `+build_prop_analysis_qp`
 
 Builder-supported model routing is:
+
 1. Search existing reports/dashboards if `QUERY_EXISTING_FIRST` applies.
 2. If no existing asset is used, read the matching builder reference.
 3. Call the matching builder with complete required parameters.
@@ -157,23 +168,34 @@ Builder-supported model routing is:
 
 Do not insert metadata/schema calls between steps 2 and 3 for builder-supported models. Specifically, do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, `get_metric`, or `get_report_definition` to prepare the builder payload. The builder resolves event/property/metric metadata internally and returns `need_clarification` when it cannot.
 
+Authenticated asset scope:
+
+- Use `--authenticated_only true` on metadata list commands (`+list_events`, `+list_properties`, `+list_metrics`, `+list_clusters`, `+list_tags`) when the user explicitly asks to see only authenticated assets.
+- Use `--authenticated_only true` on QP builders and cluster/tag definition builders when the generated QP/definition should resolve only authenticated assets.
+- Do not pass `authenticated_only` or `authenticatedOnly` to `+query_adhoc`; the filter takes effect during metadata resolution and QP/definition construction, not query execution.
+- List responses include `authenticationStatus` by default (`1` authenticated, `0` unauthenticated).
+
 Event metric shortcut:
+
 - If the user asks to query a saved/business metric through event analysis, pass the metric name/display name/remark directly as an event metric target: `--metrics '[{"event":"<metric name>"}]'`.
 - Do not call `analysis_meta +list_metrics` or `analysis_meta +get_metric` first just to expand the metric definition.
 - If the user provides an explicit formula, pass the formula and dependencies to `+build_event_analysis_qp`; do not convert it by reading schema or metric metadata first.
 
 Metric result vs metric metadata:
+
 - "Query metric result/value/trend over a time range" is an ad-hoc analysis request. Use report/dashboard search first when applicable, then builder -> `query_adhoc`.
 - "Inspect/search/update/create metric definition" is metadata/governance. Only then use `analysis_meta +list_metrics`, `+get_metric`, `+create_metric`, or `+update_metric`.
 
 For all other `query_adhoc` model types (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`), QP builder is not supported. Use the legacy path: read `query_adhoc.md`, fetch schema/metadata as required, then construct QP manually according to the relevant schema.
 
 Execution rule:
+
 - If builder result `status=generated`, call `+query_adhoc` with the same `model_type` and the returned `qp`.
 - If builder returns non-generated status (`need_clarification`, `invalid_argument`, `unsupported_feature`, `validation_error`), stop and ask the user for clarification instead of calling `query_adhoc`.
 - Never bypass a failed builder by manually assembling QP for `event`, `retention`, `funnel`, or `prop_analysis`.
 
 Builder payload rules:
+
 - Before composing any builder JSON, read the matching builder reference doc. The builder references contain the required JSON shape and model-specific field differences.
 - CLI flag names use snake_case, but nested JSON keys use the service DTO field names in camelCase. Correct: `startTime`, `endTime`, `relationEventPropertyName`, `eventPropertyName`. Wrong: `start_date`, `start_time`, `relation_property`, `fieldName`.
 - Builder dry-run still requires the normal required flags. Do not run builder dry-run by itself.
@@ -184,6 +206,7 @@ Builder payload rules:
 - If the user's request lacks a required business element such as time range, event, metric, funnel window, property, or relation field, stop and ask for clarification. If the request supplies a name but it may be a metadata ambiguity, call the builder and let it return candidates. Do not invent names or handcraft QP.
 
 Supported builder chain:
+
 1. Read the builder reference for the target model.
 2. Build structured JSON from the user's request. Use user-provided event/property/metric names as-is; do not pre-query metadata for these names.
 3. Run the matching `+build_*_analysis_qp` command.
@@ -191,6 +214,7 @@ Supported builder chain:
 5. If status is not `generated`, report the structured error or ask the user for the missing information; do not continue to `query_adhoc`.
 
 Legacy query_adhoc chain:
+
 1. Use only for `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, or `sql`.
 2. Read `references/query_adhoc.md` and required schema/metadata references.
 3. Build QP manually from the documented schema and verified project metadata.
@@ -205,10 +229,10 @@ Legacy query_adhoc chain:
 Base rate fallacy causes inaccurate attribution:
 
 | Dimension | Baseline | Comparison | Absolute Δ | Relative Δ | Contribution |
-|-----------|----------|------------|-----------|-----------|-------------|
-| A         | 1        | 5          | +4        | +400%     | **40%**     |
-| B         | 50       | 55         | +5        | +10%      | **50%**     |
-| C         | 49       | 50         | +1        | +2%       | **10%**     |
+| --------- | -------- | ---------- | ---------- | ---------- | ------------ |
+| A         | 1        | 5          | +4         | +400%      | **40%**      |
+| B         | 50       | 55         | +5         | +10%       | **50%**      |
+| C         | 49       | 50         | +1         | +2%        | **10%**      |
 
 Wrong: "Dimension A grew 400%, it is the main driver."
 Correct: "Dimension B contributed 50% of the absolute increase (+5), making it the primary driver."
@@ -231,6 +255,7 @@ contribution_pct_i = delta_dim_i / delta_total * 100%
 ##### Scenario 2: Ratio / Conversion Metrics
 
 Ratio changes come from two components:
+
 - **Composition effect**: changes in subgroup weight.
 - **Rate effect**: changes in each subgroup's own rate.
 
@@ -281,6 +306,7 @@ If any dimension shows a cross-effect, such as positive contribution but negativ
 #### Exceptions
 
 Skip absolute contribution decomposition when:
+
 - The user explicitly asks for growth-rate or percentage-change ranking only.
 - The user asks for a single dimension's trend without cross-dimension comparison.
 - A dimension baseline is zero; mark it as a new dimension separately.
@@ -289,28 +315,36 @@ Skip absolute contribution decomposition when:
 
 After outputting attribution results, verify that dimension contributions sum to approximately 100%. If the sum deviates from 100% by more than 5 percentage points, flag that some dimensions may be missing or data scoping may be inconsistent.
 
-## Tool Groups (79)
+## Tool Groups (100)
 
-### analysis (40)
+### analysis (61)
 
-Alerts (5):
+Alerts (6):
 - `+get_alert_definition_schema` ([doc](references/get_alert_definition_schema.md))
 - `+list_alerts` ([doc](references/list_alerts.md))
 - `+get_alert` ([doc](references/get_alert.md))
 - `+create_alert` ([doc](references/create_alert.md))
 - `+update_alert` ([doc](references/update_alert.md))
+- `+delete_alert` ([doc](references/delete_alert.md))
 
-Reports and Dashboards (17):
+Reports and Dashboards (24):
 - `+create_report` ([doc](references/create_report.md))
 - `+get_report_definition` ([doc](references/get_report_definition.md))
 - `+list_reports` ([doc](references/list_reports.md))
 - `+query_report_data` ([doc](references/query_report_data.md))
+- `+update_report` ([doc](references/update_report.md))
+- `+delete_report` ([doc](references/delete_report.md))
 - `+create_space` ([doc](references/create_space.md))
+- `+list_spaces` ([doc](references/list_spaces.md))
 - `+create_dashboard` ([doc](references/create_dashboard.md))
 - `+list_dashboards` ([doc](references/list_dashboards.md))
 - `+query_dashboard_detail` ([doc](references/query_dashboard_detail.md))
 - `+query_dashboard_report_data` ([doc](references/query_dashboard_report_data.md))
 - `+update_dashboard` ([doc](references/update_dashboard.md))
+- `+delete_dashboard` ([doc](references/delete_dashboard.md))
+- `+copy_dashboard` ([doc](references/copy_dashboard.md))
+- `+freeze_dashboards` ([doc](references/freeze_dashboards.md))
+- `+move_dashboard` ([doc](references/move_dashboard.md))
 - `+create_or_update_dashboard_note` ([doc](references/create_or_update_dashboard_note.md))
 - `+list_public_access_links` ([doc](references/list_public_access_links.md))
 - `+create_public_access_link` ([doc](references/create_public_access_link.md))
@@ -319,11 +353,17 @@ Reports and Dashboards (17):
 - `+get_bi_panel_detail` ([doc](references/get_bi_panel_detail.md))
 - `+query_bi_panel_data` ([doc](references/query_bi_panel_data.md))
 
-Model Analysis (11):
+Model Analysis (17):
 - `+build_event_analysis_qp` ([doc](references/build_event_analysis_qp.md))
 - `+build_retention_analysis_qp` ([doc](references/build_retention_analysis_qp.md))
 - `+build_funnel_analysis_qp` ([doc](references/build_funnel_analysis_qp.md))
 - `+build_prop_analysis_qp` ([doc](references/build_prop_analysis_qp.md))
+- `+build_attribution_analysis_qp` ([doc](references/build_attribution_analysis_qp.md))
+- `+build_distribution_analysis_qp` ([doc](references/build_distribution_analysis_qp.md))
+- `+build_heat_map_analysis_qp` ([doc](references/build_heat_map_analysis_qp.md))
+- `+build_interval_analysis_qp` ([doc](references/build_interval_analysis_qp.md))
+- `+build_path_analysis_qp` ([doc](references/build_path_analysis_qp.md))
+- `+build_rank_list_analysis_qp` ([doc](references/build_rank_list_analysis_qp.md))
 - `+query_adhoc` ([doc](references/query_adhoc.md))
 - `+cancel_query` ([doc](references/cancel_query.md))
 - `+drilldown_users` ([doc](references/drilldown_users.md))
@@ -333,53 +373,66 @@ Model Analysis (11):
 - `+get_table_columns` ([doc](references/get_table_columns.md))
 
 Entity/Event Details (4):
+
 - `+query_entity_details` ([doc](references/query_entity_details.md))
 - `+query_event_details` ([doc](references/query_event_details.md))
 - `+build_entity_details_sql` ([doc](references/build_entity_details_sql.md))
 - `+build_event_details_sql` ([doc](references/build_event_details_sql.md))
 
 Schema (3):
+
 - `+get_analysis_query_schema` ([doc](references/get_analysis_query_schema.md))
 - `+get_filter_schema` ([doc](references/get_filter_schema.md))
 - `+get_groupby_schema` ([doc](references/get_groupby_schema.md))
 
-### analysis_audience (14)
+### analysis_audience (22)
 
-Clusters (6):
+Clusters (10):
 - `+create_cluster` ([doc](references/create_cluster.md))
 - `+get_clusters_by_name` ([doc](references/get_clusters_by_name.md))
 - `+list_cluster_members` ([doc](references/list_cluster_members.md))
 - `+list_clusters` ([doc](references/list_clusters.md))
 - `+update_cluster` ([doc](references/update_cluster.md))
 - `+refresh_cluster` ([doc](references/refresh_cluster.md))
+- `+create_id_cluster` ([doc](references/create_id_cluster.md))
+- `+update_id_cluster` ([doc](references/update_id_cluster.md))
+- `+delete_cluster` ([doc](references/delete_cluster.md))
+- `+build_cluster_definition` ([doc](references/build_cluster_definition.md))
 
-Tags (6):
+Tags (10):
 - `+create_tag` ([doc](references/create_tag.md))
 - `+get_tags_by_name` ([doc](references/get_tags_by_name.md))
 - `+list_tag_members` ([doc](references/list_tag_members.md))
 - `+list_tags` ([doc](references/list_tags.md))
 - `+update_tag` ([doc](references/update_tag.md))
 - `+refresh_tag` ([doc](references/refresh_tag.md))
+- `+create_id_tag` ([doc](references/create_id_tag.md))
+- `+update_id_tag` ([doc](references/update_id_tag.md))
+- `+delete_tag` ([doc](references/delete_tag.md))
+- `+build_tag_definition` ([doc](references/build_tag_definition.md))
 
 Schema Definitions (2):
+
 - `+get_cluster_definition_schema` ([doc](references/get_cluster_definition_schema.md))
 - `+get_tag_definition_schema` ([doc](references/get_tag_definition_schema.md))
 
-### analysis_meta (23)
+### analysis_meta (24)
 
-Metadata and Governance (10):
+Metadata and Governance (11):
 - `+list_events` ([doc](references/list_events.md))
 - `+list_properties` ([doc](references/list_properties.md))
 - `+list_metrics` ([doc](references/list_metrics.md))
 - `+get_metric` ([doc](references/get_metric.md))
 - `+create_metric` ([doc](references/create_metric.md))
 - `+update_metric` ([doc](references/update_metric.md))
+- `+delete_metric` ([doc](references/delete_metric.md))
 - `+batch_edit_metadata` ([doc](references/batch_edit_metadata.md))
 - `+batch_create_metadata` ([doc](references/batch_create_metadata.md))
 - `+create_virtual_event` ([doc](references/create_virtual_event.md))
 - `+create_virtual_property` ([doc](references/create_virtual_property.md))
 
 Project and Tracking (11):
+
 - `+get_project_config` ([doc](references/get_project_config.md))
 - `+list_project_users` ([doc](references/list_project_users.md))
 - `+get_track_program` ([doc](references/get_track_program.md))
@@ -393,6 +446,7 @@ Project and Tracking (11):
 - `+delete_project_mark_times` ([doc](references/delete_project_mark_times.md))
 
 Entity Catalog (2):
+
 - `+create_entity` ([doc](references/create_entity.md))
 - `+list_entities` ([doc](references/list_entities.md))
 

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

@@ -0,0 +1,62 @@
+# analysis +build_attribution_analysis_qp (Build Attribution Analysis QP)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated attribution-analysis QP from structured attribution intent.
+- Attribution analysis assigns conversion credit to touchpoint events that preceded a target conversion event.
+- Use in the mandatory builder flow before `+query_adhoc --model_type attribution`.
+- 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.
+- `--attribution` is a JSON object. Required fields: `targetEvent`, `targetAggregation`, `attributionEvents` (array), `attributionModel`, `window`.
+- `attributionModel` values: `first`=First Touch, `last`=Last Touch, `linear`=Equal credit.
+- `window.unit`: day / hour / minute. `window.value`: 0=same day.
+- Wrap JSON in single quotes in shell commands.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_attribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --attribution '<attribution_json>'
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
+| `--time_range` | Yes | Time range JSON |
+| `--attribution` | Yes | Attribution intent JSON |
+
+## JSON Shape
+`--attribution` object:
+```json
+{
+  "targetEvent": "purchase",
+  "targetAggregation": "A101",
+  "attributionEvents": [{"event": "click_ad"}, {"event": "view_product"}],
+  "attributionModel": "last",
+  "window": {"value": 7, "unit": "day"}
+}
+```
+
+Optional fields in `--attribution`:
+- `targetProperty`: required when targetAggregation is property-based (A103/A104/A106/A107/A108 etc.)
+- `directConversion`: include direct conversions without touchpoints. Defaults to true.
+- `filters`: global filters array
+- `relation`: filter relation (and / or)
+
+## Examples
+```bash
+ae-cli analysis +build_attribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":30}' --attribution '{"targetEvent":"purchase","targetAggregation":"A101","attributionEvents":[{"event":"click_ad"}],"attributionModel":"last","window":{"value":7,"unit":"day"}}'
+```
+
+## Decision Rules
+- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
+- After successful build (`status=generated`), call `+query_adhoc --model_type attribution --qp '<response.qp>'`.
+- If non-generated status, stop and ask user to clarify.
+
+## Recommended Chain
+- `+build_attribution_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type attribution --qp '<response.qp>'`

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

@@ -0,0 +1,62 @@
+# analysis_audience +build_cluster_definition (Build Cluster Definition)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Cluster Management**
+
+## Use Cases
+
+- Build a cluster definition JSON from structured intent. Call this before `+create_cluster` or `+update_cluster` to generate the `definition` field.
+- For type=condition, event and property names are resolved from project metadata — do not guess.
+- For type=sql, pass the SQL string directly.
+- On success, pass the returned definition to `+create_cluster` or `+update_cluster`.
+
+## Required Prerequisites (MUST)
+
+- Before calling this command, you must first read and follow these reference docs:
+  - [`./get_cluster_definition_schema.md`](./get_cluster_definition_schema.md)
+  - [`./list_events.md`](./list_events.md)
+  - [`./list_properties.md`](./list_properties.md)
+- Do not construct `--conditions` / `--include_filter` / `--exclude_filter` until the schema has been read and metadata has been verified for the same `project_id`.
+
+## Commands
+
+```bash
+ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type condition --conditions '{}'
+ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type condition --conditions '{}' --include_filter '{}' --exclude_filter '{}'
+ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type sql --sql 'SELECT "#user_id" FROM ...'
+ae-cli analysis_audience +build_cluster_definition --dry-run
+```
+
+## Parameters
+
+| Parameter             | Required | Description                                                                                                                           |
+| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project_id` / `-p` | Yes      | Project ID                                                                                                                            |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the definition. |
+| `--type`              | Yes      | Cluster type. Supported values: `condition`, `sql`                                                                                    |
+| `--conditions`        | No       | For type=condition: main condition group JSON (required when type=condition). See `+get_cluster_definition_schema` for the structure. |
+| `--include_filter`    | No       | For type=condition: global include condition group JSON.                                                                              |
+| `--exclude_filter`    | No       | For type=condition: global exclude condition group JSON.                                                                              |
+| `--sql`               | No       | For type=sql: SQL query returning a single column named `#user_id`.                                                                   |
+
+## Decision Rules
+- Use `--authenticated_only true` when the definition should only resolve authenticated events/properties/metrics/clusters/tags.
+
+- Determine `--type` first, then pass the corresponding parameters.
+- For type=condition, `--conditions` is effectively required; `--include_filter` and `--exclude_filter` are optional global filters.
+- For type=sql, only `--sql` is needed; condition-related parameters are ignored.
+- Event and property names in condition JSON 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. `--conditions '{}'`) 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_cluster` or `+update_cluster`, re-read `+get_cluster_definition_schema` with `--response_mode examples` and verify metadata names again.
+
+## Recommended Chain
+
+- `+get_cluster_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_cluster_definition` → `+create_cluster`
+- `+get_cluster_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_cluster_definition` → `+update_cluster`

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

@@ -0,0 +1,67 @@
+# analysis +build_distribution_analysis_qp (Build Distribution Analysis QP)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated distribution-analysis QP from structured distribution metrics.
+- Distribution analysis shows how a metric value is distributed across users or events.
+- Use in the mandatory builder flow before `+query_adhoc --model_type distribution`.
+- 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.
+- `--distribution_metrics` is a JSON array. Each item requires `event` and `aggregation`.
+- Distribution-specific aggregations: `A200`=count, `A201`=active-days, `A202`=active-hours.
+- Standard aggregations requiring `property`: A103=sum, A104=avg, A106=max, A107=min, A117=median, A119=percentile.
+- Wrap JSON in single quotes in shell commands.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_distribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --distribution_metrics '<metrics_json>'
+ae-cli analysis +build_distribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --distribution_metrics '<metrics_json>' --time_particle_size day --groups '<groups_json>' --filters '<filters_json>' --relation and
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
+| `--time_range` | Yes | Time range JSON |
+| `--distribution_metrics` | Yes | Distribution metrics JSON array |
+| `--time_particle_size` | No | Time granularity. Allowed values: day, week, month, total. Defaults to day. |
+| `--groups` | No | Optional group-by dimensions JSON array |
+| `--filters` | No | Optional global filters JSON array |
+| `--relation` | No | Filter relation. Supported values: and, or. Default: and. |
+
+## JSON Shape
+`--distribution_metrics` array:
+```json
+[{"event":"login","aggregation":"A200"}]
+```
+
+Each metric item fields:
+- `event` (required): event name
+- `aggregation` (required): aggregation code
+- `property` (optional): required for property-based aggregations
+- `percentile` (optional): percentile value, e.g. 90 for P90. Required when aggregation=A119.
+- `intervalType` (optional): def (auto, default) / user_defined (custom) / discrete (raw value)
+- `quotaIntervalArr` (optional): custom bucket boundaries, e.g. [100,1000,10000]. Required when intervalType=user_defined.
+- `filters` (optional): metric-level filters
+- `relation` (optional): filter relation for metric-level filters
+
+## Examples
+```bash
+ae-cli analysis +build_distribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --distribution_metrics '[{"event":"login","aggregation":"A200"}]'
+
+ae-cli analysis +build_distribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --distribution_metrics '[{"event":"purchase","aggregation":"A103","property":"amount"}]'
+```
+
+## Decision Rules
+- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
+- After successful build (`status=generated`), call `+query_adhoc --model_type distribution --qp '<response.qp>'`.
+- If non-generated status, stop and ask user to clarify.
+
+## Recommended Chain
+- `+build_distribution_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type distribution --qp '<response.qp>'`

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

@@ -33,6 +33,7 @@ ae-cli analysis +build_event_analysis_qp --project_id <project_id> --time_range
 | Parameter | Required | Description |
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
 | `--time_range` | Yes | Event analysis time range JSON |
 | `--metrics` | Yes | Event metrics JSON array |
 | `--time_particle_size` | No | Time granularity. Default: total |
@@ -122,6 +123,7 @@ ae-cli analysis +build_event_analysis_qp --project_id 3137 --time_range '{"mode"
 ```
 
 ## Decision Rules
+- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
 - After successful build, call `+query_adhoc --model_type event --qp '<response.qp>'`.
 - If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
 - Wrap JSON parameters in single quotes to avoid shell escaping issues.

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

@@ -33,6 +33,7 @@ ae-cli analysis +build_funnel_analysis_qp --project_id <project_id> --time_range
 | Parameter | Required | Description |
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
 | `--time_range` | Yes | Funnel analysis time range JSON |
 | `--funnel` | Yes | Funnel intent JSON |
 | `--relation` | No | Top-level funnel filter relation. Supported values: and, or. Default: and |
@@ -131,6 +132,7 @@ ae-cli analysis +query_adhoc --project_id 3137 --model_type funnel --qp '<respon
 ```
 
 ## Decision Rules
+- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
 - After successful build, call `+query_adhoc --model_type funnel --qp '<response.qp>'`.
 - If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
 - Wrap JSON parameters in single quotes to avoid shell escaping issues.

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

@@ -0,0 +1,54 @@
+# analysis +build_heat_map_analysis_qp (Build Heatmap Analysis QP)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated heatmap-analysis QP from structured heatmap intent.
+- Heatmap analysis visualizes user interaction intensity on a 2D coordinate plane (e.g. screen position).
+- Use in the mandatory builder flow before `+query_adhoc --model_type heat_map`.
+- 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.
+- `--heat_map` is a JSON object. Required fields: `hotEvent`, `hotAggregation`, `xProp`, `yProp`.
+- `xProp` and `yProp` must be numeric event properties (e.g. screen_width, screen_height, x_position, y_position).
+- Wrap JSON in single quotes in shell commands.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_heat_map_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --heat_map '<heat_map_json>'
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
+| `--time_range` | Yes | Time range JSON |
+| `--heat_map` | Yes | Heatmap intent JSON |
+
+## JSON Shape
+`--heat_map` object:
+```json
+{"hotEvent":"screen_tap","hotAggregation":"A100","xProp":"x_position","yProp":"y_position"}
+```
+
+Optional fields in `--heat_map`:
+- `hotProperty`: required when hotAggregation is property-based (A103/A104 etc.)
+- `filters`: event filters array
+- `relation`: filter relation (and / or)
+
+## Examples
+```bash
+ae-cli analysis +build_heat_map_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --heat_map '{"hotEvent":"screen_tap","hotAggregation":"A100","xProp":"x_position","yProp":"y_position"}'
+```
+
+## Decision Rules
+- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
+- After successful build (`status=generated`), call `+query_adhoc --model_type heat_map --qp '<response.qp>'`.
+- If non-generated status, stop and ask user to clarify.
+
+## Recommended Chain
+- `+build_heat_map_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type heat_map --qp '<response.qp>'`