@thinkingai/ae-cli 6.0.30 → 6.0.32

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_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_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. |
 
 
@@ -38,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/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/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,37 @@
 
 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.
 
 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' --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`.
 
-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. |
+| `--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

@@ -2,23 +2,31 @@
 
 Use when the user needs to delete a metric.
 
-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 remove a metric from one report or to delete by guessed ID; resolve and inspect the metric first.
 
 Command:
 
 ```bash
-ae-cli analysis-meta metric delete --project-id <project_id> --metric-id <metric_id>
-ae-cli analysis-meta metric delete --dry-run
+ae-cli analysis-meta metric delete --project-id <project_id> --metric-id <metric_id> --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-meta metric delete --project-id <project_id> --metric-id <metric_id> --yes
 ```
 
 Capability id: `metadata.metric.delete`.
 
 Input sends `project_id`, `metric_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Verify with `metric list|get`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--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`

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

@@ -2,7 +2,8 @@
 
 Use when the user needs to get metric definition, events, and params.
 
-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 or trends; it returns the saved metric definition only.
+Do not call it 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.
 
 Command:
 
@@ -15,10 +16,15 @@ Capability id: `metadata.metric.get`.
 
 Input sends `project_id`, `metric_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.metric` contains the saved metric definition, or no metric when the ID does not resolve.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--metric-id` | Yes | Metric ID. |
+
+## Recommended Chaining
+
+- analysis-meta metric get -> analysis-meta metric update
+- For ad-hoc saved metric query: analysis adhoc run/export

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

@@ -1,24 +1,37 @@
 # analysis-meta metric list
 
-Use when the user needs to list project metrics.
+Use when the user needs to list, search, page, or field-project project metrics.
 
-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 calculate metric values; use report/dashboard/ad-hoc data routing for result queries.
 
 Command:
 
 ```bash
+ae-cli analysis-meta metric list --project-id <project_id>
 ae-cli analysis-meta metric list --project-id <project_id> --ignore-authentication true
+ae-cli analysis-meta metric list --project-id <project_id> --query pay
+ae-cli analysis-meta metric list --project-id <project_id> --query pay --fields '["metric_name","authentication_status"]' --limit 10 --offset 0 --authenticated-only true
 ae-cli analysis-meta metric list --dry-run
 ```
 
 Capability id: `metadata.metric.list`.
 
-Input sends `project_id`, `ignore_authentication`.
+Input sends `project_id`, `ignore_authentication`, `query`, `fields`, `limit`, `offset`, and `authenticated_only`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.metrics[]` contains project metric summaries. When `limit` or `offset` is present, output also includes `total`, `limit`, `offset`, and `has_more`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--ignore-authentication` | No | Whether to skip asset authentication status decoration. |
+| `--query` | No | Optional keyword filter. Fuzzy match on `metric_name`, `metric_desc`, and `metric_remark`. |
+| `--fields` | No | Optional result field projection JSON array. Supported fields: `metric_id`, `metric_name`, `metric_desc`, `metric_remark`, `metric_mode`, `authentication_status`, `open_id`, `creator`, `creator_login_name`, `update_open_id`, `update_creator`, `update_login_name`, `create_time`, `update_time`. |
+| `--limit` | No | Optional page size. Default: 20 when pagination is used, maximum: 50. |
+| `--offset` | No | Optional zero-based result offset. Default: 0. |
+| `--authenticated-only` | No | When true, return only authenticated metrics. |
+
+## Decision Rules
+- Do not call this just to prepare normal ad-hoc analysis. Pass saved metric wording directly in `analysis adhoc run/export --definition`; the backend compiler resolves saved metric names internally.
+- Use `--fields` to keep discovery responses compact.
+- Use `analysis-meta metric get` after this command when a full metric definition is needed.

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

@@ -2,23 +2,40 @@
 
 Use when the user needs to update metric definition, name, and remark.
 
-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.
+
+Before updating `--metric-events` / `--metric-params`, validate the event and property names with `analysis-meta event list` and `analysis-meta property list` in the same `project_id`.
 
 Command:
 
 ```bash
-ae-cli analysis-meta metric update --project-id <project_id> --payload '{}'
-ae-cli analysis-meta metric update --dry-run
+ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-desc 'New display name' --metric-remark 'New remark'
+ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-name demo --metric-desc demo --model-type event --metric-events '[]'
+ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-name demo --metric-desc demo --metric-remark demo --model-type retention --metric-events '[]' --metric-params '{}'
+ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-desc 'New display name' --dry-run
 ```
 
 Capability id: `metadata.metric.update`.
 
-Input sends `project_id`, `payload`.
+Input sends typed snake_case fields.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.metric` contains the updated summary for a full-definition update containing `metric_events`. A display-name/remark-only edit succeeds without business data.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--metric-id` | Yes | Metric ID. |
+| `--metric-name` | No | Metric technical name for a full-definition update. |
+| `--metric-desc` | No | Metric display name. |
+| `--metric-remark` | No | Metric remark. |
+| `--metric-mode` | No | Metric model mode for a full-definition update. |
+| `--model-type` | No | Semantic metric model type: `event` or `retention`. Prefer this over `--metric-mode`. |
+| `--metric-events` | No | Metric event-analysis QP JSON array for a full-definition update. |
+| `--metric-params` | No | Metric params JSON object. |
+
+## Decision Rules
+- For full-definition updates, pass `--metric-name`, `--metric-desc`, one of `--model-type` / `--metric-mode`, and `--metric-events` together.
+- If both `--model-type` and `--metric-mode` are present, they must match: `event -> 0`, `retention -> 1`.
+- Use `analysis-meta metric get` before updating if the current definition needs to be preserved and edited.
+- This is an ordinary write operation; execute it without the high-risk confirmation flag.

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

@@ -0,0 +1,25 @@
+# analysis-governance operation-record export
+
+Use when the user needs to export one asset batch operation record result through the capability gateway.
+
+Do not use it to list records or export asset rows; resolve one real `record_id` first, then export that operation's result as XLSX.
+
+Command:
+
+```bash
+ae-cli analysis-governance operation-record export --project-id <project_id> --payload '{}'
+ae-cli analysis-governance operation-record export --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_operation_record.export.
+
+Input sends project_id, payload, record_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download that exact export.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --record-id | No | Operation record ID; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -0,0 +1,31 @@
+# analysis-governance operation-record list
+
+Use when the user needs to list asset batch operation records through the capability gateway.
+
+Do not use it to submit a new batch operation; use it to find and inspect records produced by prior asset governance actions.
+
+Command:
+
+```bash
+ae-cli analysis-governance operation-record list --project-id <project_id> --payload '{}'
+ae-cli analysis-governance operation-record list --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_operation_record.list.
+
+Input sends project_id, payload, type, status, query, sort_field, sort_order, limit, offset. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the paged batch-operation record result. Use record status to distinguish submitted, running, successful, and failed work before taking another action.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --type | No | Batch operation type. |
+| --status | No | Operation status JSON array. |
+| --query | No | Keyword filter. |
+| --sort-field | No | Sort field. |
+| --sort-order | No | Sort order: asc or desc. |
+| --limit | No | Inline page size. |
+| --offset | No | Zero-based page offset. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |