@thinkingai/ae-cli 6.1.12 → 6.1.14

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

@@ -45,6 +45,7 @@ Time range:
 - `mode`: `recent`, `previous`, `custom`, `start_to_today`, or `start_to_yesterday`.
 - `recent` includes today/current unit; `previous` excludes today/current unit.
 - For `custom`, pass `start_time` and `end_time`.
+- For `start_to_today` and `start_to_yesterday`, pass `start_time`; omit `end_time` because the mode determines it.
 
 Chinese natural-language time mapping (mandatory; do not infer a different mode):
 
@@ -83,10 +84,16 @@ Group:
 {"field":{"name":"country","type":"user_property"}}
 ```
 
-Metric aggregation values should use semantic spelling, not internal A-codes:
+Metric aggregation values must use semantic spelling, not internal A-codes. The whitelist is model- and property-type-specific because it mirrors the page controls:
 
-- Count-like: `total_count`, `user_count`, `per_user_count`, `count`, `active_days`, `active_hours`
-- Property-like: `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`
+- `event`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`.
+- `retention` simultaneous metrics: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support only `sum` and `avg_per_user`; boolean properties support only `true_count`, `false_count`, `not_empty_count`, and `empty_count`.
+- `distribution`: without property use `count`, `active_days`, or `active_hours`; numeric properties support `sum`, `avg`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`.
+- `attribution`: use `total_count` without `target_property`, or `sum` with a numeric `target_property`.
+- `prop_analysis`: use `user_count` without property; property aggregations follow the event property-type rules except that `percentile` is not supported.
+- `heat_map`, `rank_list`, and `revenue`: use the event whitelist except that `percentile` is not supported.
+
+For total event count use `total_count`; `count` belongs only to distribution. Internal `Axxx` codes are persisted page details and are not valid authored AI definitions.
 
 ## Model definitions
 
@@ -117,11 +124,13 @@ Property aggregation example:
 {
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
-    {"event": "purchase", "aggregation": "sum", "property": "amount"}
+    {"event": "purchase", "display_name": "Purchase revenue", "aggregation": "sum", "property": "amount"}
   ]
 }
 ```
 
+Set optional `display_name` on an event metric when the report should show a business-facing metric name. It applies to regular event metrics, saved metrics, and formula metrics. Omit it to use the event name or the default formula-metric label.
+
 Formula metric example:
 
 ```json
@@ -129,6 +138,7 @@ Formula metric example:
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
     {
+      "display_name": "Revenue per user",
       "formula": "revenue / users",
       "dependencies": [
         {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
@@ -204,6 +214,13 @@ Use for user distribution buckets for an event or property metric.
       "event": "purchase",
       "aggregation": "sum",
       "property": "amount",
+      "filters": [
+        {
+          "field": {"name": "vip_users", "type": "cluster"},
+          "operator": "in_cluster"
+        }
+      ],
+      "relation": "and",
       "interval_type": "user_defined",
       "quota_interval_arr": [100, 1000, 10000]
     }
@@ -216,6 +233,10 @@ Use for user distribution buckets for an event or property metric.
 
 Use `interval_type=def` for automatic buckets, `user_defined` for explicit numeric boundaries, and `discrete` to group by raw values.
 
+Distribution filters must be attached to the corresponding `distribution_metrics[].filters`.
+Do not use top-level `filters` or `relation` in a distribution definition.
+When multiple metrics need the same filter, attach it to each metric explicitly. If the requested filter scope is ambiguous, clarify which metric it applies to before running the analysis.
+
 ### `attribution`
 
 Use to attribute target conversions to touchpoint/source events.
@@ -225,7 +246,7 @@ Use to attribute target conversions to touchpoint/source events.
   "time_range": {"mode": "previous", "unit": "day", "value": 14},
   "attribution": {
     "target_event": "purchase",
-    "target_aggregation": "user_count",
+    "target_aggregation": "total_count",
     "attribution_events": [
       {"event": "ad_click"},
       {"event": "campaign_view"}
@@ -238,6 +259,7 @@ Use to attribute target conversions to touchpoint/source events.
 ```
 
 `attribution_model` values: `first`, `last`, or `linear`.
+The target aggregation is intentionally narrow: use `total_count` without a property, or `sum` with a numeric `target_property`. Do not use `user_count`.
 
 ### `interval`
 
