@thinkingai/ae-cli 6.0.31 → 6.0.33

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

@@ -139,6 +139,12 @@ Formula metric example:
 }
 ```
 
+Formula rules:
+
+- Write **bare aliases** only in `formula` (e.g. `"revenue / users"` or `"pay / dau"`).
+- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Aggregation codes come from each dependency's `aggregation`; the builder expands aliases to real event tokens such as `purchase.amount.A103/login.A101`.
+- After the builder returns `status=generated`, hard-validate by querying (`analysis adhoc run` / report-data / dashboard-report-data). Do not save a report or dashboard from an unqueried formula QP.
+
 ### `retention`
 
 Use for retained/lost users from an initial event to a return event.
@@ -277,6 +283,16 @@ Use for behavior paths before or after a source event.
 
 Path `filters` are global member filters compiled to the original QP `user_filter`. They support `user_property`, `cluster`, and `tag`, but not `event_property`. Do not move a user filter into the source event's event-property filter.
 
+Path session timeout accepts only these unit/value ranges:
+
+- `second`: `1..999`
+- `minute`: `1..999`
+- `hour`: `1..24`
+
+Do not use `day`. Express one day as `session_interval=24` with `session_unit=hour`.
+
+Property types come from project metadata. If resolution says a field is an `event_property`, never relabel it as `user_property` just to satisfy the path schema. Remove the unsupported global filter, choose a model that supports event-property filtering, or ask the user to clarify the intended constraint. A familiar name such as `channel` is not universally an event or user property across projects.
+
 For every non-SQL intent model, do not call `list_events` or `list_properties` as an execution prerequisite. The successful response must expose every internally resolved event/property in `resolved`, including `input`, `resolved_name`, `match_type`, and `path`. Use metadata discovery only after a structured `need_clarification` response or an explicit resolution capability error.
 
 ### `prop_analysis`
@@ -373,7 +389,7 @@ Rules:
 - Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
 - Delimit any Trino identifier containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` and `"$part_event"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
 - For an event table, include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition.
-- Do not invent table or column names. If the table is unknown, call `analysis sql-table list --project-id <project_id>` and select an exact returned `table_ref`. Then use `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
+- Do not invent table or column names. If the user already provides a concrete table reference, use `analysis-meta datatable columns-get --project-id <project_id> --table-ref <table_ref>` to inspect columns before writing SQL. If the table itself is unknown, call `analysis sql-table list --project-id <project_id>` when available and select an exact returned `table_ref`; otherwise stop and ask for the table/data source. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
 - For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. Verify the default once with `analysis report-data run` without `--sql-params`, then verify a changed value with one value-only `--sql-params` override.
 - SQL tags and SQL clusters do not use this general parameter contract. They accept only `${PartDate:name}` with `type=part_date`, and their tables must be discovered with `analysis sql-table list/columns --usage tag_cluster`; see `user_tag_models.md` and `user_cluster_models.md`.
 

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

@@ -0,0 +1,25 @@
+# analysis alert create
+
+Use when create an alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert create [options]
+```
+
+Capability id: `analysis.alert.create`
+
+Input sends `project_id` and `definition`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--definition` | See command help | Yes |
+

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

@@ -0,0 +1,24 @@
+# analysis alert-definition-schema get
+
+Use when get the alert definition schema.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert-definition-schema get
+```
+
+Capability id: `analysis.alert_definition_schema.get`
+
+Input sends No input. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| None | - | - |
+

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

@@ -0,0 +1,26 @@
+# analysis alert delete
+
+Use when delete an alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert delete --project-id <project_id> --alert-id <alert_id> --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis alert delete --project-id <project_id> --alert-id <alert_id> --yes
+```
+
+Capability id: `analysis.alert.delete`
+
+Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |

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

