@thinkingai/ae-cli 6.0.31 → 6.0.33

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

@@ -25,7 +25,7 @@ ae-cli analysis_meta +create_entity --dry-run
 
 ## Decision Rules
 - `--table_type` must be `0` (event property) or `1` (user property); no other values are accepted.
-- Before using `--column_name`, call `analysis_meta +list_properties` to verify it exists. If the same column name appears in **both** event properties and user properties, **stop and ask the user which table type to use** — do not guess `--table_type`. Ask every time this condition is met; never carry over the answer from a previous request.
+- Before using `--column_name`, call `analysis-meta property list` to verify it exists. If the same column name appears in **both** event properties and user properties, **stop and ask the user which table type to use** — do not guess `--table_type`. Ask every time this condition is met; never carry over the answer from a previous request.
 - For the first run, pass only the required parameters and confirm before adding others.
 - This is an ordinary `write` operation and does not require CLI confirmation.
 
@@ -36,4 +36,4 @@ ae-cli analysis_meta +create_entity --dry-run
 
 ## Recommended Chaining
 - `analysis_meta +list_entities` → `+create_entity`
-- `analysis_meta +list_properties` → `+create_entity`
+- `analysis-meta property list` → `+create_entity`

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

@@ -1,8 +1,8 @@
 # analysis dashboard create
 
-Use when the user explicitly wants to create a dashboard in personal space, a project space, or a folder.
+Use only when the user explicitly wants to create the product's analysis board (`看板`) in personal space, a project space, or a folder.
 
-Do not use to copy an existing dashboard. Use `dashboard copy` for copy workflows.
+Do not use for a BI dashboard (`仪表盘`); use `analysis bi-panel create` instead. Do not use to copy an existing analysis board; use `dashboard copy` for copy workflows.
 
 Command:
 
@@ -12,4 +12,4 @@ ae-cli analysis dashboard create --project-id <project_id> --dashboard-name <nam
 
 Input sends `project_id`, `dashboard_name`, and optional `space_id`, `folder_id`, `initial_report_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the created dashboard identity or backend create result.
+Output is the gateway envelope. `data` contains the created analysis-board identity or backend create result.

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

@@ -17,6 +17,7 @@ Behavior:
 - If no daily report config flags and no `--payload` are provided, the gateway uses the dashboard's saved daily report config.
 - If the dashboard has no saved daily report config, the command fails with a stable business error instead of creating a misleading task.
 - If any config flag or `--payload` is provided, the request config is used for this immediate send. Provide at least one valid channel, for example `--enable-dd true --dd-url '["https://..."]'`, or email fields such as `--enable-email true --email-login-users user@example.com`.
+- For an explicit Feishu send, use `--enable-feishu true --feishu-info '{"app_id":"cli_xxx","app_secret":"secret_xxx","webhook":["https://open.feishu.cn/open-apis/bot/v2/hook/..."]}'`. All three fields are required because the backend obtains a tenant access token and uploads the dashboard image before calling the group-bot webhook. Treat `app_secret` as sensitive input. If the dashboard already has a complete saved Feishu config, omit all config flags to reuse it.
 - Use `dashboard-daily-report update` to save or change scheduled daily report config.
 
 Output is the gateway envelope. `data` contains the immediate send result.

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

@@ -14,4 +14,6 @@ Input sends `project_id`, `dashboard_id`, and optional daily report fields or `p
 
 When `--payload` is absent, the command sends safe defaults expected by the gateway: `need_csv=false`, empty `host_url`, all channel switches false, `send_date=1,2,3,4,5,6,7`, `send_time=09:00`, `lang=zh-CN`, `screen_type=normal`, `zone_offset=0`, and `enable_send=false`. When `--payload` is present, payload values remain authoritative; pass top-level flags only for fields you intentionally want to override.
 
+When enabling Feishu, pass `--enable-feishu true --feishu-info '{"app_id":"cli_xxx","app_secret":"secret_xxx","webhook":["https://open.feishu.cn/open-apis/bot/v2/hook/..."]}'`. All three fields are required because the backend uploads the dashboard image before calling the group-bot webhook. Treat `app_secret` as sensitive input.
+
 Output is the gateway envelope. `data` contains the daily report configuration update result.

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

@@ -9,10 +9,10 @@ Do not use this command for bounded inline previews; use `dashboard-report-data
 Command:
 
 ```bash
