@thinkingai/ae-cli 1.0.15 → 1.0.20

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

@@ -0,0 +1,141 @@
+# analysis +build_retention_analysis_qp (build retention analysis qp)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated retention-analysis QP from structured intent.
+- Use in the mandatory builder flow before `+query_adhoc --model_type retention`.
+- This command builds QP only and does not execute the analysis query.
+- This is one of exactly four QP builders: `event`, `retention`, `funnel`, `prop_analysis`.
+- Use this builder for retention ad hoc requests; do not manually build retention QP through `+get_analysis_query_schema`.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase DTO names.
+- Correct nested keys: `initialEvent`, `returnEvent`, `unitNum`, `rtnRateOrNum`, `relationEventPropertyName`, `initialFilters`, `returnFilters`, `initialFilterRelation`, `returnFilterRelation`.
+- Initial/return event filters are event-property-only and use `eventPropertyName`; they do not use the generic `field` object.
+- Retention global filters and groups use the generic `field` object.
+- Do not run syntax examples with placeholder JSON. Fill `time_range` and `retention` with valid nested fields before calling this command.
+- `--dry-run` still requires the same required flags as a real builder call. Never run this command as dry-run without `--project_id`, `--time_range`, and `--retention`.
+- Do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, or `get_metric` before this builder for normal ad-hoc analysis. The builder resolves events and properties internally.
+- Builder commands do not accept `zone_offset`; pass `--zone_offset` to `+query_adhoc` after the builder succeeds.
+- If the request misses time range, initial event, return event, or retention interval, stop and ask the user to clarify.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>'
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>' --relation and --time_particle_size day
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>' --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--time_range` | Yes | Retention analysis time range JSON |
+| `--retention` | Yes | Retention intent JSON |
+| `--relation` | No | Top-level retention filter relation. Supported values: and, or. Default: and |
+| `--time_particle_size` | No | Time granularity. Supported values: day, week, month |
+
+## JSON Shape
+`--time_range` object:
+```json
+{"mode":"start_to_yesterday","startTime":"2021-05-18"}
+```
+
+Time range fields:
+| Field | Required | Description |
+|---|---|---|
+| `mode` | Yes | `recent`, `previous`, `custom`, `start_to_today`, `start_to_yesterday` |
+| `unit` | For `recent`/`previous` | `day`, `week`, `month`, `quarter`, `year` |
+| `value` | For `recent`/`previous` | Unit count. `{"mode":"previous","unit":"day","value":1}` means yesterday. |
+| `startTime` | For `custom`/`start_to_*` | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+| `endTime` | For `custom` only | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+
+`--retention` object:
+```json
+{
+  "initialEvent":"注册",
+  "returnEvent":"商品购买",
+  "unitNum":7,
+  "statType":"retention",
+  "rtnRateOrNum":"R0",
+  "relationEventPropertyName":"账户ID",
+  "initialFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],
+  "returnFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],
+  "filters":[{"field":{"name":"城市","type":"event_property"},"operator":"exists"}],
+  "groups":[{"field":{"name":"渠道","type":"user_property"}}]
+}
+```
+
+Retention fields:
+| Field | Required | Description |
+|---|---|---|
+| `initialEvent` | Yes | Initial event display name, technical name, or remark |
+| `returnEvent` | Yes | Return event display name, technical name, or remark |
+| `unitNum` | Yes | Retention interval count, such as `1` for day-1 or `7` for day-7 |
+| `statType` | No | `retention` for retained users or `lost` for lost users |
+| `rtnRateOrNum` | No | `R0`, `rate`, or `retention` for rate; `R1`, `number`, or `count` for user count. Default: `R0`. |
+| `relationEventPropertyName` | No | Event property shared by initial event, return event, and simultaneous metrics |
+| `simultaneousMetrics` | No | Extra retention display metrics |
+| `groups` | No | Generic group-by dimensions |
+| `filters` | No | Generic retention filters |
+| `initialFilters` | No | Event-property-only filters for initial event |
+| `initialFilterRelation` | No | Relation for `initialFilters`: `and` or `or` |
+| `returnFilters` | No | Event-property-only filters for return event |
+| `returnFilterRelation` | No | Relation for `returnFilters`: `and` or `or` |
+
+Initial/return event filter object:
+```json
+{"eventPropertyName":"账户ID","operator":"exists"}
+```
+
+Generic filter object for `retention.filters`:
+```json
+{"field":{"name":"城市","type":"event_property"},"operator":"exists"}
+```
+
+Group object:
+```json
+{"field":{"name":"渠道","type":"user_property"}}
+```
+
+Metric object for `simultaneousMetrics`:
+```json
+{"event":"商品购买","aggregation":"user_count"}
+```
+
+Supported aggregations:
+`total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `true_count`, `false_count`, `not_empty_count`, `empty_count`, `median`, `percentile`, `variance`, `stddev`.
+
+Filter operator rules:
+| Operator | Values |
+|---|---|
+| `exists`, `not_exists`, `is_true`, `is_false` | Omit `values` |
+| `between` | Exactly two values |
+| `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `regex`, `not_regex` | Non-empty `values` array |
+| `in_cluster`, `not_in_cluster` | Cluster operator; values are not required by builder validation |
+
+## Examples
+Minimal day-7 retention:
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --retention '{"initialEvent":"注册","returnEvent":"商品购买","unitNum":7}'
+```
+
+Retention with relation property and event-level filters:
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id 3137 --time_range '{"mode":"start_to_yesterday","startTime":"2021-05-18"}' --retention '{"initialEvent":"special_data","returnEvent":"商品购买","unitNum":7,"relationEventPropertyName":"账户ID","initialFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],"returnFilters":[{"eventPropertyName":"账户ID","operator":"exists"},{"eventPropertyName":"城市","operator":"exists"}],"returnFilterRelation":"or","filters":[{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"},{"field":{"name":"城市","type":"event_property"},"operator":"exists"}],"groups":[{"field":{"name":"账户ID","type":"event_property"}}]}' --relation or --time_particle_size day
+```
+
+## Decision Rules
+- After successful build, call `+query_adhoc --model_type retention --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.
+- Do not pre-query metrics or metadata. Pass user-provided event/property names to the builder and let it resolve them.
+- Do not put global filter relation inside `retention`; pass it as top-level CLI flag `--relation`.
+- For overall/totals retention, omit `--time_particle_size`; only set it when user asks for day/week/month breakdown.
+- If the user gave a time zone, keep it for `+query_adhoc --zone_offset`; do not put it in the builder JSON.
+
+## Recommended Chaining
+- `+build_retention_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type retention --qp '<response.qp>'`

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

@@ -16,26 +16,26 @@ Domain: **Project Configuration**
 
 ## Commands
 ```bash
