@thinkingai/ae-cli 6.1.19 → 6.1.21

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

@@ -0,0 +1,84 @@
+# Cross-source asset configuration (L3)
+
+Use this workflow for Asset Center → Cross-source asset configuration when the user has or can prepare an Excel configuration workbook. The CLI scope is intentionally limited to upload and validation. Do not use it for row-by-row configuration creation, editing, deletion, template export, source preview, or enum management.
+
+## Discover the deployed contract
+
+```bash
+ae-cli capability search "cross_source_config" --domain metadata --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.upload --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.check --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.check_status --project-id <project_id>
+ae-cli analysis input-file purpose list --project-id <project_id>
+```
+
+The expected catalog contains only:
+
+- `metadata.cross_source_config.upload`
+- `metadata.cross_source_config.list`
+- `metadata.cross_source_config.check`
+- `metadata.cross_source_config.check_status`
+
+Use the **metadata** namespace; it routes through the analysis gateway. The deployed catalog and each capability's `input_schema` are authoritative. If upload purpose or a capability is unavailable, report that the Host has not deployed this workflow. Do not fall back to page REST, MCP, browser tokens, or direct database writes.
+
+## Upload a workbook
+
+1. Prepare the product-compatible XLS/XLSX configuration workbook from the user's source table and mapping requirements. If the workbook format is uncertain, obtain a current sample or use the page documentation before writing it; do not guess sheet names or column headers.
+2. Upload the bytes once:
+
+   ```bash
+   ae-cli analysis input-file upload \
+     --project-id <project_id> \
+     --purpose cross_source_config.workbook \
+     --file ./configured.xlsx
+   ```
+
+3. Retain `data.input_file_id`. It is bound to the authenticated user, project, purpose, and expiry. A local path is never an `input_file_id`.
+4. Inspect the upload capability, then execute it once:
+
+   ```bash
+   ae-cli capability run metadata.cross_source_config.upload \
+     --input '{"project_id":<project_id>,"input_file_id":"<input_file_id>","lang":"zh"}'
+   ```
+
+Upload is a synchronous call to the same import service used by the Asset Center page. It creates new route codes and updates existing route codes contained in the workbook. It does not delete configurations absent from the workbook. Because an existing route can be replaced, `upload` is `high-risk-write` and requires user review before execution. Use the CLI confirmation prompt interactively; in non-interactive execution, append the global `--yes` flag only after the exact upload has been authorized.
+
+`status=success` means workbook parsing and persistence completed. If `requires_review=true`, inspect `result.fail` and open `page_url`. An error response keeps the business result in `meta.business_result`. Do not automatically retry after a timeout or lost response; call `list` and inspect the page first.
+
+## Validate uploaded configurations
+
+List configurations to resolve real IDs and current states:
+
+```bash
+ae-cli capability run metadata.cross_source_config.list \
+  --input '{"project_id":<project_id>}'
+```
+
+Submit validation only for explicit IDs from that project:
+
+```bash
+ae-cli capability run metadata.cross_source_config.check \
+  --input '{"project_id":<project_id>,"ids":[<route_id>]}'
+```
+
+Then poll the same ID set with a bounded interval:
+
+```bash
+ae-cli capability run metadata.cross_source_config.check_status \
+  --input '{"project_id":<project_id>,"ids":[<route_id>]}'
+```
+
+Interpret the aggregate fields before reading individual `items`:
+
+- `status=checking`, `completed=false`: wait and poll again.
+- `status=un_checked`, `completed=false`: validation has not been submitted for every selected configuration; `next_action=check`.
+- `status=check_success`, `completed=true`, `successful=true`: all selected configurations passed.
+- `status=check_fail`, `completed=true`, `successful=false`: inspect each item's `msg_map` and open `page_url`.
+
+A successful gateway envelope only means the read succeeded. Validation passes only when `successful=true`. Do not resubmit `check` while a selected configuration is already `checking`.
+
+## Page handoff
+
+`list`, `upload`, `check`, and `check_status` return `page_path`. ae-cli converts it to a Host-qualified `page_url`. Surface this URL after upload warnings, validation failures, or whenever the user asks to review the configurations visually.
+
+Gateway `validate` and `dry-run` validate input, project scope, selected IDs, and uploaded-file ownership. They do not parse/import the workbook or start configuration validation.

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

