@thinkingai/ae-cli 6.0.30 → 6.0.32

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

@@ -0,0 +1,101 @@
+# analysis data retrieval routing
+
+This is the single routing policy for analysis data retrieval commands. It is scoped to `ae-cli analysis` data queries only; do not generalize it to other `te-cli` business modules.
+
+## Scope
+
+This policy applies to:
+
+- `analysis adhoc run` / `analysis adhoc export`
+- `analysis report-data run` / `analysis report-data export`
+- `analysis dashboard-report-data run` / `analysis dashboard-report-data export`
+- `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-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`
+- `analysis history-tag-data run` / `analysis history-tag-data export`
+- `analysis history-tag-data-drilldown run` / `analysis history-tag-data-drilldown export`
+
+This policy does not apply to:
+
+- `analysis user-cluster list/get`, `analysis user-tag list/get`, create/update/refresh/delete, ID-file operations, and history-tag management commands.
+- `analysis_meta`, metadata, DataOps, Community, Engage, or other business modules.
+- Report/dashboard/BI asset list commands, catalog exports, definition import/export, or management commands.
+
+## Decision rule
+
+Use `run` only when all conditions are true:
+
+- The user needs an inline preview or immediate JSON result.
+- The expected result fits in `<=1000` rows.
+- The query is expected to finish within the sync timeout window, normally `<=180` seconds.
+
+`run` defaults to `--limit 100`. If the user needs 101 to 1000 rows inline, pass an explicit `--limit <n>` where `n <= 1000`.
+
+The dashboard report-data sync timeout defaults to 180 seconds because one call may execute multiple reports. Other sync analysis data retrieval commands default to 120 seconds. The maximum remains 180 seconds, and an explicitly supplied lower timeout always wins.
+
+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.
+
+Use `export` when any condition is true:
+
+- The user asks for full data, all rows, a downloadable file, or an export.
+- The result size is unknown or expected to exceed 1000 rows.
+- The query may be long-running or may exceed the sync timeout window.
+- The result should be durable and processed from a file instead of printed inline.
+
+Export commands are asynchronous artifact jobs. They do not use the inline `--limit` policy. After submitting an export, use:
+
+`--artifact-format` selects the logical row format, not compression. Read the returned `format`, `compression`, `file_name`, `content_type`, and `content_encoding`; analysis query exports are currently gzip-compressed even when the logical format is `jsonl` or `csv`.
+
+Default and maximum runtime is 21600 seconds (6 hours). Omit `--timeout-seconds` to use that default, or pass a smaller value when the caller explicitly wants an earlier deadline.
+
+```bash
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>
+```
+
+Download only after `analysis run inspect` reports `status=SUCCEEDED` and `artifact_status=COMPLETED`. If download returns `ARTIFACT_NOT_READY`, inspect again later; do not keep retrying download while the run is still `RUNNING`.
+
+Cancel an async run/export with:
+
+```bash
+ae-cli analysis query cancel --run-id <run_id>
+```
+
+If `analysis run inspect` or `analysis artifact download` returns HTTP 404 for a valid `run_id` / `artifact_id` from the same export response, treat it as a backend route/capability deployment issue. Do not keep polling or invent download URLs.
+
+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.
+
+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
+
+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.
+
+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 synchronous `query_context_id` for the advertised action only:
+
+- `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.
+
+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.
+
+## BI page data note
+
+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 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

@@ -1,4 +1,4 @@
-# analysis capability-gateway asset commands
+# analysis capability-gateway commands
 
 > Prerequisite: follow [`../SKILL.md`](../SKILL.md), especially `PROJECT_ID_GATE`.
 
@@ -12,14 +12,17 @@ Flags use kebab-case. The gateway input JSON uses snake_case. Do not pass camelC
 
 This file is an overview only. Before running an L2 command, read the dedicated command reference named `references/<resource>_<action>.md` with hyphens converted to underscores, for example `dashboard_report_data_export.md`. L3 capabilities without a dedicated reference use dynamic discovery per [`ae-capability`](../../ae-capability/SKILL.md) and the L3 section below.
 
+For analysis data retrieval commands, read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing `run` or `export`. That routing policy applies only to analysis data retrieval and must not be generalized to other `te-cli` business modules.
+
 ## When to use
 
-Use these commands for dashboard, BI panel, BI panel version, project-space, folder, favorite, public-link, dashboard-definition, dashboard-daily-report, and dashboard/BI page data workflows.
+Use these commands for ad-hoc model analysis, report definition/data/management, dashboard, BI panel and panel versions, project-space, folder, favorite, public-link, dashboard-definition, dashboard-daily-report, dashboard/BI page data, metadata governance, and user cluster/tag/history-tag workflows.
 
-Prefer export commands for long-running or large data:
+When the routing policy chooses async artifact retrieval, use export commands:
 
 ```bash
 ae-cli analysis dashboard-report-data export --project-id 1 --dashboard-id 1001
