@thinkingai/ae-cli 6.1.12 → 6.1.14

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

@@ -0,0 +1,20 @@
+# analysis query-context get
+
+Read the full selectable coordinate options for one source from a bounded synchronous analysis preview.
+
+The primary `adhoc run`, `report-data run`, or `dashboard-report-data run` response intentionally returns only a compact `sources[]` summary. Call this command only when that response contains `query_context_id`, `query_context_options_capability_id=analysis.query.context_get`, and an advertised follow-up action.
+
+## Command
+
+```bash
+ae-cli analysis query-context get \
+  --project-id <project_id> \
+  --query-context-id <query_context_id> \
+  [--source '{"report_id":1001}']
+```
+
+`--project-id` must match the project stored by the context. For a context with multiple sources, copy exactly one `report_id` or `chart_id` selector from the compact primary response. Omit `--source` only when the context contains one source.
+
+The returned `source.drilldown` contains the complete `row_options`, `column_options`, and `metric_options` for the original synchronous preview. Select options and shallow-merge only their `coordinate` fragments as described in [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). The command never reruns or expands the query and never makes export rows selectable.
+
+If the context is missing, expired, owned by another user, belongs to another project, or the caller no longer has source permission, the command fails. Do not reconstruct coordinates from display text.

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

@@ -22,7 +22,7 @@ ae-cli analysis query create-result-cluster \
 
 - `--project-id` must be the project used by the synchronous preview and must match the project stored by `query_context_id`.
 - `--query-context-id`, `--source`, and all coordinate fragments must come from the same synchronous `adhoc run`, `report-data run`, or `dashboard-report-data run` response.
-- Match the desired visible row and column in `source.drilldown.row_options`/`column_options`, select the correct metric option, and shallow-merge only their `coordinate` fragments.
+- Call `analysis query-context get`, match the desired visible row and column in its `source.drilldown.row_options`/`column_options`, select the correct metric option, and shallow-merge only their `coordinate` fragments.
 - Never pass `target_id`, raw QP, display-only dates, option presentation fields, or data from an export/download. Exports do not create query contexts.
 - `--cluster-name` must be unique in the project, start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be at most 24 characters. This legacy result-cluster path is stricter than ordinary cluster creation.
 - `--display-name`, when provided, must be at most 80 characters.

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

@@ -12,4 +12,4 @@ ae-cli analysis report-change-log list --project-id <project_id> --report-id <re
 
 Input sends `project_id` and `report_id`.
 
-Output is the gateway envelope. `data` contains change log summaries and `total`. Raw report QP fields are not returned in the list.
+Output is the gateway envelope. `data` contains change log summaries and `total`. Only items with `can_rollback=true` are valid rollback sources; pass that item's `target_version` to `report-version rollback --target-version`. Create and unpack records are not rollbackable. Raw report QP fields are not returned in the list.

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

@@ -9,14 +9,14 @@ Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Rep
 Command:
 
 ```bash
-ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--report-desc "..."] [--dashboard-ids "[1001]"]
+ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>'] [--report-desc "..."] [--dashboard-ids "[1001]"]
 ```
 
-Input sends `project_id`, `report_name`, `model_type`, `definition`, optional `report_desc`, `cache_seconds`, `query_duration_ms`, and `dashboard_ids`.
+Input sends `project_id`, `report_name`, `model_type`, `definition`, optional user-confirmed `resolutions`, `report_desc`, `cache_seconds`, `query_duration_ms`, and `dashboard_ids`. `--resolutions` is not supported with `--model-type tag`.
 
 Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
 
-Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. No report is created on this failure; select an exact returned candidate or ask the user before retrying.
+Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. No report is created on this failure; follow [`../metadata_resolution.md`](../metadata_resolution.md), keep the definition unchanged, and pass `--resolutions` only after user confirmation.
 
 ## SQL dynamic parameter shortest path
 

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

@@ -6,7 +6,7 @@ Typical closed loop: discover a saved report -> verify its definition -> resolve
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `report-data export`.
 