@@ -2,16 +2,16 @@
 
 Submit dashboard report data as a downloadable async artifact. Dashboard report data follows report-data model coverage: the 12 analysis report models from `ai_models.md` plus tag report data.
 
-Typical closed loop: find the dashboard and target reports -> resolve exact filters and optional physical route -> submit export -> preserve IDs -> inspect -> download the completed artifact -> verify actual route fields inside the exported result.
+Reuse the selected dashboard and report IDs, resolve any unknown filters or requested physical route, then export with `--output <file>`. Read actual route fields from the exported result.
 
-Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `dashboard-report-data run`.
+For full data, read [export handling](analysis_data_export.md) and use this `export` command instead of `dashboard-report-data run`.
 
 Do not use this command for bounded inline previews; use `dashboard-report-data run` when the requested result fits the sync data retrieval rule.
 
 Command:
 
 ```bash
-ae-cli analysis dashboard-report-data export --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--cluster-query-scope GLOBAL|SLAVE] [--slave-cluster-id <id>] [--artifact-format jsonl]
+ae-cli analysis dashboard-report-data export --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--cluster-query-scope GLOBAL|SLAVE] [--slave-cluster-id <id>] [--artifact-format jsonl] --output <file>
 ```
 
 Omit cluster routing to follow the saved dashboard configuration. For an explicit route, use `GLOBAL` or `SLAVE` plus one physical cluster ID returned by `analysis query-cluster list`. SQL reports reject effective `GLOBAL`. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is only the CLI output formatter.
@@ -24,18 +24,10 @@ Omit cluster routing to follow the saved dashboard configuration. For an explici
 
 Dashboard `filters`, `start_time`, and `end_time` do not apply to SQL reports. Export still completes with SQL report data; the JSONL result object includes `warnings[]` with `OVERRIDE_IGNORED_FOR_MODEL`, affected SQL `report_ids`, and `ignored_fields`. Query SQL reports directly with report-data `--sql-params` when SQL conditions must change.
 
-Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, `effective_zone_offset` (the timezone actually selected for the export), status fields, and expiration fields. Exports do not create `query_context_id`. It does not expose inspect/download API paths; use the CLI commands below.
+Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, `effective_zone_offset` (the timezone actually selected for the export), status fields, and expiration fields. Exports do not create `query_context_id`. The CLI handles waiting and download through `--output`.
 
 An empty artifact is successful and means the requested time range has no data. The run reaches `FAILED` only when every returned dashboard report entry contains an explicit execution error. Mixed dashboard exports retain successful data and explicit per-report failure entries.
 
 Never use the export response or downloaded rows as a drilldown/result-cluster source. Run a bounded synchronous dashboard report preview containing the desired cell first.
 