+ae-cli analysis report-data export --project-id 1 --report-ids '[1001]'
 ae-cli analysis run inspect --run-id run_0123456789abcdef0123456789abcdef
 ae-cli analysis artifact download --run-id run_0123456789abcdef0123456789abcdef --artifact-id artifact_0123456789abcdef0123456789abcdef --output /tmp/dashboard.jsonl.gz
 ae-cli analysis bi-panel-page-data export --project-id 1 --panel-id 2001 --page-key main --result-type charts
@@ -28,7 +31,7 @@ ae-cli analysis query cancel --run-id run_0123456789abcdef0123456789abcdef
 
 ## When not to use
 
-Do not use these commands for ad-hoc model analysis, report definition, report data, drilldown, schema helpers, alerts, audience clusters/tags, project lookup, metadata governance, dashboard locks, BI panel lock, dashboard filters, UI reorder/tree/move operations, daily report retry/download/get-config, or public-link logs/source-list/get. Use the existing `+<tool_name>` references for those.
+Do not use these commands for schema helpers, alerts, project lookup, dashboard locks, BI panel locks, dashboard filters, UI reorder/tree/move operations, daily report retry/download/get-config, or public-link logs/source-list/get. Use the existing `+<tool_name>` references for those.
 
 ## Output
 
@@ -64,12 +67,32 @@ 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. The descriptor paths are informational and may be internal `/api/cli/v1/...` paths behind a domain-routed CLI host.
+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; 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 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` |
+| `report create` | `analysis.report.create` | Create a report from AI QP definition | `--report-name`, `--model-type`, `--definition` | Created report ID and normalized definition |
+| `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; 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 |
+| `report-version rollback` | `analysis.report_version.rollback` | Rollback a report version | `--report-id`, `--target-version` | Rollback result |
+| `report-abnormal get` | `analysis.report_abnormal.get` | Inspect report abnormal dependencies | `--report-id` | Abnormal info |
+| `dashboard-report add` | `analysis.dashboard_report.add` | Add reports to a dashboard | `--dashboard-id`, `--report-ids` | Add result |
 | `dashboard list` | `analysis.dashboard.list` | Find accessible dashboards | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated dashboard summaries |
 | `dashboard create` | `analysis.dashboard.create` | Create a dashboard | `--project-id`, `--dashboard-name`, optional `--space-id`, `--folder-id` | Created dashboard |
 | `dashboard get` | `analysis.dashboard.get` | Inspect one dashboard definition/share/report structure, including creator and creation/update time | `--project-id`, `--dashboard-id` | Dashboard detail |
