@thinkingai/ae-cli 6.0.30 → 6.0.32

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

@@ -0,0 +1,33 @@
+# analysis entity-detail export
+
+Submit a bounded entity detail query as an async gzip artifact.
+
+Read `analysis_data_retrieval.md` first. The submit response returns `run_id` and `artifact_id`; poll with `analysis run inspect`, then download with `analysis artifact download`.
+
+Use this command for full or unknown-size entity detail data. Common reads backend batches internally and writes one artifact.
+
+```bash
+ae-cli analysis entity-detail export \
+  --project-id <project_id> \
+  --definition '{"entity":"user","cohort":{"relation":"and","items":[{"field":{"name":"level","type":"user_property"},"operator":"gte","values":[1]}]}}' \
+  --artifact-format jsonl
+```
+
+Input:
+- `--project-id` numeric project ID.
+- `--definition` same bounded entity detail shape as `entity-detail run`.
+- `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
+- `--use-cache` optional boolean.
+- `--zone-offset` optional number.
+- `--artifact-format` `jsonl` or `csv`; default `jsonl`.
+- `--timeout-seconds` optional async runtime guard.
+
+Do not pass `--limit`; async export rejects inline limits. Use `--artifact-format`, not global `--format`, for artifact format.
+
+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

@@ -0,0 +1,57 @@
+# analysis entity-detail run
+
+Run a bounded entity detail query through the capability gateway.
+
+Read `analysis_data_retrieval.md` before choosing this command. Use `run` only when inline rows are enough; use `entity-detail export` for bounded artifact retrieval up to the detail export row cap.
+
+Use this command for the first small entity detail preview that fits inline. It is not a pagination API; do not loop with offsets to collect more rows.
+
+```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":[{"name":"country","type":"user_property"}],"sort":[{"field":"#user_id","order":"asc"}]}' \
+  --limit 100
+```
+
+Input:
+- `--project-id` numeric project ID.
+- `--definition` bounded entity detail JSON object with `entity`, `cohort`, optional `properties`, and optional `sort`.
+- `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
+- `--use-cache` optional boolean.
+- `--zone-offset` optional number.
+- `--limit` first inline preview rows, default 100, max 1000.
+- `--timeout-seconds` sync timeout, default 120, max 180.
+
+`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
+{
+  "relation": "and",
+  "items": [
+    {
+      "field": { "name": "level", "type": "user_property" },
+      "operator": "gte",
+      "values": [1]
+    }
+  ]
+}
+```
+
+Supported `cohort.items[].field.type` values are `user_property`, `tag`, and `cluster`. Event behavior cohort conditions are not supported by this command yet; do not invent raw cluster QP for them.
+
+Do not put raw QP at the capability top level. Use `properties` items as strings or `{ "name": "...", "type": "user_property" }`, not `columnName/tableType`.
+
+Do not use this command for full, unknown-size, or later-page detail retrieval. Use `analysis entity-detail export` and check its artifact metadata for `truncated`.
+
+Output:
+
+Returns JSON with `items`, `total`, `limit`, `returned_rows`, `truncated`, `column_meta`, and `request_id`. `truncated=true` means the preview hit its row cap or the backend reported more rows; use `analysis entity-detail export` instead of trying to page or claiming completeness.

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

@@ -0,0 +1,20 @@
+# analysis entity id-import-options
+
+Discover how imported values must map to one analysis entity before creating or updating an imported-value cluster or tag.
+
+```bash
+ae-cli analysis entity id-import-options --project-id <project_id> --entity-id <entity_id>
+```
+
+If the entity ID is not already known, discover it first instead of guessing:
+
+```bash
+ae-cli analysis_meta +list_entities --project_id <project_id> --fields '["entityId","entityName","columnName","entityType"]'
+```
+
+- `match_mode=user_property`: `--association-property` is required and must be copied from `association_properties`; `#user_id` is forbidden.
+- `match_mode=entity_id`: omit `--association-property`; the first CSV column contains that entity's own IDs.
+
+Output includes the resolved `entity_column`, matching mode, whether an association property is required, explicitly excluded properties, and the allowed property names/types.
+
+Do not guess `entity_id`, property names, or CSV shape.

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to list event metadata change logs.
 
