@thinkingai/ae-cli 6.0.30 → 6.0.31

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

@@ -0,0 +1,29 @@
+# analysis report create
+
+Use when the user explicitly wants to create a saved analysis report from an AI QP definition.
+
+Do not use raw QP, `analysis_query`, `events`, `event_view`, or `visual_view`. The gateway accepts `model_type` plus AI QP `definition`.
+
+Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Report create supports the 12 analysis models plus `tag` for saved tag report data.
+
+Command:
+
+```bash
+ae-cli analysis report create --project-id <project_id> --report-name "Demo" --model-type event --definition '{...}' [--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`.
+
+Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
+
+## SQL dynamic parameter shortest path
+
+When a SQL report contains a `${...}` placeholder, define its saved default in the same AI-facing `definition`. Example:
+
+```bash
+ae-cli analysis report create --project-id <project_id> --report-name "Recent SQL" --model-type sql --definition '{"sql":"select * from events where ${PartDate:ds} limit 100","params":[{"name":"ds","type":"part_date","recent_day":"1-7"}]}'
+```
+
+After creation, keep the `report_id` returned by this exact create response. To verify the report, query the saved default first with `analysis report-data run` and omit `--sql-params`; then make one second query with a value-only `--sql-params` override. Do not rebuild internal `sqlViewParams` or guess an ID.
+
+After any successful report create, call `analysis_common +get_resource_url` with that returned `report_id` and output its `markdown_link`.

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

@@ -0,0 +1,37 @@
+# analysis report-data export
+
+Submit saved report data as a downloadable async artifact. 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.
+
+Before adding overrides, call `analysis report get` for every report. The model matrix is the same as `report-data run`: SQL accepts only saved `definition.params` names through `--sql-params`; non-SQL analysis models accept filters/group/time overrides; tag executes its saved definition. Never put generic overrides and `--sql-params` in one homogeneous-model request.
+
+Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `report-data run`.
+
+Do not use this command for bounded inline previews; use `report-data run` when the requested result fits the sync data retrieval rule.
+
+Command:
+
+```bash
+# Non-SQL analysis report
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --artifact-format jsonl
+
+# SQL report
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --artifact-format jsonl
+```
+
+Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `use_cache`, artifact `format`, and `timeout_seconds`. 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>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+Override model:
+
+- `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
+- `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields.
+
+Mixed-model export batches are best-effort rather than rejected only for being mixed. Prefer one model per overridden export because artifact formats cannot surface submission-time warnings as prominently as inline `meta.warnings`.
+
+Output is the gateway envelope. `data` contains opaque `run_id` and `artifact_id`, lifecycle status and expiration, effective timeout/deadline fields, plus `query_context_id` and `query_context_expires_at` when Redis context creation succeeds. Inspect/download through the dedicated CLI commands using the IDs.
+
+Keep `run_id` and `artifact_id` from the same export response. Inspect that exact `run_id`, then download only that paired `artifact_id`; never combine IDs from different exports.
+
+An empty artifact is a successful query and means the requested time range has no data. If every requested report explicitly fails, the run reaches `FAILED` instead of completing an error-only artifact. Mixed exports may contain explicit per-report error markers alongside successful report data.
+
+Use the submit response `query_context_id` immediately with `analysis drilldown-users run` or `analysis query create-result-cluster` when present. JSONL artifacts repeat `query_context_id` and `query_context_expires_at` in the first metadata line; CSV remains pure CSV and carries context only in the submit descriptor. Do not pass raw QP.

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