-Do not use this command for full, unknown-size, larger than 1000-row, or long-running report data; use `report-data export`.
+Do not use this command for full, unknown-size, larger than the current runtime synchronous maximum, or long-running report data; use `report-data export`.
 
 This gateway report-data capability executes saved reports with model-specific overrides. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
@@ -22,19 +22,19 @@ Command:
 
 ```bash
 # Non-SQL analysis report
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --start-time 2026-07-01 --end-time 2026-07-09 --limit 20
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --start-time 2026-07-01 --end-time 2026-07-09 --preview-rows 20
 
 # SQL report, after analysis report get confirms definition.params contains platform
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --limit 20
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --preview-rows 20
 
 # Explicit local-time mode (not UTC+99)
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --limit 20
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --preview-rows 20
 
 # One physical slave query cluster
-ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --cluster-query-scope SLAVE --slave-cluster-id jp --limit 20
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --cluster-query-scope SLAVE --slave-cluster-id jp --preview-rows 20
 ```
 
-Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Use `GLOBAL` only for explicit cross-cluster aggregation; use `SLAVE` with exactly one ID returned by `analysis query-cluster list`. SQL reports reject `GLOBAL`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180.
+Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Use `GLOBAL` only for explicit cross-cluster aggregation; use `SLAVE` with exactly one ID returned by `analysis query-cluster list`. SQL reports reject `GLOBAL`. Omit `--preview-rows` to use each report model's current cluster synchronous limit; explicit values must not exceed the runtime model limit. Agents should normally pass 100. `--timeout-seconds` defaults to 120 and has a maximum of 180.
 
 Timezone contract:
 
@@ -53,8 +53,8 @@ A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `en
 
 For a newly created or updated dynamic SQL report, omit `--sql-params` to execute the saved default first. After that succeeds, then make one second call with `--sql-params` to change only the requested value. This separates a broken saved default from a broken override and avoids repeating the same query.
 
-Output is the gateway envelope. `data` contains bounded inline report result items plus `query_context_id` and `sources[]`. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. `sources[].drilldown` is present when the returned preview exposes follow-up actions. Each source is evaluated independently; SQL and other unsupported models have no actions.
+Output is the gateway envelope. When at least one report exposes a follow-up action, `data` contains bounded inline report result items plus `query_context_id` and compact `sources[]` summaries. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. SQL-only and otherwise non-drillable results omit query context entirely. Use `analysis query-context get` to read the selected source's full coordinate options.
 
 `meta.actual_cluster_query_scope`, optional `meta.actual_slave_cluster_id`, and `meta.cluster_query_scope_source` describe the actual physical route. Verify them before comparing or drilling down. An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Select only returned row/column/metric options and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Call `analysis query-context get`, select only its returned row/column/metric options, and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.

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

@@ -7,11 +7,11 @@ Do not use for report data execution or report definition writes. Use `report-da
 Command:
 
 ```bash
-ae-cli analysis report list --project-id <project_id> [--query <keyword>] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--limit 50] [--offset 0]
+ae-cli analysis report list --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name","report_desc","report_model","version"]'] [--limit 50] [--offset 0]
 ```
 
-Input sends `project_id`, optional `query`, `model_types`, `fields`, `limit`, and `offset` as snake_case gateway input. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
+Input sends `project_id`, optional `queries`, `model_types`, `fields`, `limit`, and `offset` as snake_case gateway input. `queries` is a JSON array of 1 to 20 non-empty strings with OR semantics; matching rows include `matched_queries` and `matched_fields`. The legacy singular `query` is not accepted. `limit` defaults to 50 and must be 1..200; out-of-range values are rejected rather than silently clamped.
 
 Output is the gateway envelope. `data` contains report summaries, `total`, effective `limit`, `offset`, `has_more`, and nullable `next_offset`. When `has_more` is true, use exactly `next_offset` for the next call; stop when it is false. Include `version` in `--fields` when the next step is `analysis report update`.
 
-When locating one report, narrow with `--query` or `--model-types` before paging and stop when the required report is found; do not enumerate every report page when the server-side filters can identify the target.
+When locating reports, group known names into one `--queries` call or narrow with `--model-types` before paging. Stop when the required reports are found; do not issue one list call per name.

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

@@ -7,9 +7,9 @@ Do not use for report data values. Use `report-data export` when the output shou
 Command:
 
 ```bash
-ae-cli analysis report list-export --project-id <project_id> [--query <keyword>] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name"]'] [--artifact-format jsonl] [--request-id cli_0123456789abcdef0123456789abcdef] [--timeout-seconds 21600]
+ae-cli analysis report list-export --project-id <project_id> [--queries '["growth","retention"]'] [--model-types '["event","sql","tag","revenue"]'] [--fields '["report_id","report_name"]'] [--artifact-format jsonl] [--request-id cli_0123456789abcdef0123456789abcdef] [--timeout-seconds 21600]
 ```
 
-Input sends `project_id`, optional `query`, semantic `model_types`, `fields`, lifecycle `request_id`, artifact `format`, and `timeout_seconds`. ae-cli generates and announces `request_id` before dispatch when it is omitted.
+Input sends `project_id`, optional `queries`, semantic `model_types`, `fields`, lifecycle `request_id`, artifact `format`, and `timeout_seconds`. `queries` accepts 1 to 20 non-empty strings with OR semantics; the singular `query` is not accepted. ae-cli generates and announces `request_id` before dispatch when it is omitted.
 
 Output is the gateway envelope. `data` contains an async artifact descriptor including `run_id`, `artifact_id`, status, and expiration fields. Inspect and download through the dedicated CLI commands using those opaque IDs.

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

@@ -10,14 +10,14 @@ Command:
 
 ```bash
 ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --report-name "New name"
-ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}'
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <version> --model-type event --definition '{...}' [--resolutions '<confirmed_resolution_json>']
 ```
 
-Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided.
+Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, and at least one of `report_name`, `report_desc`, or `definition`. Read `version` from `analysis report get` before updating. `model_type` is required when `definition` is provided; `resolutions` is allowed only with that unchanged definition and is not supported with `model_type=tag`.
 
 Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
 
-When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. The report is not changed on this failure; resolve the ambiguity before retrying.
+When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves the full structured error array. The report is not changed on this failure; follow [`../metadata_resolution.md`](../metadata_resolution.md), keep the definition unchanged, and retry with `--resolutions` only after confirmation.
 
 For the shortest safe update, read the current `version` exactly once with `analysis report get` immediately before the write; do not reuse a version from an older list or conversation turn. If a SQL dynamic parameter definition changed, query the saved default before applying an override so default persistence and override behavior are verified separately.
 

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

@@ -2,7 +2,7 @@
 
 Use when the user explicitly wants to rollback one report to a previous history version.
 
-Do not use without first identifying the target version from `report-change-log list` or an exact user-provided version.
+Do not use without first choosing an item with `can_rollback=true` from `report-change-log list` or receiving an exact user-provided version. Pass the selected item's `target_version`; do not infer it from `version` or `original_version`.
 
 Command:
 

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

@@ -7,18 +7,20 @@ Do not use it to discover rule field syntax; use `rule-schema` for construction
 Command:
 
 ```bash
-ae-cli analysis-governance rule list --project-id <project_id>
+ae-cli analysis-governance rule list --project-id <project_id> --limit 50 --offset 0
 ae-cli analysis-governance rule list --dry-run --project-id <project_id>
 ```
 
-Capability id: analysis_meta.asset_rule.list.
+Capability id: `governance.rule.list`.
 
-Input sends project_id, payload. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends `project_id`, optional `payload`, `limit`, and `offset`. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
 
-Output `data` is the saved governance rule collection for the project. Resolve a real `rule_id` from this result before update or delete.
+Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Resolve a real `rule_id` from `items` before update or delete.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |

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