-ae-cli analysis_meta +generate_track_program --project_id <project_id> --form_data '{}'
+ae-cli analysis_meta +generate_track_program --project_id <project_id> --language <language> --form_data '{}'
 ae-cli analysis_meta +generate_track_program --dry-run
 ```
 
 ## Parameters
-| Parameter             | Required | Description                                                                                                                                                                                                                                                                                                                                                                            |
-|-----------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--project_id` / `-p` | Yes      | Project ID                                                                                                                                                                                                                                                                                                                                                                             |
-| `--form_data`         | Yes      | Structured business context JSON object. Optional fields: account_system, revenue_model, core_gameplay, currency_system, main_entries, language, predefinedEvent (array of event names like install, start, close), developmentCarrier (array of platforms like Android, iOS, Unity, Cocos, Douyin Mini Game, WeChat Mini Game). All fields can be customized based on business needs. |
+| Parameter             | Required | Description                                                                                                                                                                                                                                                                                                                                                                              |
+|-----------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--project_id` / `-p` | Yes      | Project ID                                                                                                                                                                                                                                                                                                                                                                               |
+| `--language` / `-l`   | Yes      | Language code. Supported values: `zh-CN`, `en-US`, `ja-JP`, `ko-KR`                                                                                                                                                                                                                                                                                                                      |
+| `--form_data`         | Yes      | Structured business context JSON object. Optional fields for example: account_system, revenue_model, core_gameplay, currency_system, main_entries, predefinedEvent (array of event names like install, start, close), developmentCarrier (array of platforms like Android, iOS, Unity, Cocos, Douyin Mini Game, WeChat Mini Game). All fields can be customized based on business needs. |
 
 ## Decision Rules
 - **CRITICAL: Always call `+get_track_program` first to check existing tracking plan before generating.**
-- First run should only pass the required parameters (`--project_id`, `--form_data`).
+- First run should only pass the required parameters (`--project_id`, `--language`, `--form_data`).
 - Wrap JSON arguments in single quotes (for example `--form_data '{}'`) to avoid shell escaping issues.
 - This is an asynchronous operation; check in-site message center for generation results.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id` and `--form_data`).
