@thinkingai/ae-cli 6.0.39 → 6.0.40

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

@@ -23,7 +23,18 @@ Use this sequence when creating or updating a task draft:
 Build event primitives from `ae-analysis` user-cluster / audience models. Hermes wraps those
 primitives in the task-specific envelope selected by `channelType`, `triggerType`, and
 `eventTriggerType`, then validates the final persisted QP before save. Never construct persisted
-execution QP.
+execution QP. Follow the documented closed semantic shapes: unknown fields are rejected, and a
+property `field` may be a technical-name string or a `{name,type}` reference.
+Every custom-audience `event` and `behavior_sequence` requires its own `time_range`. For
+`recent` and `previous`, use a positive integer `value` and only `unit=day`; `custom` requires
+both `start_time` and `end_time`.
+
+Custom audiences support `behavior_sequence` nodes, including sequence/step windows, step
+filters, `completed`, and `relative_to_first`. A task `get` may return top-level `compound`
+nodes when the stored member-group, event-group, and outer relations differ. Preserve those
+compounds when reusing `definition_request`; flattening them changes audience semantics.
+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:
 
@@ -266,6 +277,19 @@ The guide treats the A rule as a discriminated envelope:
 Do not copy the accumulated example and only change `eventTriggerType`. Hermes rejects a final QP
 whose event structure does not match its envelope.
 
+#### `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes`
+
+Treat this as the source of truth for completion target and experiment main-goal event-filter
+property types:
+
+- `allowed` lists the supported metadata `select_type` values.
+- `excluded` lists values that must not be used.
+- `datetime` is excluded because the task completion-indicator editor cannot display it.
+
+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.
+
 ### 4.9 `handoff`
 
 This is the final section before `save_task`.

package/skills/ae-engage/references/common-metric.md

@@ -3,6 +3,13 @@
 > Trigger keywords: common metric, shared metric · Capability ids: `engage-setting.common-metric.{list,get,create,update,delete}` · Permission: `opsEditSetting`.
 
 Common metric capabilities expose semantic event/formula definitions. Do not submit or reuse `metric_qp`, `Axxx`, display metadata, formula dependency internals, or property metadata.
+Metric definitions and formula dependencies reject unknown fields. Event filter `field` accepts
+either a technical-name string or `{"name":"...","type":"event_property"}`.
+
+When metadata reports an event property as `array_row`, express it as an `object_group` filter
+with `any_satisfy`, `none_satisfy`, or `all_satisfy`; its nested `conditions.items` may reference
+only child properties of that parent. Flat filters on the `array_row` parent are rejected before
+the metric is saved.
 
 ## Commands
 
@@ -39,8 +46,41 @@ ae-cli engage-setting common-metric delete --project-id <project_id> --metric-na
 }
 ```
 
+Object-group filter example:
+
+```json
+{
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
+  }
+}
+```
+
 Supported aggregations include `total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`.
 
+Property aggregations require `property`. `percentile` additionally requires a numeric
+`percentile` greater than `0` and at most `100`:
+
+```json
+{
+  "type": "event",
+  "event": "purchase",
+  "aggregation": "percentile",
+  "property": "amount",
+  "percentile": 90
+}
+```
+
 ## Formula metric
 
 ```json
@@ -65,6 +105,11 @@ Supported aggregations include `total_count`, `user_count`, `per_user_count`, `s
 }
 ```
 
+Every dependency requires a non-empty, unique `key`, and every key must be used in
+`expression`. Write bare keys only: use `purchases/refunds`, never `purchases.A100/refunds.A100`.
+Aggregation codes are derived from each dependency. Formula dependencies follow the same
+property and percentile requirements as event metrics.
+
 Resolve every event and property through `ae-cli analysis-meta event list` and the corresponding property metadata before writing. `get` and `list` return `metric_definition`, `metric_definition_status`, and an optional unavailable reason. Raw metric QP is hidden.
 
 `metric_type=1` remains required for setting-page common metrics. Metric windows remain separate from the semantic definition, and their unit must be `minute` / `hour` / `day`.

package/skills/ae-engage/references/preset-event.md

@@ -12,6 +12,8 @@ ae-cli engage-setting preset-event update --project-id <project_id> \
 ```
 
 At least one definition is required for update. Event filters use semantic `field`, `operator`, `values`, and `and`/`or`; Hermes resolves project metadata and compiles the stored event object.
+`field` accepts a technical-name string or `{"name":"...","type":"event_property"}`. Unknown
+semantic fields, unsupported relations/operators, and invalid time ranges are rejected.
 
 List hides the stored event QP and returns each semantic field plus its conversion status:
 

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

@@ -177,6 +177,14 @@ ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<co
 ```
 
 Prefer the created cluster reference for an existing-cluster audience. For a custom audience, pass the semantic definition as `targetDefinitionRequest`; do not copy or construct stored execution QP.