@@ -0,0 +1,45 @@
+# analysis report-data run
+
+Execute bounded inline data from one or more saved reports.
+
+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`.
+
+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.
+
+Before adding any query-condition override, call `analysis report get` for every `report_id` and branch on `data.model_type`:
+
+| Saved report model | Valid query-condition overrides |
+|---|---|
+| `sql` | Only `--sql-params`. SQL time conditions must be saved `definition.params` items of type `part_date` or time and overridden there. |
+| Non-SQL analysis model | `--filters`, `--group-by`, `--start-time`, `--end-time`, `--time-granularity` |
+| `tag` | No generic report-data override. Execute the saved tag definition or use `analysis history-tag-data run` for a tag-specific view. |
+
+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
+
+# 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
+```
+
+Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `use_cache`, `limit`, and `timeout_seconds`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+
+Override model:
+
+- `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
+- `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields.
+
+A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `end_time`, or `time_granularity` fails with `INVALID_OVERRIDE_FOR_MODEL`. A homogeneous non-SQL request with `sql_params` also fails. Mixed-model batches are best-effort: data still returns and `meta.warnings[]` uses `OVERRIDE_IGNORED_FOR_MODEL`, `model_type`, `report_ids`, and `ignored_fields` to identify fields that did not apply. Do not discard these warnings.
+
+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`, `drilldown_available`, and `result_cluster_available` when a context can be created.
+
+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. Mixed batches keep successful items and return `meta.partial`, counts, and per-report `meta.failures` for partial-result handling.
+
+Use `query_context_id` with `analysis drilldown-users run` or `analysis query create-result-cluster`. Do not pass raw QP.

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

@@ -0,0 +1,17 @@
+# analysis report delete
+
+Use when the user explicitly wants to delete one or more saved reports.
+
+Do not use without first confirming the target report IDs through `report list` or user-provided exact IDs.
+
+Command:
+
+```bash
+ae-cli analysis report delete --project-id <project_id> --report-ids '[1001,1002]' --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis report delete --project-id <project_id> --report-ids '[1001,1002]' --yes
+```
+
+Input sends `project_id` and `report_ids`. Use an array even for one report.
+
+Output is the gateway envelope. `data` contains deleted `report_ids` and `deleted_count`.

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

@@ -0,0 +1,21 @@
+# analysis report get
+
+Use when the user needs one saved report definition as AI QP without executing the report.
+
+Do not use as a workaround after a builder-supported ad-hoc QP builder fails. For builder failure, stop and handle the structured error or ask for clarification.
+
+Command:
+
+```bash
+ae-cli analysis report get --project-id <project_id> --report-id <report_id>
+```
+
+Input sends `project_id` and `report_id`.
+
+Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
+
+This read is mandatory before applying report-data overrides. Branch on `data.model_type`:
+
+- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter.
+- non-SQL analysis models: use `--filters`, `--group-by`, `--start-time`, `--end-time`, or `--time-granularity`; do not send `--sql-params`.
+- `tag`: report-data executes the saved tag definition. For a different tag view, use `analysis history-tag-data run/export`.

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

@@ -0,0 +1,17 @@
+# analysis report list
+
+Use when the user needs to find reports they can access in a project, with optional keyword search, semantic model filtering, field projection, and inline pagination.
+
+Do not use for report data execution or report definition writes. Use `report-data run/export` for data and `report create/update` for writes.
+
+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]
+```
+
+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.
+
+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.

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

@@ -0,0 +1,15 @@
+# analysis report list-export
+
+Use when the user needs to export the full accessible report catalog or a larger catalog than inline pagination should return.
+
+Do not use for report data values. Use `report-data export` when the output should be report result data, not catalog metadata.
+
+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]
+```
+
+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.
+
+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

@@ -0,0 +1,22 @@
+# analysis report update
+
+Use when the user explicitly wants to update saved report metadata or replace its AI QP definition.
+
+Do not use raw QP, `qp`, `report_model`, or `analysis_query`. When changing the definition, pass `model_type` and AI QP `definition` together.
+
+Read [`ai_models.md`](ai_models.md) for the single AI-facing model registry. Report update supports the 12 analysis models plus `tag` for saved tag report data.
+
+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 '{...}'
+```
+
+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.
+
+Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
+
+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.
+
+After a successful update, call `analysis_common +get_resource_url` with the updated `report_id` and output its `markdown_link`.

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

@@ -0,0 +1,15 @@
+# analysis report-version rollback
+
+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.
+
+Command:
+
+```bash
+ae-cli analysis report-version rollback --project-id <project_id> --report-id <report_id> --target-version <version>
+```
+
+Input sends `project_id`, `report_id`, and target `version` from CLI `--target-version`.
+
+Output is the gateway envelope. `data` contains `report_id`, `rolled_back`, `target_version`, and `previous_version`.

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

