@thinkingai/ae-cli 6.0.30 → 6.0.31

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to validate affected range before saving exchange-rate rules.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+Do not use it to persist rules. Validation is the mandatory preflight for `exchange rule-update`.
 
 Command:
 
 ```bash
-ae-cli analysis-meta exchange rule-validate --project-id <project_id> --payload '{}'
+ae-cli analysis-meta exchange rule-validate --project-id <project_id> --payload '{"target_currency":"USD","exchange_rules":[{"source_currency":"EUR","source_currency_column":"currency","target_column_desc":"amount_usd"}]}'
 ae-cli analysis-meta exchange rule-validate --dry-run
 ```
 
@@ -15,10 +15,10 @@ Capability id: `metadata.exchange_rule.validate`.
 
 Input sends `project_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data` is the pre-save affected-range/conflict result. It does not modify rules.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--payload` | Yes | `{target_currency,exchange_rules}`; both are required and `exchange_rules` must be non-empty. Rule fields include `id`, `source_currency`, `source_currency_column`, required `target_column_desc`, and optional `operate_type`. |

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

@@ -7,7 +7,7 @@ Do not use for sharing or moving assets.
 Command:
 
 ```bash
-ae-cli analysis favorite add --project-id <project_id> [--asset-id <id>] [--asset-type dashboard|bi_panel|folder] [--space-id <space_id>] [--id <backend_id>] [--payload '{...}'] --yes
+ae-cli analysis favorite add --project-id <project_id> [--asset-id <id>] [--asset-type dashboard|bi_panel|folder] [--space-id <space_id>] [--id <backend_id>] [--payload '{...}']
 ```
 
 Input sends `project_id` and asset identity fields or backend-compatible `payload`.

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

@@ -7,7 +7,7 @@ Do not use to delete the asset itself.
 Command:
 
 ```bash
-ae-cli analysis favorite remove --project-id <project_id> [--asset-id <id>] [--asset-type dashboard|bi_panel|folder] [--space-id <space_id>] [--id <backend_id>] [--payload '{...}'] --yes
+ae-cli analysis favorite remove --project-id <project_id> [--asset-id <id>] [--asset-type dashboard|bi_panel|folder] [--space-id <space_id>] [--id <backend_id>] [--payload '{...}']
 ```
 
 Input sends `project_id` and asset identity fields or backend-compatible `payload`.

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

@@ -4,15 +4,14 @@ Use when the user wants to create a folder in personal space or project space.
 
 Do not use to create a project space. Use `analysis.project_space.create` via capability run.
 
-This capability has no curated `ae-cli analysis` command. Read [`ae-capability`](../../ae-capability/SKILL.md), then:
+This capability has no curated `ae-cli analysis` command. Read [`ae-capability`](../../ae-capability/SKILL.md) (on-demand validate/dry-run table), then:
 
 ```bash
 ae-cli capability inspect analysis.folder.create
-ae-cli capability dry-run analysis.folder.create --input '{"project_id":1,"folder_name":"Weekly","space_id":10}'
 ae-cli capability run analysis.folder.create --input '{"project_id":1,"folder_name":"Weekly","space_id":10}'
 ```
 
-`risk=write` — no chat confirmation required after dry-run succeeds.
+`risk=write` — no chat confirmation required.
 
 Input uses snake_case JSON. Common fields:
 

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

@@ -4,15 +4,14 @@ Use when the user wants to modify folder sharing members.
 
 Do not use to inspect members only. Use `analysis.folder.members` via `capability search/inspect/run`; see [`analysis_gateway_assets.md`](analysis_gateway_assets.md) L3 members section.
 
-This capability has no curated `ae-cli analysis` command. Read [`ae-capability`](../../ae-capability/SKILL.md), then:
+This capability has no curated `ae-cli analysis` command. Read [`ae-capability`](../../ae-capability/SKILL.md) (on-demand validate/dry-run table), then:
 
 ```bash
 ae-cli capability inspect analysis.folder.share
-ae-cli capability dry-run analysis.folder.share --input '{"project_id":1,"folder_id":1001,"payload":{...}}'
 ae-cli capability run analysis.folder.share --input '{"project_id":1,"folder_id":1001,"payload":{...}}'
 ```
 
-`risk=write` — no chat confirmation required after dry-run succeeds.
+`risk=write` — no chat confirmation required. Compose nested `payload` from the inspect `input_schema`.
 
 Input uses snake_case JSON. Common fields:
 

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Generate a tracking plan from structured business context. This AI generation flow is different from save_track_items: save_track_items persists explicitly provided plan items, while this tool requests AI generation and saves the generated result asynchronously.
 - Users should check the in-site message center for final results.
+- Do not use it to persist a fully specified set of tracking items; use `+save_track_items` when the exact items are already known.
 
 ## CRITICAL: Pre-execution Check
 **Before calling this command, you MUST:**
@@ -48,4 +49,4 @@ Example response: "Command submitted successfully. The tracking plan generation
 
 ## Recommended Chaining
 - **+get_track_program (check existing) -> +generate_track_program (if empty or user confirms) -> (check message center) -> +get_track_program (verify result)**
-- +get_project_config -> +get_track_program -> +generate_track_program
+- +get_project_config -> +get_track_program -> +generate_track_program

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Generate SDK sample files based on the current tracking plan and requested SDK types. This flow is asynchronous and users should check in-site messages for final downloadable results.
 - Useful for developers who need SDK integration code samples based on the tracking plan.
+- Do not use it to create or change the tracking plan itself; generate samples only after `+get_track_program` confirms the plan content.
 
 ## Commands
 ```bash
@@ -40,4 +41,4 @@ ae-cli analysis_meta +generate_track_sdk_sample --dry-run
 Example response: "Command submitted successfully. The SDK sample generation is running asynchronously. Please check your TE inbox for the download link once it completes."
 
 ## Recommended Chaining
-- +get_track_program -> +generate_track_sdk_sample -> (check message center for download)
+- +get_track_program -> +generate_track_sdk_sample -> (check message center for download)

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

@@ -6,6 +6,10 @@ Domain: **Metadata Lookup**
 
 ## Use Cases
 - Get detailed information about a specific alert by alertId.
+- Do not use it to discover an unknown alert ID; call `+list_alerts` first.
+
+## Output
+Returns the alert identity and saved definition. Use that returned definition as the baseline before an update; do not reconstruct it from memory.
 
 ## Commands
 ```bash

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

@@ -10,6 +10,7 @@ Domain: **Metadata queries**
 - Typical follow-up tools: `+create_alert`, `+update_alert`
 - Get the alert definition schema. Returns field definitions, enum descriptions, and examples for creating or updating alerts.
 - Use this to understand the alert definition structure before calling create_alert or update_alert.
+- Do not use the schema response as an alert instance or query result; it only describes valid definition fields.
 
 ## Command
 ```bash

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

@@ -6,11 +6,11 @@ Domain: **Metadata Query**
 
 ## Constraints
 
-**Not a builder pre-step:** Do not call `+get_metric` before `+build_event_analysis_qp` for normal ad-hoc analysis. If the user asks to query a saved metric, pass the metric display/name/remark directly as `metrics:[{"event":"<metric name>"}]` to `+build_event_analysis_qp`. The builder resolves saved metrics internally. If it cannot resolve the metric, stop on the builder's structured error and ask for clarification.
+**Not an ad-hoc pre-step:** Do not call `+get_metric` just to expand a saved metric before normal ad-hoc analysis. If the user asks to query a saved metric, pass the metric display/name/remark directly in `analysis adhoc run --definition`; the backend compiler resolves saved metrics internally.
 
 ## Use Cases
 - Get the definition details of a single metric. Returns the metric name, display name, remark, model type, linked events, and parameter definition without executing metric calculation.
-- Use this command for metric metadata inspection, metric editing, auditing, or when the user explicitly asks for metric definition details. Do not use it merely to expand a saved metric before a builder-supported ad-hoc query.
+- Use this command for metric metadata inspection, metric editing, auditing, or when the user explicitly asks for metric definition details. Do not use it merely to expand a saved metric before an ad-hoc query.
 
 ## Commands
 ```bash
@@ -26,7 +26,7 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Decision Rules
 - For the first run, pass only the required parameters (`--project_id` and `--metric_id`) to confirm the path works, then add optional parameters.
-- For builder-supported ad-hoc analysis, do not read metric details first. Call the matching builder with the user's metric/event/property wording.
+- For ad-hoc analysis, do not read metric details first. Call `analysis adhoc run` or `analysis adhoc export` with the user's metric/event/property wording.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -35,4 +35,4 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Recommended Chaining
 - +get_metric -> +update_metric
-- For ad-hoc saved metric query: +build_event_analysis_qp -> +query_adhoc
+- For ad-hoc saved metric query: analysis adhoc run/export

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Get project configuration details. Returns: projectId, projectName, companyId, defaultTimeZoneOffset (project default time zone offset), remark, timeZoneEnabled (whether multiple time zones are supported), timeZoneOffsetColumn (time zone column name in event data), and availableTimeZones (array of time zone offsets used in this project). Call this tool when you need project basic info or time zone configuration.
 - Get project configuration details.
+- Do not use it for project discovery or membership lookup; use `analysis_common +list_projects` or `+list_project_users` respectively.
 
 ## Command
 ```bash

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

@@ -30,3 +30,4 @@ ae-cli analysis_common +get_resource_url --dry-run
 ## Recommended Chaining
 - `+create_*` -> `analysis_common +get_resource_url`
 - `+update_*` -> `analysis_common +get_resource_url`
+- For `analysis report create/update`, use the returned `report_id` directly as `--resource_id`; do not run a broad report list to rediscover the asset.

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

@@ -8,6 +8,9 @@ Domain: **Project Configuration**
 - Query TRACKING-PLAN metadata (bury program), including planned events/properties/common properties. This is NOT system metadata. Do NOT use MetaTool/MetaPowerTool for these plan objects.
 - Query TRACKING-PLAN metadata (bury program), including planned events/properties/common properties.
 