+Use only the documented semantic fields. Unknown fields are rejected, and property `field` values
+may be technical-name strings or `{name,type}` references.
+
+Custom flow audiences support `behavior_sequence`. When `flow get` returns relation-preserving
+top-level `compound` nodes, retain them unchanged in subsequent saves; they preserve distinct
+member-group, event-group, and outer relations.
+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.
 
 ### 5.2 Project Channels
 
@@ -239,6 +247,12 @@ Inside action nodes: `channel_name` → real `channelId`; `content` → `content
 3. Every path must eventually end at `exit_flow`.
 4. `config` may be a JSON object or a JSON string. `targetDefinitionRequest` itself is a JSON object.
 5. Hermes compiles `targetDefinitionRequest` and Flow-specific `triggerDefinition` fields (including branch definitions) on `nodes[]`, `nodeConfigs[]`, and `slotAnswer.nodeConfig.config` before legacy node validation. `node-config validate` uses the same compile path. Other compatible input normalization remains unchanged.
+6. Never send `targetClusterQp`; it is a server-authored execution field. Every `event` and
+   `behavior_sequence` inside `targetDefinitionRequest` must include its own `time_range`.
+   Entry-node `startDate` / `endDate` values do not provide an audience-event time range.
+7. Audience fields must resolve through the current Flow editor metadata scope. If Hermes
+   rejects a field, choose another property returned for the same project, timezone, and user
+   entity instead of constructing persisted metadata manually.
 
 ### 7.2 Common Node Types
 

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

@@ -120,6 +120,39 @@ Task aggregate and completion event definitions support:
 - `aggregation`: `count`, `sum`, or `distinct_count`
 - `operator`: `gt`, `gte`, or `eq`
 
+Completion target and experiment main-goal event filters must not use properties whose metadata
+`select_type` is `datetime`. The supported filter-property select types are `string`, `number`,
+`bool`, `bool-s`, `date`, `array`, `array_string`, `row`, and `array_row`. This restriction applies
+to `completionIndicatorDef.completionIndicators[].eventDefinition.filters`; it does not apply to
+trigger-event filters.
+
+For an event property whose metadata `select_type` is `array_row`, never submit it as a flat
+property filter. Use an object-group filter and place only that parent's child properties inside
+`conditions`:
+
+```json
+{
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
+  }
+}
+```
+
+Object-group operators are `any_satisfy`, `none_satisfy`, and `all_satisfy`. Resolve the parent
+and child fields from current metadata. Hermes validates the metadata type, child-parent
+relationship, and supported operators before saving, so do not flatten `array_row` or invent child
+field names.
+
 Trigger events have an additional envelope contract selected by `eventTriggerType`. Do not apply
 one aggregate event shape to every trigger type. Use the matrix and examples in section 4.4.
 
@@ -381,6 +414,8 @@ Minimum required field:
 
 When the guide points to event-based completion or experiment-driven main-goal rules, build
 `completionIndicatorDef.completionIndicators[].eventDefinition` from the semantic event contract.
+Read `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes` and exclude
+every property type listed under `excluded` before constructing its `filters`.
 
 Important constraints that still apply:
 

package/skills/ae-engage/references/scene-strategy-audience.md

@@ -25,19 +25,19 @@ Use the same condition definition accepted by Analysis user-cluster commands:
     "relation": "and",
     "items": [
       {
-        "type": "user_property",
-        "property": "vip_level",
+        "type": "user",
+        "field": "vip_level",
         "operator": "eq",
-        "value": "gold"
+        "values": ["gold"]
       },
       {
-        "type": "event_behavior",
+        "type": "event",
         "event": "purchase",
         "aggregation": "count",
         "operator": "gte",
         "value": 2,
-        "time": {
-          "type": "relative",
+        "time_range": {
+          "mode": "recent",
           "unit": "day",
           "value": 7
         }
@@ -48,8 +48,13 @@ Use the same condition definition accepted by Analysis user-cluster commands:
 ```
 
 Before writing, resolve real event and property names through Analysis metadata commands. Never invent names or copy internal calculation codes from historical output.
+Use only the documented semantic fields. Unknown fields are rejected; property `field` accepts a
+technical-name string or a `{name,type}` reference.
 
-Nested `and`/`or`, user properties, event behavior, include/exclude existing clusters, relative time, and custom time use the Analysis semantic shape documented by `ae-analysis`.
+Nested `and`/`or`, user properties, event behavior, `behavior_sequence`, include/exclude existing
+clusters, relative time, and custom time use the Analysis semantic shape documented by
+`ae-analysis`. A `get` response may contain top-level `compound` nodes when stored member,
+event, and outer relations differ. Preserve those compounds when updating the strategy.
 
 ## Create or update