@@ -0,0 +1,27 @@
+# analysis alert-detail list
+
+Use when list alert delivery details.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert-detail list [options]
+```
+
+Capability id: `analysis.alert_detail.list`
+
+Input sends `project_id`, `alert_id`, optional `start_time`, and optional `end_time`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |
+| `--start-time` | See command help | No |
+| `--end-time` | See command help | No |
+

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

@@ -0,0 +1,25 @@
+# analysis alert get
+
+Use when get one alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert get [options]
+```
+
+Capability id: `analysis.alert.get`
+
+Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |
+

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

@@ -0,0 +1,24 @@
+# analysis alert-job list
+
+Use when list alert job status.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert-job list [options]
+```
+
+Capability id: `analysis.alert_job.list`
+
+Input sends `project_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+

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

@@ -0,0 +1,27 @@
+# analysis alert list
+
+Use when list project alerts.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert list [options]
+```
+
+Capability id: `analysis.alert.list`
+
+Input sends `project_id`, optional `query`, `limit`, and `offset`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--query` | See command help | No |
+| `--limit` | See command help | No |
+| `--offset` | See command help | No |
+

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

@@ -0,0 +1,24 @@
+# analysis alert-notice-config list
+
+Use when list alert notice configs.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert-notice-config list [options]
+```
+
+Capability id: `analysis.alert_notice_config.list`
+
+Input sends `project_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+

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

@@ -0,0 +1,25 @@
+# analysis alert start
+
+Use when start an alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert start [options]
+```
+
+Capability id: `analysis.alert.start`
+
+Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |
+

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

@@ -0,0 +1,25 @@
+# analysis alert stop
+
+Use when stop an alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert stop [options]
+```
+
+Capability id: `analysis.alert.stop`
+
+Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |
+

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

