@thinkingai/ae-cli 6.0.31 → 6.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.31",
+  "version": "6.0.32",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {

package/skills/ae-analysis/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-analysis
-version: 4.0.2
-description: "Use ae-cli for AE/TE analysis-side data questions and asset operations: reports, dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update analysis assets."
+version: 4.0.3
+description: "Use ae-cli for AE/TE analysis-side data questions, asset operations, and asset governance: reports, dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update/govern analysis assets."
 ---
 
 # ae-analysis
@@ -12,7 +12,7 @@ This is the single entry skill for analysis intent and command execution.
 
 1. If the command family is already known, open its dedicated reference directly. Otherwise search only the matching row in [`references/command_index.md`](references/command_index.md) (for example with `rg`); do not read the exhaustive index end to end.
 2. Read the selected command's dedicated reference before composing it:
-   - `+list_events` -> `references/list_events.md`
+   - `event list` -> `references/event_list.md`
    - `analysis dashboard list` -> `references/dashboard_list.md`
    - replace hyphens with underscores in gateway filenames.
 3. For an AI-facing ad-hoc definition, also read [`references/ai_models.md`](references/ai_models.md).
@@ -27,8 +27,9 @@ Use this skill for these CLI services:
 
 - `analysis`: reports, dashboards, BI panels, ad-hoc analysis, drilldown, detail data, alerts, clusters, tags, and async runs/artifacts.
 - `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata.
+- `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
 - `analysis_meta`: metadata governance, metrics, virtual metadata, project config, tracking plans, mark times, and entity catalog.
-- `analysis_common`: project discovery and resource links.
+- `analysis_common`: project discovery.
 
 For metadata gateway detail outside the commands in the generated index, use the metadata skill. For Engage, DataOps, or Community work, use the corresponding skill.
 
@@ -46,6 +47,7 @@ ae-cli analysis_meta +<command> [options]
 ae-cli analysis_common +<command> [options]
 ae-cli analysis <resource> <action> [options]
 ae-cli analysis-meta <resource> <action> [options]
+ae-cli analysis-governance <resource> <action> [options]
 ae-cli capability search|inspect|validate|dry-run|run [options]
 ```
 
@@ -110,7 +112,7 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 - Metric value, trend, comparison, or anomaly -> saved report/dashboard first, then ad-hoc data.
 - Metric definition search/create/update -> metadata commands.
 - Event/entity rows -> `event-detail run|export` or `entity-detail run|export`.
-- User members from a query result -> follow the returned `query_context_id` and `sources[].target_contract`; never reconstruct raw QP.
+- Events/entities from a query result -> follow the returned synchronous `query_context_id` and `sources[].drilldown`; never reconstruct raw QP or use export rows as coordinates.
 - Cluster/tag definition -> matching gateway cluster/tag commands and matching model reference.
 - Alert/configuration/tracking-plan requests -> dedicated legacy command reference from the index.
 
@@ -118,8 +120,9 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 
 - `run` is a bounded inline preview for known-small work that can complete within the synchronous limits.
 - `export` is for complete, unknown-size, over-limit, or long-running results. It returns `run_id` and `artifact_id`.
+- Drilldown event/entity/user-event exports are `csv.gz` full-download streams bounded by `model_full_download_limit`; never pass or simulate `limit`, `offset`, `page_num`, or `page_size`.
 - Inspect with `analysis run inspect`, download with `analysis artifact download`, and cancel with `analysis query cancel`. Do not call raw lifecycle URLs.
-- Drilldown requires the context IDs and target contracts returned by a supported data result. If they are absent, report that drilldown/result-cluster creation is unavailable.
+- Drilldown requires a synchronous preview context and the selected source's returned row/column/metric coordinate options. If they are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
 
 ### Writes and destructive operations
 
@@ -127,7 +130,7 @@ Write only with explicit user intent. Use `--validate` alone while correcting co
 
 Project-space and folder create/delete/share are L3 capabilities rather than curated `analysis` commands. Read the matching command reference, then use `ae-cli capability inspect|dry-run|run`; discover `*.members` through `capability search|inspect|run` and [`references/analysis_gateway_assets.md`](references/analysis_gateway_assets.md). For `risk=high-risk-write`, dry-run first, summarize the impact, and execute with `--yes` only after a later explicit confirmation.
 
-After a successful create/update, if a resource ID and supported resource type are available, call `analysis_common +get_resource_url` and return the link. Explicitly state when link generation is skipped because no resource ID exists or when it fails.
+After a successful create/update, if a resource ID and supported resource type are available, call `analysis-meta asset url-get` and return the link. Explicitly state when link generation is skipped because no resource ID exists or when it fails.
 
 ## Analysis workflow
 

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

@@ -23,7 +23,7 @@ ae-cli analysis adhoc export \
 
 Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
 
-For SQL model definitions, do not invent table or column names. If the table is unknown, call `analysis sql-table list --project-id <project_id>`; then inspect the selected `table_ref` with `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL.
+For SQL model definitions, do not invent table or column names. If the table reference is known, inspect columns with `analysis-meta datatable columns-get`; if the table is unknown, ask for it instead of guessing.
 
 ## Definition contract
 
@@ -49,12 +49,9 @@ The response is an async artifact descriptor:
 - `run_id`: poll or cancel this run.
 - `artifact_id`: download this artifact after completion.
 - `status` / `artifact_status`: initial lifecycle states.
-- `format`: actual logical artifact format (`jsonl` or `csv`).
-- `compression` / `content_encoding`: actual compression/encoding; analysis ad-hoc exports currently return `gzip`.
-- `file_name` / `content_type`: actual downloadable file contract. Do not infer compression from `--artifact-format` alone.
 - `expires_at` / `expires_at_iso`: artifact expiration.
 - `effective_timeout_seconds`, `timeout_source`, `deadline_at`: effective lifecycle policy.
-- `query_context_id` / `query_context_expires_at`: reusable follow-up context when Redis context creation succeeds.
+- Export descriptors contain lifecycle/artifact metadata only. They do not create `query_context_id` or selectable drilldown options.
 
 Preserve the `run_id` and `artifact_id` from this exact submit response as one pair. Do not infer either ID from a path or reuse an ID from another export.
 
@@ -68,4 +65,4 @@ ae-cli analysis query cancel --run-id <run_id>
 
 If query execution fails, `run inspect` reaches `FAILED`; it must not produce a completed empty artifact. Download only after the successful terminal states documented in `analysis_data_retrieval.md`.
 
-Use the submit response `query_context_id` immediately with `analysis drilldown-users run` or `analysis query create-result-cluster` when present. JSONL artifacts repeat query context plus `format`, `compression`, `content_type`, and `content_encoding` in the first metadata line. Source metadata includes `effective_time_range`, `time_range_adjustments`, and `clipping_reasons`. Date rows expose stable `drilldown_date` and separate `display_date`; copy only `drilldown_date` into a drilldown target. CSV remains pure CSV and carries context/format metadata only in the submit and run-inspect descriptors. Do not pass raw QP.
+Exported rows are durable data, not interactive preview coordinates. Never drill down or create a result cluster from the submit response or downloaded artifact. Run a bounded synchronous preview containing the desired cell first.

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

@@ -25,7 +25,7 @@ ae-cli analysis adhoc run \
 
 Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
 
-For SQL model definitions, do not invent table or column names. If the table is unknown, call `analysis sql-table list --project-id <project_id>`; then inspect the selected `table_ref` with `analysis sql-table columns --project-id <project_id> --table-ref <table_ref>` before writing SQL.
+For SQL model definitions, do not invent table or column names. If the table reference is known, inspect columns with `analysis-meta datatable columns-get`; if the table is unknown, ask for it instead of guessing.
 
 ## Input
 
@@ -33,7 +33,7 @@ For SQL model definitions, do not invent table or column names. If the table is
 - `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
 - `--definition`: model-specific AI-facing definition JSON.
 
-Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 60 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
 If the user asks for more than 1000 rows, or the SQL text requests `LIMIT 2000` (or any limit above 1000), go directly to `analysis adhoc export`. Do not lower the SQL limit to 1000, run a truncated sync query first, or loop over repeated `run` calls.
 
@@ -43,16 +43,12 @@ Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP buil
 
 The response may include:
 
-- `query_context_id`: Redis-backed context for drilldown or result-cluster creation.
-- `drilldown_available`: whether the response contains a complete machine-readable follow-up target. When false, read `drilldown_unavailable_reason` and do not infer a target from display text.
-- `sources[].target_contract.default_target`: a complete target that can be passed directly to a follow-up command. Copy and replace only fields named by `copy_from_selected_result` when drilling into a different row or cell.
+- `query_context_id`: Redis-backed context for follow-ups from this bounded synchronous preview.
+- `sources[].drilldown`: finite row, column, and metric options plus allowed actions. The preview `limit` is the selection boundary.
 - `title` / `rows` / `total` / `returned_rows` / `truncated`: tabular preview fields. When truncated, use `adhoc export`; there is no next-page request.
 - `result`: direct result for non-tabular models.
 - `request_id`: lifecycle request id.
-- `effective_time_range`: the resolved query scope actually sent to execution. `clipping_reasons` is empty when the gateway applied no range cap.
-- `data_time_range`: the minimum/maximum machine dates present in returned rows when available. Compare it with `effective_time_range` to distinguish query-range clipping from missing data.
-- `row_metadata`: row-aligned machine fields. For date-drilldown rows, copy `drilldown_date`; `display_date` is presentation text only.
 
 Execution failures are returned as command failures with `request_id`; only the explicit project-no-data condition is a successful empty result. Do not interpret an empty object as evidence that a failed query succeeded.
 
-Use `query_context_id` with `analysis drilldown-users run` or `analysis query create-result-cluster` only when `drilldown_available=true` and the selected source includes `target_contract.default_target`. Do not pass raw QP or infer a target from display text.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source/metric, and assemble the coordinate only from returned option fragments. Do not pass raw QP or infer a coordinate from display text.

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/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_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.