@@ -281,6 +303,8 @@ Use for behavior paths before or after a source event.
 
 `direction=forward` asks what users do after `source_event`; `direction=backward` asks what users did before it. Do not send original-QP fields such as `source_type` or `event_names`.
 
+For path analysis, `preview_rows` is a graph-display boundary aligned with the analysis UI: it keeps up to that many real nodes per path level, then combines overflow nodes into `more`. `result.nodes` retains the synthesized `more` node for graph structure and drilldown coordinates. The top-level `returned_rows` counts real business nodes actually returned across all levels; it excludes synthesized `more` nodes and the real nodes folded into them. The count may still exceed `preview_rows` because the boundary applies independently to each level. `has_more=true` means at least one level contains real nodes folded into `more`; a linear multi-level path can return more real nodes than `preview_rows` with `has_more=false`.
+
 Path `filters` are global member filters compiled to the original QP `user_filter`. They support `user_property`, `cluster`, and `tag`, but not `event_property`. Do not move a user filter into the source event's event-property filter.
 
 Path session timeout accepts only these unit/value ranges:
@@ -346,6 +370,10 @@ Trino special identifiers must use double-quoted identifier delimiters:
 {"sql":"SELECT \"#user_id\", \"$part_event\" FROM hive.ta.v_event_1 WHERE \"$part_date\" BETWEEN '2026-07-01' AND '2026-07-07' LIMIT 20"}
 ```
 
+Reserved words used as identifiers must also be double quoted, for example `SELECT "end" FROM ...`.
+
+For multiline SQL JSON, ensure JSON decoding produces a real line break in the `sql` value. Do not submit a literal `\\n` sequence outside a quoted SQL string value; use a JSON escape that the caller decodes once before invoking the capability.
+
 Event-table queries must include a date-partition predicate on the quoted `"$part_date"` column. The backend rejects SQL against an event table when this predicate is absent. This requirement is specific to event tables; do not invent a `$part_date` condition for a table whose discovered columns do not include it.
 
 Typed condition-fragment placeholder:
@@ -386,9 +414,10 @@ Rules:
 - If SQL has no `${...}` placeholder, omit `params`.
 - If SQL has placeholders, every placeholder must have one matching item in `params`.
 - Raw variables use `${name}`, not `${Variable:name}`. A selector's `value` must equal one of its `options[].value` values. `${PartDate:name}` expands to a complete predicate, so place it directly after `WHERE`/`AND` rather than after a column name.
+- A `part_date` parameter must provide either `recent_day` or a complete custom range with both `start_time` and `end_time`; one-sided custom ranges are invalid.
 - `use_timezone` is an optional boolean definition field that is only valid for `part_date`. It defaults to `false`. When `true`, that PartDate parameter uses the query's effective timezone selected by `zone_offset` or the current user/project default; when `false`, it follows the non-timezone-aware PartDate path. This is distinct from the command-level `zone_offset`.
 - Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
-- Delimit any Trino identifier containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` and `"$part_event"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
+- Delimit any Trino identifier containing `#`, `$`, `@`, spaces, punctuation, or a reserved word with double quotes, for example `"#user_id"`, `"$part_event"`, and `"end"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
 - For an event table, include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition.
 - Do not invent table or column names. If the user already provides a concrete table reference, use `analysis-meta datatable columns-get --project-id <project_id> --table-ref <table_ref>` to inspect columns before writing SQL. If the table itself is unknown, call `analysis sql-table list --project-id <project_id>` when available and select an exact returned `table_ref`; otherwise stop and ask for the table/data source. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
 - For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. Verify the default once with `analysis report-data run` without `--sql-params`, then verify a changed value with one value-only `--sql-params` override.

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

@@ -12,7 +12,7 @@ ae-cli analysis alert list [options]
 
 Capability id: `analysis.alert.list`
 
-Input sends `project_id`, optional `query`, `limit`, and `offset`. Do not send camelCase aliases.
+Input sends `project_id`, optional `queries`, `limit`, and `offset`. `queries` accepts 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. Do not send singular `query` or camelCase aliases.
 
 Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
 
@@ -21,7 +21,6 @@ Parameters:
 | Parameter | Description | Required |
 | --- | --- | --- |
 | `--project-id` | See command help | Yes |
-| `--query` | See command help | No |
+| `--queries` | JSON array of 1 to 20 keyword filters | No |
 | `--limit` | See command help | No |
 | `--offset` | See command help | No |
-

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