-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 for the current event definition or tracking data; use `event get` or an analysis query.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.changelog_list`.
 
 Input sends `project_id`, `event_name`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.changelogs[]` contains metadata change records for the event.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to create super events and optionally associate event properties.
 
-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 for a virtual event, tracking-plan event, or description-only update. Use the corresponding virtual-event, tracking-plan, or `event update` command.
 
 Command:
 
 ```bash
-ae-cli analysis-meta event create --project-id <project_id> --payload '{}'
+ae-cli analysis-meta event create --project-id <project_id> --payload '{"event_name":"purchase","event_desc":"Purchase","source_type":"<source_type>","source_event_name":"<source_event>"}'
 ae-cli analysis-meta event create --dry-run
 ```
 
@@ -15,10 +15,10 @@ Capability id: `metadata.event.create`.
 
 Input sends `project_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Read back with `event get`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--payload` | Yes | Super-event object. Required: `event_name`, `source_type`. Optional: `event_desc`, `remark`, `source_event_name`, `source_route_code`, `super_event_prop_ids`. Use real source metadata; `{}` is invalid. |

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

@@ -2,20 +2,21 @@
 
 Use when the user needs to batch delete events or virtual events.
 
-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 before `event influence-list` is reviewed for every target, or for tracking-plan entries.
 
 Command:
 
 ```bash
-ae-cli analysis-meta event delete --project-id <project_id> --event-names '{}'
-ae-cli analysis-meta event delete --dry-run
+ae-cli analysis-meta event delete --project-id <project_id> --event-names '["purchase"]' --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis-meta event delete --project-id <project_id> --event-names '["purchase"]' --yes
 ```
 
 Capability id: `metadata.event.delete`.
 
 Input sends `project_id`, `event_names`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Verify with `event list`.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -0,0 +1,33 @@
+# analysis event-detail export
+
+Submit a bounded event detail query as an async gzip artifact.
+
+Read `analysis_data_retrieval.md` first. The submit response returns `run_id` and `artifact_id`; poll with `analysis run inspect`, then download with `analysis artifact download`.
+
+Use this command for full or unknown-size event detail data. Common reads backend batches internally and writes one artifact.
+
+```bash
+ae-cli analysis event-detail export \
+  --project-id <project_id> \
+  --definition '{"event":"login","time_range":{"mode":"relative","relative_date_range":"0-7"}}' \
+  --artifact-format jsonl
+```
+
+Input:
+- `--project-id` numeric project ID.
+- `--definition` same AI-facing shape as `event-detail run`.
+- `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
+- `--use-cache` optional boolean.
+- `--zone-offset` optional number.
+- `--artifact-format` `jsonl` or `csv`; default `jsonl`.
+- `--timeout-seconds` optional async runtime guard.
+
+Do not pass `--limit`; async export rejects inline limits. Use `--artifact-format`, not global `--format`, for artifact format.
+
+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

@@ -0,0 +1,60 @@
+# analysis event-detail run
+
+Run a bounded event detail query through the capability gateway.
+
+Read `analysis_data_retrieval.md` before choosing this command. Use `run` only when inline rows are enough; use `event-detail export` for bounded artifact retrieval up to the detail export row cap.
+
+Use this command for the first small event detail preview that fits inline. It is not a pagination API; do not loop with offsets to collect more rows.
+
+```bash
+ae-cli analysis event-detail run \
+  --project-id <project_id> \
+  --definition '{"event":"login","time_range":{"mode":"absolute","start_time":"2026-07-01 00:00:00","end_time":"2026-07-01 23:59:59"},"properties":["#event_time",{"name":"country","type":"user_property"}],"sort":[{"field":"#event_time","order":"desc"}]}' \
+  --limit 100
+```
+
+Input:
+- `--project-id` numeric project ID.
+- `--definition` AI-facing JSON object. Required keys: `event`, `time_range`. Optional keys: `filters`, `properties`, `sort`.
+- `--request-id` optional `cli_<32 lowercase hex>` lifecycle ID.
+- `--use-cache` optional boolean.
+- `--zone-offset` optional number, for example `8` for UTC+8.
+- `--limit` first inline preview rows, default 100, max 1000.
+- `--timeout-seconds` sync timeout, default 120, max 180.
+
+Definition shape:
+
+```json
+{
+  "event": "login",
+  "time_range": {
+    "mode": "absolute",
+    "start_time": "2026-07-01 00:00:00",
+    "end_time": "2026-07-01 23:59:59"
+  },
+  "filters": {
+    "relation": "and",
+    "items": [
+      {
+        "field": { "name": "country", "type": "user_property" },
+        "operator": "eq",
+        "values": ["US"]
+      }
+    ]
+  },
+  "properties": ["#event_time", { "name": "country", "type": "user_property" }],
+  "sort": [{ "field": "#event_time", "order": "desc" }]
+}
+```
+
+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:
+
+Returns JSON with `items`, `total`, `limit`, `returned_rows`, `truncated`, `column_meta`, and `request_id`. `truncated=true` means the preview hit its row cap or the backend reported more rows; use `analysis event-detail export` instead of trying to page or claiming completeness.

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to get one super event metadata detail.
 
-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 for event result data, virtual-event-by-ID detail, or fuzzy discovery; use analysis data, `virtual-event get`, or `event list`.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.get`.
 
 Input sends `project_id`, `event_name`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.event` contains the super-event metadata detail.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to batch hide or show events.
 
-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 for deletion: this changes metadata visibility and keeps the event. Review affected assets first when needed.
 
 Command:
 
 ```bash
-ae-cli analysis-meta event hide-update --project-id <project_id> --event-names '{}' --is-hide true
+ae-cli analysis-meta event hide-update --project-id <project_id> --event-names '["purchase"]' --is-hide true
 ae-cli analysis-meta event hide-update --dry-run
 ```
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.hide_update`.
 
 Input sends `project_id`, `event_names`, `is_hide`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Verify visibility with `event list|get`.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to list assets affected by event delete, hide, or update.
 
-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 as mutation or as proof that deletion is safe without reviewing every returned dependency.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.influence_list`.
 
 Input sends `project_id`, `event_name`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is the snake_case event influence object returned by Common, including dependent assets and operation constraints.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -1,23 +1,31 @@
 # 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 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 for raw tracked events, event counts, or one full definition; it lists project super-event metadata.
 
 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`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+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.
 
 ## Parameters
 | 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/{super_metadata_export.md → event_property_bundle_export.md}

@@ -1,15 +1,15 @@
-# analysis-meta super-metadata export
+# analysis-meta event-property-bundle export
 
 Use when the user needs to export super event and super property 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 for result data, a partial metadata subset, or import. The artifact is the complete super-event/super-property configuration export.
 
 Command:
 
 ```bash
-ae-cli analysis-meta super-metadata export --project-id <project_id>
-ae-cli analysis-meta super-metadata export --project-id <project_id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 3600
-ae-cli analysis-meta super-metadata export --dry-run
+ae-cli analysis-meta event-property-bundle export --project-id <project_id>
+ae-cli analysis-meta event-property-bundle export --project-id <project_id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 21600
+ae-cli analysis-meta event-property-bundle export --dry-run
 ```
 
 Capability id: `metadata.super_metadata.export`.
@@ -24,7 +24,7 @@ Follow-up workflow:
 2. Poll status with `ae-cli analysis run inspect --run-id <run_id>`.
 3. Continue polling while status is running or pending. Treat `COMPLETED` or `SUCCEEDED` as success, and `FAILED`, `CANCELED`, or `CANCELLED` as terminal failure.
 4. On success, download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>.xlsx`.
-5. If the export is no longer needed, cancel with `ae-cli analysis query cancel --run-id <run_id> --yes`.
+5. If the export is no longer needed, cancel with `ae-cli analysis query cancel --run-id <run_id>`.
 
 Do not write custom Python/curl for polling or download unless the CLI command itself is unavailable.
 
@@ -33,4 +33,4 @@ Do not write custom Python/curl for polling or download unless the CLI command i
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
-| `--timeout-seconds` | No | Timeout in seconds, 1 to 7200. Default 3600. |
+| `--timeout-seconds` | No | Timeout in seconds, 1 to 21600. Default 21600 (6 hours). |

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

@@ -0,0 +1,25 @@
+# analysis-meta event-property-bundle import
+
+Use this reference only to identify the reserved future import contract; the current backend is intentionally blocked.
+
+Do not use it for a real import. It always returns `CAPABILITY_REQUIRES_FILE_ADAPTER` until CLI input-file handling is wired to the server import service.
+
+Command:
+
+```bash
+ae-cli analysis-meta event-property-bundle import --project-id <project_id> --operation pre_import --input-file-id <input_file_id> --dry-run
+```
+
+Capability id: `metadata.super_metadata.import`.
+
+Input sends `project_id`, `operation`, and the operation-specific file or pre-import identifier.
+
+Output is the structured `CAPABILITY_REQUIRES_FILE_ADAPTER` error with `implementation_status=blocked`; no metadata is imported.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--operation` | Yes | Import step: `pre_import` or `ensure_import`. |
+| `--input-file-id` | No | Uploaded XLSX file ID for `pre_import`; upload it with purpose `super_metadata.import.xlsx`. |
+| `--pre-import-meta-uuid` | No | UUID returned by `pre_import`, required for `ensure_import`. |

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to update event-property connection or source relations.
 
-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 for display-name/remark-only edits; use `event update`. This command replaces the relation-bearing super-event definition.
 
 Command:
 
 ```bash
-ae-cli analysis-meta event relation-update --project-id <project_id> --payload '{}'
+ae-cli analysis-meta event relation-update --project-id <project_id> --payload '{"event_name":"purchase","source_type":"<source_type>","source_event_name":"<source_event>","super_event_prop_ids":[<property_id>]}'
 ae-cli analysis-meta event relation-update --dry-run
 ```
 
@@ -15,10 +15,10 @@ Capability id: `metadata.event.relation_update`.
 
 Input sends `project_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Read back with `event get`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--payload` | Yes | Complete relation-bearing super-event object: required `event_name` and `source_type`; optional `event_desc`, `remark`, `source_event_name`, `source_route_code`, and `super_event_prop_ids`. |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to update event display names and remarks.
 
-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 change source-event/property relations; use `event relation-update` for the complete relation definition.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.update`.
 
 Input sends `project_id`, `event_name`, `event_desc`, `remark`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Read back with `event get`.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to update exchange-rate configuration switch or value.
 
-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 edit conversion rules or refresh rate data; those are `exchange rule-update` and `exchange rate-refresh`.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.exchange_config.update`.
 
 Input sends `project_id`, `config_val`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to refresh exchange-rate data manually.
 
-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 change rules/configuration, and do not repeatedly refresh to compensate for an invalid rule.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.exchange_rate.refresh`.
 
 Input sends `project_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data after the refresh request completes.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,7 +2,7 @@
 
 Use when the user needs to list exchange-rate conversion 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 validate or persist proposed rules; use `exchange rule-validate` then `exchange rule-update`.
 
 Command:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.exchange_rule.list`.
 
 Input sends `project_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.rules[]` contains the project's current exchange rules.
 
 ## Parameters
 | Parameter | Required | Description |

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

@@ -2,12 +2,12 @@
 
 Use when the user needs to save currency field, amount field, and target currency 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 before `exchange rule-validate`, or when the user only wants to inspect current rules.
 
 Command:
 
 ```bash
-ae-cli analysis-meta exchange rule-update --project-id <project_id> --payload '{}'
+ae-cli analysis-meta exchange rule-update --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-update --dry-run
 ```
 
@@ -15,10 +15,10 @@ Capability id: `metadata.exchange_rule.update`.
 
 Input sends `project_id`, `payload`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output is a successful gateway envelope with no business data. Read back with `exchange rule-list`.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Capability payload JSON. |
+| `--payload` | Yes | The exact `{target_currency,exchange_rules}` object already accepted by `exchange rule-validate`; do not reconstruct a different payload after validation. |

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`.