-ae-cli analysis dashboard-report-data export --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--start-time <time>] [--end-time <time>] [--artifact-format jsonl]
+ae-cli analysis dashboard-report-data export --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--start-time <time>] [--end-time <time>] [--zone-offset <offset>] [--artifact-format jsonl]
 ```
 
-Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`, `start_time`, `end_time`, `use_cache`, `request_id`, `timeout_seconds`, `format`. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`, `start_time`, `end_time`, `zone_offset`, `use_cache`, `request_id`, `timeout_seconds`, `format`. When `--zone-offset` is specified, that timezone is used for every selected non-SQL report. When omitted, the current user's `currentTimezone` is used when available, otherwise the project default. Fixed UTC offsets are `-12` through `14`; `99` is local-time mode and is not UTC+99. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
 `--filters` uses the same AI-facing filter model as report data. The gateway resolves fields and compiles it to the dashboard backend filter. Do not pass a dashboard UI control dump or raw QP filter. Minimal shape:
 
@@ -22,11 +22,11 @@ Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`,
 
 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`, status fields, expiration fields, and `query_context_id` / `query_context_expires_at` when Redis context creation succeeds. 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`. It does not expose inspect/download API paths; use the CLI commands below.
 
 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.
 
-Use the submit response `query_context_id` immediately with `analysis drilldown-users run` or `analysis query create-result-cluster` when present. After the run completes, the downloaded artifact's first metadata line repeats the query context for file consumers. Do not pass raw QP.
+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:
 

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

@@ -9,10 +9,10 @@ Do not use this command for full, unknown-size, larger than 1000-row, or long-ru
 Command:
 
 ```bash
-ae-cli analysis dashboard-report-data run --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--start-time <time>] [--end-time <time>] [--limit 100] [--timeout-seconds 180]
+ae-cli analysis dashboard-report-data run --project-id <project_id> --dashboard-id <dashboard_id> [--report-ids '[1,2]'] [--filters '{...}'] [--start-time <time>] [--end-time <time>] [--zone-offset <offset>] [--limit 100] [--timeout-seconds 180]
 ```
 
-Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`, `start_time`, `end_time`, `use_cache`, `request_id`, `timeout_seconds`, `limit`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default and max 180. An explicitly supplied lower timeout still wins. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`, `start_time`, `end_time`, `zone_offset`, `use_cache`, `request_id`, `timeout_seconds`, `limit`. When `--zone-offset` is specified, that timezone is used for every selected non-SQL report. When omitted, the current user's `currentTimezone` is used when available, otherwise the project default. Fixed UTC offsets are `-12` through `14`; `99` is local-time mode and is not UTC+99. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default and max 180. An explicitly supplied lower timeout still wins. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
 
 `--filters` uses the same AI-facing filter model as report data. The gateway resolves fields and compiles it to the dashboard backend filter. Do not pass a dashboard UI control dump or raw QP filter. Minimal shape:
 
@@ -22,8 +22,8 @@ Input sends `project_id`, `dashboard_id`, and optional `report_ids`, `filters`,
 
 Dashboard `filters`, `start_time`, and `end_time` do not apply to SQL reports. The query still succeeds and returns those SQL report results. Inspect `data.warnings[]`; `OVERRIDE_IGNORED_FOR_MODEL` contains the affected SQL `report_ids` and `ignored_fields`. To change SQL conditions, query the SQL report directly with `analysis report-data run` and saved `definition.params` through `--sql-params`.
 