@@ -82,8 +105,8 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. The de
 | `dashboard freeze` | `analysis.dashboard.freeze` | Freeze/unfreeze dashboards | `--dashboard-ids`, optional `--freeze false` | Freeze status |
 | `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 |
-| `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 |
+| `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; 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 |
@@ -111,12 +134,40 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. The de
 | `public-link update` | `analysis.public_link.update` | Edit public link | `--link-id`, `--effective-at`, `--expires-at` | Update result |
 | `public-link offline` | `analysis.public_link.offline` | Take links offline | `--link-id` or `--link-ids` | Offline result |
 | `public-link delete` | `analysis.public_link.delete` | Delete public links | `--link-id` or `--link-ids` | Delete result |
+| `user-cluster list` | `analysis.user_cluster.list` | Find accessible user clusters | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated cluster summaries |
+| `user-cluster get` | `analysis.user_cluster.get` | Inspect exact clusters | `--cluster-names '[...]'` | Cluster details |
+| `user-cluster-member list` | `analysis.user_cluster_member.list` | Bounded inline cluster members | `--cluster-name`, optional properties/fields/query/limit/offset | Member rows |
+| `user-cluster-member export` | `analysis.user_cluster_member.export` | Export cluster members as jsonl | `--cluster-name`, optional properties/fields/query | Async artifact descriptor |
+| `user-cluster create` | `analysis.user_cluster.create` | Create condition/sql cluster directly from semantic intent | `--cluster-name`, `--display-name`, `--definition-request` | Create result and canonical request |
+| `user-cluster update` | `analysis.user_cluster.update` | Update condition/sql cluster | `--cluster-name`, fields to change, optional `--definition-request` | Update result |
+| `user-cluster create-id` | `analysis.user_cluster.create_id` | Map imported values to an entity and create a cluster | `--display-name`, `--entity-id`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
+| `user-cluster update-id` | `analysis.user_cluster.update_id` | Remap imported values for an ID cluster | `--cluster-name`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
+| `user-cluster refresh` | `analysis.user_cluster.refresh` | Trigger cluster recompute | `--cluster-name` | Refresh result |
+| `user-cluster delete` | `analysis.user_cluster.delete` | Delete cluster after dependency review | `--cluster-name`, `--confirmed`, `--yes` | Delete result |
+| `user-tag list` | `analysis.user_tag.list` | Find accessible user tags | `--project-id`, optional `--query`, `--fields`, `--limit`, `--offset` | Paginated tag summaries |
+| `user-tag get` | `analysis.user_tag.get` | Inspect exact tags | `--tag-names '[...]'` | Tag details |
+| `user-tag-member list` | `analysis.user_tag_member.list` | Bounded inline tag members | `--tag-name`, optional `--snapshot-date`, properties/fields/query/limit/offset | Member rows |
+| `user-tag-member export` | `analysis.user_tag_member.export` | Export tag members as jsonl | `--tag-name`, optional `--snapshot-date`, properties/fields/query | Async artifact descriptor |
+| `user-tag create` | `analysis.user_tag.create` | Create tag directly from semantic intent | `--tag-name`, `--display-name`, `--definition-request` | Create result and canonical request |
+| `user-tag update` | `analysis.user_tag.update` | Update tag | `--tag-name`, fields to change, optional `--definition-request` | Update result |
+| `user-tag refresh` | `analysis.user_tag.refresh` | Trigger tag recompute | `--tag-name` | Refresh result |
+| `user-tag create-id` | `analysis.user_tag.create_id` | Map imported values to an entity and create a tag | `--display-name`, `--entity-id`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
+| `user-tag update-id` | `analysis.user_tag.update_id` | Remap imported values for an ID tag | `--tag-name`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
+| `user-tag delete` | `analysis.user_tag.delete` | Delete tag after dependency review | `--tag-name`, `--confirmed`, `--yes` | Delete result |
+| `history-tag list` | `analysis.history_tag.list` | List history snapshots for a tag | `--tag-name` | Snapshot summaries |
+| `history-tag refresh` | `analysis.history_tag.refresh` | Refresh one history snapshot | `--tag-name`, `--refresh-date` | Refresh result |
+| `history-tag batch-refresh` | `analysis.history_tag.batch_refresh` | Batch refresh snapshots | `--tag-name`, `--refresh-request` | Async refresh result |
+| `history-tag clear` | `analysis.history_tag.clear` | Clear snapshots in date range | `--tag-name`, date range, `--confirmed`, `--yes` | Clear result |
+| `history-tag-data run` | `analysis.history_tag_data.run` | Bounded inline history tag statistics | `--tag-name`, `--view`, `--limit` | Statistic result |
+| `history-tag-data export` | `analysis.history_tag_data.export` | Export history tag statistics as jsonl | `--tag-name`, `--view` | Async artifact descriptor |
+| `history-tag-data-drilldown run` | `analysis.history_tag_data_drilldown.run` | Bounded inline users for one statistic value/bucket | `--tag-name`, `--snapshot-date`, `--group-col`, `--view`, optional member fields | Drilldown member rows |
+| `history-tag-data-drilldown export` | `analysis.history_tag_data_drilldown.export` | Export all users for one statistic value/bucket as jsonl | `--tag-name`, `--snapshot-date`, `--group-col`, `--view`, optional member fields | Async artifact descriptor |
 
 ## L3 project-space and folder capabilities
 
-Per [`capability-command-admission` §10](../../../docs/capability-command-admission.md): new gateway capabilities default to **dynamic discovery** (`capability search` → `inspect` → `dry-run` → `run`); standalone skill references are **exceptions only** (L2 bar, confusion, high-risk delete, multi-step orchestration).
+Per [`capability-command-admission` §10](../../../docs/capability-command-admission.md): new gateway capabilities default to **dynamic discovery** (`capability search` → `inspect` →（按需二选一：`validate` **或** `dry-run`，默认不叠打）→ `run`); standalone skill references are **exceptions only** (L2 bar, confusion, high-risk delete, multi-step orchestration).
 
-For **create / delete / share**, read the linked reference before `capability inspect/dry-run/run`. For **`*.members` read**, use this matrix only — no separate `references/*.md` (pilot).
+For **create / delete / share**, read the linked reference before `capability inspect` then `run` (optional pre-check per [`ae-capability`](../../ae-capability/SKILL.md) on-demand table). For **`*.members` read**, use this matrix only — no separate `references/*.md` (pilot).
 
 | Capability ID | Use for | Reference / discovery |
 | --- | --- | --- |
@@ -156,9 +207,19 @@ Output is the gateway envelope; `data` contains members.
 ## Examples
 
 ```bash
-ae-cli analysis dashboard list --project-id 1 --query retention --limit 20
-ae-cli analysis dashboard update --project-id 1 --operation note-upsert --dashboard-id 1001 --note-title "Summary" --description "Weekly note" --yes
+ae-cli analysis dashboard list --project-id 1 --query retention --limit 50
+ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from events limit 20"}'
+ae-cli analysis adhoc export --project-id 1 --model-type sql --definition '{"sql":"select * from events where country ${Text:country}","params":[{"name":"country","type":"text","value":"US"}]}' --artifact-format jsonl
+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 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
-ae-cli analysis public-link create --project-id 1 --resource-type dashboard --resource-id 1001 --effective-at "2026-07-08 00:00:00" --expires-at "2026-08-08 00:00:00" --yes
+ae-cli analysis public-link create --project-id 1 --resource-type dashboard --resource-id 1001 --effective-at "2026-07-08 00:00:00" --expires-at "2026-08-08 00:00:00"
+ae-cli analysis user-cluster list --project-id 1 --query retained --limit 50
+ae-cli analysis user-cluster-member export --project-id 1 --cluster-name retained_users --artifact-format jsonl
+ae-cli analysis user-tag create --project-id 1 --tag-name user_level --display-name "User Level" --definition-request '{"type":"condition","condition_values":[]}'
 ```

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

@@ -0,0 +1,38 @@
+# Analysis interpretation
+
+Use this guide after obtaining comparable result data. It defines how to attribute metric changes and how to distinguish evidence from hypothesis.
+
+## Absolute contribution for additive metrics
+
+Use for counts and sums such as DAU, event count, orders, or payment amount:
+
+```text
+delta_total = total_comparison - total_baseline
+delta_dimension_i = value_i_comparison - value_i_baseline
+contribution_i = delta_dimension_i / delta_total * 100%
+```
+
+Rank by `abs(delta_dimension_i)`, preserving the sign. Do not rank primary drivers by relative growth `delta_dimension_i / value_i_baseline`; a tiny baseline can create a large percentage with little effect on the total.
+
+Report each leading dimension's baseline, comparison, absolute delta, relative change, and contribution share. Treat a zero baseline as a new/lost dimension rather than an infinite growth rate.
+
+## Ratio and conversion metrics
+
+A ratio changes because subgroup rates change, subgroup composition changes, or both. First report numerator, denominator, and subgroup rates. When the user requests structural decomposition, use:
+
+```text
+rate_effect_i = weight_i_baseline * (rate_i_comparison - rate_i_baseline)
+composition_effect_i = (weight_i_comparison - weight_i_baseline) * rate_i_baseline
+```
+
+Keep rate effects and composition effects separate. Do not apply additive-count contribution directly to conversion rates.
+
+## Workflow and checks
+
+1. Keep project, population, filters, dimensions, timezone, and aggregation identical across periods.
+2. Prefer one query with comparison mode when the model supports it; otherwise run two definitions that differ only in time.
+3. Compute deltas and sort by absolute contribution.
+4. Verify additive dimension deltas reconcile with the total delta. If contribution shares differ from 100% by more than 5 percentage points, flag missing dimensions or inconsistent scope.
+5. Call a cause “observed” only when the data directly demonstrates it. Product releases, campaigns, and incidents remain hypotheses until independently verified.
+
+Skip cross-dimension contribution only when the user explicitly asks for percentage ranking or a single dimension's trend.

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

@@ -1,17 +1,23 @@
 # analysis artifact download
 
-Use after `run inspect` shows an export artifact is complete.
+Download an async analysis artifact returned by an export command.
 
-Do not use before the run reaches a successful terminal status. Use `run inspect` first.
+Use after an export returns both `run_id` and `artifact_id`; keep this pair bound together. Before downloading, inspect the run and wait until `status=SUCCEEDED` and `artifact_status=COMPLETED`.
 
-Command:
+Both IDs must come from the same export response. A valid `run_id` paired with a different export's `artifact_id` is invalid even if each ID exists separately.
+
+Do not use a raw `download_path` without preserving the `run_id`/`artifact_id` pair. Do not use this for synchronous `run` responses; it only downloads async artifacts. If the artifact is still running, this command returns `ARTIFACT_NOT_READY`; call `analysis run inspect` again later instead of retrying download in a loop.
+
+Input:
+
+- `run_id`: required async run ID returned by the export response.
+- `artifact_id`: required artifact ID from the same export response.
+- `output`: required local output path.
 
 ```bash
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output /tmp/result.jsonl.gz
 ```
 
-Input sends `run_id`, `artifact_id`, and local `output` path.
-
-Output is the gateway download result written to the local `--output` path. The command returns JSON with `run_id`, `artifact_id`, `output_path`, `bytes`, and response content headers.
+Output is local file metadata. The command writes the artifact bytes to `--output` and returns JSON with `run_id`, `artifact_id`, absolute `output_path`, `bytes`, and response content headers. The artifact may be gzip-compressed depending on the backend; preserve the returned/downloaded extension unless you intentionally decompress it yourself.
 
 Do not paste large artifact content into chat. Inspect the local file or summarize only the needed rows.

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

@@ -1,21 +1,21 @@
-# analysis-meta asset abnormal-get
+# analysis-meta asset-abnormal get
 
 Use when the user needs to get abnormal reason for one asset.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it to list all abnormal assets or to inspect normal asset definitions; use `asset abnormal-list` or the asset's own get command.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset abnormal-get --project-id <project_id> --resource-type <resource_type> --resource-id <resource_id> --resource-name <resource_name> --table-type <table_type>
-ae-cli analysis-meta asset abnormal-get --dry-run
+ae-cli analysis-meta asset-abnormal get --project-id <project_id> --resource-type <resource_type> --resource-id <resource_id> --resource-name <resource_name> --table-type <table_type>
+ae-cli analysis-meta asset-abnormal get --dry-run
 ```
 
 Capability id: `metadata.asset_abnormal.get`.
 
 Input sends `project_id`, `resource_type`, `resource_id`, `resource_name`, `table_type`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.resource` contains the matched asset's abnormal detail/reason.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -1,21 +1,21 @@
-# analysis-meta asset abnormal-list
+# analysis-meta asset-abnormal list
 
 Use when the user needs to list abnormal assets by resource type.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it for one known asset's detailed reason or for a general asset inventory; use `asset abnormal-get` or `asset search`.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset abnormal-list --project-id <project_id> --resource-types <resource_types>
-ae-cli analysis-meta asset abnormal-list --dry-run
+ae-cli analysis-meta asset-abnormal list --project-id <project_id> --resource-types <resource_types>
+ae-cli analysis-meta asset-abnormal list --dry-run
 ```
 
 Capability id: `metadata.asset_abnormal.list`.
 
 Input sends `project_id`, `resource_types`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.resources[]` contains abnormal assets in the requested resource types.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -1,21 +1,21 @@
-# analysis-meta asset authentication-list
+# analysis-meta asset-authentication list
 
 Use when the user needs to list authenticatable project assets and authentication status.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it as a complete asset search or to change status; use `asset search` or `asset authentication-update` respectively.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset authentication-list --project-id <project_id>
-ae-cli analysis-meta asset authentication-list --dry-run
+ae-cli analysis-meta asset-authentication list --project-id <project_id>
+ae-cli analysis-meta asset-authentication list --dry-run
 ```
 
 Capability id: `metadata.asset_authentication.list`.
 
 Input sends `project_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.assets[]` contains authenticatable asset identities and their current authentication status.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -1,24 +1,24 @@
-# analysis-meta asset authentication-update
+# analysis-meta asset-authentication update
 
 Use when the user needs to batch authenticate or unauthenticate assets.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it to edit the asset itself or to authenticate a guessed asset name; call `asset authentication-list` first and submit only returned asset identities.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset authentication-update --project-id <project_id> --payload '{}'
-ae-cli analysis-meta asset authentication-update --dry-run
+ae-cli analysis-meta asset-authentication update --project-id <project_id> --payload '{"authentication_status":1,"asset_list":[{"asset_name":"<name>","asset_type":"<type>"}]}'
+ae-cli analysis-meta asset-authentication update --dry-run
 ```
 
 Capability id: `metadata.asset_authentication.update`.
 
 Input sends `project_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Verify with `asset authentication-list`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--payload` | Yes | `{authentication_status, asset_list}`. `authentication_status` is `1` to authenticate or `0` to revoke; each `asset_list` item requires the real `asset_name` and `asset_type` returned by the list command. |

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

@@ -0,0 +1,26 @@
+# analysis-governance asset batch-dashboard-schedule-freeze
+
+Use when the user needs to batch freeze dashboard schedules for governed assets through the capability gateway.
+
+Do not use it for non-dashboard assets or ordinary dashboard content edits; it changes schedule, cache, refresh, and freeze settings in one batch.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-dashboard-schedule-freeze --project-id <project_id> --payload '{}'
+ae-cli analysis-governance asset batch-dashboard-schedule-freeze --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_batch.dashboard_schedule_freeze.
+
+Input sends project_id, payload, node_ids, reports_version, zone_offset, schedule_ui_config, dashboard_status, refresh_type, cache_config. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the dashboard batch-operation submission result. Verify its returned operation record before reporting the schedules as frozen.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
+| --dashboard-status | No | Dashboard status, such as freeze or normal. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -0,0 +1,26 @@
+# analysis-governance asset batch-delete
+
+Use when the user needs to batch delete governed assets through the capability gateway.
+
+Do not use it for a single unverified name or as cleanup after a failed test; resolve exact `node_ids`, dry-run the final set, and require explicit confirmation.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-delete --project-id <project_id> --payload '{}' --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-governance asset batch-delete --project-id <project_id> --payload '{}' --yes
+```
+
+Capability id: analysis_meta.asset_batch.delete.
+
+Input sends project_id, payload, node_ids. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the batch-operation submission result. Preserve any returned record identity/status and use `operation-record-list` to verify completion.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |