@thinkingai/ae-cli 6.0.29 → 6.0.31

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

@@ -0,0 +1,61 @@
+# analysis drilldown-users run
+
+Precondition: the upstream response must have `drilldown_available=true` and the selected source must contain `target_contract`. If either is absent, do not call this command or reconstruct a target from display text.
+
+Drill down to users from a previous analysis data query context.
+
+Use this after any analysis data command that returns `query_context_id`:
+
+- `analysis adhoc run`
+- `analysis adhoc export`
+- `analysis report-data run`
+- `analysis report-data export`
+- `analysis dashboard-report-data run`
+- `analysis dashboard-report-data export`
+
+Do not pass raw QP.
+
+## Command
+
+```bash
+ae-cli analysis drilldown-users run \
+  --query-context-id <query_context_id> \
+  --target '<json>' \
+  [--limit 100] \
+  [--timeout-seconds 120]
+```
+
+## Input
+
+- `--query-context-id`: returned by an analysis data run/export submit response, or by the first metadata line of a JSONL artifact.
+- `--target`: pass the selected source's `target_contract.default_target` directly for the whole-result default. For a specific result row or cell, copy that object and replace only the fields named by `target_contract.copy_from_selected_result`.
+- `--properties`: optional backend property request object array. Omit this in normal agent calls and use the default returned columns. Do not pass string-name arrays such as `["#user_id"]`.
+
+Do not use raw QP or reconstruct the first query request. The server resolves the source QP from Redis by `query_context_id`.
+
+## Target
+
+`--target` identifies the cell/step/bucket/date to drill down. The upstream `sources[]` entry is the machine-readable contract. Do not infer a target shape from model memory or reuse a target from a different source/model.
+
+`target_contract.default_target` already contains `report_id` or `chart_id` when needed. Preserve it unchanged:
+
+```json
+{"report_id":1001,"drilldown_date":"2026-07-01","drilldown_groups":["ios"],"event_index":0}
+```
+
+Common fields:
+
+- `report_id`: required when the context contains multiple report sources.
+- `chart_id`: required when the context contains multiple BI chart sources. BI SQL chart contexts normally return `drilldown_available=false`; do not call drilldown unless the first response explicitly says `drilldown_available=true`.
+- `drilldown_date` or `target_dates`: target date(s) from the result row. Include one of these when you plan to call `drilldown-user-events` next; `include_total` alone can list users but may not carry enough date context for event-sequence lookup.
+- `drilldown_groups`: group values from the result row.
+- `event_index`: event model index, starting from 0.
+- `retention_days`, `is_lost`: retention target.
+- `funnel_step`, `is_churned_user`: funnel target.
+- `interval`, `distribution_bucket`, `compare_index`, `include_total`, `relation_val`: model-specific target fields.
+
+## Output
+
+The response contains at most `limit` user rows and a `drilldown_context_id`. When `truncated=true`, use `analysis drilldown-users export`; do not attempt to fetch another page.
+
+Use `drilldown_context_id` with `analysis drilldown-user-events run` or `analysis drilldown-user-events export`.

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

@@ -0,0 +1,31 @@
+# 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.
+
+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,50 @@
+# 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":["#user_id",{"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.
+
+`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,31 @@
+# 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.
+
+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,58 @@
+# 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`.
+
+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

@@ -2,7 +2,7 @@
 
 Use when the user needs to list project super 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:
 
@@ -15,7 +15,7 @@ Capability id: `metadata.event.list`.
 
 Input sends `project_id`.
 
-Output is the gateway envelope. `data` contains the common-service capability result.
+Output `data.events[]` contains project super-event metadata records.
 
 ## Parameters
 | Parameter | Required | Description |

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