@@ -4,7 +4,7 @@ Inspect an async analysis capability-gateway run returned by export commands.
 
 Use for `analysis adhoc export`, `analysis report-data export`, `analysis dashboard-report-data export`, `analysis bi-panel-page-data export`, and other analysis exports that return `run_id`.
 
-Do not use this for MCP `request_id` cancellation or status. MCP query lifecycle uses the specific MCP command contract.
+Legacy transport `request_id` values are outside this skill's execution path. This command accepts only the capability-gateway `run_id`; if the caller has only a legacy request ID, report that it cannot be inspected or canceled here.
 
 Input:
 
@@ -20,9 +20,12 @@ Input sends `run_id`.
 
 Output is the gateway run descriptor with run status, artifact status, and error fields when the run failed. Keep the `run_id` from the same export result; do not invent or reuse it across artifacts.
 
-Polling rule:
+State interpretation:
 
-- Continue polling while status is running or pending.
-- Treat `COMPLETED` or `SUCCEEDED` as success.
-- Treat `FAILED`, `CANCELED`, or `CANCELLED` as terminal failure.
+- Continue only while run or artifact status is `RUNNING`.
+- Treat only run `SUCCEEDED` plus artifact `COMPLETED` as downloadable success.
+- Treat run or artifact `FAILED`/`CANCELED` as terminal failure.
 - After success, download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>`.
+
+For managed polling and resumability, use `ae-cli analysis run wait --run-id
+<run_id> [--output <file>]` instead of scripting an unbounded inspect loop.

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

@@ -0,0 +1,37 @@
+# analysis run wait
+
+Resume client-side waiting for an asynchronous run and optionally download its
+completed artifact.
+
+Use this after an export was submitted without `--wait`, or when a previous
+wait was interrupted, detached, reached its client or server deadline, or
+stopped after persistent transient network failures. Do not use it for
+synchronous `run` results, and do not treat it as a cancellation command.
+
+```bash
+ae-cli analysis run wait --run-id <run_id> [--wait-timeout-seconds <n>] [--output <file>] [--force]
+```
+
+Input:
+
+- `--run-id`: exact run ID returned by the original async export.
+- `--wait-timeout-seconds`: optional local wait bound, `1..21600`; default
+  `600`. Expiry does not cancel the remote run.
+- `--output`: optional destination. When present, download begins only after
+  run `SUCCEEDED` and artifact `COMPLETED`.
+- `--force`: optional atomic replacement of an existing `--output`; invalid
+  without `--output`.
+
+The command polls with repeated short inspect requests and internal adaptive
+backoff. Local waiting stops at the earlier of `--wait-timeout-seconds` and the
+server lifecycle deadline, with a short artifact-materialization grace. Ctrl-C
+or a local wait failure never cancels the remote run. The error returns the
+latest lifecycle state plus `remote_run_canceled=false` and `resume_command`.
+Use `analysis query cancel --run-id <run_id>` only when cancellation is
+explicitly intended.
+
+Without `--output`, the response is the successful terminal run descriptor.
+With `--output`, success additionally guarantees a complete atomically
+published local file and returns `output_path`, `bytes`, and content headers.
+Run/artifact failure, unknown protocol states, 404, or authorization failure
+returns a non-zero structured error; do not turn those outcomes into success.

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

@@ -7,7 +7,7 @@ List the server-authoritative SQL table references that the current user may que
 ```bash
 ae-cli analysis sql-table list \
   --project-id <project_id> \
-  [--query <keyword>] \
+  [--queries '["user","event"]'] \
   [--limit <1-200>] \
   [--offset <next_offset>] \
   [--usage analysis|tag_cluster]
@@ -17,6 +17,7 @@ ae-cli analysis sql-table list \
 
 - Use this command before writing SQL when the table is not already known. Do not ask the customer to supply the fixed project event/user table name and do not guess `v_event_<id>` or `v_user_<id>`.
 - `table_ref` is the exact server-authorized reference to copy into SQL and into `analysis sql-table columns --table-ref`.
