@thinkingai/ae-cli 6.1.19 → 6.1.21

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

@@ -1,6 +1,8 @@
 # Analysis AI-facing models
 
-This file is the single reference for `model_type` spelling and AI-facing `definition` shape.
+This file defines `model_type` spelling and shared AI-facing building blocks. Each model's definition contract has its own file below.
+
+Read the needed common building blocks and open the selected model file directly from the registry. Reuse unchanged content already read; other model files do not add requirements to the selected model.
 
 ## Capability coverage
 
@@ -14,25 +16,25 @@ Do not pass raw QP, `events`, `eventView`, `visualView`, frontend DTOs, schema-g
 
 Common analysis models (9):
 
-- `event`: event analysis
-- `retention`: retention analysis
-- `funnel`: funnel conversion analysis
-- `distribution`: distribution analysis
-- `attribution`: attribution analysis
-- `interval`: interval analysis
-- `path`: path analysis
-- `prop_analysis`: property analysis
-- `sql`: SQL analysis
+- [`event`](ai_models/event.md): event analysis
+- [`retention`](ai_models/retention.md): retention analysis
+- [`funnel`](ai_models/funnel.md): funnel conversion analysis
+- [`distribution`](ai_models/distribution.md): distribution analysis
+- [`attribution`](ai_models/attribution.md): attribution analysis
+- [`interval`](ai_models/interval.md): interval analysis
+- [`path`](ai_models/path.md): path analysis
+- [`prop_analysis`](ai_models/prop_analysis.md): property analysis
+- [`sql`](ai_models/sql.md): SQL analysis
 
 Scenario analysis models (3):
 
-- `heat_map`: heat map analysis
-- `rank_list`: ranking analysis
-- `revenue`: revenue analysis
+- [`heat_map`](ai_models/heat_map.md): heat map analysis
+- [`rank_list`](ai_models/rank_list.md): ranking analysis
+- [`revenue`](ai_models/revenue.md): revenue analysis
 
 Report write only:
 
-- `tag`: saved tag report data. Use this spelling in CLI.
+- [`tag`](ai_models/tag.md): saved tag report data. Use this spelling in CLI.
 
 ## Common building blocks
 
@@ -66,7 +68,6 @@ Field reference:
 
 - `type` can be `event_property`, `user_property`, `cluster`, or `tag`.
 - Omit `type` only when the field name is unambiguous.
-- `prop_analysis` dimensions and filters support `user_property`, `cluster`, and `tag`; they do not support `event_property`.
 
 Filter:
 
@@ -78,456 +79,34 @@ Filter:
 - Omit `values` for `exists` and `not_exists`.
 - Use exactly two values for `between`.
 