-Output is the gateway envelope. `data` contains bounded inline report data, optional structured `warnings`, plus `query_context_id`, `drilldown_available`, and `result_cluster_available` when a context can be created.
+Output is the gateway envelope. `data.effective_zone_offset` is the timezone actually used by the query, and each report source repeats it as `sources[].effective_zone_offset`. `data` also contains bounded inline report data, optional structured `warnings`, plus `query_context_id` and per-report `sources[].drilldown` options when a returned report exposes follow-up actions. Unsupported report models have empty actions.
 
 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`.
 
-Use `query_context_id` with `analysis drilldown-users run` or `analysis query create-result-cluster`. Do not pass raw QP.
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Pass the selected report source and merge only its returned coordinate fragments for the advertised action. Do not pass raw QP.

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

@@ -0,0 +1,26 @@
+# analysis drilldown-entities export
+
+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.
+
+```bash
+ae-cli analysis drilldown-entities export \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '<same returned coordinate>' \
+  [--properties '[{...}]'] \
+  [--artifact-format csv] \
+  [--timeout-seconds 21600]
+```
+
+Property support matches the synchronous preview exactly:
+
+- For the `#user_id` user subject, `--properties` accepts `[{"columnName":"<property_name>","tableType":"user"}]`. The artifact always retains `#user_id`, `#account_id`, and `#distinct_id` plus the requested user properties.
+- For a custom entity subject, omit `--properties`; the artifact contains only the entity value column. Supplying properties returns `CUSTOM_ENTITY_PROPERTIES_UNSUPPORTED` instead of silently ignoring them.
+
+`#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.
+
+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_entities_run.md

@@ -0,0 +1,33 @@
+# analysis drilldown-entities run
+
+Preview users or custom entities behind one selected synchronous-preview cell.
+
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. Call this only when the selected metric/action advertises `drilldown_entities`. Event metrics require `analysis_angle=USER_LIST|ENTITY_LIST`; retention, funnel, distribution, interval, property, path, and attribution results expose their analysis subject in `source.drilldown.subject`.
+
+## Command
+
+```bash
+ae-cli analysis drilldown-entities run \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '<merged returned row/column/metric coordinate>' \
+  [--properties '[{...}]'] \
+  [--limit 100] \
+  [--timeout-seconds 120]
+```
+
+The context, source, and coordinate must all come from the same synchronous preview. Select a visible row from `row_options`, a drillable column from `column_options`, and the relevant metric option; shallow-merge their coordinate fragments. Never send `row_index`, `column_index`, `values`, `label`, `target_id`, raw QP, or a coordinate derived from an export file.
+
+Property support depends on the returned subject:
+
+- `subject.type=user` (`column_name=#user_id`): `--properties` may select additional user properties with `[{"columnName":"<property_name>","tableType":"user"}]`. The named value `user` is required; do not send numeric enum codes. Every row still contains `#user_id`, `#account_id`, and `#distinct_id`.
+- `subject.type=entity`: do not pass `--properties`. A custom entity returns only its entity value. Supplying properties is invalid and must return `CUSTOM_ENTITY_PROPERTIES_UNSUPPORTED`; it is never silently ignored.
+
+## Output and next intent
+
+The response contains `subject`, `items`, `total`, `returned_rows`, and `truncated`.
+
+- `subject.type=user`: items include canonical `user_id`; `attributes` always includes `#user_id`, `#account_id`, and `#distinct_id`, followed by requested user properties. `#user_id` is an internal association key that customers normally do not care about. In user-facing tables or summaries, show account ID and visitor ID by default and keep `#user_id` only for machine linkage or explicit troubleshooting. If `drilldown_context_id` and the user-event follow-up are present, the Agent may ask for one returned user's event sequence with `analysis drilldown-user-events run|export`.
+- `subject.type=entity`: items contain `entity_value`; do not call user-event commands because non-user entities have no event sequence.
+- When `truncated=true` or complete membership is requested, repeat the same context/source/coordinate with `analysis drilldown-entities export`. Do not page this command.
+- Creating a result cluster is a sibling action from the original analysis cell, not from an entity row. Use the original `query_context_id`, source, and coordinate with `analysis query create-result-cluster` only if that action was advertised.

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