-- If `FORM_DATA_REQUIRED_FIELDS_MISSING` occurs, ensure all required fields are provided: account_system, revenue_model, core_gameplay, currency_system, main_entries, language.
+- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--language`, and `--form_data`).
 - If `Invalid JSON` occurs, validate with the smallest JSON structure first.
 
 ## Agent Response Flow

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

@@ -4,13 +4,22 @@
 
 Domain: **Model schema queries**
 
+> **CRITICAL - Builder-supported ad hoc models**
+>
+> Do **not** use this tool for natural-language ad hoc requests whose target model is `event`, `retention`, `funnel`, or `prop_analysis`.
+> For those four models, use the matching QP builder first:
+> `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp`, 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 non-builder/manual model paths such as `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, or `sql`.
 > **You MUST execute these steps in order. Do NOT skip any step.**
 >
 > | Step | Command | When to proceed |
 > |------|---------|-----------------|
-> | **Step 1 (MANDATORY)** | `--model_type <type>` **without `--segments`** | Always execute first. Review result. |
+> | **Step 1 (MANUAL PATH ONLY)** | `--model_type <type>` **without `--segments`** | Execute first only for non-builder/manual models. 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 |
 >
@@ -19,26 +28,27 @@ Domain: **Model schema queries**
 
 ## Pre-call Checklist (Execute in Order)
 
+0. ✓ **Builder-supported model?** → If `event`/`retention`/`funnel`/`prop_analysis`, 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**: Uncertain → execute Step 1 first.
+**Rule**: For non-builder/manual models, uncertain → execute Step 1 first. For `event`, `retention`, `funnel`, or `prop_analysis`, uncertain → read the matching builder reference first.
 
 ## Command (Execute in Order)
 
 ```bash
-# Step 1: ALWAYS START HERE (no segments)
-ae-cli analysis +get_analysis_query_schema --model_type event
+# Step 1: start here only for non-builder/manual models (no segments)
+ae-cli analysis +get_analysis_query_schema --model_type distribution
 
 # Step 2: Only after Step 1, if filter/groupBy needed
-ae-cli analysis +get_analysis_query_schema --model_type event --segments 'filter_group' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --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 event --segments 'examples' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --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 event --segments 'examples' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --segments 'examples' --include_core false
 ```
 
 ## Parameters
@@ -53,9 +63,10 @@ ae-cli analysis +get_analysis_query_schema --model_type event --segments 'exampl
 
 | 场景 | 参数 | 执行顺序 |
 |---|---|---|
-| 简单 | 不传 `--segments` | **Step 1** - 单事件、单指标、无过滤、无分组 |
-| 中等 | `--segments 'filter_group'` | **Step 2** - 有过滤或分组，需先完成 Step 1 |
-| 复杂 | `--segments 'examples'` | **Step 3** - 多指标、时间对比、自定义公式，需先完成 Step 1 |
+| Builder 支持模型 | 不适用 | `event`/`retention`/`funnel`/`prop_analysis` 禁止用此工具作为 QP 准备步骤，改用 builder |
+| 简单 | 不传 `--segments` | **Step 1** - 非 builder/manual 模型 |
+| 中等 | `--segments 'filter_group'` | **Step 2** - 非 builder/manual 模型，有过滤或分组，需先完成 Step 1 |
+| 复杂 | `--segments 'examples'` | **Step 3** - 非 builder/manual 模型，需先完成 Step 1 |
 
 ## Next Steps on Failure
-- Verify model type and segment compatibility (e.g., aggregatetype not for funnel/path/interval/sql)
+- Verify model type and segment compatibility (e.g., aggregatetype not for funnel/path/interval/sql)

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