-Group:
-
-```json
-{"field":{"name":"country","type":"user_property"}}
-```
-
-Metric aggregation values must use semantic spelling, not internal A-codes. The whitelist is model- and property-type-specific because it mirrors the page controls:
-
-- `event`: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`.
-- `retention` simultaneous metrics: without property use `total_count`, `user_count`, or `per_user_count`; numeric properties support only `sum` and `avg_per_user`; boolean properties support only `true_count`, `false_count`, `not_empty_count`, and `empty_count`.
-- `distribution`: without property use `count`, `active_days`, or `active_hours`; numeric properties support `sum`, `avg`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`; string/date/datetime properties support `distinct_count`; boolean properties support `true_count`, `false_count`, `not_empty_count`, `empty_count`, and `distinct_count`.
-- `attribution`: use `total_count` without `target_property`, or `sum` with a numeric `target_property`.
-- `prop_analysis`: use `user_count` without property; property aggregations follow the event property-type rules except that `percentile` is not supported.
-- `heat_map`, `rank_list`, and `revenue`: use the event whitelist except that `percentile` is not supported.
-
-For total event count use `total_count`; `count` belongs only to distribution. Internal `Axxx` codes are persisted page details and are not valid authored AI definitions.
-
-## Model definitions
-
-### `event`
-
-Use for event metrics, trends, grouping, filters, and comparisons.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "time_particle_size": "day",
-  "metrics": [
-    {"event": "login", "aggregation": "user_count"}
-  ],
-  "groups": [
-    {"field": {"name": "country", "type": "user_property"}}
-  ],
-  "filters": [
-    {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
-  ],
-  "relation": "and"
-}
-```
-
-Property aggregation example:
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "metrics": [
-    {"event": "purchase", "display_name": "Purchase revenue", "aggregation": "sum", "property": "amount"}
-  ]
-}
-```
-
-Set optional `display_name` on an event metric when the report should show a business-facing metric name. It applies to regular event metrics, saved metrics, and formula metrics. Omit it to use the event name or the default formula-metric label.
-
-Formula metric example:
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "metrics": [
-    {
-      "display_name": "Revenue per user",
-      "formula": "revenue / users",
-      "dependencies": [
-        {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
-        {"alias": "users", "event": "login", "aggregation": "user_count"}
-      ]
-    }
-  ]
-}
-```
-
-Formula rules:
-
-- Write **bare aliases** only in `formula` (e.g. `"revenue / users"` or `"pay / dau"`).
-- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Aggregation codes come from each dependency's `aggregation`; the builder expands aliases to real event tokens such as `purchase.amount.A103/login.A101`.
-- After the builder returns `status=generated`, hard-validate by querying (`analysis adhoc run` / report-data / dashboard-report-data). Do not save a report or dashboard from an unqueried formula QP.
-
-### `retention`
-
-Use for retained/lost users from an initial event to a return event.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "time_particle_size": "day",
-  "retention": {
-    "initial_event": "register",
-    "return_event": "login",
-    "stat_type": "retention",
-    "unit_num": 1,
-    "rtn_rate_or_num": "rate",
-    "groups": [
-      {"field": {"name": "channel", "type": "user_property"}}
-    ]
-  }
-}
-```
-
-Use `stat_type=lost` for lost-user analysis. Use `rtn_rate_or_num=count` when the user asks for user counts instead of rates.
-
-Initial-event and return-event property filters use the retention-specific shape below. Put them inside `retention`; use `event_property_name` instead of a generic `field` object. Do not use top-level `filters`, `retention.filters`, or `initial_event_filters`.
-
-```json
-{
-  "time_range": {"mode": "custom", "start_time": "2026-08-18 00:00:00", "end_time": "2026-08-18 23:59:59"},
-  "time_particle_size": "day",
-  "retention": {
-    "initial_event": "register",
-    "initial_filters": [
-      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
-    ],
-    "initial_filter_relation": "and",
-    "return_event": "login",
-    "return_filters": [
-      {"event_property_name": "case_id", "operator": "eq", "values": ["retention_test"]}
-    ],
-    "return_filter_relation": "and",
-    "stat_type": "retention",
-    "unit_num": 1,
-    "rtn_rate_or_num": "rate",
-    "groups": [
-      {"field": {"name": "channel", "type": "event_property"}}
-    ]
-  }
-}
-```
-
-### `funnel`
-
-Use for ordered conversion steps with a conversion window.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "time_particle_size": "day",
-  "funnel": {
-    "steps": [
-      {"event": "view_product"},
-      {"event": "add_to_cart"},
-      {"event": "purchase"}
-    ],
-    "window": {"value": 3, "unit": "day"},
-    "groups": [
-      {"field": {"name": "channel", "type": "user_property"}}
-    ]
-  }
-}
-```
-
-If the user asks to match users across events by a shared event property, set `relation_event_property_name`.
-
-### `distribution`
-
-Use for user distribution buckets for an event or property metric.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "distribution_metrics": [
-    {
-      "event": "purchase",
-      "aggregation": "sum",
-      "property": "amount",
-      "filters": [
-        {
-          "field": {"name": "vip_users", "type": "cluster"},
-          "operator": "in_cluster"
-        }
-      ],
-      "relation": "and",
-      "interval_type": "user_defined",
-      "quota_interval_arr": [100, 1000, 10000]
-    }
-  ],
-  "groups": [
-    {"field": {"name": "country", "type": "user_property"}}
-  ]
-}
-```
-
-Use `interval_type=def` for automatic buckets, `user_defined` for explicit numeric boundaries, and `discrete` to group by raw values.
-
-Distribution filters must be attached to the corresponding `distribution_metrics[].filters`.
-Do not use top-level `filters` or `relation` in a distribution definition.
-When multiple metrics need the same filter, attach it to each metric explicitly. If the requested filter scope is ambiguous, clarify which metric it applies to before running the analysis.
-
-### `attribution`
-
-Use to attribute target conversions to touchpoint/source events.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 14},
-  "attribution": {
-    "target_event": "purchase",
-    "target_aggregation": "total_count",
-    "attribution_events": [
-      {"event": "ad_click"},
-      {"event": "campaign_view"}
-    ],
-    "attribution_model": "first",
-    "window": {"value": 7, "unit": "day"},
-    "direct_conversion": true
-  }
-}
-```
-
-`attribution_model` values: `first`, `last`, or `linear`.
-The target aggregation is intentionally narrow: use `total_count` without a property, or `sum` with a numeric `target_property`. Do not use `user_count`.
-
-### `interval`
-
-Use for elapsed-time analysis between an initial event and a return event.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "time_particle_size": "day",
-  "interval": {
-    "initial_event": "register",
-    "return_event": "first_purchase",
-    "window": {"value": 7, "unit": "day"},
-    "groups": [
-      {"field": {"name": "channel", "type": "user_property"}}
-    ]
-  }
-}
-```
-
-### `path`
+Tag and cluster result-date policy:
 