-Follow-up workflow:
-
-1. Save `data.run_id` and `data.artifact_id` from the export response.
-2. Poll status with `ae-cli analysis run inspect --run-id <run_id>`.
-3. Continue polling while status is running or pending. Treat `COMPLETED` or `SUCCEEDED` as success, and `FAILED`, `CANCELED`, or `CANCELLED` as terminal failure.
-4. On success, download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>`.
-5. If the export is no longer needed, cancel with `ae-cli analysis query cancel --run-id <run_id>`.
-
-Do not write custom Python/curl for polling or download unless the CLI command itself is unavailable.
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).

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

@@ -37,4 +37,4 @@ Output is the gateway envelope. Verify `data.actual_cluster_query_scope`, option
 
 An empty dashboard 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 dashboard batches keep successful data and return `meta.partial`, counts, and per-report `meta.failures`.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Fetch the selected report source with `analysis query-context get` and merge only its returned coordinate fragments for the advertised action. Do not pass raw QP.
+Only when the user requests a supported follow-up action, read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Fetch the selected report source with `analysis query-context get` and merge only its returned coordinate fragments for the advertised action. Do not pass raw QP.

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

@@ -1,6 +1,6 @@
 # analysis dashboard update
 
-Use when the user wants to update dashboard settings in batch, upsert a dashboard note, or replace the dashboard-level business filter.
+Use when the user wants to update dashboard settings in batch, upsert a dashboard note, save a dashboard-wide or personal default filter, or replace the dashboard-level business filter.
 
 Do not use for moving/copying dashboards. Use `dashboard copy`, `dashboard handover`, or the relevant project-space/folder command.
 
@@ -10,8 +10,9 @@ Command:
 ae-cli analysis dashboard update --project-id <project_id> --operation settings --dashboard-ids '[1001,1002]' [--zone-offset 8] [--payload '{...}']
 ae-cli analysis dashboard update --project-id <project_id> --operation settings --dashboard-id <dashboard_id> --refresh-type 1 --dashboard-status normal --payload '{"dashboard_job_schedule":"0 0 8 * * ?","time_config_open":true,"time_config":{},"cache_config":{},"schedule_ui_config":{}}'
 ae-cli analysis dashboard update --project-id <project_id> --operation note-upsert --dashboard-id <dashboard_id> [--note-id <note_id>] [--note-title <title>] [--description <text>]
-ae-cli analysis dashboard update --project-id <project_id> --operation default-filter --dashboard-id <dashboard_id> --filter-name <name> --filter '{"junction_kind":"and","ta_filters":[...]}'
-ae-cli analysis dashboard update --project-id <project_id> --operation business-filter --dashboard-id <dashboard_id> --filter '{"junction_kind":"and","ta_filters":[...]}'
+ae-cli analysis dashboard update --project-id <project_id> --operation default-filter --dashboard-id <dashboard_id> --filter-name <name> --filter '{"junction_kind":"and","ta_filters":[{"filter_type":"SIMPLE","column_name":"app","table_type":"1","select_type":"string","calcu_symbol":"C00","ftv":["X"]}]}'
+ae-cli analysis dashboard update --project-id <project_id> --operation personal-default-filter --dashboard-id <dashboard_id> --filter-name <name> --filter '{"junction_kind":"and","ta_filters":[{"filter_type":"SIMPLE","column_name":"app","table_type":"1","select_type":"string","calcu_symbol":"C00","ftv":["X"]}]}'
+ae-cli analysis dashboard update --project-id <project_id> --operation business-filter --dashboard-id <dashboard_id> --filter '{"junction_kind":"and","ta_filters":[{"filter_type":"SIMPLE","column_name":"app","table_type":"1","select_type":"string","calcu_symbol":"C00","ftv":["X"]}]}'
 ```
 
 For `operation=settings`:
@@ -22,10 +23,20 @@ For `operation=settings`:
 - `zone_offset` is an integer hour offset from `-12` to `14`;
 - complex settings belong in snake_case `payload`: `reports_version` string, `dashboard_job_schedule` string, `time_config_open` boolean, and object fields `time_config`, `cache_config`, `schedule_ui_config`; `ui_config` may be a string or object.
 
-For `operation=note-upsert`, pass `dashboard_id`; omit `note_id` to create a note or pass it to update an existing note. Do not mix note fields with batch settings fields.
+For `operation=note-upsert`, `dashboard_id` is required. Omit `note_id` to create a note attached to that dashboard, or pass it to update an existing note. A created note defaults missing `note_title` and `description` to empty strings. An update preserves `note_title`, `description`, and `ui_config` when the corresponding field is omitted; pass an explicit empty string to clear text. Do not mix note fields with batch settings fields.
 
 For `operation=default-filter`, pass one `dashboard_id`, `filter_name`, and `filter`. This saves a favorite filter and enables it as the dashboard-wide default filter; it is distinct from the current caller's personal default filter.
 