@@ -4,9 +4,13 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Not a builder pre-step:** Do not call `+get_metric` before `+build_event_analysis_qp` for normal ad-hoc analysis. If the user asks to query a saved metric, pass the metric display/name/remark directly as `metrics:[{"event":"<metric name>"}]` to `+build_event_analysis_qp`. The builder resolves saved metrics internally. If it cannot resolve the metric, stop on the builder's structured error and ask for clarification.
+
 ## Use Cases
 - Get the definition details of a single metric. Returns the metric name, display name, remark, model type, linked events, and parameter definition without executing metric calculation.
-- Get the definition details of a single metric.
+- Use this command for metric metadata inspection, metric editing, auditing, or when the user explicitly asks for metric definition details. Do not use it merely to expand a saved metric before a builder-supported ad-hoc query.
 
 ## Commands
 ```bash
@@ -22,6 +26,7 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Decision Rules
 - For the first run, pass only the required parameters (`--project_id` and `--metric_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, do not read metric details first. Call the matching builder with the user's metric/event/property wording.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -30,3 +35,4 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Recommended Chaining
 - +get_metric -> +update_metric
+- For ad-hoc saved metric query: +build_event_analysis_qp -> +query_adhoc

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

@@ -4,6 +4,10 @@
 
 Domain: **Report Management**
 
+## Constraints
+
+**Not a builder fallback:** Do not call `+get_report_definition` to repair or replace a failed `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp` call. For builder-supported ad-hoc analysis, 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.

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

@@ -4,6 +4,10 @@
 
 Domain: **Metadata Lookup**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
 ## Use Cases
 - List all alerts in the project. Supports keyword filtering by alert name. Returns a paginated list containing alerts array and pager result with total count.
 - List all alerts in the project.

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

@@ -4,6 +4,10 @@
 
 Domain: **Cluster Management**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
 ## Use Cases
 - List cluster metadata accessible to the current user in the project.
 - Supports payload governance parameters: `query`, `fields`, `limit`, `offset`.

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

@@ -4,6 +4,12 @@
 
 Domain: **Dashboard management**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
+**Builder failure is terminal:** For builder-supported ad-hoc analysis, this command may be used only in the initial `QUERY_EXISTING_FIRST` dashboard search. Do not call dashboard/report detail tools as a fallback after a QP builder returns non-generated status.
+
 ## Use Cases
 - List dashboard metadata accessible to the current user in the project. Supports keyword filtering and returns dashboard IDs, names, descriptions, and related metadata, but not dashboard configuration or report data.
 - List dashboard metadata accessible to the current user in the project.

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

@@ -4,9 +4,15 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
+**Not a builder pre-step:** Do not call `+list_events` before builder-supported ad-hoc analysis (`event`, `retention`, `funnel`, `prop_analysis`). The matching QP builder resolves event names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - Read-only query for SYSTEM METADATA already effective in the project. Use for super events in production metadata. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA already effective in the project.
+- Read-only query for SYSTEM METADATA already effective in the project. Use when the user explicitly asks to inspect event metadata, not as a required preparation step for QP builder.
 
 ## Commands
 ```bash
@@ -26,6 +32,7 @@ ae-cli analysis_meta +list_events --dry-run
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 ## Decision Rules
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, pass the user's event wording to the builder instead of pre-querying event metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -4,10 +4,17 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
+**Not a builder pre-step:** Do not call `+list_metrics` before `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp` for normal ad-hoc analysis. Event builder resolves saved metric names internally when the metric name is passed in `metrics[].event`. If the builder fails, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - List metric metadata in the project. Supports keyword filtering and returns metric IDs, names, display names, model types, remarks, and related metadata, but not metric calculation results.
 - Supports pagination with fields/limit/offset for payload governance.
 - Query performs fuzzy matching on metricName, metricDesc, and metricRemark.
+- Use this command for metric metadata management, metric editing, auditing, or when the user explicitly asks to inspect/search metric metadata. Do not use it merely to prepare a builder-supported ad-hoc query.
 
 ## Command
 ```bash