-Use for behavior paths before or after a source event.
+- `cluster_date_policy` is valid only when `field.type` is `tag` or `cluster`.
+- `LATEST` uses the latest computed tag/cluster result and is the default when the field is omitted.
+- `AUTO` dynamically matches the computed result for each analysis date. Use it for historical daily analysis that must evaluate each day against that day's tag or cluster state.
+- `SPECIFIED` uses one fixed result date and requires `specified_cluster_date` in `yyyy-MM-dd` format. Do not send `specified_cluster_date` with `LATEST` or `AUTO`.
 
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "filters": [
-    {"field": {"name": "account_id", "type": "user_property"}, "operator": "exists"}
-  ],
-  "relation": "and",
-  "path": {
-    "source_event": "purchase",
-    "included_events": ["view_product", "add_to_cart", "purchase"],
-    "session_interval": 30,
-    "session_unit": "minute",
-    "direction": "forward"
-  }
-}
-```
-
-`direction=forward` asks what users do after `source_event`; `direction=backward` asks what users did before it. Do not send original-QP fields such as `source_type` or `event_names`.
-
-For path analysis, `preview_rows` is a graph-display boundary aligned with the analysis UI: it keeps up to that many real nodes per path level, then combines overflow nodes into `more`. `result.nodes` retains the synthesized `more` node for graph structure and drilldown coordinates. The top-level `returned_rows` counts real business nodes actually returned across all levels; it excludes synthesized `more` nodes and the real nodes folded into them. The count may still exceed `preview_rows` because the boundary applies independently to each level. `has_more=true` means at least one level contains real nodes folded into `more`; a linear multi-level path can return more real nodes than `preview_rows` with `has_more=false`.
-
-Path `filters` are global member filters compiled to the original QP `user_filter`. They support `user_property`, `cluster`, and `tag`, but not `event_property`. Do not move a user filter into the source event's event-property filter.
-
-Path session timeout accepts only these unit/value ranges:
-
-- `second`: `1..999`
-- `minute`: `1..999`
-- `hour`: `1..24`
-
-Do not use `day`. Express one day as `session_interval=24` with `session_unit=hour`.
-
-Property types come from project metadata. If resolution says a field is an `event_property`, never relabel it as `user_property` just to satisfy the path schema. Remove the unsupported global filter, choose a model that supports event-property filtering, or ask the user to clarify the intended constraint. A familiar name such as `channel` is not universally an event or user property across projects.
-
-For every non-SQL intent model, do not call `list_events` or `list_properties` as an execution prerequisite. The successful response must expose every internally resolved event/property in `resolved`, including `input`, `resolved_name`, `match_type`, and `path`. Use metadata discovery only after a structured `need_clarification` response or an explicit resolution capability error.
-
-### `prop_analysis`
-
-Use for user-property metrics, grouping, filters, and user-crowd comparison.
-
-```json
-{
-  "prop_analysis": {
-    "metric": {"aggregation": "user_count"},
-    "groups": [
-      {"field": {"name": "country", "type": "user_property"}}
-    ],
-    "filters": [
-      {"field": {"name": "vip_level", "type": "user_property"}, "operator": "gte", "values": ["3"]}
-    ],
-    "user_crowds": [
-      {
-        "name": "US users",
-        "filters": [
-          {"field": {"name": "country", "type": "user_property"}, "operator": "eq", "values": ["US"]}
-        ]
-      }
-    ]
-  }
-}
-```
-
-For property aggregations, pass the user property:
-
-```json
-{"prop_analysis":{"metric":{"aggregation":"distinct_count","property":"account_id"}}}
-```
-
-### `sql`
-
-Use for SQL analysis. The AI-facing model has only:
-
-- `sql`: required SQL text.
-- `params`: optional dynamic parameter values and definitions, required only when SQL contains `${...}` placeholders.
-
-Simple SQL:
-
-```json
-{"sql":"SELECT 1 AS value"}
-```
-
-Trino special identifiers must use double-quoted identifier delimiters:
-
-```json
-{"sql":"SELECT \"#user_id\", \"$part_event\" FROM hive.ta.v_event_1 WHERE \"$part_date\" BETWEEN '2026-07-01' AND '2026-07-07' LIMIT 20"}
-```
-
-Reserved words used as identifiers must also be double quoted, for example `SELECT "end" FROM ...`.
-
-For multiline SQL JSON, ensure JSON decoding produces a real line break in the `sql` value. Do not submit a literal `\\n` sequence outside a quoted SQL string value; use a JSON escape that the caller decodes once before invoking the capability.
-
-Event-table queries must include a date-partition predicate on the quoted `"$part_date"` column. The backend rejects SQL against an event table when this predicate is absent. This requirement is specific to event tables; do not invent a `$part_date` condition for a table whose discovered columns do not include it.
-
-Typed condition-fragment placeholder:
-
-```json
-{
-  "sql": "select * from events where country ${Text:country}",
-  "params": [
-    {"name": "country", "type": "text", "operator": "eq", "value": "US"}
-  ]
-}
-```
-
-Raw variable placeholder:
-
-```json
-{
-  "sql": "select * from events where country = ${country}",
-  "params": [
-    {"name": "country", "type": "variable", "value": "'US'"}
-  ]
-}
-```
-
-Time placeholder:
-
-```json
-{
-  "sql": "select * from events where ${PartDate:ds}",
-  "params": [
-    {"name": "ds", "type": "part_date", "recent_day": "1-7", "use_timezone": true}
-  ]
-}
-```
-
-Rules:
-
-- If SQL has no `${...}` placeholder, omit `params`.
-- If SQL has placeholders, every placeholder must have one matching item in `params`.
-- Raw variables use `${name}`, not `${Variable:name}`. A selector's `value` must equal one of its `options[].value` values. `${PartDate:name}` expands to a complete predicate, so place it directly after `WHERE`/`AND` rather than after a column name.
-- A `part_date` parameter must provide either `recent_day` or a complete custom range with both `start_time` and `end_time`; one-sided custom ranges are invalid.
-- `use_timezone` is an optional boolean definition field that is only valid for `part_date`. It defaults to `false`. When `true`, that PartDate parameter uses the query's effective timezone selected by `zone_offset` or the current user/project default; when `false`, it follows the non-timezone-aware PartDate path. This is distinct from the command-level `zone_offset`.
-- Do not pass SQL-IDE internals such as `sqlVoParams`, `sqlViewParams`, `paramType`, `paramName`, `paramExpress`, `commonFilter`, or `requiredEvents`.
-- Delimit any Trino identifier containing `#`, `$`, `@`, spaces, punctuation, or a reserved word with double quotes, for example `"#user_id"`, `"$part_event"`, and `"end"`. Single quotes create string literals, not identifiers. Escape a literal double quote inside an identifier by doubling it. The CLI preserves the submitted SQL and does not rewrite identifiers.
-- For an event table, include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition.
-- Do not invent table or column names. If the user already provides a concrete table reference, use `analysis-meta datatable columns-get --project-id <project_id> --table-ref <table_ref>` to inspect columns before writing SQL. If the table itself is unknown, call `analysis sql-table list --project-id <project_id>` when available and select an exact returned `table_ref`; otherwise stop and ask for the table/data source. Ask the user only when multiple authorized tables remain semantically plausible after discovery.
-- For a saved dynamic SQL report, put the default values in `analysis report create/update --definition`. Verify the default once with `analysis report-data run` without `--sql-params`, then verify a changed value with one value-only `--sql-params` override.
-- `use_timezone` belongs to the saved parameter definition. To change it, update the report `definition`; never pass it through report-data `--sql-params`, which changes values only.
-- SQL tags and SQL clusters do not use this general parameter contract. They accept only `${PartDate:name}` with `type=part_date`, and their tables must be discovered with `analysis sql-table list/columns --usage tag_cluster`; see `user_tag_models.md` and `user_cluster_models.md`.
-
-### `heat_map`
-
-Use for two-dimensional heat map analysis based on numeric event coordinate properties.
-
-```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "heat_map": {
-    "hot_event": "click",
-    "hot_aggregation": "total_count",
-    "x_prop": "screen_x",
-    "y_prop": "screen_y",
-    "filters": [
-      {"field": {"name": "page", "type": "event_property"}, "operator": "eq", "values": ["home"]}
-    ]
-  }
-}
-```
-
-For property metrics, set `hot_property` and use a property aggregation such as `sum` or `avg`.
-
-### `rank_list`
-
-Use for ranking users/entities by an event metric.
+For example, the following filter evaluates `tag_pay_level != 非R` against each analysis day's tag result:
 
 ```json
 {
-  "time_range": {"mode": "previous", "unit": "day", "value": 7},
-  "rank_list": {
-    "rank_dimension": {"field": {"name": "#account_id", "type": "user_property"}},
-    "rank_event": "purchase",
-    "rank_aggregation": "sum",
-    "rank_property": "amount",
-    "rank_type": "dense_rank",
-    "order_by": "DESC"
-  }
+  "field": {"name": "tag_pay_level", "type": "tag"},
+  "operator": "neq",
+  "values": ["非R"],
+  "cluster_date_policy": "AUTO"
 }
 ```
 