@@ -0,0 +1,21 @@
+# analysis drilldown-events export
+
+Stream all raw events behind one selected `EVENT_LIST` coordinate into one `csv.gz` artifact.
+
+Use this only when the selected synchronous preview metric advertises `drilldown_events`. Copy the same `query_context_id`, optional `source`, and semantic `coordinate` used by `analysis drilldown-events run`; never pass raw QP or `target_id`.
+
+```bash
+ae-cli analysis drilldown-events export \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '<same returned coordinate>' \
+  [--properties '[{"columnName":"<event_property_name>","tableType":"event"}]'] \
+  [--artifact-format csv] \
+  [--timeout-seconds 21600]
+```
+
+This command does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`. Common executes one full-download query and streams its result directly into the artifact; it does not repeatedly call the synchronous preview. “All” follows the platform full-download ceiling (`model_full_download_limit`), not an unbounded query.
+
+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.

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

@@ -0,0 +1,23 @@
+# analysis drilldown-events run
+
+Preview raw event rows behind one event-analysis metric cell.
+
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. Call this command only when the selected event `metric_option` has `analysis_angle=EVENT_LIST` and includes `drilldown_events` in `actions`. Event totals commonly have this angle; triggered-user/entity counts do not.
+
+## Command
+
+```bash
+ae-cli analysis drilldown-events run \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '{"group_values":["Beijing"],"date":"2026-07-16","metric_index":0}' \
+  [--properties '[{...}]'] \
+  [--limit 100] \
+  [--timeout-seconds 120]
+```
+
+`--query-context-id` must come from the same synchronous preview that returned the selected source and options. `--source` is required only to disambiguate multiple returned sources. Assemble `--coordinate` only by merging the selected returned option fragments. Do not pass `target_id`, raw QP, display-only dates, or values from an export/download.
+
+`--properties` is an optional exact event-property projection. Omit it for default columns; string arrays such as `["#event_time"]` are invalid. Each item uses the backend field names `columnName` and `tableType`, for example `[{"columnName":"<event_property_name>","tableType":"event"}]`. `tableType` uses the documented name `event`, not a numeric enum code. Required system event columns remain present, but unrelated event properties must not be returned.
+
+The response contains at most `limit` event rows from that selected preview cell. `total` is the exact number of matching events, `returned_rows` is the number included in this response, and `truncated=true` means more matching events exist. This command has no paging offset. When complete event detail is required, call `analysis drilldown-events export` once with the same returned context/source/coordinate; that sibling capability uses the backend full-download stream and does not page or enlarge the synchronous selection boundary.

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

@@ -8,13 +8,16 @@ Export the complete event sequence for one user from a drilldown context. Do not
 ae-cli analysis drilldown-user-events export \
   --drilldown-context-id <drilldown_context_id> \
   --user-id <user_id> \
+  [--properties '[{"columnName":"<event_property_name>","tableType":"event"}]'] \
   [--sort-order desc] \
-  [--artifact-format jsonl] \
+  [--artifact-format csv] \
   [--timeout-seconds 21600]
 ```
 
-Use identifiers returned by `analysis drilldown-users run` or its export artifact. Export does not accept `--limit`, `--page-num`, or `--page-size`; Common advances backend pages internally and writes one JSONL artifact.
+The nested backend keys are exactly `columnName` and `tableType`, and the table type is the named value `event`. String-name arrays, numeric enum codes, and snake_case rewrites are invalid. With an explicit projection, the artifact retains `#user_id`, account ID, visitor ID, event name, and event time and appends exactly the requested event properties. `#user_id` is internal; Agents should normally present account ID and visitor ID to customers.
+
+Use the exact `drilldown_context_id` and canonical `user_id` returned by a user-subject `analysis drilldown-entities run`. Do not use a custom entity, an entity export artifact, or a guessed identity. Export does not accept `--limit`, `--offset`, `--page-num`, or `--page-size`; Common builds the same authorized event-sequence query without the synchronous 1000-row preview cap and streams one `csv.gz` artifact. The platform full-download ceiling (`model_full_download_limit`) still applies.
 
 Inspect the returned `run_id` with `analysis run inspect`, then download the completed artifact with `analysis artifact download`.
 
-Output is an async run/artifact descriptor. The complete event rows exist only in the downloaded artifact.
+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/drilldown_user_events_run.md

@@ -1,8 +1,8 @@
 # analysis drilldown-user-events run
 
-Query event sequence details for one user after `analysis drilldown-users run`.
+Query event sequence details for one user after a user-subject `analysis drilldown-entities run`.
 
-Use this only after `analysis drilldown-users run` returns a `drilldown_context_id`.
+Use this only when `analysis drilldown-entities run` returns `subject.type=user`, a `drilldown_context_id`, and the user-event follow-up action. Custom entities do not have event sequences.
 
 Do not pass raw QP.
 
@@ -19,15 +19,15 @@ ae-cli analysis drilldown-user-events run \
 
 ## Input
 