@@ -30,6 +37,7 @@ ae-cli analysis_meta +list_metrics --dry-run
 - First run should only pass the required parameter (`--project_id`), and add optional parameters only after the path is confirmed to work.
 - For pagination, use `--limit` and `--offset` together. Default limit is 20.
 - Use `--fields` to select specific columns for lighter response payloads.
+- For builder-supported ad-hoc analysis, do not search metrics here first. Pass the user-provided metric name directly to the builder.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -39,3 +47,4 @@ ae-cli analysis_meta +list_metrics --dry-run
 
 ## Recommended Chaining
 - +list_metrics -> +create_metric -> +get_metric
+- For ad-hoc event metric query: +build_event_analysis_qp -> +query_adhoc

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

@@ -4,9 +4,13 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Not a builder pre-step:** Do not call `+list_properties` before builder-supported ad-hoc analysis (`event`, `retention`, `funnel`, `prop_analysis`). The matching QP builder resolves property names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - Read-only query for SYSTEM METADATA properties already effective in the project. Supports event/user scope. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA properties already effective in the project.
+- Read-only query for SYSTEM METADATA properties already effective in the project. Use when the user explicitly asks to inspect property metadata, not as a required preparation step for QP builder.
 
 ## Commands
 ```bash
@@ -30,6 +34,7 @@ ae-cli analysis_meta +list_properties --dry-run
 
 ## Decision Rules
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, pass the user's property wording to the builder instead of pre-querying property metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -4,6 +4,12 @@
 
 Domain: **Report management**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
+**Builder failure is terminal:** For builder-supported ad-hoc analysis, this command may be used only in the initial `QUERY_EXISTING_FIRST` report search. Do not call `+list_reports` or `+get_report_definition` as a fallback after a QP builder returns non-generated status.
+
 ## Use Cases
 - List report metadata accessible to the current user in the project. Supports keyword filtering and returns report IDs, names, model types, update times, and related metadata, but not report definitions or analysis data.
 - List report metadata accessible to the current user in the project.

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

@@ -4,6 +4,10 @@
 
 Domain: **Tag Management**
 
+## Constraints
+
+**Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
+
 ## Use Cases
 - List tag metadata accessible to the current user in the project.
 - Supports payload governance parameters: `query`, `fields`, `limit`, `offset`.

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

@@ -4,9 +4,37 @@
 
 Domain: **Model analysis**
 
+## Constraints
+
+**⚠️ QUERY_EXISTING_FIRST:** Before using ad-hoc query, you MUST first check for existing reports/dashboards with `list_reports` and `list_dashboards`. Only use `query_adhoc` if no matching reports found. See [SKILL.md § D. QUERY_EXISTING_FIRST](../SKILL.md#d-query_existing_first).
+
+**⚠️ QP_BUILDER_SUPPORTED_MODELS_ONLY:** QP builder supports exactly four ad-hoc model types: `event`, `retention`, `funnel`, and `prop_analysis`.
+
+For these four model types, call the matching builder before `query_adhoc`. Do not handcraft QP from `get_analysis_query_schema`, examples, or prior knowledge.
+
+For all other model types (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`), QP builder is not supported. Use the legacy schema/metadata path and construct QP manually according to the model schema.
+
+For builder-supported models, schema/metadata tools are not builder pre-steps. After report/dashboard lookup misses, do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, `get_metric`, or `get_report_definition` before the builder. The builder resolves event/property/metric metadata internally.
+
+**Hard stop rule:** If builder status is not `generated`, stop and ask the user to clarify or report the builder error. Do not call `query_adhoc`, `get_analysis_query_schema`, or manually assemble QP for `event`, `retention`, `funnel`, or `prop_analysis`.
+
+Builder mapping:
+1. `event` -> `+build_event_analysis_qp`
+2. `retention` -> `+build_retention_analysis_qp`
+3. `funnel` -> `+build_funnel_analysis_qp`
+4. `prop_analysis` -> `+build_prop_analysis_qp`
+
+**Quick check workflow:**
+1. `list_reports --query <keyword>` - search matching reports
+2. `list_dashboards --query <keyword>` - search matching dashboards
+3. If found → use `query_report_data` or `query_dashboard_report_data`
+4. If not found and model is builder-supported (`event`/`retention`/`funnel`/`prop_analysis`) → read matching builder reference, call matching builder, then call `query_adhoc` with `model_type` + built `qp`; do not insert schema or metadata lookup before the builder
+5. If not found and model is not builder-supported (`distribution`/`attribution`/`heat_map`/`interval`/`path`/`rank_list`/`sql`) → use the legacy schema/metadata path, then call `query_adhoc`
+
 ## Use Cases