-`rank_type` values: `rank`, `dense_rank`, or `row_rank`.
-
-### `revenue`
+A successful ad-hoc response returns the effective policy in `definition`. A saved report read returns the persisted policy when it is present in the report QP. Treat `AUTO` as the evidence for dynamic matching; `field.type=tag` or `sub_table_type=tag_by_static_condition` alone does not prove it.
 
-Use for revenue cohort metrics such as LTV, ROI, revenue, and cost.
+Group:
 
 ```json
-{
-  "time_range": {"mode": "previous", "unit": "day", "value": 30},
-  "initial_event": {"event": "register"},
-  "pay_event": {"event": "purchase"},
-  "revenue_metric": {"event": "purchase", "aggregation": "sum", "property": "amount"},
-  "cost_metric": {"event": "ad_cost", "aggregation": "sum", "property": "cost"},
-  "observation_days": 14,
-  "selected_metrics": ["payAmount", "ltv", "roi"],
-  "groups": [
-    {"field": {"name": "channel", "type": "user_property"}}
-  ]
-}
+{"field":{"name":"country","type":"user_property"}}
 ```
 
-`cost_metric` is optional when the user does not ask for cost/ROI.
-`selected_metrics` supports `payUsers`, `payAmount`, `cumPayUsers`, `cumPayAmount`, `payRate`, `cumPayRate`, `ltv`, `ltvMultiple`, and `roi`.
-
-### `tag` report write only
-
-Use only with `analysis report create/update`; do not use with `analysis adhoc run/export`.
-
-`tag_name` is the only tag-report name field. Do not send `cluster_name` for a tag report; `cluster_name` belongs only to audience-cluster commands.
+Metric aggregation values must use semantic spelling, not internal A-codes. Use the selected model file's aggregation whitelist; it is specific to the model and property type.
 