-- `--drilldown-context-id`: returned by `analysis drilldown-users run`.
-- `--user-id`: user id returned by `analysis drilldown-users run`.
-- `--properties`: optional backend property request object array. Omit this in normal agent calls and use the default returned columns. Do not pass string-name arrays such as `["event_time"]`.
+- `--drilldown-context-id`: returned by the same user-subject `analysis drilldown-entities run`.
+- `--user-id`: canonical `user_id` from one item in that same response. Never substitute `entity_value`, `#distinct_id`, account ID, or another identity field.
+- `--properties`: optional exact event-property projection. Omit it to use the default event columns. If present, each item uses backend keys `columnName` and `tableType`, for example `[{"columnName":"<event_property_name>","tableType":"event"}]`. `#user_id`, account ID, visitor ID, event name, and event time remain present; unrelated event properties must not be returned. `#user_id` is an internal association key, so Agents should normally display account ID and visitor ID to customers. Do not pass numeric table-type codes, string-name arrays, or snake_case nested keys.
 - `--sort-order`: `asc` or `desc`.
 - `--event-name-filter`, `--time-filter`, `--time-filter-before-nums`, `--time-filter-after-nums`: optional event sequence filters.
 
 Do not use raw QP, `query_context_id`, or guessed user IDs for this command.
 
-The `drilldown_context_id` must come from a `drilldown-users` target that includes date context, such as `drilldown_date` or `target_dates`. A context created from `include_total` alone can list users, but may fail event-sequence lookup with `TARGET_DATES_REQUIRED`.
+Do not call this command merely because an entity row looks like a user. The explicit subject and follow-up context are the authority.
 
 ## Output
 

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

@@ -26,6 +26,8 @@ Do not pass `--limit`; async export rejects inline limits. Use `--artifact-forma
 
 Export does not accept `--limit` or `--offset`; backend batching is internal.
 
+For `entity="user"`, every artifact row includes `#user_id`, `#account_id`, and `#distinct_id` plus requested user properties. For a custom entity, omit `properties`; the artifact contains only the entity value column and rejects additional properties. When presenting user artifacts, Agents should display account ID and visitor ID instead of exposing internal `#user_id` as the only visible identity.
+
 Output:
 
 Returns an async descriptor with opaque `run_id` / `artifact_id`, lifecycle status, expiration, and effective timeout/deadline fields. JSONL artifacts start with metadata and schema lines; CSV artifacts start directly with the header and contain only valid CSV records.

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

@@ -9,7 +9,7 @@ Use this command for the first small entity detail preview that fits inline. It
 ```bash
 ae-cli analysis entity-detail run \
   --project-id <project_id> \
-  --definition '{"entity":"user","cohort":{"relation":"and","items":[{"field":{"name":"level","type":"user_property"},"operator":"gte","values":[1]}]},"properties":["#user_id",{"name":"country","type":"user_property"}],"sort":[{"field":"#user_id","order":"asc"}]}' \
+  --definition '{"entity":"user","cohort":{"relation":"and","items":[{"field":{"name":"level","type":"user_property"},"operator":"gte","values":[1]}]},"properties":[{"name":"country","type":"user_property"}],"sort":[{"field":"#user_id","order":"asc"}]}' \
   --limit 100
 ```
 
@@ -24,6 +24,13 @@ Input:
 
 `entity` may be `"user"` for the default user entity or `{ "id": 123 }` in multi-entity projects.
 
+Property and identity rules depend on the entity:
+
+- `entity="user"` resolves to the `#user_id` user entity. `properties` may contain user properties. Every row always contains `#user_id`, `#account_id`, and `#distinct_id` plus the requested properties.
+- A custom entity (`{"id":123}` whose entity column is not `#user_id`) returns only its entity value column. Do not provide `properties`; doing so returns `CUSTOM_ENTITY_PROPERTIES_UNSUPPORTED`.
+
+`#user_id` is an internal association key and is normally not meaningful to customers. In user-facing output, Agents should show account ID and visitor ID by default; retain `#user_id` for machine linkage or explicit troubleshooting.
+
 `cohort` is AI-facing for simple entity-set filters and uses the same filter item shape as report/detail filters:
 
 ```json

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

@@ -0,0 +1,25 @@
+# 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.
+
+Command:
+
+```bash
+ae-cli tracking event-blacklist add [options]
+```
+
+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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--event-names` | See command help | Yes |
+

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

@@ -0,0 +1,24 @@
+# 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.
+
+Command:
+
+```bash
+ae-cli tracking event-blacklist list [options]
+```
+
+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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+

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