@@ -23,44 +23,95 @@ This policy applies to:
 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.
+- `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
 
+Synchronous data commands use `--preview-rows` for the maximum business rows
+returned per result. Omit it to use the model's current cluster-configured
+synchronous limit; the CLI does not detect an Agent sandbox or inject a smaller
+default. Agents should normally pass `--preview-rows 100` to control context and
+memory use. Human or script callers may omit it when the native synchronous
+result is wanted directly. User tag/cluster member list commands are the
+exception: omission returns at most 1000 rows, matching the UI member query.
+
 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 expected result fits in the chosen synchronous preview.
 - 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 runtime validates an explicit `--preview-rows` against the effective model
+or SQL cluster configuration. Do not hard-code one universal maximum. Model
+queries reserve their own internal total/summary rows, so the physical query
+limit may be `N+M`; these internal rows do not reduce the requested `N` business
+rows. SQL/list-shaped queries may fetch one look-ahead row to determine
+`has_more`. User tag/cluster member list commands accept explicit values up to
+100000; this does not change their omitted default of 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.
+Detail `run` commands (`event-detail run` and `entity-detail run`) support
+`--preview-rows`, but not `--limit`, `--offset`, or stable pagination. If
+`has_more=true`, switch to the matching `export`.
 
 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 result size is unknown or expected to exceed the chosen preview.
 - The query may be long-running or may exceed the sync timeout window.
+- A data-query `run` times out.
 - 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:
+Export commands are asynchronous artifact jobs and do not accept
+`--preview-rows`. Native full-download paths retain their existing model/SQL total row
+ceilings.
 
 `--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.
 
+Choose one lifecycle form:
+
 ```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>
+# Submit only. Preserve the returned run_id/artifact_id.
+ae-cli analysis adhoc export ...
+
+# Submit, then wait through repeated short inspect requests.
+ae-cli analysis adhoc export ... --wait
+
+# Submit, wait, and stream the completed artifact to a local file.
+ae-cli analysis adhoc export ... --output <file>
+
+# Resume after interruption, client wait expiry, or a detached shell.
+ae-cli analysis run wait --run-id <run_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`.
+`--output` implies `--wait`. `--wait-timeout-seconds` controls only how long the
+current CLI process remains attached; it defaults to 600 seconds and is capped
+at 21600 seconds. The server lifecycle descriptor remains a hard upper bound
+with a short artifact-materialization grace period. Ctrl-C, client wait expiry,
+or a persistent transient network failure stops only local waiting; it never
+cancels the remote run. Resume with the returned `resume_command` or printed
+`analysis run wait` command.
+
+Waiting succeeds only for `status=SUCCEEDED` plus
+`artifact_status=COMPLETED`. Run or artifact `FAILED`/`CANCELED` is terminal and
+returns a non-zero error. Unknown states, authorization failures, and 404s fail
+immediately instead of being polled indefinitely.
+
+Downloads stream into a temporary file in the destination directory and publish
+the complete file atomically. Existing output paths are refused by default; pass
+`--force` only when replacement is intentional. The primitive commands remain
+available for manual control:
+
+```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> [--force]
+```
 
 Cancel an async run/export with:
 
@@ -68,17 +119,35 @@ Cancel an async run/export with:
 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 `analysis run inspect`, `analysis run wait`, 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.
+Drilldown event/entity/user-event, ad-hoc/report/dashboard model, BI chart,
+user tag/cluster member, and history-tag drilldown exports use Common's
+full-download streaming paths. They accept no `limit`, `offset`, `page_num`, or
+`page_size`, and remain bounded by the existing full-download ceiling. Do not
+collect full data by repeated `list/run` calls.
+
+User tag/cluster member and history-tag drilldown exports support both
+`jsonl.gz` and `csv.gz`, defaulting to `jsonl.gz`; format selection does not
+change the native full-download query or introduce paging.
 
 ## 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.
+Only synchronous `adhoc run`, `report-data run`, and `dashboard-report-data run`
+previews with at least one available follow-up action create `query_context_id`
+and compact `sources[]` summaries. SQL, BI SQL, unsupported models, and previews
+without a drillable analysis angle do not create a useless context. Exports and
+downloaded artifacts never create this context and never expand the selectable
+result. The Common/UI synchronous result is the drilldown boundary.
+
+Before composing a follow-up coordinate, call `analysis query-context get` with
+the returned `query_context_id` and, for multi-source results, one exact source
+selector from the compact summary. The command reads the full row, column, and
+metric options already stored for that preview; it does not rerun the query.
 