+For `operation=personal-default-filter`, pass one `dashboard_id`, `filter_name`, and `filter`. This saves a favorite filter owned by the current caller and enables it as that caller's personal default for the dashboard. It does not change the dashboard-wide default filter or another user's personal default.
+
 For `operation=business-filter`, pass one `dashboard_id` and a `filter` object in snake_case QP form. This replaces the dashboard-level business filter saved in `ta_dashboard_business_filter`; it is not a condition-filter favorite or a space-level filter. Each simple condition uses fields such as `filter_type`, `column_name`, `table_type`, `column_type`, `select_type`, `calcu_symbol`, `ftv`, and `lack_value`. A condition with `lack_value=true` is saved as a selectable field but does not restrict query data. Pass `{"junction_kind":"and","ta_filters":[]}` to clear all dashboard-level business-filter conditions.
 
 Output is the gateway envelope. `data` contains the update result.
+
+### Raw QP filter contract
+
+All three filter operations require raw QP, not report-intent filters. The root is an object with `junction_kind` (`"and"` or `"or"`) and a `ta_filters` array. Each SIMPLE condition requires `filter_type`, `column_name`, `table_type`, `select_type`, and `calcu_symbol` (the operator may be omitted only when `lack_value:true`). `table_type` is a string code: `"0"` event, `"1"` user, `"2"` cluster/tag. Metadata API names `event` / `user` are not valid here. Equality uses `calcu_symbol:"C00"` and `ftv:["X"]`; `filter_type:"equal"`, `property_name`, `property_type`, `operator`, and `values` are not accepted.
+
+A compound condition is `{"filter_type":"COMPOUND","relation":"1","filts":[...]}` (`"1"` = and, `"0"` = or). Children follow the same raw QP contract. Existing scalar `ftv` values are also supported; existence and boolean operators do not require a value. `lack_value:true` preserves a selectable field without applying a comparison; it may omit `calcu_symbol` and `ftv`. A SIMPLE condition may omit `filts` or set it to null, while COMPOUND requires an array.
+
+Common validates the dashboard filter format on the server; ae-cli forwards the filter without local QP validation. Follow the contract above when constructing input. Use `capability inspect analysis.dashboard.update` to inspect the target environment's schema, and use `--validate` when server-side parameter validation is needed. Both command entry points preserve explicit server `error.type:"validation"` errors, including the returned hint and metadata. Correct the input using those details before retrying. After writing, read back the dashboard and verify condition fields, operators, and values instead of relying only on `ok:true`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta datatable columns-get --project-id <project_id> --table-ref <table_ref>
-ae-cli analysis-meta datatable columns-get --dry-run
 ```
 
 Capability id: `metadata.data_table.columns_get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta datatable influence-list --project-id <project_id> --datatable-id <datatable_id>
-ae-cli analysis-meta datatable influence-list --dry-run
 ```
 
 Capability id: `metadata.data_table.influence_list`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta datatable version-get --project-id <project_id> --version-id <version_id>
-ae-cli analysis-meta datatable version-get --dry-run
 ```
 
 Capability id: `metadata.data_table_version.get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta datatable version-list --project-id <project_id> --datatable-id <datatable_id> --limit 50 --offset 0
-ae-cli analysis-meta datatable version-list --dry-run
 ```
 
 Capability id: `metadata.data_table_version.list`.

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

@@ -11,8 +11,7 @@ ae-cli tracking debug-device add --project-id <project_id> --device-id <device_i
 
 Capability id: `tracking.debug_device.add`.
 