+- `queries` accepts 1 to 20 non-empty strings with OR semantics. Matching rows include `matched_queries` and `matched_fields`; singular `query` is not accepted.
 - Each item also returns `catalog`, `schema`, `table`, `table_type`, and `description`.
 - `usage=analysis` is the default table set for SQL analysis and reports. Use `usage=tag_cluster` for SQL tags or SQL clusters. These server-authorized sets differ, and the same usage must be passed to `sql-table columns`.
 - When `has_more=true`, continue only with the returned `next_offset`. Stop when `has_more=false`.
@@ -25,7 +26,7 @@ ae-cli analysis sql-table list \
 ## Example workflow
 
 ```bash
-ae-cli analysis sql-table list --project-id 1 --query user
+ae-cli analysis sql-table list --project-id 1 --queries '["user","account"]'
 ae-cli analysis sql-table columns --project-id 1 --table-ref hive.ta.v_user_1
 ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from hive.ta.v_user_1 limit 10"}'
 ```

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

@@ -0,0 +1,13 @@
+# analysis user-cluster export
+
+Export every matching accessible user cluster without pagination.
+
+```bash
+ae-cli analysis user-cluster export \
+  --project-id <project_id> \
+  --output <temporary_path>/clusters.jsonl
+```
+
+Capability id: `analysis.user_cluster.export`.
+
+Optional filters are `--queries`, `--fields`, and `--authenticated-only`. `--limit`, `--offset`, and `--all` are not accepted. The CLI requires a `.jsonl` output path and writes an adjacent `.meta.json` completeness and identity sidecar. Search the file locally; do not load the full snapshot into model context.

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

@@ -2,7 +2,9 @@
 
 List accessible user clusters for discovery. Use this before any get/update/delete/member command; do not invent `cluster_name`.
 
-Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--queries` is a JSON array of 1-20 keywords and uses OR matching. Default `--limit` is 50; maximum is 200.
 
 `--offset` is only for stable asset browsing. It is not a member-data pagination strategy.
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
@@ -10,6 +12,8 @@ When `has_more=true`, continue only with the returned `next_offset`; do not calc
 Output is a paged cluster inventory, not cluster members or definition-build results.
 
 ```bash
-ae-cli analysis user-cluster list --project-id <project_id> --query retained --limit 50
+ae-cli analysis user-cluster list --project-id <project_id> --queries '["retained","retention"]' --limit 50
 ae-cli analysis user-cluster list --project-id <project_id> --fields '["cluster_name","display_name","users_num"]' --limit 50 --offset 0
 ```
+
+For a complete catalog, use [`user_cluster_export.md`](user_cluster_export.md).

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

@@ -1,12 +1,14 @@
 # analysis user-cluster-member export
 
-Export cluster members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+Stream the native full cluster-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+Do not use this command for an inline sample or filtered keyword search; use `user-cluster-member run` for preview behavior.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
-Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+Export does not accept `--offset`, `--fields`, `--query`, or `--use-cache`. Common executes the native full-download SQL once and streams result rows directly as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages. The existing full-download ceiling still applies.
 
 ```bash
 ae-cli analysis user-cluster-member export --project-id <project_id> --cluster-name retained_users --artifact-format jsonl

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

@@ -4,16 +4,16 @@ Run a bounded inline cluster member query. Read `analysis_data_retrieval.md` bef
 
 Do not use it for complete/unknown-size membership retrieval or cluster metadata. Output contains at most the requested inline limit and has no caller pagination contract.
 
-Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--preview-rows`, `--timeout-seconds`.
 
 When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, and `#distinct_id`. Cluster members do not expose tag-only fields such as `tag_value` or `tag_date`. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
-The inline member limit defaults to 50 and accepts 1..200.
+Omit `--preview-rows` to return at most 1000 rows, matching the UI member query. Explicit values must be between 1 and 100000; use a smaller preview when only a sample is needed.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
 For full or unknown-size member data, use `user-cluster-member export`; the list command has no next-page contract.
 
 ```bash
-ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --limit 100
-ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","country"]' --query US --limit 50
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --preview-rows 100
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","country"]' --query US --preview-rows 50
 ```

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