-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.
+Follow-up commands are allowed only when the compact source summary advertises the exact action. Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md), fetch full options with `analysis query-context get`, select only those returned row/column/metric options, and never infer source IDs, dates, groups, model fields, or analysis angles from display text.
 
 Pass the original `--project-id` with every query-context or drilldown-context follow-up. Gateway uses it for project authorization, and Common rejects it if it does not match the project stored by the context ID.
 
@@ -92,12 +161,31 @@ Use that synchronous `query_context_id` for the advertised action only:
 
 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.
+If the synchronous response does not include `query_context_id` and the required
+action, or `analysis query-context get` does not return the required selectable
+options, 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.
+For sync `run`, trust Common's `has_more`. Common uses model totals or one extra
+lookahead business unit at the requested `preview_rows` boundary, or at that
+model's configured boundary when `preview_rows` is omitted. The lookahead unit
+is never returned, and reaching the boundary alone does not imply
+`has_more=true`. Use `export` whenever completeness matters.
 
 ## 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.
+`analysis bi-panel-page-data run --result-type charts` supports
+`--preview-rows` per chart and has no row pagination contract. A configured
+chart top-N still applies as a semantic chart limit. Summary is rendered
+presentation data, is available only from `run`, and rejects `--preview-rows`.
+
+Use `export --result-type charts` for complete, unknown-size, timed-out, or
+long-running chart data. Common streams rows directly under
+`model_full_download_limit`.
+
+User tag-member, cluster-member, and history-tag drilldown exports call their
+native full-download SQL paths and stream CSV rows directly into a gzip artifact.
+These exports support `--property-names`, but do not support the preview-only
+`--fields`, `--query`, or `--use-cache` options.
 
 BI SQL page/chart data does not support this analysis drilldown contract.

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

@@ -4,19 +4,19 @@ This contract controls every follow-up from an analysis result. Read it before c
 
 ## 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.
+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 `--preview-rows` boundary is applied. If `--preview-rows 10` returns ten rows, only coordinates represented by those ten rows may be selected.
 
 Every query-context or drilldown-context follow-up must also pass the original `--project-id`. Gateway uses it for project authorization, then Common verifies that it matches the project stored by the context ID. Never substitute a different project ID.
 
 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.
+SQL, `heat_map`, `rank_list`, `revenue`, and scenario models do not support this analysis drilldown contract and therefore do not create a query context. Stop when the primary response has no `query_context_id` or advertised action.
 
 ## 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`.
+The primary response contains compact `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":...}`, to `analysis query-context get`. Never put source IDs inside `coordinate`.
 
-Each source has `drilldown`:
+The query-context response contains the selected full `source`. Its `drilldown` object is the only coordinate option catalog for follow-up commands:
 
 - `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.

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

@@ -81,7 +81,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `drilldown-entities run/export` | `analysis.query.drilldown_entities` / `analysis.query.drilldown_entities_export` | Preview/export users or custom entities for an advertised entity cell | `--project-id`, `--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 | `--project-id`, `--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 | `--project-id`, `--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` | `analysis.report.list` | Find accessible reports | `--project-id`, optional `--queries`, `--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 |
@@ -95,7 +95,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `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 list` | `analysis.dashboard.list` | Find accessible dashboards | `--project-id`, optional `--queries`, `--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 |
 | `dashboard update` | `analysis.dashboard.update` | Update settings or upsert a note | `--operation settings|note-upsert`, IDs, optional `--payload` | Update result |
@@ -131,27 +131,29 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `bi-panel-page-data export` | `analysis.bi_panel_page_data.export` | Large/long BI page data | same as run, optional `--artifact-format jsonl` | Async artifact descriptor |
 | `project-space list` | `analysis.project_space.list` | Find accessible project spaces | `--project-id`, optional list filters | Paginated project spaces |
 | `project-space get` | `analysis.project_space.get` | Inspect one project space | `--project-id`, `--space-id` | Project space detail |
-| `favorite add` | `analysis.favorite.add` | Favorite dashboard/BI/folder | `--asset-id`, `--asset-type`, optional `--payload` | Favorite result |
+| `favorite add` | `analysis.favorite.add` | Favorite dashboard/BI/folder | required `--asset-id`, `--asset-type`; optional `--space-id` | Favorite result |
 | `favorite remove` | `analysis.favorite.remove` | Remove favorite | same as add | Remove result |
 | `public-link create` | `analysis.public_link.create` | Generate public link | `--resource-type`, `--resource-id`, `--effective-at`, `--expires-at` | Link result |
 | `public-link list` | `analysis.public_link.list` | List public links | `--project-id`, optional list filters | Paginated links |
 | `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 list` | `analysis.user_cluster.list` | Find accessible user clusters | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated cluster summaries |
+| `user-cluster export` | `analysis.user_cluster.export` | Export complete matching cluster catalog | `--project-id`, optional filters, required `--output` | Local JSONL catalog and integrity sidecar |
 | `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-member export` | `analysis.user_cluster_member.export` | Stream native full cluster members as csv.gz | `--cluster-name`, optional properties | 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 list` | `analysis.user_tag.list` | Find accessible user tags | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated tag summaries |