@@ -0,0 +1,27 @@
+# analysis-governance rule create
+
+Use when the user needs to create an asset governance rule through the capability gateway.
+
+Do not use it when a matching saved rule already exists; list rules first and use `rule-update` for an existing `rule_id`.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule create --project-id <project_id> --payload '{}'
+ae-cli analysis-governance rule create --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.create.
+
+Input sends project_id, payload, rule_name, comment, rule. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data.rule_id` is the created governance rule identity. Preserve it for later update/delete operations.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --rule-name | No | Rule name; required unless provided inside payload. |
+| --comment | No | Rule comment. |
+| --rule | No | Governance Filter JSON; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -0,0 +1,26 @@
+# analysis-governance rule delete
+
+Use when the user needs to delete an asset governance rule through the capability gateway.
+
+Do not use it to disable a rule or with a guessed ID; resolve the saved rule, dry-run the final deletion, and require explicit confirmation.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule delete --project-id <project_id> --payload '{}' --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-governance rule delete --project-id <project_id> --payload '{}' --yes
+```
+
+Capability id: analysis_meta.asset_rule.delete.
+
+Input sends project_id, payload, rule_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data.deleted` reports whether the identified rule was deleted; `false` must not be presented as a successful deletion.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --rule-id | No | Rule ID; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -0,0 +1,24 @@
+# analysis-governance rule list
+
+Use when the user needs to list asset governance rules through the capability gateway.
+
+Do not use it to discover rule field syntax; use `rule-schema` for construction metadata and this command for existing rule IDs and definitions.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule list --project-id <project_id>
+ae-cli analysis-governance rule list --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.list.
+
+Input sends project_id, payload. 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.
+
+## 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. |

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

@@ -0,0 +1,24 @@
+# analysis-governance rule schema
+
+Use when the user needs to get asset governance rule field schema through the capability gateway.
+
+Do not use it to list saved governance rules; use it before create/update only when the allowed rule fields or operators are unknown.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule schema --project-id <project_id>
+ae-cli analysis-governance rule schema --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.schema.
+
+Input sends project_id, payload. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the project-specific rule column/operator schema consumed by the `rule` object in rule create and update commands.
+
+## 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. |

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

@@ -0,0 +1,28 @@
+# analysis-governance rule update
+
+Use when the user needs to update an asset governance rule through the capability gateway.
+
+Do not use it to create a new rule or guess a rule ID; resolve the existing rule with `rule-list` before updating its full definition.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule update --project-id <project_id> --payload '{}'
+ae-cli analysis-governance rule update --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.update.
+
+Input sends project_id, payload, rule_id, rule_name, comment, rule. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` returns the updated `rule_id` and `updated=true`; a missing rule is an operation failure, not a create fallback.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --rule-id | No | Rule ID; required unless provided inside payload. |
+| --rule-name | No | Rule name; required unless provided inside payload. |
+| --comment | No | Rule comment. |
+| --rule | No | Governance Filter JSON; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -1,10 +1,16 @@
 # analysis run inspect
 
-Use after an export command returns `run_id`.
+Inspect an async analysis capability-gateway run returned by export commands.
 
-Do not use for MCP query cancellation or old `request_id` lifecycle. This is only for capability-gateway export `run_id`.
+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`.
 
-Command:
+Do not use this for MCP `request_id` cancellation or status. MCP query lifecycle uses the specific MCP command contract.
+
+Input:
+
+- `run_id`: required async run ID returned by the export response.
+
+Use the exact `run_id` from the same export response that supplied the artifact; do not substitute a request ID, invocation ID, path segment, or an older run ID.
 
 ```bash
 ae-cli analysis run inspect --run-id <run_id>
@@ -12,7 +18,7 @@ ae-cli analysis run inspect --run-id <run_id>
 
 Input sends `run_id`.
 
-Output is the gateway envelope. `data` contains run status, artifact status, and error fields when the run failed.
+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:
 

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

@@ -8,6 +8,9 @@ Domain: **Project Configuration**
 - Create/update TRACKING-PLAN metadata only (planned bury items). Do not use this tool to create or edit effective system metadata. If the user intent is production metadata changes, route to MetaPowerTool instead.
 - Create/update TRACKING-PLAN metadata only (planned bury items).
 
+## Output
+The response reports persistence of the submitted tracking-plan items. Read the plan back with `+get_track_program` before claiming the saved structure is effective.
+
 ## Command
 ```bash
 ae-cli analysis_meta +save_track_items --project_id <project_id> --track_data '{}'
@@ -24,7 +27,7 @@ ae-cli analysis_meta +save_track_items --dry-run
 - First run should only pass the required parameters (`--project_id`, `--track_data`), and add optional parameters only after the path is confirmed to work.
 - Wrap JSON arguments in single quotes (for example `--track_data '{}'`) to avoid shell escaping issues.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep the confirmation prompt by default; re-evaluate whether to use `--yes` in automation scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps After Failure
 - If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id` and `--track_data`).

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