+## Output
+Returns the current plan content. An empty plan permits first-time generation; a non-empty result must be reviewed before any merge-generating operation.
+
 ## Commands
 ```bash
 ae-cli analysis_meta +get_track_program --project_id <project_id>

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

@@ -0,0 +1,19 @@
+# analysis history-tag batch-refresh
+
+Batch refresh history tag snapshots over one inclusive date range.
+
+Flags: `--project-id`, `--tag-name`, `--refresh-request` required.
+
+```bash
+ae-cli analysis history-tag batch-refresh --project-id <project_id> --tag-name user_level --refresh-request '{"start_time":"2026-07-01","end_time":"2026-07-07","only_abnormal":false,"use_user_table_type":"user_table"}'
+```
+
+Input:
+
+- `start_time` and `end_time` are required, inclusive, and use `yyyy-MM-dd`;
+- `only_abnormal` is optional boolean, default `false`;
+- `use_user_table_type` is optional: `user_table`, `user_backup_table_default`, or `user_backup_table_last_date`.
+
+Do not pass the Java DTO name, camelCase fields such as `startDate`/`endDate`, or alternate `start_date`/`end_date` aliases.
+
+Output is the gateway envelope containing the batch refresh task result.

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

@@ -0,0 +1,13 @@
+# analysis history-tag clear
+
+Clear history tag snapshots in a date range after explicit user confirmation.
+
+Do not use it to cancel a running refresh or to remove the tag itself. Output confirms the requested date range was cleared; verify remaining snapshots with `history-tag list`.
+
+Flags: `--project-id`, `--tag-name`, `--start-time`, `--end-time` required. Values use `yyyy-MM-dd`. Add `--confirmed` and `--yes` only after the user accepts the dry-run impact.
+
+```bash
+ae-cli analysis history-tag clear --project-id <project_id> --tag-name user_level --start-time 2026-07-01 --end-time 2026-07-07 --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis history-tag clear --project-id <project_id> --tag-name user_level --start-time 2026-07-01 --end-time 2026-07-07 --confirmed --yes
+```

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

@@ -0,0 +1,15 @@
+# analysis history-tag-data-drilldown export
+
+Export all users for one value/bucket returned by `history-tag-data run/export` as an async jsonl artifact.
+
+Do not use it for an inline sample or for a group value that did not come from the upstream statistics response. Output is an async descriptor with `run_id` and `artifact_id`, not the user rows themselves.
+
+Flags: `--project-id`, `--tag-name`, `--snapshot-date`, `--group-col`, `--view` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+Use the same `--view` that produced the statistic row. `--group-col` must be the exact statistic value or bucket label. Download the artifact only after `analysis run inspect` reports success.
+
+```bash
+ae-cli analysis history-tag-data-drilldown export --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --group-col VIP --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output history-tag-drilldown.jsonl.gz
+```

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

@@ -0,0 +1,13 @@
+# analysis history-tag-data-drilldown run
+
+Run a bounded inline user drilldown for one value/bucket returned by `history-tag-data run/export`.
+
+Do not use it for complete or unknown-size drilldown data. Output contains only the bounded inline user result; use export when truncation would change the answer.
+
+Flags: `--project-id`, `--tag-name`, `--snapshot-date`, `--group-col`, `--view` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+
+Use the same `--view` that produced the statistic row. `--group-col` must be the exact statistic value or bucket label. Use export for full drilldown users; this command has no next-page contract.
+
+```bash
+ae-cli analysis history-tag-data-drilldown run --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --group-col VIP --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --limit 100
+```

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

@@ -0,0 +1,15 @@
+# analysis history-tag-data export
+
+Export history tag statistics as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+
+Flags: `--project-id`, `--tag-name`, `--view` required. Optional: `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+`--view` is AI-facing history tag view JSON. It must include a history date range (`recent_day` or `start_time`/`end_time`) and `time_particle_size:"T1"`. Optional fields include `interval_type`, `property_range`, `time_particle`, `array_group_type`, and `column_splited_str`. Do not pass raw frontend wrapper DTOs.
+
+```bash
+ae-cli analysis history-tag-data export --project-id <project_id> --tag-name user_level --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output history-tag-data.jsonl.gz
+```

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

@@ -0,0 +1,15 @@
+# analysis history-tag-data run
+
+Run a bounded inline history tag statistics query. Read `analysis_data_retrieval.md` before choosing run vs export.
+
+Output is bounded history-tag statistics, not member rows. Use `history-tag-data-drilldown run/export` for users behind a returned value or bucket.
+
+Flags: `--project-id`, `--tag-name`, `--view` required. Optional: `--request-id`, `--limit`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+`--view` is AI-facing history tag view JSON. It must include a history date range (`recent_day` or `start_time`/`end_time`) and `time_particle_size:"T1"`. Optional fields include `interval_type`, `property_range`, `time_particle`, `array_group_type`, and `column_splited_str`. Do not pass raw frontend wrapper DTOs.
+
+```bash
+ae-cli analysis history-tag-data run --project-id <project_id> --tag-name user_level --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --limit 100
+```

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

@@ -0,0 +1,11 @@
+# analysis history-tag list
+
+List history snapshots for a tag. Discover the exact `tag_name` with `user-tag list` first.
+
+Do not use it for tag definitions, member rows, or statistics. Output is the available snapshot inventory used to select dates for later commands.
+
+Flags: `--project-id`, `--tag-name` required.
+
+```bash
+ae-cli analysis history-tag list --project-id <project_id> --tag-name user_level
+```

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

@@ -0,0 +1,11 @@
+# analysis history-tag refresh
+
+Refresh one history tag snapshot.
+
+Do not use it to refresh a date range or change the tag definition; use batch refresh or tag update respectively. Output means the refresh was submitted, not that computation has completed.
+
+Flags: `--project-id`, `--tag-name`, `--refresh-date` required. Optional: `--use-user-table-type`.
+
+```bash
+ae-cli analysis history-tag refresh --project-id <project_id> --tag-name user_level --refresh-date 2026-07-01
+```

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

@@ -0,0 +1,9 @@
+# analysis input-file inspect
+
+Inspect an uploaded analysis input file owned by the current user.
+
+```bash
+ae-cli analysis input-file inspect --input-file-id <ifile_id>
+```
+
+Do not use this command to read file content or inspect another user's file. The response returns descriptor metadata; ownership mismatches fail as `INPUT_FILE_NOT_FOUND`.

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

@@ -0,0 +1,9 @@
+# analysis input-file purpose list
+
+List input-file purposes the current identity may upload in one project.
+
+```bash
+ae-cli analysis input-file purpose list --project-id <project_id>
+```
+
+Use this before the low-level upload command. Do not guess purpose strings. The response returns each purpose's analysis gateway domain, formats, size limit, and consuming capabilities.

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

@@ -0,0 +1,11 @@
+# analysis input-file upload
+
+Upload a local file to the analysis gateway for a declared purpose and return an `input_file_id`.
+
+```bash
+ae-cli analysis input-file upload --project-id <project_id> --purpose <purpose> --file <local_path>
+```
+
+Call `analysis input-file purpose list` first and copy a returned purpose. Do not invent a purpose or use this low-level command when `user-tag create-id --input-file` or `user-cluster create-id --input-file` can perform the upload automatically.
+
+The response returns an owner/project/purpose-bound `ifile_...` identifier and inspection metadata.

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

@@ -11,12 +11,13 @@ Domain: **Metadata Lookup**
 ## Use Cases
 - List all alerts in the project. Supports keyword filtering by alert name. Returns a paginated list containing alerts array and pager result with total count.
 - List all alerts in the project.
+- Do not use it for alert result data or one known alert's complete definition; use `+get_alert` after resolving the ID.
 
 ## Commands
 ```bash
 ae-cli analysis +list_alerts --project_id <project_id>
 ae-cli analysis +list_alerts --project_id <project_id> --query demo
-ae-cli analysis +list_alerts --project_id <project_id> --limit 20 --offset 0
+ae-cli analysis +list_alerts --project_id <project_id> --limit 50 --offset 0
 ae-cli analysis +list_alerts --dry-run
 ```
 
@@ -25,7 +26,7 @@ ae-cli analysis +list_alerts --dry-run
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID |
 | `--query` / `-q` | No | Optional keyword filter. Performs fuzzy matching against alert names; if omitted, all alerts are returned. |
-| `--limit` / `-l` | No | Optional page size. Default: 20, maximum: 10000. |
+| `--limit` / `-l` | No | Optional page size. Default: 50, maximum: 200. |
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 
 ## Decision Rules

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

@@ -7,13 +7,14 @@ Domain: **Entity Query**
 ## Use Cases
 - List entities in the project. Returns entity details such as entity ID, name, column name, column description, and type. Can be filtered by event name.
 - List entities in the project.
+- Do not use it to list user members or event rows; it returns entity metadata only.
 
 ## Command
 ```bash
 ae-cli analysis_meta +list_entities --project_id <project_id>
 ae-cli analysis_meta +list_entities --project_id <project_id> --query demo
 ae-cli analysis_meta +list_entities --project_id <project_id> --event_name demo
-ae-cli analysis_meta +list_entities --project_id <project_id> --fields '["entityId", "entityName", "columnName", "columnDesc", "selectType"]' --limit 20 --offset 0
+ae-cli analysis_meta +list_entities --project_id <project_id> --fields '["entityId", "entityName", "columnName", "columnDesc", "selectType"]' --limit 50 --offset 0
 ae-cli analysis_meta +list_entities --dry-run
 ```
 
@@ -24,7 +25,7 @@ ae-cli analysis_meta +list_entities --dry-run
 | `--event_name` | No | Optional event name filter |
 | `--query` / `-q` | No | Optional keyword filter. Fuzzy match is applied to entityName, columnName, and columnDesc; if omitted, all accessible dashboards are returned. |
 | `--fields` / `-f` | No | Optional fields to return (JSON array). Supported fields: `entityId`, `entityName`, `columnName`, `columnDesc`, `selectType`, `tableType`, `entityType`. Default fields when omitted: `entityId`, `entityName`, `columnName`, `columnDesc`, `selectType`. Entity metadata exposes `columnDesc` as the description field; no remark field is available in this list response. |
-| `--limit` / `-l` | No | Optional page size. Default: 20, maximum: 10000. |
+| `--limit` / `-l` | No | Optional page size. Default: 50, maximum: 200. |
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 
 

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

@@ -8,17 +8,17 @@ Domain: **Metadata Query**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
-**Not a builder pre-step:** Do not call `+list_events` before non-SQL ad-hoc analysis. The matching QP builder resolves event names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+**Not an ad-hoc pre-step:** Do not call `+list_events` just to prepare `analysis adhoc run/export`. Pass the user's event wording in the AI-facing `definition`; the backend compiler resolves it or returns a structured clarification/error. Use this command only when the user explicitly wants to inspect metadata or when a prior compiler error asks for disambiguation.
 
 ## Use Cases
 - Read-only query for SYSTEM METADATA already effective in the project. Use for super events in production metadata. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA already effective in the project. Use when the user explicitly asks to inspect event metadata, not as a required preparation step for QP builder.
+- Read-only query for SYSTEM METADATA already effective in the project. Use when the user explicitly asks to inspect event metadata, not as a required preparation step for ad-hoc AI model construction.
 
 ## Commands
 ```bash
 ae-cli analysis_meta +list_events --project_id <project_id>
 ae-cli analysis_meta +list_events --project_id <project_id> --query demo
-ae-cli analysis_meta +list_events --project_id <project_id> --query demo --fields '["eventId", "eventName", "eventDesc", "remark"]' --limit 20 --offset 0
+ae-cli analysis_meta +list_events --project_id <project_id> --query demo --fields '["eventId", "eventName", "eventDesc", "remark"]' --limit 50 --offset 0
 ae-cli analysis_meta +list_events --dry-run
 ```
 
@@ -28,14 +28,14 @@ ae-cli analysis_meta +list_events --dry-run
 | `--project_id` / `-p` | Yes | Project ID |
 | `--query` / `-q` | No | Optional keyword filter. Performs fuzzy matching against eventName, eventDesc, and remark; if omitted, all events are returned. |
 | `--fields` / `-f` | No | Optional fields to return (JSON array). Supported fields: `eventId`, `eventName`, `eventDesc`, `remark`, `eventTag`, `authenticationStatus`. Default fields when omitted: `eventId`, `eventName`, `eventDesc`, `remark`, `authenticationStatus`. |
-| `--limit` / `-l` | No | Optional page size. Default: 20, maximum: 50. |
+| `--limit` / `-l` | No | Optional page size. Default: 50, maximum: 200. |
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 | `--authenticated_only` | No | When true, return only authenticated events. |
 
 ## Decision Rules
 - Use `--authenticated_only true` only when the user explicitly asks for authenticated assets. `authenticationStatus` is `1` for authenticated and `0` for unauthenticated.
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
-- For builder-supported ad-hoc analysis, pass the user's event wording to the builder instead of pre-querying event metadata.
+- For ad-hoc analysis, pass the user's event wording in the AI-facing `definition` instead of pre-querying event metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -8,13 +8,13 @@ Domain: **Metadata Query**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
-**Not a builder pre-step:** Do not call `+list_metrics` before non-SQL ad-hoc analysis. The matching builder resolves referenced metrics internally; the event builder accepts a saved metric name in `metrics[].event`. If the builder fails, stop and ask for clarification instead of using this command as a fallback.
+**Not an ad-hoc pre-step:** Do not call `+list_metrics` just to prepare normal ad-hoc analysis. Pass the saved metric wording directly in `analysis adhoc run/export --definition`; the backend compiler resolves saved metric names internally. If compilation fails, stop and ask for clarification instead of using this command as a fallback.
 
 ## Use Cases
 - List metric metadata in the project. Supports keyword filtering and returns metric IDs, names, display names, model types, remarks, and related metadata, but not metric calculation results.
 - Supports pagination with fields/limit/offset for payload governance.
 - Query performs fuzzy matching on metricName, metricDesc, and metricRemark.
-- Use this command for metric metadata management, metric editing, auditing, or when the user explicitly asks to inspect/search metric metadata. Do not use it merely to prepare a builder-supported ad-hoc query.
+- Use this command for metric metadata management, metric editing, auditing, or when the user explicitly asks to inspect/search metric metadata. Do not use it merely to prepare an ad-hoc query.
 
 ## Command
 ```bash
@@ -30,7 +30,7 @@ ae-cli analysis_meta +list_metrics --dry-run
 | `--project_id` / `-p` | Yes | Project ID |
 | `--query` / `-q` | No | Optional keyword filter. Fuzzy match on metricName, metricDesc, metricRemark. |
 | `--fields` | No | Optional fields to return. Supported: metricId, metricName, metricDesc, metricRemark, metricMode, authenticationStatus, openId, creator, creatorLoginName, updateOpenId, updateCreator, updateLoginName, createTime, updateTime. Default fields when omitted: metricId, metricName, metricDesc, metricRemark, metricMode, authenticationStatus. Invalid fields cause INVALID_FIELDS error. |
-| `--limit` | No | Optional limit. Default: 20, maximum: 50. |
+| `--limit` | No | Optional limit. Default: 50, maximum: 200. |
 | `--offset` | No | Optional offset. Default: 0. |
 | `--authenticated_only` | No | When true, return only authenticated metrics. |
 
@@ -39,7 +39,7 @@ ae-cli analysis_meta +list_metrics --dry-run
 - First run should only pass the required parameter (`--project_id`), and add optional parameters only after the path is confirmed to work.
 - For pagination, use `--limit` and `--offset` together. Default limit is 20.
 - Use `--fields` to select specific columns for lighter response payloads.
-- For builder-supported ad-hoc analysis, do not search metrics here first. Pass the user-provided metric name directly to the builder.
+- For ad-hoc analysis, do not search metrics here first. Pass the user-provided metric name directly to `analysis adhoc run/export`.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -49,4 +49,4 @@ ae-cli analysis_meta +list_metrics --dry-run
 
 ## Recommended Chaining
 - +list_metrics -> +create_metric -> +get_metric
-- For ad-hoc event metric query: +build_event_analysis_qp -> +query_adhoc
+- For ad-hoc event metric query: analysis adhoc run/export

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

@@ -8,6 +8,7 @@ Domain: **Project Configuration**
 - List project date markers. Returns marker IDs, timestamps, content, and visibility status.
 - Supports pagination with fields/limit/offset for payload governance.
 - Query performs fuzzy matching on markContent.
+- Do not use it for report time ranges or event timestamps; this command only lists project date markers.
 
 ## Commands
 ```bash
@@ -24,7 +25,7 @@ ae-cli analysis_meta +list_project_mark_times --dry-run
 | `--zone_offset` | No | Marker time zone offset |
 | `--query` / `-q` | No | Optional keyword filter. Fuzzy match on markContent. |
 | `--fields` | No | Optional fields to return. Supported: id, projectId, markTime, userZoneTime, zoneOffset, markContent, isShow, creatorName, creatorId, lastModifierName, lastModifierId, createTime, updateTime. Invalid fields cause INVALID_FIELDS error. |
-| `--limit` | No | Optional limit. Default: 20, maximum: 10000. |
+| `--limit` | No | Optional limit. Default: 50, maximum: 200. |
 | `--offset` | No | Optional offset. Default: 0. |
 
 ## Decision Rules

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Get all project members. Returns userId, loginName, and userName for each member. Use this to resolve userId when managing dashboard share members.
 - Get all project members.
+- Do not use it as an organization-wide people search or as proof of resource-level authority; it lists project membership only.
 
 ## Command
 ```bash

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

@@ -6,17 +6,17 @@ Domain: **Metadata Query**
 
 ## Constraints
 
-**Not a builder pre-step:** Do not call `+list_properties` before non-SQL ad-hoc analysis. The matching QP builder resolves property names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+**Not an ad-hoc pre-step:** Do not call `+list_properties` just to prepare `analysis adhoc run/export`. Pass the user's property wording in the AI-facing `definition`; the backend compiler resolves it or returns a structured clarification/error. Use this command only when the user explicitly wants to inspect metadata or when a prior compiler error asks for disambiguation.
 
 ## Use Cases
 - Read-only query for SYSTEM METADATA properties already effective in the project. Supports event/user scope. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA properties already effective in the project. Use when the user explicitly asks to inspect property metadata, not as a required preparation step for QP builder.
+- Read-only query for SYSTEM METADATA properties already effective in the project. Use when the user explicitly asks to inspect property metadata, not as a required preparation step for ad-hoc AI model construction.
 
 ## Commands
 ```bash
 ae-cli analysis_meta +list_properties --project_id <project_id>
 ae-cli analysis_meta +list_properties --project_id <project_id> --scope event --event_name purchase --query demo
-ae-cli analysis_meta +list_properties --project_id <project_id> --query demo --fields '["propId", "propName", "propDesc", "remark", "selectType", "tableType"]' --limit 20 --offset 0
+ae-cli analysis_meta +list_properties --project_id <project_id> --query demo --fields '["propId", "propName", "propDesc", "remark", "selectType", "tableType"]' --limit 50 --offset 0
 ae-cli analysis_meta +list_properties --dry-run
 ```
 
@@ -28,7 +28,7 @@ ae-cli analysis_meta +list_properties --dry-run
 | `--event_name` | No | Optional event name. If provided, only event properties available for that event are returned. |
 | `--query` / `-q` | No | Optional keyword filter. Fuzzy match is applied to propName, propDesc, and remark; if omitted, all matched properties are returned. |
 | `--fields` / `-f` | No | Optional fields to return (JSON array). Supported fields: `propId`, `propName`, `propDesc`, `remark`, `selectType`, `tableType`, `subTableType`, `authenticationStatus`. Default fields when omitted: `propId`, `propName`, `propDesc`, `remark`, `selectType`, `tableType`, `authenticationStatus`. |
-| `--limit` / `-l` | No | Optional page size. Default: 20, maximum: 50. |
+| `--limit` / `-l` | No | Optional page size. Default: 50, maximum: 200. |
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 | `--authenticated_only` | No | When true, return only authenticated properties. |
 
@@ -36,7 +36,7 @@ ae-cli analysis_meta +list_properties --dry-run
 ## Decision Rules
 - Use `--authenticated_only true` only when the user explicitly asks for authenticated assets. `authenticationStatus` is `1` for authenticated and `0` for unauthenticated.
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
-- For builder-supported ad-hoc analysis, pass the user's property wording to the builder instead of pre-querying property metadata.
+- For ad-hoc analysis, pass the user's property wording in the AI-facing `definition` instead of pre-querying property metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -12,6 +12,9 @@ Domain: **Model Analysis**
 - clusterDatePolicy is only used when tableType=user and user clusters are involved. Supported values: LATEST, AUTO, SPECIFIED.
 - Load candidate values for a property.
 
+## Output
+Returns candidate values for the requested property and scope. Treat the list as selectable values, not as aggregated counts or analysis results.
+
 ## Commands
 ```bash
 ae-cli analysis +load_filters --project_id <project_id> --quot demo --table_type event

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

@@ -2,23 +2,28 @@
 
 Use when the user needs to create a metric from event or retention analysis configuration.
 
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+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.
 
 Command:
 
 ```bash
-ae-cli analysis-meta metric create --project-id <project_id> --payload '{}'
-ae-cli analysis-meta metric create --dry-run
+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
 ```
 
 Capability id: `metadata.metric.create`.
 
-Input sends `project_id`, `payload`.
+Input sends typed snake_case fields. Common serializes `metric_events` and `metric_params` for the backend.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.metric` contains the created metric summary.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--metric-name` | Yes | Metric technical name. |
+| `--metric-desc` | Yes | Metric display name. |
+| `--metric-mode` | Yes | Metric model mode, for example `0` for event analysis. |
+| `--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. |