@@ -2,11 +2,11 @@
 
 Update a condition or SQL user cluster. Discover the exact `cluster_name` first.
 
-Do not use it for ID-file membership replacement or to create a missing cluster. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-cluster refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A successful update means the definition was saved, not that the new result is complete. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
+Do not use it for ID-file membership replacement or to create a missing cluster. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-cluster refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. A successful update means the definition was saved, not that the new result is complete. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
 
 The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
-Flags: `--project-id`, `--cluster-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`. The cluster type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--cluster-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. The cluster type comes from `definition_request.type` when the definition changes.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `cluster_name` is an existing exact identifier and cannot be renamed by update.
 
@@ -14,4 +14,6 @@ Read `user_cluster_models.md` before changing the definition. The backend valida
 
 ```bash
 ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --display-name "Retained Users v2"
+
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --auto-refresh-cron '0 30 2 * * ? *'
 ```

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

@@ -0,0 +1,13 @@
+# analysis user-tag export
+
+Export every matching accessible user tag without pagination.
+
+```bash
+ae-cli analysis user-tag export \
+  --project-id <project_id> \
+  --output <temporary_path>/tags.jsonl
+```
+
+Capability id: `analysis.user_tag.export`.
+
+Optional filters are `--queries`, `--fields`, and `--authenticated-only`. `--limit`, `--offset`, and `--all` are not accepted. The CLI requires a `.jsonl` output path and writes an adjacent `.meta.json` completeness and identity sidecar. Search the file locally; do not load the full snapshot into model context.

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

@@ -2,7 +2,9 @@
 
 List accessible user tags for discovery. Use this before get/update/delete/member/history-tag commands; do not invent `tag_name`.
 
-Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+Flags: `--project-id` required. Optional: `--queries`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--queries` is a JSON array of 1-20 keywords and uses OR matching. Default `--limit` is 50; maximum is 200.
 
 `--offset` is only for stable asset browsing. It is not a tag-member pagination strategy.
 When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
@@ -12,6 +14,8 @@ Output is a paged tag inventory whose identifier is `tag_name`, the same field c
 Tags never accept `cluster_name`; that field belongs only to user clusters. Do not retry a tag command by substituting one identifier for the other.
 
 ```bash
-ae-cli analysis user-tag list --project-id <project_id> --query level --limit 50
+ae-cli analysis user-tag list --project-id <project_id> --queries '["level","tier"]' --limit 50
 ae-cli analysis user-tag list --project-id <project_id> --fields '["tag_name","display_name","users_num"]' --limit 50 --offset 0
 ```
+
+For a complete catalog, use [`user_tag_export.md`](user_tag_export.md).

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

@@ -1,12 +1,14 @@
 # analysis user-tag-member export
 
-Export tag members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+Stream the native full tag-member download as an async gzip artifact. Read `analysis_data_retrieval.md` first.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+Do not use this command for an inline sample or filtered keyword search; use `user-tag-member run` for preview behavior.
+
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
-Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+Export does not accept `--offset`, `--fields`, `--query`, or `--use-cache`. Common executes the native current-tag or history-tag full-download SQL once and streams result rows directly as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages. The existing full-download ceiling still applies.
 
 ```bash
 ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl

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

@@ -4,16 +4,16 @@ Run a bounded inline tag member query. Read `analysis_data_retrieval.md` before
 
 Do not use it for complete/unknown-size membership retrieval or history statistics. Output contains at most the requested inline limit and has no caller pagination contract.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--preview-rows`, `--timeout-seconds`.
 
 When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, `#distinct_id`, and the stable logical `tag_value`. Internal calculated tag column names are never part of the public response. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