@@ -0,0 +1,20 @@
+# analysis sql-table columns
+
+List queryable columns for one server-authorized SQL table.
+
+First call `analysis sql-table list --project-id <project_id>`, then copy an exact returned `table_ref`. Do not guess table or column names.
+
+```bash
+ae-cli analysis sql-table columns \
+  --project-id <project_id> \
+  --table-ref <table_ref> \
+  [--usage analysis|tag_cluster]
+```
+
+The result identifies the resolved catalog/schema/table and returns its columns with machine names, types, and available descriptions. A unique table-only reference is accepted; ambiguous references fail with candidate tables instead of selecting one arbitrarily.
+
+Pass the same `usage` used for `sql-table list`. For SQL tags and SQL clusters this must be `--usage tag_cluster`; the default is `analysis`.
+
+When copying returned columns into Trino SQL, delimit identifiers containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` or `"$part_event"`. Single quotes are string literals. The CLI does not auto-rewrite SQL.
+
+If the selected table is an event table, the SQL must 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 apply this rule to a table whose discovered columns do not include `$part_date`.

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

@@ -0,0 +1,33 @@
+# analysis sql-table list
+
+List the server-authoritative SQL table references that the current user may query in one project.
+
+## Command
+
+```bash
+ae-cli analysis sql-table list \
+  --project-id <project_id> \
+  [--query <keyword>] \
+  [--limit <1-200>] \
+  [--offset <next_offset>] \
+  [--usage analysis|tag_cluster]
+```
+
+## Contract
+
+- 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`.
+- 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`.
+- An empty list means the current identity has no queryable SQL tables in that project; do not fabricate a table name.
+
+## Example workflow
+
+```bash
+ae-cli analysis sql-table list --project-id 1 --query user
+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"}'
+```
+
+Use the exact `table_ref` returned by the first command; the example reference is illustrative only.

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

@@ -37,7 +37,7 @@ ae-cli analysis +update_alert --dry-run
 - On the first run, start with only the required parameters (`--project_id`, `--alert_id`, `--definition`) and add optional parameters after confirming the path works.
 - Wrap JSON parameters in single quotes (for example `--definition '{}'`) to avoid shell escaping issues.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` for automated scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps on Failure
 - If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--alert_id`, `--definition`).

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

@@ -5,23 +5,21 @@
 Domain: **Metadata Query**
 
 ## Use Cases
-- Before updating `events` / `params`, you must first obtain the corresponding model schema and supplement the project with real event/property metadata.
+- Before updating `events` / `params`, you must supplement the payload with real event/property metadata.
 - Update a metric definition. Currently only the event and retention models are supported. Returns the updated metric information without executing metric calculation.
 - Update a metric definition.
 
 ## MUST Prerequisites
 - Before updating `--events` / `--params`, you must first read and follow these reference documents:
-  - [`./get_analysis_query_schema.md`](./get_analysis_query_schema.md)
   - [`./list_events.md`](./list_events.md)
   - [`./list_properties.md`](./list_properties.md)
 - Do not submit new `events` / `params` until the document review and prerequisite command calls above are complete.
 
 ## Prerequisite Call Chain (Required for Updating events/params)
 1. Determine `--model_type` first (`event` / `retention`).
-2. Read `get_analysis_query_schema.md`, then call `ae-cli analysis +get_analysis_query_schema --model_type <event|retention>` to get the structure.
-3. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>`.
-4. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>`.
-5. Build the new `events` / `params` from the schema + metadata, then execute `+update_metric`.
+2. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>`.
+3. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>`.
+4. Build the new `events` / `params` from the metric API payload shape and verified metadata, then execute `+update_metric`.
 
 ## Commands
 ```bash
@@ -39,23 +37,22 @@ ae-cli analysis_meta +update_metric --dry-run
 | `--display_name` | Yes | Metric display name |
 | `--remark` | No | Optional metric remark |
 | `--model_type` | Yes | Metric model type. Currently supports event and retention. |
-| `--events` | Yes | Metric event JSON. MUST follow `+get_analysis_query_schema` for the selected `model_type`, and use fields validated by `analysis_meta +list_events` / `analysis_meta +list_properties` in the same `project_id`. |
-| `--params` | No | Metric params JSON. If provided, MUST follow the schema from `+get_analysis_query_schema` and use project metadata from `analysis_meta +list_events` / `analysis_meta +list_properties`. |
+| `--events` | Yes | Metric event JSON. Use fields validated by `analysis_meta +list_events` / `analysis_meta +list_properties` in the same `project_id`. |
+| `--params` | No | Metric params JSON. If provided, use project metadata from `analysis_meta +list_events` / `analysis_meta +list_properties`. |
 
 ## Decision Rules
-- `events` / `params` must not be handwritten by intuition alone: they must satisfy both the schema structure and the project's real metadata constraints.
+- `events` / `params` must not be handwritten by intuition alone: they must satisfy the metric API payload shape and the project's real metadata constraints.
 - Set `--model_type` first, then use the matching schema; do not mix event/retention structures.
 - Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
