@thinkingai/ae-cli 6.0.30 → 6.0.31

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-users run` / `analysis drilldown-users 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; Common advances backend batches internally and writes one artifact.
+
+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.
+
+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.
+
+## 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.
+
+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`.
+
+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:
+
+- `analysis drilldown-users run` or `analysis drilldown-users 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.
+
+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 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`.

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,31 @@ 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. For analysis data exports, the descriptor and first artifact metadata line may also contain `query_context_id` when Redis context creation succeeds.
 
 ## 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` |
+| `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 |
+| `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; artifact metadata may include `query_context_id` |
+| `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 +104,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; artifact metadata may include `query_context_id` |
 | `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 +133,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 +206,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 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 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. |

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

@@ -0,0 +1,26 @@
+# analysis-governance asset batch-disable-auto-backup
+
+Use when the user needs to batch disable auto backup for assets through the capability gateway.
+
+Do not use it to disable auto updates; this command disables backup behavior and optionally clears tag history for selected nodes.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-disable-auto-backup --project-id <project_id> --payload '{}'
+ae-cli analysis-governance asset batch-disable-auto-backup --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_batch.disable_auto_backup.
+
+Input sends project_id, payload, node_ids, clear_history_tag. 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 its record/status so the operation can be audited without resubmission.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
+| --clear-history-tag | No | Whether to clear tag history: 1 yes, 0 no. |
+| --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_disable_auto_update.md

@@ -0,0 +1,26 @@
+# analysis-governance asset batch-disable-auto-update
+
+Use when the user needs to batch disable auto update for assets through the capability gateway.
+
+Do not use it to disable backups or freeze dashboard schedules; this operation only changes automatic update behavior for selected nodes.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-disable-auto-update --project-id <project_id> --payload '{}'
+ae-cli analysis-governance asset batch-disable-auto-update --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_batch.disable_auto_update.
+
+Input sends project_id, payload, node_ids, refresh_type. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the batch-operation submission result. Follow the returned record/status through `operation-record-list` instead of repeating the command.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
+| --refresh-type | No | Dashboard refresh type: 1 enabled, 0 disabled. |
+| --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_handover.md

@@ -0,0 +1,26 @@
+# analysis-governance asset batch-handover
+
+Use when the user needs to batch hand over governed assets to another user through the capability gateway.
+
+Do not use it to share assets or modify permissions; it transfers ownership of verified nodes to one verified numeric user ID.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-handover --project-id <project_id> --payload '{}'
+ae-cli analysis-governance asset batch-handover --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_batch.handover.
+
+Input sends project_id, payload, node_ids, to_user_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the ownership-transfer batch submission result. Confirm completion from its operation record rather than assuming submission equals handover.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
+| --to-user-id | No | Target user ID; 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. |

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

@@ -0,0 +1,25 @@
+# analysis-governance asset batch-info-export
+
+Use when the user needs to batch export asset information through the capability gateway.
+
+Do not use it to change the selected assets or export SQL definitions; it creates an XLSX information artifact for verified `node_ids` only.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset batch-info-export --project-id <project_id> --payload '{}'
+ae-cli analysis-governance asset batch-info-export --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_batch.info_export.
+
+Input sends project_id, payload, node_ids, reports_version, zone_offset, schedule_ui_config, dashboard_status, refresh_type, cache_config, clear_history_tag. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download the returned artifact IDs.
+
+## 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. |