@@ -0,0 +1,26 @@
+# analysis alert update
+
+Use when update an alert.
+
+Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+
+Command:
+
+```bash
+ae-cli analysis alert update [options]
+```
+
+Capability id: `analysis.alert.update`
+
+Input sends `project_id`, `alert_id`, and `definition`. Do not send camelCase aliases.
+
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--alert-id` | See command help | Yes |
+| `--definition` | See command help | Yes |
+

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

@@ -12,7 +12,8 @@ This policy applies to:
 - `analysis bi-panel-page-data run` / `analysis bi-panel-page-data export`
 - `analysis event-detail run` / `analysis event-detail export`
 - `analysis entity-detail run` / `analysis entity-detail export`
-- `analysis drilldown-users run` / `analysis drilldown-users export`
+- `analysis drilldown-events run` / `analysis drilldown-events export`
+- `analysis drilldown-entities run` / `analysis drilldown-entities export`
 - `analysis drilldown-user-events run` / `analysis drilldown-user-events export`
 - `analysis user-cluster-member list` / `analysis user-cluster-member export`
 - `analysis user-tag-member list` / `analysis user-tag-member export`
@@ -39,7 +40,7 @@ The dashboard report-data sync timeout defaults to 180 seconds because one call
 
 Detail `run` commands (`event-detail run` and `entity-detail run`) return only the first bounded preview rows. They do not support `--offset` or stable pagination. If the response has `truncated=true`, switch to the matching `export` command instead of trying to fetch later pages. For detail run, `truncated=true` can mean the preview hit its row cap even when the backend total is not an exact full count.
 
-User member, history-tag drilldown, and result drilldown `list/run` commands are bounded previews. They do not expose pagination. Use the matching `export` command for full or unknown-size data; Common advances backend batches internally and writes one artifact.
+User member, history-tag drilldown, and result drilldown `list/run` commands are bounded previews. They do not expose pagination. Use the matching `export` command for full or unknown-size data.
 
 Use `export` when any condition is true:
 
@@ -71,26 +72,25 @@ If `analysis run inspect` or `analysis artifact download` returns HTTP 404 for a
 
 If the current host returns `CAPABILITY_NOT_FOUND` for a documented command, treat it as host/backend capability unavailability. Do not retry with different JSON shapes or flags; choose another supported path only when it satisfies the user's request, otherwise report the backend gap.
 
-Detail, drilldown, user-member, and history-tag exports read backend batches until completion. Backend paging is an implementation detail and must not appear as `offset`, `page_num`, or `page_size` in the caller contract. Do not collect full data by repeated `list/run` calls.
+Drilldown event/entity/user-event exports use Common's full-download stream and write `csv.gz` directly; they do not collect synchronous preview pages. They accept no `limit`, `offset`, `page_num`, or `page_size`, and remain bounded by `model_full_download_limit`. Other detail, user-member, and history-tag exports may advance backend batches internally, but paging is never part of the caller contract. Do not collect full data by repeated `list/run` calls.
 
 ## Follow-up context
 
-Analysis data `run` responses, export submit responses, and JSONL export artifact metadata may include `query_context_id` and `sources` when Redis context creation succeeds. Follow-up commands are allowed only when `drilldown_available=true` and the selected source includes `target_contract`; otherwise read `drilldown_unavailable_reason` and do not infer source IDs, dates, groups, or model fields from display text.
+Only synchronous `adhoc run`, `report-data run`, and `dashboard-report-data run` previews create `query_context_id`, `sources`, and selectable `sources[].drilldown` options. Exports and downloaded artifacts never create this context and never expand the selectable result. The sync `--limit` is the drilldown boundary.
 
-For date-based drilldown, copy the stable machine field `drilldown_date`, never parse `display_date`. The machine format follows the query particle: day/week `yyyy-MM-dd`, month/quarter `yyyy-MM`, year `yyyy`, hour/minute `yyyy-MM-dd HH:mm`, and millisecond `yyyy-MM-dd HH:mm:ss.SSS`.
+Follow-up commands are allowed only when the selected source/metric advertises the exact action. Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md), select only returned row/column/metric options, and never infer source IDs, dates, groups, model fields, or analysis angles from display text.
 
 When present, compare `effective_time_range` with `data_time_range`. `effective_time_range` is the resolved query scope, while `data_time_range` is the observed returned-row range. `clipping_reasons=[]` means the gateway applied no silent range cap; a narrower `data_time_range` then reflects available/returned data rather than a gateway range clamp.
 
-Use that `query_context_id` for:
+Use that synchronous `query_context_id` for the advertised action only:
 
-- `analysis drilldown-users run` or `analysis drilldown-users export`
+- `analysis drilldown-events run` or `analysis drilldown-events export`
+- `analysis drilldown-entities run` or `analysis drilldown-entities export`
 - `analysis query create-result-cluster`
 
 Do not reconstruct or pass raw QP for follow-up drilldown or result-cluster creation.
 
-CSV artifacts intentionally contain only CSV data; obtain `query_context_id` and `sources` from the export submit response instead of looking for a metadata line in CSV.
-
-If the response does not include `query_context_id` and does not explicitly expose `drilldown_available=true`, stop before drilldown/result-cluster commands. Report that this result cannot be followed up with context-based drilldown in the current response.
+If the synchronous response does not include `query_context_id`, source options, and the required action, stop before drilldown/result-cluster commands. Report that this preview does not expose that follow-up.
 
 For sync `run`, ae-cli may add `_cli_inline_limit` and `_cli_truncation` metadata when it has to truncate returned `rows` arrays locally to enforce the requested inline limit. Use `export` for full data.
 
@@ -98,4 +98,4 @@ For sync `run`, ae-cli may add `_cli_inline_limit` and `_cli_truncation` metadat
 
 For `analysis bi-panel-page-data`, `--row-limit`, `--row-offset`, `--block-limit`, and `--block-offset` are BI page/chart/summary window controls. They are not the generic sync-vs-async routing policy and do not change the rule above: use `run` for bounded inline results, and `export` for full, unknown-size, larger than 1000-row, or long-running data retrieval.
 
-BI page `charts` results may return `query_context_id` for SQL chart-source traceability. Treat it as drilldown-capable only when `drilldown_available=true`; BI SQL chart contexts normally return `drilldown_available=false` and `result_cluster_available=false`.
+BI SQL page/chart data does not support this analysis drilldown contract.

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

@@ -0,0 +1,93 @@
+# analysis drilldown contract
+
+This contract controls every follow-up from an analysis result. Read it before composing `drilldown-events`, `drilldown-entities`, or `query create-result-cluster`.
+
+## Hard boundary
+
+Only a synchronous `adhoc run`, `report-data run`, or `dashboard-report-data run` preview can create `query_context_id` and selectable drilldown coordinates. The selectable population is exactly the returned preview, after its `--limit` is applied. If `--limit 10` returns ten rows, only coordinates represented by those ten rows may be selected.
+
+Exports never create a query context. A downloaded file, export submit response, or export artifact must never be used to invent or extend drilldown coordinates. To drill into a large result, first run a bounded synchronous preview containing the desired row; do not raise the limit merely to manufacture a complete target catalog.
+
+SQL, `heat_map`, `rank_list`, `revenue`, and scenario models do not support this analysis drilldown contract. Stop when `source.drilldown.actions` is empty or `unavailable_reason` is present.
+
+## Select a cell without `target_id`
+
+The response contains `sources[]`. Select the source that owns the visible result. When more than one source exists, pass the source selector returned there, normally `{"report_id":...}` or `{"chart_id":...}`. Never put source IDs inside `coordinate`.
+
+Each source has `drilldown`:
+
+- `selection_boundary` must be `synchronous_preview_only`.
+- `row_options[]` contains only rows from this preview. Match the user's row by `values`, then copy that option's `coordinate` fragment.
+- `column_options[]` contains only drillable result columns. Match the requested visible column by `label`/`column_index`, then copy its `coordinate` fragment.
+- `metric_options[]` describes the analysis angle and allowed `actions`. For event analysis, select the metric by `metric_index`; different metrics in one result may allow different actions.
+- `coordinate_fields` is the allowlist for the final coordinate.
+
+Build one coordinate by shallow-merging the selected row, column, and metric coordinate fragments. Identical keys must have identical values. Use the returned snake_case keys and values exactly. Do not send `row_index`, `column_index`, `values`, `label`, `target_id`, display-only dates, raw QP, or any inferred value.
+
+An event-analysis phase-summary row is metric-dependent. The same visible row may therefore appear more than once in `row_options`, with a different `metric_index` in each coordinate fragment. Select the option whose `metric_index` matches the chosen metric column; never remove or replace that field. The backend advertises only these valid combinations:
+
+| Phase calculation | Drillable metric angle |
+|---|---|
+| `sum` (`PERIOD_TOTAL`) | `EVENT_LIST` only |
+| `dist` (`PERIOD_DISTINCT`) | `EVENT_LIST`, `USER_LIST`, or `ENTITY_LIST` |
+| averages, integer averages, min/max, weighted averages, and every `intact_*` calculation | none |
+
+This distinction is mathematical: event counts are additive across date buckets, while bucket-level distinct subject counts are not. A `dist` value is recomputed for the complete phase and can therefore identify one event/entity population. `intact_*` values exclude incomplete periods, but the current total drilldown query does not carry that reduced time range.
+
+`time_granularity=T5` is not a phase-summary calculation. Its single returned row is the native full-range metric and remains selectable when the metric advertises `EVENT_LIST`, `USER_LIST`, or `ENTITY_LIST`.
+
+Example:
+
+```json
+{
+  "source": {"report_id": 1001},
+  "coordinate": {
+    "group_values": ["Beijing"],
+    "date": "2026-07-16",
+    "metric_index": 1
+  }
+}
+```
+
+This represents one visible cell: the returned Beijing/date row plus metric column 1. It is not a server-generated ID for every possible cell.
+
+## Choose the action from the analysis angle
+
+Never infer an action from the model name or the numeric cell value. Use the selected `metric_options[].actions` for event analysis and `source.drilldown.actions` for other supported models.
+
+| `analysis_angle` | Allowed next action |
+|---|---|
+| `EVENT_LIST` | `analysis drilldown-events run|export` only |
+| `USER_LIST` | `analysis drilldown-entities run|export`; `analysis query create-result-cluster` |
+| `ENTITY_LIST` | The same entity commands; `subject` identifies the analysis entity, which may be a custom entity rather than a user |
+| `NONE` | No drilldown or result-cluster action |
+
+`USER_LIST` is one special case of entity drilldown. A custom `ENTITY_LIST` result must be returned and saved as that entity type, not silently converted to users.
+
+## Model coordinate meanings
+
+Use only fragments actually returned in options; the table explains their business meaning and must not be used to synthesize missing choices.
+
+| Model | Coordinate fields and special values |
+|---|---|
+| `event` | `group_values`, optional machine `date`, `metric_index`, optional `compare_index`, optional `scope=total`. Phase-summary row options already contain the only allowed `metric_index`; T5 total rows use `scope=total` without phase restrictions. The main time range omits `compare_index`; comparison block 1 uses `compare_index=0`. The chosen metric's `analysis_angle` decides events versus entities. |
+| `retention` | `group_values`, machine `cohort_date`, `period_index`, `population=retained|lost`, optional `relation`. Only returned cohort rows and population-count period columns are selectable; average/rate/simultaneous-metric rows are not coordinates. |
+| `funnel` | `group_values`, optional `date`, one-based `step`, `population=completed|churned`. Only returned step-population columns are selectable; conversion-rate columns are not. |
+| `distribution` | `group_values`, machine `date`, optional raw `bucket`, `scope=total|bucket`. Bucket values are backend interval values returned by the contract, not localized column labels. Percentage and comparison rows are not selectable populations. |
+| `interval` | `group_values`, optional machine `date`; the aggregate entity-count column returns `scope=total`. A raw `interval_bucket` is valid only when a returned column option explicitly contains it. Never infer a bucket from a displayed duration; descriptive interval statistics are not selectable populations. |
+| `prop_analysis` | `group_values`, `population_index`. With configured user/entity populations, the row chooses `population_index`; otherwise it is `0`. |
+| `path` | `session_level`, `current_nodes`, optional `next_nodes`, `relation=total|with_next|without_next|with_next_specific`, `current_is_more`, `next_is_more`. Copy the returned node objects; event names and group values are machine values. |
+| `attribution` | `attribution_event_id`, `source_group_values`, `target_group_values`. The event ID is returned machine metadata for that row; never derive it from the displayed event name. |
+
+## Entity result and user-event continuation
+
+`analysis drilldown-entities run` returns `subject` and normalized `items[]`.
+
+- For `subject.type=user`, each item contains canonical `user_id`. The response may also return `drilldown_context_id` and a user-event follow-up action. Only then may the Agent call `analysis drilldown-user-events run|export` with that exact context and returned `user_id`.
+- For `subject.type=entity`, items contain `entity_value` and attributes. Custom entities do not have user event sequences, so no user-event context or follow-up is valid.
+- `subject.column_name` is the authoritative machine identity column used to normalize `entity_value`; never substitute `#user_id` for a custom entity.
+- `analysis query create-result-cluster` saves the selected subject as the corresponding entity's result cluster.
+
+The entity export is for complete member data only. It does not create a new context for another drilldown step.
+
+All three drilldown exports are full-download streams, not paging APIs. They accept no limit/offset/page controls and produce `csv.gz`; the platform `model_full_download_limit` remains the safety ceiling. Export artifacts never add selectable coordinates or user-event continuation identities.

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

@@ -67,17 +67,18 @@ Artifact workflow:
 4. Download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>`.
 5. Cancel long or abandoned exports with `ae-cli analysis query cancel --run-id <run_id>`.
 
-Prefer the run/artifact commands over hand-written HTTP, Python, or curl. For analysis data exports, the descriptor and first artifact metadata line may also contain `query_context_id` when Redis context creation succeeds.
+Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analysis exports never create interactive `query_context_id`; drilldown coordinates exist only in bounded synchronous previews.
 
 ## Command matrix
 
 | Command | Capability ID | Use for | Key input | Output |
 | --- | --- | --- | --- | --- |
 | `adhoc run` | `analysis.adhoc.run` | Unified ad-hoc inline query for 12 AI models: 9 common + 3 scenario models | `--project-id`, `--model-type`, AI-facing `--definition` | Inline data plus optional `query_context_id` |
-| `adhoc export` | `analysis.adhoc.export` | Unified ad-hoc async export for 12 AI models: 9 common + 3 scenario models | same as run, plus optional `--artifact-format`; no inline `--limit` | Async artifact descriptor; artifact metadata may include `query_context_id` |
-| `query drilldown-users` | `analysis.query.drilldown_users` | Drill down to users from an analysis data query context | `--query-context-id`, `--target` | User rows plus `drilldown_context_id` |
+| `adhoc export` | `analysis.adhoc.export` | Unified ad-hoc async export for 12 AI models: 9 common + 3 scenario models | same as run, plus optional `--artifact-format`; no inline `--limit` | Async artifact descriptor; no drilldown context |
+| `drilldown-events run/export` | `analysis.query.drilldown_events` / `analysis.query.drilldown_events_export` | Preview or full-stream events for an advertised `EVENT_LIST` cell | `--query-context-id`, optional `--source`, `--coordinate` | Bounded event rows or `csv.gz` artifact |
+| `drilldown-entities run/export` | `analysis.query.drilldown_entities` / `analysis.query.drilldown_entities_export` | Preview/export users or custom entities for an advertised entity cell | `--query-context-id`, optional `--source`, `--coordinate` | Subject plus entity rows/artifact |
 | `query drilldown-user-events` | `analysis.query.drilldown_user_events` | Query one drilldown user's event sequence | `--drilldown-context-id`, `--user-id` | Event sequence rows |
-| `query create-result-cluster` | `analysis.query.create_result_cluster` | Save users matched by an analysis result target as a result cluster | `--query-context-id`, `--target`, `--cluster-name` | Result cluster creation result |
+| `query create-result-cluster` | `analysis.query.create_result_cluster` | Save the advertised user/custom-entity cell population as its result cluster | `--query-context-id`, optional `--source`, `--coordinate`, `--cluster-name` | Result cluster creation result |
 | `report list` | `analysis.report.list` | Find accessible reports | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated report summaries |
 | `report list-export` | `analysis.report.list_export` | Export report catalog | same as list, plus optional `--artifact-format`, `--request-id` | Async artifact descriptor |
 | `report get` | `analysis.report.get` | Inspect current report definition as AI QP | `--project-id`, `--report-id` | Report metadata plus `model_type` and `definition` |
@@ -85,7 +86,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. For an
 | `report update` | `analysis.report.update` | Update metadata or AI QP definition | `--report-id`, `--report-version`, update fields | Update result |
 | `report delete` | `analysis.report.delete` | Delete reports | `--report-ids '[...]'` | Delete result |
 | `report-data run` | `analysis.report_data.run` | Bounded inline report data | `--report-ids`, optional AI-facing `--filters`, `--group-by`, SQL dynamic parameter value-only `--sql-params`, time/limit | Inline data plus optional `query_context_id` |
-| `report-data export` | `analysis.report_data.export` | Large/long report data | same as run, plus optional `--artifact-format` | Async artifact descriptor; artifact metadata may include `query_context_id` |
+| `report-data export` | `analysis.report_data.export` | Large/long report data | same as run, plus optional `--artifact-format` | Async artifact descriptor; no drilldown context |
 | `query cancel` | `analysis.query.cancel` | Cancel any async analysis export | `--run-id`, optional `--reason` | Cancellation result |
 | `report-change-log list` | `analysis.report_change_log.list` | List one report's change logs | `--report-id` | Change log summaries |
 | `report-change-log get` | `analysis.report_change_log.get` | Inspect one change log detail | `--report-id`, optional `--history-version` | Change log detail with AI QP definition when available |
@@ -105,7 +106,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. For an
 | `dashboard abnormal-get` | `analysis.dashboard.abnormal_get` | Inspect abnormal dependencies | `--dashboard-id` | Abnormal info |
 | `dashboard task-status` | `analysis.dashboard.task_status` | Inspect scheduled task status | `--dashboard-id` | Task status |
 | `dashboard-report-data run` | `analysis.dashboard_report_data.run` | Bounded inline dashboard report data; `--filters` is analysis Filter JSON from `+get_filter_schema` | `--dashboard-id`, optional `--report-ids`, `--filters`, `--start-time`, `--end-time`, `--limit` | Inline data plus optional `query_context_id` |
-| `dashboard-report-data export` | `analysis.dashboard_report_data.export` | Large/long dashboard report data | same as run, plus optional `--artifact-format jsonl` | Async artifact descriptor; artifact metadata may include `query_context_id` |
+| `dashboard-report-data export` | `analysis.dashboard_report_data.export` | Large/long dashboard report data | same as run, plus optional `--artifact-format jsonl` | Async artifact descriptor; no drilldown context |
 | `run inspect` | `analysis.run.inspect` | Poll async export status | `--run-id` | Run and artifact status |
 | `artifact download` | `analysis.artifact.download` | Download run-bound export artifact | `--run-id`, `--artifact-id`, `--output` | Local output file info |
 | `query cancel` | `analysis.query.cancel` | Cancel gateway run/export | `--run-id`, optional `--reason` | Cancellation result |
@@ -212,8 +213,8 @@ ae-cli analysis adhoc export --project-id 1 --model-type sql --definition '{"sql
 ae-cli analysis report list --project-id 1 --query revenue --limit 50
 ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --limit 50
 ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --group-by '[{"field":{"name":"country","type":"user_property"}}]' --sql-params '[{"name":"platform","value":"ios"}]' --limit 50
-ae-cli analysis query drilldown-users --query-context-id ctx_0123456789abcdef0123456789abcdef --target '{"report_id":1001,"drilldown_date":"2026-07-01"}'
-ae-cli analysis query create-result-cluster --query-context-id ctx_0123456789abcdef0123456789abcdef --target '{"report_id":1001,"drilldown_date":"2026-07-01"}' --cluster-name retained_users
+ae-cli analysis drilldown-entities run --query-context-id ctx_0123456789abcdef0123456789abcdef --source '{"report_id":1001}' --coordinate '{"cohort_date":"2026-07-01","group_values":[],"period_index":1,"population":"retained"}'
+ae-cli analysis query create-result-cluster --query-context-id ctx_0123456789abcdef0123456789abcdef --source '{"report_id":1001}' --coordinate '{"cohort_date":"2026-07-01","group_values":[],"period_index":1,"population":"retained"}' --cluster-name retained_users
 ae-cli analysis dashboard update --project-id 1 --operation note-upsert --dashboard-id 1001 --note-title "Summary" --description "Weekly note"
 ae-cli analysis dashboard-definition export --project-id 1 --dashboard-id 1001 --export-file-name retention_dashboard
 ae-cli analysis dashboard-definition import --project-id 1 --definition '{"dashboard_folders":[],"shared_spaces":[]}' --validate-only true

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

@@ -1,13 +1,14 @@
 # analysis-meta asset url-get
 
-Use when the user needs to get or normalize an asset governance resource link payload through the capability gateway.
+Use when the user needs to get a clickable resource link through the capability gateway, including post-write resource link completion.
 
-Do not use it to discover assets or query asset data; resolve a real asset first, then use this command only to turn its governance identity into a link.
+Do not use it to discover assets or query asset data; resolve a real asset first, then use this command only to turn its governance identity or resource ID into a link.
 
 Command:
 
 ```bash
 ae-cli analysis-meta asset url-get --project-id <project_id> --payload '{}'