-Input sends `project_id`, `device_id`, and `device_name`. Prefer a stable device ID that the validation script can reuse. After creation, select the same device with `tracking debug-device select`.
-The result confirms that the device was created or updated; use `debug-device list` to verify the saved device before selecting it.
+Input sends `project_id`, `device_id`, and `device_name`. Prefer a stable device ID that the validation script can reuse. The response confirms creation or update; reuse that result. Select the device with `tracking debug-device select` only when the task needs it as the active Debug device.
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 Stream the complete users or custom entities behind one selected synchronous-preview coordinate as a `csv.gz` artifact.
 
-Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) and first validate the coordinate with the corresponding synchronous preview/`drilldown-entities run` path. The export consumes an existing sync-preview context; it never creates a query context or additional drilldown choices.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) and select the coordinate from the existing synchronous query context. The export consumes an existing sync-preview context; it never creates a query context or additional drilldown choices.
 
 ```bash
 ae-cli analysis drilldown-entities export \
@@ -12,7 +12,7 @@ ae-cli analysis drilldown-entities export \
   --coordinate '<same returned coordinate>' \
   [--properties '[{...}]'] \
   [--artifact-format csv] \
-  [--timeout-seconds 21600]
+  [--timeout-seconds 21600] --output <file>
 ```
 
 `--project-id` must match the project stored by `query_context_id`; a mismatch is rejected before export execution.
@@ -24,6 +24,6 @@ Property support matches the synchronous preview exactly:
 
 `#user_id` is an internal association key. When presenting downloaded user rows to a customer, Agents should display account ID and visitor ID by default rather than using `#user_id` as the only visible identity.
 
-This command does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`. Common executes one full-download query and streams it directly into the artifact; it does not repeatedly call the synchronous preview. “Complete” follows the platform full-download ceiling (`model_full_download_limit`). Inspect `run_id`, then download only after completion.
+This command does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`. Common executes one full-download query and streams it directly into the artifact; it does not repeatedly call the synchronous preview. “Complete” follows the platform full-download ceiling (`model_full_download_limit`). Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with the returned `run_id` and `--output <file>`.
 
 The file is durable member data, not a new interactive result. Do not use rows in the downloaded artifact to construct another analysis coordinate. User event continuation requires the `drilldown_context_id` and canonical `user_id` returned by a user-subject `drilldown-entities run`, not this export.

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

@@ -12,7 +12,8 @@ ae-cli analysis drilldown-events export \
   --coordinate '<same returned coordinate>' \
   [--properties '[{"columnName":"<event_property_name>","tableType":"event"}]'] \
   [--artifact-format csv] \
-  [--timeout-seconds 21600]
+  [--timeout-seconds 21600] \
+  --output <file>
 ```
 
 `--project-id` must match the project stored by `query_context_id`; a mismatch is rejected before export execution.
@@ -21,4 +22,4 @@ This command does not accept `--limit`, `--offset`, `--page-num`, or `--page-siz
 
 When `--properties` is present, the artifact contains required system event columns plus exactly the requested event properties. The export and synchronous preview use the same projection contract.
 
-Inspect `run_id`, wait for completion, then download the bound artifact. The downloaded rows are durable event detail only; they do not create or enlarge the interactive drilldown coordinate set.
+Use `--output` to wait and download the completed artifact. If interrupted, resume with [`analysis run wait`](run_wait.md) using the returned `run_id` and `--output <file>`. The downloaded rows are durable event detail only; they do not create or enlarge the interactive drilldown coordinate set.

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

@@ -12,7 +12,7 @@ ae-cli analysis drilldown-user-events export \
   [--properties '[{"columnName":"<event_property_name>","tableType":"event"}]'] \
   [--sort-order desc] \
   [--artifact-format csv] \