-- For the first run, pass only the required parameters (`--project_id`, `--metric_id`, `--name`) to confirm the path works, then add optional parameters.
+- The smallest valid request still requires `--project_id`, `--metric_id`, `--name`, `--display_name`, `--model_type`, and `--events`; do not omit the new definition to “test the path.” Use `--dry-run` with the complete request for preflight.
 - Wrap JSON parameters in single quotes (for example `--events '{}'` and `--params '{}'`) to avoid shell escaping issues.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep confirmation prompts by default; evaluate whether to use `--yes` only for automation scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--metric_id`, and `--name`).
-- If `Invalid JSON` appears, first check the schema's required fields, then verify whether the event and property names come from metadata query results in the same `project_id`.
+- If required parameters are missing, complete all required fields listed above before retrying.
+- If `Invalid JSON` appears, first check required fields, then verify whether the event and property names come from metadata query results in the same `project_id`.
 - If the result after writing does not match expectations, immediately reread the corresponding list/get interfaces for before-and-after comparison.
 
 ## Recommended Chaining
-- +get_analysis_query_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +update_metric
 - +list_metrics -> +get_metric -> +update_metric

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Update an existing project date marker. Returns the updated marker ID, timestamp, content, and visibility status.
 - Update an existing project date marker.
+- Do not use it to create a marker or change analysis data; use `+create_project_mark_time` for a new marker.
 
 ## Command
 ```bash
@@ -26,13 +27,13 @@ ae-cli analysis_meta +update_project_mark_time --dry-run
 | `--is_visible` | No | Whether the marker is visible. Default: 1 |
 
 ## Decision Rules
-- First run should only pass required parameters (`--mark_time_id`, `--project_id`, `--marked_at`), and add optional parameters only after the path is confirmed to work.
+- The smallest valid request also includes required `--content`; use `--dry-run` with `--mark_time_id`, `--project_id`, `--marked_at`, and `--content` before executing.
 - For date/time ranges, first validate with a short range, then expand the range step by step.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep the confirmation prompt by default; re-evaluate whether to use `--yes` in automation scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--mark_time_id`, `--project_id`, and `--marked_at`).
+- If required parameters are missing, supply `--mark_time_id`, `--project_id`, `--marked_at`, and `--content` before retrying.
 - If the result after writing is not as expected, immediately read back the corresponding list/get interface for a before-and-after comparison.
 
 ## Recommended Chaining

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

@@ -0,0 +1,15 @@
+# analysis user-cluster create
+
+Create a condition or SQL user cluster directly from an AI-facing definition request.
+
+Do not use it for uploaded-ID clusters or result-derived clusters; use `user-cluster create-id` or `query create-result-cluster`. A successful create automatically starts the initial computation. Do not immediately call `user-cluster refresh`; use `user-cluster get` to observe the initial refresh/computation status and refresh only for a later explicit recomputation.
+
+Flags: `--project-id`, `--cluster-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The cluster type comes from `definition_request.type`.
+
+Read `user_cluster_models.md` before constructing `--definition-request`. Create does not accept `--remark`; set it later with `user-cluster update` when needed.
+
+The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the cluster. Condition clusters are saved as mixed-condition clusters (`clusterType=CONDITION`, `clusterSubType=MIX_CONDITION`).
+
+```bash
+ae-cli analysis user-cluster create --project-id <project_id> --cluster-name retained_users --display-name "Retained Users" --definition-request '{"type":"condition","conditions":{"relation":"and","items":[{"type":"user","field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster create-id
+
+Create a cluster by mapping imported values to an analysis entity.
+
+Flags: `--project-id`, `--display-name`, and `--entity-id` are required. Prefer `--input-file <local_csv>`; the CLI uploads it automatically. `--input-file-id` resumes from an existing upload, while `--file-content` is only for small local tests. Exactly one of the three is allowed. Optional: `--cluster-name`, `--remarks`, and conditional `--association-property`.
+
+Use `--input-file` for real local files; use `--input-file-id` only when resuming from an existing upload. Do not inline large ID lists.
+
+Run `analysis entity id-import-options` first. For the primary user entity, pass an allowed `--association-property` and put its real values in the single CSV column; `#user_id` is forbidden. For a non-primary entity, omit the flag and put that entity's own IDs in the single column. Every row must be non-empty.
+
+Create returns `operation_status=PROCESSING` and `match_summary_status=PENDING`; it does not report submission-time counters as final matching results. Poll `user-cluster get` until progress is 100 for the final `match_summary`.
+
+```bash
+ae-cli analysis user-cluster create-id --project-id <project_id> --display-name "VIP IDs" --entity-id <entity_id> --association-property email --input-file /tmp/vip.csv --cluster-name vip_ids
+```