+| `user-tag export` | `analysis.user_tag.export` | Export complete matching tag catalog | `--project-id`, optional filters, required `--output` | Local JSONL catalog and integrity sidecar |
 | `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-member export` | `analysis.user_tag_member.export` | Stream native full tag members as csv.gz | `--tag-name`, optional `--snapshot-date`, properties | 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 |
@@ -162,10 +164,10 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `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 run` | `analysis.history_tag_data.run` | Bounded inline history tag statistics | `--tag-name`, `--view`, optional `--preview-rows` | 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 |
+| `history-tag-data-drilldown export` | `analysis.history_tag_data_drilldown.export` | Stream native full users for one statistic value/bucket as csv.gz | `--tag-name`, `--snapshot-date`, `--group-col`, `--view`, optional properties | Async artifact descriptor |
 
 ## L3 project-space and folder capabilities
 
@@ -211,19 +213,19 @@ Output is the gateway envelope; `data` contains members.
 ## Examples
 
 ```bash
-ae-cli analysis dashboard list --project-id 1 --query retention --limit 50
+ae-cli analysis dashboard list --project-id 1 --queries '["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 report list --project-id 1 --queries '["revenue","收入"]' --limit 50
+ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --preview-rows 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"}]' --preview-rows 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"
-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-cluster list --project-id 1 --queries '["retained","retention"]' --limit 50
+ae-cli analysis user-cluster-member export --project-id 1 --cluster-name retained_users --artifact-format csv
 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/artifact_download.md

@@ -6,18 +6,19 @@ Use after an export returns both `run_id` and `artifact_id`; keep this pair boun
 
 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.
+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, use `analysis run wait` 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.
+- `force`: optional explicit permission to replace an existing output file.
 
 ```bash
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output /tmp/result.jsonl.gz
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output /tmp/result.jsonl.gz [--force]
 ```
 
-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.
+Output is local file metadata. The command streams into a same-directory temporary file and publishes the complete file atomically, then returns JSON with `run_id`, `artifact_id`, absolute `output_path`, `bytes`, and response content headers. Existing paths are refused unless `--force` is explicit. Failed or interrupted transfers remove the temporary file. 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_list.md

@@ -7,18 +7,20 @@ Do not use it for one known asset's detailed reason or for a general asset inven
 Command:
 
 ```bash
-ae-cli analysis-meta asset-abnormal list --project-id <project_id> --resource-types <resource_types>
+ae-cli analysis-meta asset-abnormal list --project-id <project_id> --resource-types <resource_types> --limit 50 --offset 0
 ae-cli analysis-meta asset-abnormal list --dry-run
 ```
 
 Capability id: `metadata.asset_abnormal.list`.
 
-Input sends `project_id`, `resource_types`.
+Input sends `project_id`, `resource_types`, `limit`, and `offset`.
 
-Output `data.resources[]` contains abnormal assets in the requested resource types.
+Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--resource-types` | Yes | Resource types to query. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

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

@@ -7,17 +7,19 @@ Do not use it as a complete asset search or to change status; use `asset search`
 Command:
 
 ```bash
-ae-cli analysis-meta asset-authentication list --project-id <project_id>
+ae-cli analysis-meta asset-authentication list --project-id <project_id> --limit 50 --offset 0
 ae-cli analysis-meta asset-authentication list --dry-run
 ```
 
 Capability id: `metadata.asset_authentication.list`.
 
-Input sends `project_id`.
+Input sends `project_id`, `limit`, and `offset`.
 
