@thinkingai/ae-cli 6.1.17 → 6.1.19

package/skills/ae-engage/references/build-task-save-guide.md

@@ -36,12 +36,16 @@ compounds when reusing `definition_request`; flattening them changes audience se
 For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
 from the third step onward when its window must be measured from step 1.
 
-For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
+For server-side existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
 ```bash
 ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cluster_name>"]'
 ```
 
+Server-side channels allow custom (`1`) or existing (`2`) audiences and reject all users (`3`).
+`client_push` (`channelType=3`) allows custom (`1`) or all users (`3`) and rejects existing (`2`).
+Always pass `channelType` in `context` so the guide can validate this matrix.
+
 4. Build the final grouped `save_task.req`.
 5. Submit with `ae-cli engage-task task save --project-id <projectId> --req '{...}'`.
 
@@ -229,6 +233,8 @@ When experiment mode is enabled (`context.enableExp=true` or draft `expConfig.en
 - capability `engage-task.task.build-save-guide` enriches `handoff.reqTemplate.channelConfig.groupContentList`
   so each entry carries `expGroupName`, `expGroupType`, `percentageInExperiment`, `order`, and `contentList`
 - do not drop those association fields when filling content; they must stay aligned with `expConfig.expGroupList`
+- copy the complete group tuple (`expGroupName`, `expGroupType`, `percentageInExperiment`, `order`)
+  into both lists; matching only by list position is not sufficient
 
 ### 4.8 `fieldRules`
 
@@ -300,6 +306,11 @@ Apply this rule only to
 `completionIndicatorDef.completionIndicators[].eventDefinition.filters`. Trigger-event filters have
 their own scenario rules and are not subject to this completion-filter restriction.
 
+For `completionIndicatorType=0`, also read and preserve `requiredMainGoalFields` and
+`touchCycleRule`. A valid main goal includes `touch_cycle_num` and `touch_cycle_num_unit`; use `1`
+and `day` when no custom completion window is requested. Do not rely on static `--validate` alone
+because the save service performs this additional business validation.
+
 ### 4.9 `handoff`
 
 This is the final section before `save_task`.
@@ -336,6 +347,8 @@ Recommended usage pattern:
    definition directly
 7. omit `clientConfig.clientQp`; partial updates preserve the server-authored value
 8. call `engage-task task save`
+9. after an experiment save succeeds, call `engage-task task get` and verify that both
+   `exp_config.exp_group_list` and `group_content_list` contain the expected group tuples
 
 ---
 

package/skills/ae-engage/references/save-flow.md

@@ -305,9 +305,45 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `ab_split_flow`
 
 ```json
-{ "branchList": [ { "branchId": "<branchId>", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 34 }, { "branchId": "<branchId>", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 33 } ], "indicatorsDef": [], "activateIndicatorsDef": null }
+{
+  "branchList": [
+    { "branchId": "control", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 50 },
+    { "branchId": "experiment_a", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 50 }
+  ],
+  "indicatorsDef": [
+    {
+      "indicatorsUuid": "metric_1",
+      "name": "Maximum payment amount",
+      "desc": "",
+      "completionIndicatorType": 0,
+      "touch_cycle_num": 1,
+      "touch_cycle_num_unit": "day",
+      "eventDefinition": {
+        "type": "event",
+        "event": "payment",
+        "aggregation": "max",
+        "property": "pay_amount",
+        "operator": "gt",
+        "value": 0,
+        "filters": {
+          "relation": "and",
+          "items": [
+            { "field": "gold", "operator": "gt", "values": [20] }
+          ]
+        }
+      }
+    }
+  ],
+  "activateIndicatorsDef": null
+}
 ```
 
+Use `eventDefinition` for new Capability requests. Its top-level `operator` compares the aggregate
+result with `value`; each `filters.items[].operator` compares an event property with its `values`.
+Both comparison levels are explicit and must not be omitted. Do not construct persisted fields such
+as `event`, `taPropQuota`, `uceCalcuSymbol`, `num`, `filts`, or `calcuSymbol`; Hermes compiles them.
+Legacy `event` remains accepted temporarily for older clients, but never send both fields.
+
 #### `event_judge`
 
 ```json

package/skills/ae-engage/references/save-task.md

@@ -245,6 +245,12 @@ Use the guide to decide which audience shape applies:
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
 - `targetClusterType=3`: all users, forbids `definitionRequest` and `clusterKey`
 
+Audience availability depends on delivery side:
+
+- Server-side channels support `targetClusterType=1` (custom) and `2` (existing), but not `3` (all users).
+- `client_push` (`channelType=3`) supports `targetClusterType=1` (custom) and `3` (all users), but not `2` (existing).
+- Determine the delivery side from the selected real channel; do not infer audience support from `triggerType` alone.
+
 For a custom audience, pass the semantic definition directly. Do not create an intermediate
 cluster or copy persisted QP.
 
@@ -426,6 +432,11 @@ When the guide points to event-based completion or experiment-driven main-goal r
 Read `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes` and exclude
 every property type listed under `excluded` before constructing its `filters`.
 
+For a main goal (`completionIndicatorType=0`), always include `touch_cycle_num` and
+`touch_cycle_num_unit`. If the user does not request another completion window, use
+`touch_cycle_num=1` and `touch_cycle_num_unit="day"`. Static Capability validation may accept a
+main goal without these fields, but the Hermes save service rejects it.
+
 Important constraints that still apply:
 
 - `doNotDisturb.enableDoNotDisturb=true` requires `startTime` and `endTime` in `HH:mm`
@@ -444,6 +455,81 @@ compatibility field, and partial task updates preserve the existing server value
 client-side condition has no semantic field in the current contract, stop and report that it cannot
 be safely authored through this Capability.
 
+### 4.7 Verified A/B Task Template
+
+Use this shape as the starting point for a server-channel split experiment. Replace every
+placeholder with metadata discovered from the current project.
+
+```json
+{
+  "baseInfo": {
+    "taskName": "<taskName>",
+    "taskDesc": "<taskDescription>",
+    "tzOffset": "<projectTimezoneOrDefaultSentinel>"
+  },
+  "channelConfig": {
+    "channelType": 1,
+    "channelId": "<verifiedChannelId>",
+    "groupContentList": [
+      {
+        "expGroupName": "Control",
+        "expGroupType": 1,
+        "percentageInExperiment": 50,
+        "order": 0,
+        "contentList": [{ "pushLanguageCode": "default", "content": "<channelContentJsonString>" }]
+      },
+      {
+        "expGroupName": "Experiment A",
+        "expGroupType": 2,
+        "percentageInExperiment": 50,
+        "order": 1,
+        "contentList": [{ "pushLanguageCode": "default", "content": "<channelContentJsonString>" }]
+      }
+    ]
+  },
+  "targetConfig": {
+    "targetClusterType": 1,
+    "definitionRequest": "<semanticAudienceDefinition>"
+  },
+  "triggerConfig": { "triggerType": 2 },
+  "controlConfig": {
+    "completionIndicatorDef": {
+      "completionIndicators": [
+        {
+          "completionIndicatorType": 0,
+          "touch_cycle_num": 1,
+          "touch_cycle_num_unit": "day",
+          "eventDefinition": {
+            "type": "event",
+            "event": "<verifiedGoalEvent>",
+            "aggregation": "count",
+            "operator": "gte",
+            "value": 1
+          }
+        }
+      ]
+    },
+    "frequencyLimits": { "enableFrequencyLimits": false, "ruleList": [] }
+  },
+  "expConfig": {
+    "enableExp": true,
+    "expType": 1,
+    "percentageInLayer": 100,
+    "expIndicatorBizType": 1,
+    "controlGroupSkipPush": false,
+    "expGroupList": [
+      { "expGroupName": "Control", "expGroupType": 1, "percentageInExperiment": 50, "order": 0 },
+      { "expGroupName": "Experiment A", "expGroupType": 2, "percentageInExperiment": 50, "order": 1 }
+    ]
+  }
+}
+```
+
+The experiment group tuple (`expGroupName`, `expGroupType`, `percentageInExperiment`, `order`)
+must be identical between each `expConfig.expGroupList` entry and its corresponding
+`channelConfig.groupContentList` entry. Validate the final request, save it, then call `task get`
+and verify both persisted lists; a successful task ID alone is not sufficient verification.
+
 ---
 
 ## 5. Final Self-Check Before `engage-task task save`
@@ -461,6 +547,8 @@ Before submission, verify:
 9. No unsupported `triggerType=6` is used.
 10. Ordered steps contain `eventDefinition` and sequence metadata, not persisted aggregate fields.
 11. No placeholder IDs or fabricated resource names remain in the request.
+12. Every main goal includes `touch_cycle_num` and `touch_cycle_num_unit`.
+13. For experiments, `expGroupList` and `groupContentList` contain identical group tuples.
 
 ---
 

package/skills/ae-experiment/SKILL.md

@@ -33,10 +33,14 @@ Naming and response boundary:
   `targeting.definition_request`. Never generate or submit `targetConfig`.
 - Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
   `metric_definition`. Never generate or submit `metricConfig`, `calcType`, or `Axxx` codes.
+- Event-property comparisons belong in `metricDefinition.filters`, using
+  `{relation,items:[{field,operator,values}]}`. Never put comparison fields directly on
+  `metricDefinition`, and never submit raw `filts`, `calcuSymbol`, or `ftv` fields.
 - For metric aggregations `sum` / `avg` / `max` / `distinct_count`, `metricDefinition.property`
   is **required** and must be a concrete available event property from Analysis metadata.
   Never create property aggregations without `property` (for example `metric_avg_no_property_*`).
-- Event-count aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Preset event aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Experiment metric creation does not support `avg_per_user` / `A105`.
 - Resolve event and property names with Analysis metadata before saving semantic definitions.
 - Lists return `data.items` and `data.total`; detail commands return `data.item`.
 - Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
@@ -56,6 +60,7 @@ Naming and response boundary:
    - `experiment feature save`
    - `experiment metric save`
 3. Create or patch the experiment draft with `experiment experiment save`.
+   Use `experiment experiment update-metrics` when replacing metric bindings or assigning guardrail roles.
 4. Check readiness with `experiment experiment ready-check`.
 5. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
 6. Move status with `experiment experiment manage`.
@@ -66,11 +71,12 @@ If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for t
 ## Parameter Conventions
 
 - Experiment save payloads distinguish two allocation fields: experiment-level `req.allocation` (**integer only; no decimals**) and group-level `req.groups[].allocation` (**integer only; sum must equal `100` exactly**).
+- Public experiment metric roles are `primary`, `secondary`, and `guardrail`. The internal `observation` role is currently unavailable for saves. Guardrail is a binding role; updating metrics replaces the full binding list.
 
 ```bash
 ae-cli experiment experiment get --project-id 1 --exp-id exp_123
 ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --dry-run
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
 ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
 ```
 
@@ -92,7 +98,9 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### Experiment
 
-`experiment experiment save`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+`experiment experiment save`, `experiment experiment update-metrics`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+
+Read [`manage_guardrail_metrics.md`](references/manage_guardrail_metrics.md) before assigning or replacing metric roles.
 
 ### Traffic Layer and Buckets
 
@@ -104,4 +112,6 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### Metric and Feature
 
-`experiment metric save`, `experiment metric get`, `experiment metric list`, `experiment metric delete`, `experiment feature save`, `experiment feature update-status`, `experiment feature get`, `experiment feature list`, `experiment feature version-list`, `experiment feature operation-log query`, `experiment feature batch-delete`
+`experiment metric save`, `experiment metric get`, `experiment metric list`, `experiment metric delete`, `experiment feature save`, `experiment feature update-status`, `experiment feature get`, `experiment feature list`, `experiment feature version-list`, `experiment feature operation-log query`, `experiment feature batch-delete`, `experiment feature whitelist list`, `experiment feature whitelist save`, `experiment feature whitelist update-status`, `experiment feature whitelist batch-delete`
+
+Read [`manage_feature_whitelist.md`](references/manage_feature_whitelist.md) before querying or changing Feature whitelist rules.

package/skills/ae-experiment/references/manage_feature_whitelist.md

@@ -0,0 +1,66 @@
+# Feature Whitelist Rules
+
+List, create, modify, enable, disable, or delete explicit Feature whitelist rules.
+
+## List
+
+```bash
+ae-cli experiment feature whitelist list \
+  --project-id <id> --feature-key <feature_key>
+```
+
+The result contains only explicit whitelist rules for the Feature. Each item exposes `rule_id`,
+`feature_key`, `priority`, `status`, and a structured snake-case `whitelist` array. Use the returned
+`rule_id` for modification, status changes, or deletion.
+
+## Save
+
+```bash
+ae-cli experiment feature whitelist save \
+  --project-id <id> \
+  --feature-key <feature_key> \
+  --status enable \
+  --whitelist '[{"bucket_id":"#user_id","rules":[{"ids":["u1","u2"],"value":"on"}]}]'
+```
+
+Pass `--rule-id` to modify an existing whitelist rule. Omit it to create a rule. The Hermes
+Capability fixes the Atlas rule type to `targeting` and serializes the supplied buckets into the
+server's explicit whitelist rule configuration.
+
+Rules:
+
+- Resolve the Feature with `experiment feature get` before writing.
+- `bucket_id` is the split subject, such as `#user_id` or `#account_id`.
+- Each bucket contains one or more rows with a non-empty `ids` array and a string `value`.
+- An empty string Feature value is allowed. Bucket IDs cannot be empty or duplicated. IDs must be
+  unique within one bucket, while different buckets may use the same string ID.
+- The server validates each value against the Feature type and limits the total ID count.
+- Only one explicit whitelist rule can be enabled for the same Feature.
+- Enabling, modifying, disabling, or deleting an enabled whitelist rule immediately creates a new
+  version and syncs RCC when the Feature itself is online.
+
+## Status
+
+```bash
+ae-cli experiment feature whitelist update-status \
+  --project-id <id> --rule-id <rule_id> --status enable
+```
+
+Valid status transitions exposed by this command are `enable` and `disable`.
+
+## Delete
+
+```bash
+ae-cli experiment feature whitelist batch-delete \
+  --project-id <id> --rule-ids '["0001"]'
+```
+
+Deletion is high risk and requires confirmation. Enabled whitelist rules may be deleted; Hermes
+resynchronizes affected online Features afterward.
+
+All four commands use Capability Gateway with CLI-token authentication:
+
+- `experiment.feature_whitelist.list`
+- `experiment.feature_whitelist.save`
+- `experiment.feature_whitelist.update_status`
+- `experiment.feature_whitelist.batch_delete`

package/skills/ae-experiment/references/manage_guardrail_metrics.md

@@ -0,0 +1,26 @@
+# experiment experiment update-metrics
+
+Replace the metric bindings of an existing experiment draft and assign metric roles, including
+guardrail metrics.
+
+```bash
+ae-cli experiment experiment update-metrics \
+  --project-id <id> \
+  --exp-id <exp_id> \
+  --metrics '[{"metricId":"conversion","metricRole":"primary"},{"metricId":"error_rate","metricRole":"guardrail"}]'
+```
+
+## Contract
+
+- Discover every `metricId` with `experiment metric list`; never invent metric IDs.
+- `--metrics` must be a non-empty array. Each item requires camelCase `metricId` and `metricRole`.
+- `metricRole` is one of `primary`, `secondary`, or `guardrail`. Do not submit the internal
+  `observation` role; Hermes currently rejects it at save boundaries.
+- This command replaces all saved metric bindings because Hermes treats a non-empty `metrics` list
+  in a draft patch as a replacement. Include bindings that must remain, not only the new guardrail.
+- Guardrail is a binding role, not a separate metric type. Create the underlying metric first with
+  `experiment metric save` when it does not exist.
+- At least one `primary` metric is still required before readiness succeeds.
+
+Run with `--dry-run` first, then verify the persisted roles with `experiment experiment get` and
+run `experiment experiment ready-check`.

package/skills/ae-experiment/references/save_experiment.md

@@ -104,7 +104,7 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
 - `expCycle.cycleType` can be `day` or `sample`; when `cycleType=day`, `dayNum` is `1..90`. Blank cycle defaults to day + 30.
 - Before readiness, `groups` must be non-empty, contain exactly one control group (`isControl=1`), group allocations must sum to exactly `100`, and each `expGroupValue` must be a non-empty JSON string array.
 - Feature experiments must bind `featureKeyList` before readiness. `featureKeyList` contains Feature key strings, not Feature objects. The MCP currently supports one `featureKey` for feature experiments.
-- Metrics use `metricRole=primary|secondary|guardrail|observation`; before readiness at least one primary metric is required.
+- Metrics use `metricRole=primary|secondary|guardrail`; the internal `observation` role is currently unavailable for saves. Before readiness at least one primary metric is required.
 - `targeting` replaces the saved targeting object when provided.
 - Custom audience QP must be supplied as the semantic object
   `targeting.definitionRequest`. Do not submit the internal `targeting.targetConfig`

package/skills/ae-experiment/references/save_metric.md

@@ -21,9 +21,13 @@ See [`save_build_guide.md`](save_build_guide.md) / [`save_validate.md`](save_val
 - Supply metric QP as `req.metricDefinition`.
 - Never submit internal `metricConfig`, `calcType`, or an `Axxx` calculation code.
 - Experiment metrics currently accept event definitions only.
+- Event-property comparisons belong in `metricDefinition.filters`. Each item uses
+  `field`, `operator`, and `values`; do not place `operator` or `value` directly on
+  `metricDefinition`.
 - Supported aggregations:
-  - Event-count (no property): `total_count`, `user_count`, `active_days`
+  - Preset event metrics (omit `property`): `total_count`, `user_count`, `active_days`
   - Property-based (**`property` REQUIRED**): `sum`, `avg`, `max`, `distinct_count`
+- `avg_per_user` (`A105`) is not supported for experiment metric creation.
 
 ### Property rule (mandatory)
 
@@ -38,6 +42,12 @@ When `aggregation` is `sum`, `avg`, `max`, or `distinct_count`:
 
 When `aggregation` is `total_count`, `user_count`, or `active_days`, omit `property`.
 
+### Preset event metric example (no property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_users","metricName":"Payment users","createType":"event","goalDirection":"up","metricDesc":"Users who triggered payment","metricDefinition":{"type":"event","event":"payment","aggregation":"user_count"}}'
+```
+
 ### Correct example (avg with property)
 
 ```bash
@@ -51,7 +61,11 @@ ae-cli experiment metric save --project-id 1 --req '{
     "type":"event",
     "event":"payment",
     "aggregation":"avg",
-    "property":"amount"
+    "property":"amount",
+    "filters":{
+      "relation":"and",
+      "items":[{"field":"amount","operator":"gt","values":[10]}]
+    }
   }
 }'
 ```
@@ -69,11 +83,9 @@ ae-cli experiment metric save --project-id 1 --req '{
 }
 ```
 
-### Event-count example (no property)
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`. For the frontend example `gold > 10`, use:
 
-```bash
-ae-cli experiment metric save --project-id 1 --req '{"metricId":"purchase_users","metricName":"Purchase users","createType":"event","goalDirection":"up","metricDesc":"Unique purchasers","metricDefinition":{"type":"event","event":"purchase","aggregation":"user_count"}}'
+```json
+{"filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}
 ```
-
-Filters use the semantic `filters` tree with `relation=and|or` and items containing
-`field`, `operator`, and `values`.