@@ -0,0 +1,26 @@
+# 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.
+
+Command:
+
+```bash
+ae-cli tracking event-blacklist update [options]
+```
+
+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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--event-names` | See command help | Yes |
+| `--type` | See command help | Yes |
+

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

@@ -26,6 +26,8 @@ Do not pass `--limit`; async export rejects inline limits. Use `--artifact-forma
 
 Export does not accept `--limit` or `--offset`; backend batching is internal.
 
+`definition.properties` uses the same exact projection as `event-detail run`. The artifact may include required system event columns, but it must not expand to every visible event property.
+
 Output:
 
 Returns an async descriptor with opaque `run_id` / `artifact_id`, lifecycle status, expiration, and effective timeout/deadline fields. JSONL artifacts start with metadata and schema lines; CSV artifacts start directly with the header and contain only valid CSV records.

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

@@ -51,6 +51,8 @@ Use `{"mode":"relative","relative_date_range":"0-7"}` for recent-day queries.
 
 Do not pass raw QP, `eventView`, `taFilters`, `columnName`, or `tableType`.
 
+When `definition.properties` is present, it is an exact projection: required system event columns remain, requested properties are appended, and unrelated properties must not be returned.
+
 Do not use this command for full, unknown-size, or later-page detail retrieval. Use `analysis event-detail export` and check its artifact metadata for `truncated`.
 
 Output:

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

@@ -1,6 +1,6 @@
 # analysis-meta event list
 
-Use when the user needs to list project super events.
+Use when the user needs to list project super events, search event metadata, page results, project fields, or filter to authenticated events.
 
 Do not use it for raw tracked events, event counts, or one full definition; it lists project super-event metadata.
 
@@ -8,12 +8,15 @@ Command:
 
 ```bash
 ae-cli analysis-meta event list --project-id <project_id>
+ae-cli analysis-meta event list --project-id <project_id> --query login --fields '["event_name","event_desc","authentication_status"]' --limit 20 --offset 0 --authenticated-only
 ae-cli analysis-meta event list --dry-run
 ```
 
 Capability id: `metadata.event.list`.
 
-Input sends `project_id`.
+Input sends `project_id`, `query`, `fields`, `limit`, `offset`, and `authenticated_only`.
+
+Use snake_case projection fields: `event_id`, `event_name`, `event_desc`, `remark`, `event_tag`, `authentication_status`. Do not send legacy camelCase field names.
 
 Output `data.events[]` contains project super-event metadata records.
 
@@ -21,3 +24,8 @@ Output `data.events[]` contains project super-event metadata records.
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
+| `--query` / `-q` | No | Optional keyword filter. Fuzzy match is applied to `event_name`, `event_desc`, and `remark`. |
+| `--fields` / `-f` | No | Optional JSON array of snake_case fields to return. |
+| `--limit` / `-l` | No | Optional page size. When omitted, existing full-list behavior is preserved. Maximum: 50. |
+| `--offset` / `-o` | No | Optional zero-based page offset. |
+| `--authenticated-only` | No | When true, return only authenticated events and include `authentication_status` when projected. |

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

@@ -0,0 +1,27 @@
+# tracking ingest-error list
+
+Use when list tracking ingest errors for one data name.
+
+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.
+
+Command:
+
+```bash
+ae-cli tracking ingest-error list [options]
+```
+
+Capability id: `tracking.ingest_error.list`
+
+Input sends `project_id`, `data_name`, `start_time`, and `end_time`. 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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--data-name` | See command help | Yes |
+| `--start-time` | See command help | No |
+| `--end-time` | See command help | No |
+

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

@@ -0,0 +1,26 @@
+# tracking ingest summary
+
+Use when get tracking ingest summary.
+
+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.
+
+Command:
+
+```bash
+ae-cli tracking ingest summary [options]
+```
+
+Capability id: `tracking.ingest.summary`
+
+Input sends `project_id`, `start_time`, and `end_time`. 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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--start-time` | See command help | No |
+| `--end-time` | See command help | No |
+

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

@@ -39,4 +39,4 @@ ae-cli analysis_meta +list_entities --dry-run
 - If the result is empty, first confirm the project ID/keyword, then try loosening the filter conditions.
 
 ## Recommended Chaining