-```json
-{
-  "tag": {
-    "tag_name": "vip_users",
-    "time_range": {"mode": "recent", "unit": "day", "value": 7},
-    "time_particle_size": "day"
-  }
-}
-```
+For total event count use `total_count`; `count` belongs only to distribution. Internal `Axxx` codes are persisted page details and are not valid authored AI definitions.
 
-Prefer `time_range` for new tag reports. `recent_day`, `start_time`, and `end_time` are only for report readback or precise round-trip updates.
+Use verified canonical metadata when constructing an intent model. Discover missing definitions or fields with [metadata resolution](metadata_resolution.md). Successful responses expose internally resolved events/properties in `resolved`, including `input`, `resolved_name`, `match_type` and `path`; reuse those mappings.

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

@@ -1,24 +1,24 @@
 # analysis alert create
 
-Use when create an alert.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to create an alert.
 
 Command:
 
 ```bash
-ae-cli analysis alert create [options]
+ae-cli analysis alert create --project-id <project_id> --definition-request '<definition_request>'
 ```
 
 Capability id: `analysis.alert.create`
 
 Input sends `project_id` and `definition_request`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
+
+If the alert definition fields are not known from the current task, inspect `ae-cli capability inspect analysis.alert.create` once and use its snake_case input schema.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--definition-request` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
+| `--definition-request` | Structured alert definition request JSON object using snake_case field names. | Yes |

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

@@ -1,8 +1,6 @@
 # analysis alert delete
 
-Use when delete an alert.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to delete an alert.
 
 Command:
 
@@ -16,11 +14,11 @@ Capability id: `analysis.alert.delete`
 
 Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--alert-id` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