-Output `data.assets[]` contains authenticatable asset identities and their current authentication status.
+Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

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

@@ -7,18 +7,20 @@ Do not use it to query report/dashboard result data; it discovers asset records
 Command:
 
 ```bash
-ae-cli analysis-meta asset search --project-id <project_id> --payload '{"keyword":"revenue"}'
+ae-cli analysis-meta asset search --project-id <project_id> --payload '{"keyword":"revenue"}' --limit 50 --offset 0
 ae-cli analysis-meta asset search --dry-run
 ```
 
 Capability id: `metadata.asset.search`.
 
-Input sends `project_id`, `payload`.
+Input sends `project_id`, `payload`, `limit`, and `offset`.
 
-Output `data.resources[]` contains matching assets. A blank keyword returns an empty array rather than a full asset list.
+Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. A blank keyword returns an empty envelope rather than a full asset list.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--payload` | Yes | Search object. Required semantic field: non-blank `keyword`. Optional filters are `own_types` and `res_cats`; do not pass server-owned identity or pagination-test fields. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

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

@@ -7,10 +7,10 @@ Do not use for dashboard assets. Use `dashboard list`.
 Command:
 
 ```bash
-ae-cli analysis bi-panel list --project-id <project_id> [--query <keyword>] [--limit 50] [--offset 0]
+ae-cli analysis bi-panel list --project-id <project_id> [--queries '["growth","retention"]'] [--limit 50] [--offset 0]
 ```
 
-Input sends `project_id` and optional `query`, `fields`, `limit`, `offset`. Prefer the default projection for discovery. Do not request generic `id`; BI panel summaries use fields such as `panel_id` and `name` when projected.
+Input sends `project_id` and optional `queries`, `fields`, `limit`, `offset`. `queries` accepts 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`, and singular `query` is not accepted. Prefer the default projection for discovery. Do not request generic `id`; BI panel summaries use fields such as `panel_id` and `name` when projected.
 
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
 

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

@@ -12,7 +12,7 @@ Command:
 ae-cli analysis bi-panel-page-data export --project-id <project_id> --panel-id <panel_id> --page-key <page_key> --result-type charts [--chart-ids '["chart1"]'] [--artifact-format jsonl]
 ```
 
-Input sends `project_id`, `panel_id`, `page_key`, `result_type`, and optional control, paging, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. `--row-limit` and related BI page controls are chart/summary window controls, not the generic async artifact row policy; see [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `panel_id`, `page_key`, `result_type=charts`, and optional chart, control, column, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. The export does not accept row/block paging fields: Common streams chart rows directly and applies only `model_full_download_limit`. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. BI summary is rendered presentation data; query it with `bi-panel-page-data run`.
 
 Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. It does not create `query_context_id` or expose inspect/download API paths; use the CLI commands below.
 

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

@@ -1,18 +1,18 @@
 # analysis bi-panel-page-data run
 
-Use for bounded inline BI panel page chart or summary data.
+Use for inline BI panel page chart or summary data with the same result cap as the UI.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `bi-panel-page-data export`.
 
-Do not use this command for full, unknown-size, larger than 1000-row, or long-running page data; use `bi-panel-page-data export`.
+Do not use this command when completeness matters, the result size is unknown, or the query is long-running; use `bi-panel-page-data export`.
 
 Command:
 
 ```bash
-ae-cli analysis bi-panel-page-data run --project-id <project_id> --panel-id <panel_id> --page-key <page_key> --result-type charts [--chart-ids '["chart1"]'] [--row-limit 100] [--limit 100] [--timeout-seconds 120]
+ae-cli analysis bi-panel-page-data run --project-id <project_id> --panel-id <panel_id> --page-key <page_key> --result-type charts [--chart-ids '["chart1"]'] [--timeout-seconds 120]
 ```
 
-Input sends `project_id`, `panel_id`, `page_key`, `result_type`, and optional control, paging, cache, request, timeout, and limit fields. Control defaults: inline `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. Chart `--row-limit` default 100 / max 1000. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `panel_id`, `page_key`, `result_type`, and optional control, cache, request, and timeout fields. `--timeout-seconds` defaults to 120 and is capped at 180. There are no row/block paging flags. Chart results use the configured top-N when enabled, otherwise the BI UI default cap of 20,000 rows, and return `has_more`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
 Output is the gateway envelope. `data` contains bounded inline page data.