-- +list_entities -> +create_virtual_property / +create_virtual_event
+- +list_entities -> analysis-meta virtual-property create / analysis-meta virtual-event create

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

@@ -0,0 +1,27 @@
+# tracking live-data export
+
+Use when export recent tracking live data.
+
+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.
+
+Command:
+
+```bash
+ae-cli tracking live-data export [options]
+```
+
+Capability id: `tracking.live_data.export`
+
+Input sends `project_id`, optional `data_type`, optional `request_id`, and optional `timeout_seconds`. 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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--data-type` | See command help | No |
+| `--request-id` | See command help | No |
+| `--async-timeout-seconds` | See command help | No |
+

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

@@ -0,0 +1,27 @@
+# tracking live-data list
+
+Use when list recent tracking live data.
+
+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.
+
+Command:
+
+```bash
+ae-cli tracking live-data list [options]
+```
+
+Capability id: `tracking.live_data.list`
+
+Input sends `project_id`, optional `data_type`, optional `request_id`, and optional `timeout_seconds`. 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.
+
+Parameters:
+
+| Parameter | Description | Required |
+| --- | --- | --- |
+| `--project-id` | See command help | Yes |
+| `--data-type` | See command help | No |
+| `--request-id` | See command help | No |
+| `--timeout-seconds` | See command help | No |
+

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

@@ -2,13 +2,14 @@
 
 Use when the user needs to create a metric from event or retention analysis configuration.
 
-Do not use it to query metric values. Use this gateway command for an exact metric definition; use `analysis_meta +create_metric` only when the gateway capability is unavailable.
+Do not use it to query metric values. Use this gateway command for an exact metric definition.
 
 Command:
 
 ```bash
-ae-cli analysis-meta metric create --project-id <project_id> --metric-name pay_amount --metric-desc 'Pay Amount' --metric-mode <mode> --metric-events '[...]' --metric-params '{}'
-ae-cli analysis-meta metric create --project-id <project_id> --metric-name pay_amount --metric-desc 'Pay Amount' --metric-mode <mode> --metric-events '[...]' --dry-run
+ae-cli analysis-meta metric create --project-id <project_id> --metric-name pay_amount --metric-desc 'Pay Amount' --model-type event --metric-events '[...]' --metric-params '{}'
+ae-cli analysis-meta metric create --project-id <project_id> --metric-name retained_users --metric-desc 'Retained Users' --model-type retention --metric-events '[...]' --metric-params '{}'
+ae-cli analysis-meta metric create --project-id <project_id> --metric-name pay_amount --metric-desc 'Pay Amount' --metric-mode 0 --metric-events '[...]' --dry-run
 ```
 
 Capability id: `metadata.metric.create`.
@@ -23,7 +24,15 @@ Output `data.metric` contains the created metric summary.
 | `--project-id` | Yes | Numeric project ID. |
 | `--metric-name` | Yes | Metric technical name. |
 | `--metric-desc` | Yes | Metric display name. |
-| `--metric-mode` | Yes | Metric model mode, for example `0` for event analysis. |
+| `--model-type` | No | Semantic metric model type: `event` or `retention`. Prefer this over `--metric-mode`. |
+| `--metric-mode` | No | Metric model mode, for example `0` for event analysis. Required only when `--model-type` is omitted. |
 | `--metric-events` | Yes | Metric event-analysis QP JSON array. |
 | `--metric-remark` | No | Metric remark. |
 | `--metric-params` | No | Metric params JSON object; common defaults it to `{}` when needed. |
+
+## Decision Rules
+
+- Pass exactly one semantic model selector when possible: prefer `--model-type event` or `--model-type retention`.
+- `--metric-mode` remains available for existing scripts; if both are provided, they must describe the same model.
+- For event metrics, `--metric-params` is usually a format config such as `{"format":"integer"}`.
+- For retention metrics, `--metric-params` should be the retention `eventView` configuration.

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

@@ -23,3 +23,10 @@ Output is a successful gateway envelope with no business data. Verify with `metr
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--metric-id` | Yes | Metric ID. |
+
+## Decision Rules
+- Use `analysis-meta metric list` first to confirm the metric ID before deleting.
+- This is a destructive operation; keep the confirmation prompt unless automation is explicitly required.
+
+## Recommended Chain
+- `analysis-meta metric list` -> `analysis-meta metric delete`