+| `--alert-id` | Alert task ID. | Yes |

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

@@ -1,27 +1,25 @@
 # analysis alert-detail list
 
-Use when list alert delivery details.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to list alert delivery details.
 
 Command:
 
 ```bash
-ae-cli analysis alert-detail list [options]
+ae-cli analysis alert-detail list --project-id <project_id> --alert-id <alert_id>
 ```
 
 Capability id: `analysis.alert_detail.list`
 
 Input sends `project_id`, `alert_id`, optional `start_time`, and optional `end_time`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--alert-id` | See command help | Yes |
-| `--start-time` | See command help | No |
-| `--end-time` | See command help | No |
+| `--project-id` | Numeric project ID. | Yes |
+| `--alert-id` | Alert task ID. | Yes |
+| `--start-time` | Optional alert detail start time. | No |
+| `--end-time` | Optional alert detail end time. | No |
 

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

@@ -1,25 +1,23 @@
 # analysis alert get
 
-Use when get one alert.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to get one alert.
 
 Command:
 
 ```bash
-ae-cli analysis alert get [options]
+ae-cli analysis alert get --project-id <project_id> --alert-id <alert_id>
 ```
 
 Capability id: `analysis.alert.get`
 
 Input sends `project_id` and `alert_id`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--alert-id` | See command help | Yes |
+| `--project-id` | Numeric project ID. | Yes |
+| `--alert-id` | Alert task ID. | Yes |