-- Precondition helper: call `+get_analysis_query_schema` to get the structure before using this tool.
-- When constructing a real `qp`, you must supplement it with real project metadata; first call `analysis_meta +list_events` and `analysis_meta +list_properties`.
+- Execute a QP produced by the required chain for the target model.
+- Builder-supported models (`event`, `retention`, `funnel`, `prop_analysis`): execute the `qp` returned by builder tools.
+- Non-builder models (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`): execute handcrafted QP from the legacy schema/metadata path when needed.
 - Event analysis: metrics such as event trigger counts, user counts, sums, averages, and more.
 - Retention analysis: metrics such as user churn and retention.
 - Funnel analysis: metrics such as multi-step conversion.
@@ -18,27 +46,41 @@ Domain: **Model analysis**
 - Heat map: visual heat map analysis of user interactions.
 - Rank list: ranking / leaderboard analysis.
 - SQL: custom SQL analysis.
-- Process: fetch events/properties and the schema first, then assemble the query JSON, and finally execute the analysis.
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--qp`, you must first read and follow these reference documents:
-  - [`./get_analysis_query_schema.md`](./get_analysis_query_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate the final `qp` until the documentation review and prerequisite command calls are complete.
-
-## Prerequisite call chain (required for constructing qp)
-1. First determine `--model_type`.
-2. Read `get_analysis_query_schema.md`, then call `ae-cli analysis +get_analysis_query_schema --model_type <model_type>` to get the structure.
-3. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>` to get the available events.
-4. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>` to get the available properties.
-5. Build `qp` from the schema + metadata, then call `+query_adhoc`.
-
-## Command
+- Process:
+  - Builder-supported models: builder -> `query_adhoc`
+  - Non-builder models: metadata/schema lookup -> handcraft `qp` -> `query_adhoc`
+
+## Builder-Supported Model Chain
+Use this chain only for `event`, `retention`, `funnel`, and `prop_analysis`.
+
+1. Read the matching builder reference:
+   - `event`: [`build_event_analysis_qp.md`](./build_event_analysis_qp.md)
+   - `retention`: [`build_retention_analysis_qp.md`](./build_retention_analysis_qp.md)
+   - `funnel`: [`build_funnel_analysis_qp.md`](./build_funnel_analysis_qp.md)
+   - `prop_analysis`: [`build_prop_analysis_qp.md`](./build_prop_analysis_qp.md)
+2. Compose the builder JSON using the documented DTO keys. Nested JSON keys are camelCase, not snake_case.
+3. Run the builder with all required flags. `--dry-run` is allowed only with complete required builder inputs, not by itself.
+4. If builder returns `status=generated`, copy `data.qp` from the builder response and pass it as `--qp`.
+5. If the builder returns `need_clarification`, `invalid_argument`, `unsupported_feature`, or `validation_error`, stop and ask for clarification. Do not use the legacy/manual path as a fallback for these four models.
+
+## Legacy Query Chain
+Use this chain only for `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, and `sql`.
+
+1. Read this reference and the required schema/metadata references.
+2. Call `+get_analysis_query_schema` for the target model when the QP shape is not already verified.
+3. Discover real events/properties/metrics with analysis metadata commands as needed.
+4. Construct QP according to the documented schema and verified metadata.
+5. Call `+query_adhoc`.
+
+Timezone rule:
+- Builder commands do not accept `zone_offset`.
+- Apply timezone only on this execution command, for example `--zone_offset -11`.
+
+## Command Syntax
 ```bash
-ae-cli analysis +query_adhoc --project_id <project_id> --model_type event --qp '{}'
-ae-cli analysis +query_adhoc --project_id <project_id> --model_type event --qp '{}' --fields '["date","event"]' --limit 10 --offset 0 --zone_offset 8 --request_id demo --use_cache true --is_sort_by_columns true --resolve_recent_day true --timeout_minutes 8
-ae-cli analysis +query_adhoc --dry-run
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>'
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>' --fields '["date","event"]' --limit 10 --offset 0 --zone_offset 8 --request_id demo --use_cache true --is_sort_by_columns true --resolve_recent_day true --timeout_minutes 8
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>' --dry-run
 ```
 
 ## Parameters
@@ -46,12 +88,12 @@ ae-cli analysis +query_adhoc --dry-run
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID used to identify the analysis project |
 | `--model_type` | Yes | Model type. Supported values: event, retention, funnel, distribution, attribution, heat_map, interval, path, rank_list, prop_analysis, sql. |
-| `--qp` | Yes | Query parameter JSON. MUST call `+get_analysis_query_schema` first, and use event/property metadata from `analysis_meta +list_events` / `analysis_meta +list_properties` in the same `project_id`. |
+| `--qp` | Yes | Query parameter JSON. For `event`/`retention`/`funnel`/`prop_analysis`, pass QP returned by the matching builder tool. For non-builder models, construct QP through the legacy schema/metadata path. |
 | `--request_id` | No | Optional unique request ID used for tracking and deduplication. Generated automatically if omitted. |
 | `--use_cache` | No | Whether to use result cache. Default: true |
 | `--zone_offset` | No | Time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5 |
 | `--is_sort_by_columns` | No | Whether to sort query results by columns. Default: false |
-| `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". Default: false |
+| `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". If omitted, service auto-resolves when `qp.eventView.recentDay` exists and `startTime`/`endTime` is incomplete; otherwise defaults to false. |
 | `--fields` | No | Optional fields to return. Must match column names in result. Invalid fields cause INVALID_FIELDS error. |
 | `--limit` | No | Optional limit. Default: 20, maximum: 50. |
 | `--offset` | No | Optional offset. Default: 0. |
@@ -59,18 +101,26 @@ ae-cli analysis +query_adhoc --dry-run
 
 ## Decision Rules
 - On the first run, start with only the required parameters (`--project_id`,`--model_type`,`--qp`), and add optional parameters after confirming the path works.
+- Do not call this command with placeholder QP such as `{}`. For builder-supported models, wait for builder `status=generated`; for non-builder models, build QP from verified schema/metadata first.
+- For builder-supported models, do not run metadata/schema lookup to "help" the builder. The builder is the metadata resolver.
 - For pagination, use `--limit` and `--offset` together. Default limit is 20.
 - Use `--fields` to select specific columns for lighter response payloads.
-- `qp` 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.
-- Wrap JSON parameters in single quotes (for example `--qp '{}'`) to avoid shell escaping issues.
+- `event`, `retention`, `funnel`, and `prop_analysis` must not manually craft QP with schema-first flow; call the builder and use the returned `qp`.
+- For non-builder models, `qp` must satisfy both schema structure and project metadata constraints.
+- Wrap JSON parameters in single quotes (for example `--qp '<real_qp_json>'`) to avoid shell escaping issues.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- If the user supplied a timezone such as UTC-11, pass `--zone_offset -11` here, not to the builder.
 
 ## 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`, `--model_type`, `--qp`).
-- 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 required parameters are missing, resolve `project_id`, `model_type`, and a real `qp` first. Do not run placeholder calls except explicit `--dry-run` validation.
+- If a builder returns non-`generated` status for `event`, `retention`, `funnel`, or `prop_analysis`, stop and ask user to clarify before calling `query_adhoc`.
+- If `Invalid JSON` appears on legacy manual QP paths, first check schema required fields, then verify whether event/property names come from metadata query results for the same `project_id`.
 - If the query times out or results are abnormal, first narrow the time range / grouping dimensions, then split the subqueries to locate the issue.
 
 ## Recommended chaining
-- +get_analysis_query_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_adhoc
+- +build_event_analysis_qp -> +query_adhoc
+- +build_retention_analysis_qp -> +query_adhoc
+- +build_funnel_analysis_qp -> +query_adhoc
+- +build_prop_analysis_qp -> +query_adhoc
+- +get_analysis_query_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_adhoc (non-builder models only)
 - +list_events -> +list_properties -> +query_adhoc -> +drilldown_users -> +drilldown_user_events