+ae-cli analysis-meta asset url-get --project-id <project_id> --resource-type dashboard --resource-id 1
 ae-cli analysis-meta asset url-get --dry-run --project-id <project_id>
 ```
 
@@ -15,7 +16,7 @@ Capability id: analysis_meta.asset_url.get.
 
 Input sends project_id, payload, node_id, resource_id, resource_type, link_info. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
 
-Output `data` identifies the normalized asset and returns `raw_url` plus `markdown_link` when the resource type supports a link; `status=ok` without a URL means no URL mapping was available.
+Output `data` identifies the normalized asset and returns `raw_url` plus `markdown_link` when the resource type supports a link. ae-cli rewrites relative URL/link fields into absolute URLs using the current host. `status=ok` without a URL means no URL mapping was available.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -1,8 +1,8 @@
 # analysis bi-panel create
 
-Use when the user explicitly wants to create a BI panel.
+Use when the user explicitly wants to create the product's BI dashboard (`仪表盘`), including requests phrased as `BI 仪表盘`.
 
-Do not use to copy an existing BI panel. Use `bi-panel copy`.
+Do not use for an analysis board (`看板`); use `analysis dashboard create` instead. Do not use to copy an existing BI dashboard; use `bi-panel copy`.
 
 Command:
 
@@ -12,4 +12,4 @@ ae-cli analysis bi-panel create --project-id <project_id> [--panel-name <name>]
 
 Input sends `project_id` plus optional BI panel identifiers, target IDs, and `payload`.
 
-Output is the gateway envelope. `data` contains the created BI panel result.
+Output is the gateway envelope. `data` contains the created BI-dashboard result.

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

@@ -14,9 +14,9 @@ ae-cli analysis bi-panel-page-data export --project-id <project_id> --panel-id <
 
 Input sends `project_id`, `panel_id`, `page_key`, `result_type`, and optional control, paging, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. `--row-limit` and related BI page controls are chart/summary window controls, not the generic async artifact row policy; see [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
-Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, expiration fields, and possibly `query_context_id`. It does not expose inspect/download API paths; use the CLI commands below.
+Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. It does not create `query_context_id` or expose inspect/download API paths; use the CLI commands below.
 
-When `result_type=charts` and the backend can resolve chart SQL sources, the export descriptor and first artifact metadata line may include `query_context_id` plus `sources`. BI chart sources are SQL contexts, so `drilldown_available` and `result_cluster_available` are false unless the response explicitly says otherwise. Do not call model drilldown commands from a BI SQL context with `drilldown_available=false`.
+BI chart sources are SQL and do not support analysis drilldown or result-cluster creation. Exported rows are not interactive coordinates.
 
 Follow-up workflow:
 

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

@@ -16,4 +16,4 @@ Input sends `project_id`, `panel_id`, `page_key`, `result_type`, and optional co
 
 Output is the gateway envelope. `data` contains bounded inline page data.
 
-When `result_type=charts` and the backend can resolve chart SQL sources, the response may include `query_context_id` plus `sources`. BI chart sources are SQL contexts, so `drilldown_available` and `result_cluster_available` are false unless the response explicitly says otherwise. Do not call model drilldown commands from a BI SQL context with `drilldown_available=false`.
+BI page/chart sources are SQL and do not support analysis drilldown or result-cluster creation. Do not call model drilldown commands from this result.