-The inline member limit defaults to 50 and accepts 1..200.
+Omit `--preview-rows` to return at most 1000 rows, matching the UI member query. Explicit values must be between 1 and 100000; use a smaller preview when only a sample is needed.
 
 If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
 
 For full or unknown-size member data, use `user-tag-member export`; the list command has no next-page contract.
 
 ```bash
-ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --limit 100
-ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","tag_value","country"]' --limit 50
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --preview-rows 100
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","tag_value","country"]' --preview-rows 50
 ```

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

@@ -2,11 +2,11 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
 
 The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`. The tag type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `tag_name` is an existing exact identifier and cannot be renamed by update.
 
@@ -14,4 +14,6 @@ Read `user_tag_models.md` before changing the definition. The backend validates
 
 ```bash
 ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --display-name "User Level v2"
+
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-cron '0 30 2 * * ? *'
 ```

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

@@ -11,7 +11,7 @@ Command:
 ```bash
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --table-type event --select-type string --sql-expression 'event_name' --sql-event-relation-type relation_default
 ae-cli analysis-meta virtual-property create --project-id <project_id> --property-name '#vp@demo' --property-desc demo --table-type event --select-type string --sql-expression "CASE WHEN status = 1 THEN 'active' ELSE 'inactive' END" --sql-event-relation-type relation_by_setting --related-events '[{"eventName":"purchase"}]' --property-remark demo
-ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --properties '[...]'
+ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{"property":{"column_name":"#vp@demo","table_type":"event","select_type":"string"}}' --properties '[...]'
 ae-cli analysis-meta virtual-property create --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
 ```
 
@@ -26,7 +26,7 @@ Output is a successful gateway envelope with no business data.
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--sql-expression` | Yes | SQL expression used to calculate the virtual property. |
-| `--v-prop` | No | Full virtual property JSON object with `property.column_name`, `table_type`, and `select_type`. Use typed property flags unless an exact DTO is already available. |
+| `--v-prop` | No | Full virtual property JSON object with `property.column_name`, `property.table_type`, and `property.select_type`. All three fields belong inside `property`; use typed property flags unless an exact DTO is already available. |
 | `--property-name` | No | Virtual property name. Must start with `#vp@`. Required when `--v-prop` is omitted. |
 | `--property-desc` | No | Virtual property display name. |
 | `--table-type` | No | Property table type: `event` or `user`. Required when `--v-prop` is omitted. |

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

@@ -7,8 +7,8 @@ Do not use it for renaming a physical property. Use only when replacing the comp
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --properties '[...]'
-ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{...}' --dry-run
+ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --properties '[...]'
+ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --sql-expression '<sql>' --v-prop '{"prop_id":22990,"property":{"column_name":"#vp@demo","table_type":"event","select_type":"number"}}' --dry-run
 ```
 
 Capability id: `metadata.virtual_property.sql_rule_update`.
@@ -22,7 +22,7 @@ Output is a successful gateway envelope with no business data.
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--sql-expression` | Yes | Replacement SQL expression. |
-| `--v-prop` | Yes | Existing virtual property JSON object, including its ID and property fields. |
+| `--v-prop` | Yes | Existing virtual property JSON object. Put `prop_id` directly under `v_prop`, beside `property`; do not put it inside `property`. |
 | `--properties` | No | Dependent property JSON array. |
 | `--sql-event-relation-type` | No | `relation_default`, `relation_always`, or `relation_by_setting`. |
 | `--related-events` | No | Related events JSON array for `relation_by_setting`. |

package/skills/ae-community/SKILL.md

@@ -42,7 +42,7 @@ Safety constraints:
 - Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
 - **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
-**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), and `operation` (operations).
+**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis-meta` (metadata), and `operation` (operations).
 
 ---
 
@@ -262,7 +262,7 @@ Commands below are shown **without** the `ae-cli community` prefix; all use the
 
 ## Composite scenario skills
 
-Structured multi-step reports (MCP tool chains) — open the linked reference for full workflows.
+Structured multi-step report workflows — open the linked reference for the complete ae-cli command sequence.
 
 | Skill | Purpose |
 |-------|---------|