-  [--timeout-seconds 21600]
+  [--timeout-seconds 21600] --output <file>
 ```
 
 `--project-id` must match the project stored by `drilldown_context_id`; a mismatch is rejected before export execution.
@@ -26,6 +26,6 @@ preserves the machine date coordinates returned by the source query together
 with that query's time granularity, such as daily, weekly, or monthly. Do not
 construct dates outside that context or force a daily granularity.
 
-Inspect the returned `run_id` with `analysis run inspect`, then download the completed artifact with `analysis artifact download`.
+Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with the returned `run_id` and `--output <file>`.
 
 Output is an async run/artifact descriptor. The complete event rows exist only in the downloaded artifact; they cannot be used as new analysis coordinates.

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

@@ -2,7 +2,7 @@
 
 Submit a bounded entity detail query as an async gzip artifact.
 
-Read `analysis_data_retrieval.md` first. The submit response returns `run_id` and `artifact_id`; poll with `analysis run inspect`, then download with `analysis artifact download`.
+Read `analysis_data_retrieval.md` for the run/export choice. Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with the returned `run_id` and `--output <file>`.
 
 Use this command for full or unknown-size entity detail data. Common reads backend batches internally and writes one artifact.
 
@@ -10,12 +10,13 @@ Use this command for full or unknown-size entity detail data. Common reads backe
 ae-cli analysis entity-detail export \
   --project-id <project_id> \
   --definition '{"entity":"user","cohort":{"relation":"and","items":[{"field":{"name":"level","type":"user_property"},"operator":"gte","values":[1]}]}}' \
-  --artifact-format jsonl
+  --artifact-format jsonl --output <file>
 ```
 
 Input:
 - `--project-id` numeric project ID.
 - `--definition` same bounded entity detail shape as `entity-detail run`.
+- `--intent-snapshot` optional local snapshot containing `schema_version: 1`, non-empty `requirement`, and the exact final `definition`; omit `model_type` for detail commands. It checks JSON drift locally and is never sent to Gateway. A passing check does not establish user confirmation or correct business semantics.
 - `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
 - `--use-cache` optional boolean.
 - `--zone-offset` optional number.

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

@@ -16,6 +16,7 @@ ae-cli analysis entity-detail run \
 Input:
 - `--project-id` numeric project ID.
 - `--definition` bounded entity detail JSON object with `entity`, `cohort`, optional `properties`, and optional `sort`.
+- `--intent-snapshot` optional local snapshot containing `schema_version: 1`, non-empty `requirement`, and the exact final `definition`; omit `model_type` for detail commands. It checks JSON drift locally and is never sent to Gateway. A passing check does not establish user confirmation or correct business semantics.
 - `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
 - `--use-cache` optional boolean.
 - `--zone-offset` optional number.

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

@@ -1,25 +1,23 @@
 # tracking event-blacklist add
 
-Use when add events to tracking event blacklist.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to add events to tracking event blacklist.
 
 Command:
 
 ```bash
-ae-cli tracking event-blacklist add [options]
+ae-cli tracking event-blacklist add --project-id <project_id> --event-names '<event_names>'
 ```
 
 Capability id: `tracking.event_blacklist.add`
 
 Input sends `project_id` and `event_names`. Do not send 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.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--event-names` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
+| `--event-names` | JSON array of event names. | Yes |
 

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

@@ -1,24 +1,22 @@
 # tracking event-blacklist list
 
-Use when list tracking event blacklist configuration.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to list tracking event blacklist configuration.
 
 Command:
 
 ```bash
-ae-cli tracking event-blacklist list [options]
+ae-cli tracking event-blacklist list --project-id <project_id>
 ```
 
 Capability id: `tracking.event_blacklist.list`
 
 Input sends `project_id`. Do not send 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.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
 

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

@@ -1,26 +1,24 @@
 # tracking event-blacklist update
 
-Use when update tracking event blacklist config.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to update tracking event blacklist config.
 
 Command:
 
 ```bash
-ae-cli tracking event-blacklist update [options]
+ae-cli tracking event-blacklist update --project-id <project_id> --event-names '<event_names>' --type <type>
 ```
 
 Capability id: `tracking.event_blacklist.update`
 
 Input sends `project_id`, `event_names`, and `type`. Do not send 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.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--event-names` | See command help | Yes |
-| `--type` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
+| `--event-names` | JSON array of event names. | Yes |
+| `--type` | Blacklist event config type: 0 or 1. | Yes |
 

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event changelog-list --project-id <project_id> --event-name <event_name>
-ae-cli analysis-meta event changelog-list --dry-run
 ```
 
 Capability id: `metadata.event.changelog_list`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event create --project-id <project_id> --payload '{"event_name":"purchase","event_desc":"Purchase","source_type":"<source_type>","source_event_name":"<source_event>"}'
-ae-cli analysis-meta event create --dry-run
 ```
 
 Capability id: `metadata.event.create`.

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

@@ -2,7 +2,7 @@
 
 Submit a bounded event detail query as an async gzip artifact.
 
-Read `analysis_data_retrieval.md` first. The submit response returns `run_id` and `artifact_id`; poll with `analysis run inspect`, then download with `analysis artifact download`.
+Read `analysis_data_retrieval.md` for the run/export choice. Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with the returned `run_id` and `--output <file>`.
 
 Use this command for full or unknown-size event detail data. Common reads backend batches internally and writes one artifact.
 
@@ -10,12 +10,13 @@ Use this command for full or unknown-size event detail data. Common reads backen
 ae-cli analysis event-detail export \
   --project-id <project_id> \
   --definition '{"event":"login","time_range":{"mode":"relative","relative_date_range":"0-7"}}' \
-  --artifact-format jsonl
+  --artifact-format jsonl --output <file>
 ```
 
 Input:
 - `--project-id` numeric project ID.
 - `--definition` same AI-facing shape as `event-detail run`.
+- `--intent-snapshot` optional local snapshot containing `schema_version: 1`, non-empty `requirement`, and the exact final `definition`; omit `model_type` for detail commands. It checks JSON drift locally and is never sent to Gateway. A passing check does not establish user confirmation or correct business semantics.
 - `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
 - `--use-cache` optional boolean.
 - `--zone-offset` optional number.

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

@@ -16,6 +16,7 @@ ae-cli analysis event-detail run \
 Input:
 - `--project-id` numeric project ID.
 - `--definition` AI-facing JSON object. Required keys: `event`, `time_range`. Optional keys: `filters`, `properties`, `sort`.
+- `--intent-snapshot` optional local snapshot containing `schema_version: 1`, non-empty `requirement`, and the exact final `definition`; omit `model_type` for detail commands. It checks JSON drift locally and is never sent to Gateway. A passing check does not establish user confirmation or correct business semantics.
 - `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
 - `--use-cache` optional boolean.
 - `--zone-offset` optional number, for example `8` for UTC+8.

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

@@ -9,7 +9,6 @@ Command:
 ```bash
 ae-cli analysis-meta event export --project-id <project_id> --output <temporary_path>/events.json
 ae-cli analysis-meta event export --project-id <project_id> --queries '["login","sign in"]' --fields '["event_name","event_desc"]' --output <temporary_path>/events.json
-ae-cli analysis-meta event export --dry-run
 ```
 
 Capability id: `metadata.event.export`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event get --project-id <project_id> --event-name <event_name>
-ae-cli analysis-meta event get --dry-run
 ```
 
 Capability id: `metadata.event.get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event hide-update --project-id <project_id> --event-names '["purchase"]' --is-hide true
-ae-cli analysis-meta event hide-update --dry-run
 ```
 
 Capability id: `metadata.event.hide_update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event influence-list --project-id <project_id> --event-name <event_name>
-ae-cli analysis-meta event influence-list --dry-run
 ```
 
 Capability id: `metadata.event.influence_list`.

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

@@ -9,7 +9,6 @@ Command:
 ```bash
 ae-cli analysis-meta event list --project-id <project_id>
 ae-cli analysis-meta event list --project-id <project_id> --queries '["login","sign in"]' --fields '["event_name","event_desc","authentication_status"]' --limit 50 --offset 0 --authenticated-only
-ae-cli analysis-meta event list --dry-run
 ```
 
 Capability id: `metadata.event.list`.

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

@@ -7,26 +7,16 @@ Do not use it for result data, a partial metadata subset, or import. The artifac
 Command:
 
 ```bash
-ae-cli analysis-meta event-property-bundle export --project-id <project_id>
-ae-cli analysis-meta event-property-bundle export --project-id <project_id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 21600
-ae-cli analysis-meta event-property-bundle export --dry-run
+ae-cli analysis-meta event-property-bundle export --project-id <project_id> --output <file>
 ```
 
-Capability id: `metadata.super_metadata.export`.
+Capability id: `metadata.event_property_bundle.export`.
 
 Input sends `project_id`, and optional `request_id`, `timeout_seconds`.
 
-Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. It does not expose inspect/download API paths; use the CLI commands below.
+Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. The CLI handles waiting and download with `--output`.
 
-Follow-up workflow:
-
-1. Save `data.run_id` and `data.artifact_id` from the export response.
-2. Poll status with `ae-cli analysis run inspect --run-id <run_id>`.
-3. Continue polling while status is running or pending. Treat `COMPLETED` or `SUCCEEDED` as success, and `FAILED`, `CANCELED`, or `CANCELLED` as terminal failure.
-4. On success, download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>.xlsx`.
-5. If the export is no longer needed, cancel with `ae-cli analysis query cancel --run-id <run_id>`.
-
-Do not write custom Python/curl for polling or download unless the CLI command itself is unavailable.
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).
 
 ## Parameters
 | Parameter | Required | Description |
@@ -34,3 +24,4 @@ Do not write custom Python/curl for polling or download unless the CLI command i
 | `--project-id` | Yes | Numeric project ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
 | `--timeout-seconds` | No | Timeout in seconds, 1 to 21600. Default 21600 (6 hours). |
+| `--output` | No | Wait and download to this local file. |

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

@@ -4,13 +4,9 @@ Use this reference only to identify the reserved future import contract; the cur
 
 Do not use it for a real import. It always returns `CAPABILITY_REQUIRES_FILE_ADAPTER` until CLI input-file handling is wired to the server import service.
 
-Command:
+Reserved command: `ae-cli analysis-meta event-property-bundle import`. Do not invoke it while the backend is blocked.
 
-```bash
-ae-cli analysis-meta event-property-bundle import --project-id <project_id> --operation pre_import --input-file-id <input_file_id> --dry-run
-```
-
-Capability id: `metadata.super_metadata.import`.
+Capability id: `metadata.event_property_bundle.import`.
 
 Input sends `project_id`, `operation`, and the operation-specific file or pre-import identifier.
 

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event relation-update --project-id <project_id> --payload '{"event_name":"purchase","source_type":"<source_type>","source_event_name":"<source_event>","super_event_prop_ids":[<property_id>]}'
-ae-cli analysis-meta event relation-update --dry-run
 ```
 
 Capability id: `metadata.event.relation_update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta event update --project-id <project_id> --event-name <event_name> --event-desc <event_desc> --remark <remark>
-ae-cli analysis-meta event update --dry-run
 ```
 
 Capability id: `metadata.event.update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta exchange config-update --project-id <project_id> --config-val <config_val>
-ae-cli analysis-meta exchange config-update --dry-run
 ```
 
 Capability id: `metadata.exchange_config.update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta exchange rate-refresh --project-id <project_id>
-ae-cli analysis-meta exchange rate-refresh --dry-run
 ```
 
 Capability id: `metadata.exchange_rate.refresh`.