@thinkingai/ae-cli 6.1.11 → 6.1.12

package/dist/{te-experiment-JWXOYJ3W.js → te-experiment-PVEY7AEZ.js}

@@ -37,6 +37,9 @@ function readRequiredStringArray(ctx, name) {
 function addOptionalString(input, name, value) {
   if (value !== "") input[name] = value;
 }
+function addOptionalBoolean(input, ctx, flagName, fieldName) {
+  if (ctx.str(flagName) !== "") input[fieldName] = ctx.bool(flagName);
+}
 
 // src/commands/te-experiment/bucket/list.ts
 var bucketList = createExperimentCapabilityCommand({
@@ -481,7 +484,7 @@ var saveBuildGuide = createExperimentCapabilityCommand({
   resource: "save",
   command: "build-guide",
   capabilityId: "experiment.save.build-guide",
-  description: "Build a read-only save guide for feature, traffic layer, experiment, or metric saves.",
+  description: "Build a read-only save guide for feature, traffic layer, experiment, or metric saves. WARNING: data.guide.example_args.req keys are recursively snake_cased for display; do not copy them into --req. Final save DTOs require camelCase (e.g. expName). Prefer capability inspect <final-save-id> input_schema.properties.req.",
   flags: [
     { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
     {
@@ -509,7 +512,7 @@ var saveValidate = createExperimentCapabilityCommand({
   resource: "save",
   command: "validate",
   capabilityId: "experiment.save.validate",
-  description: "Dry-run validation for feature, traffic layer, experiment, or metric save requests.",
+  description: "Dry-run validation for feature, traffic layer, experiment, or metric save requests. WARNING: valid=true is not a final-save schema pass; snake_case req keys (e.g. exp_name) can still fail on experiment \u2026 save. Always pass camelCase --req. Do not copy example_args.req key casing from this response.",
   flags: [
     { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
     {
@@ -518,7 +521,12 @@ var saveValidate = createExperimentCapabilityCommand({
       required: true,
       desc: "Save operation mode: save_feature, save_traffic_layer, save_experiment, or save_metric."
     },
-    { name: "req", type: "json", required: true, desc: "Candidate camelCase save request object." }
+    {
+      name: "req",
+      type: "json",
+      required: true,
+      desc: "Candidate camelCase save request object (expName/metricId/\u2026). Never use snake_case DTO keys."
+    }
   ],
   risk: "read",
   validate: (ctx) => {
@@ -535,6 +543,98 @@ var saveValidate = createExperimentCapabilityCommand({
   })
 });
 
+// src/commands/te-experiment/report/metric-trend.ts
+var reportMetricTrend = createExperimentCapabilityCommand({
+  resource: "report",
+  command: "metric-trend",
+  capabilityId: "experiment.report.metric-trend",
+  description: "Query an experiment metric trend report for a date range.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "exp-id", type: "string", required: true, desc: "Experiment ID." },
+    { name: "metric-id", type: "string", required: true, desc: "Metric ID." },
+    { name: "start-time", type: "string", required: true, desc: "Start date in yyyy-MM-dd format." },
+    { name: "end-time", type: "string", required: true, desc: "End date in yyyy-MM-dd format." },
+    {
+      name: "request-id",
+      type: "string",
+      required: false,
+      desc: "Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted."
+    },
+    { name: "force-refresh", type: "boolean", required: false, desc: "Force refresh report data." }
+  ],
+  risk: "read",
+  buildInput: (ctx) => {
+    const input = {
+      project_id: ctx.num("project-id"),
+      exp_id: ctx.str("exp-id"),
+      metric_id: ctx.str("metric-id"),
+      start_time: ctx.str("start-time"),
+      end_time: ctx.str("end-time")
+    };
+    addOptionalString(input, "request_id", ctx.str("request-id"));
+    addOptionalBoolean(input, ctx, "force-refresh", "force_refresh");
+    return input;
+  }
+});
+
+// src/commands/te-experiment/report/sample-size.ts
+var reportSampleSize = createExperimentCapabilityCommand({
+  resource: "report",
+  command: "sample-size",
+  capabilityId: "experiment.report.sample-size",
+  description: "Query an experiment sample-size report for a date range.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "exp-id", type: "string", required: true, desc: "Experiment ID." },
+    { name: "start-time", type: "string", required: true, desc: "Start date in yyyy-MM-dd format." },
+    { name: "end-time", type: "string", required: true, desc: "End date in yyyy-MM-dd format." },
+    {
+      name: "request-id",
+      type: "string",
+      required: false,
+      desc: "Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted."
+    },
+    { name: "force-refresh", type: "boolean", required: false, desc: "Force refresh report data." },
+    { name: "by-hour", type: "boolean", required: false, desc: "Break results down by hour." }
+  ],
+  risk: "read",
+  buildInput: (ctx) => {
+    const input = {
+      project_id: ctx.num("project-id"),
+      exp_id: ctx.str("exp-id"),
+      start_time: ctx.str("start-time"),
+      end_time: ctx.str("end-time")
+    };
+    addOptionalString(input, "request_id", ctx.str("request-id"));
+    addOptionalBoolean(input, ctx, "force-refresh", "force_refresh");
+    addOptionalBoolean(input, ctx, "by-hour", "by_hour");
+    return input;
+  }
+});
+
+// src/commands/te-experiment/report/summary.ts
+var reportSummary = createExperimentCapabilityCommand({
+  resource: "report",
+  command: "summary",
+  capabilityId: "experiment.report.summary",
+  description: "Query an experiment report summary.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "exp-id", type: "string", required: true, desc: "Experiment ID." },
+    { name: "force-refresh", type: "boolean", required: false, desc: "Force refresh report data." }
+  ],
+  risk: "read",
+  buildInput: (ctx) => {
+    const input = {
+      project_id: ctx.num("project-id"),
+      exp_id: ctx.str("exp-id")
+    };
+    addOptionalBoolean(input, ctx, "force-refresh", "force_refresh");
+    return input;
+  }
+});
+
 // src/commands/te-experiment/traffic-layer/batch-delete.ts
 var trafficLayerBatchDelete = createExperimentCapabilityCommand({
   resource: "traffic-layer",
@@ -616,6 +716,9 @@ var commands = [
   trafficLayerGet,
   trafficLayerList,
   trafficLayerBatchDelete,
+  reportSummary,
+  reportSampleSize,
+  reportMetricTrend,
   metricSave,
   metricGet,
   metricList,
@@ -654,6 +757,9 @@ export {
   metricList,
   metricSave,
   operationLogQuery,
+  reportMetricTrend,
+  reportSampleSize,
+  reportSummary,
   saveBuildGuide,
   saveValidate,
   trafficLayerBatchDelete,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.1.11",
+  "version": "6.1.12",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "verify:metadata-capability": "npx tsx test/metadata-capability-commands.test.mjs",
     "verify:community-capability": "node test/community-capability-routing.test.mjs",
     "verify:community-report": "npx tsx tests/community-report-standard-v5.test.ts && npx tsx tests/community-report-client.test.ts && npx tsx tests/community-report-framework.test.ts && npx tsx tests/community-data-report-command.test.ts && node test/community-data-report-skill.test.mjs",
-    "verify:engage-capability": "tsx test/engage/engage-capability-command.test.mjs && node test/engage/engage-skill-capability.test.mjs",
+    "verify:engage-capability": "tsx test/engage/engage-capability-command.test.mjs && tsx test/engage/semantic-qp-validation.test.mjs && node test/engage/engage-skill-capability.test.mjs",
     "verify:retired-analysis-commands": "node --test test/retired-analysis-commands.test.mjs",
     "verify:analysis-meta-tools": "node scripts/verify-te-meta-tools.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, and task management. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task."
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, and operation activities. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity."
 ---
 
 # ae-engage
@@ -56,6 +56,7 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
 | **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — semantic `definitionRequest` (Analysis condition shape); do not pass `targetClusterQp`/`qp`; preflight props (stop + list if missing); template: `scene-template.md` |
 | **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
+| **Operation activity** | Campaign activity management and delivery trends by activity, topic, or standalone task | `engage-activity` | `references/activity-activity.md` | `activity-data-detail.md`, `activity-topic.md`, `activity-task.md`, `activity-approval.md` |
 | **Template** | Strategy templates under a config item | `engage-scene` | `references/scene-template.md` | `scene-config-param.md` (template fields reference `paramId`); enable via `template update` then `template update-status` before strategy create |
 
 **Easy to confuse:**
@@ -75,6 +76,7 @@ Naming boundary:
 
 - CLI flags use kebab-case; outer Capability input and all Capability response keys use snake_case.
 - Nested business DTOs passed through `--req` or `--payload` keep their documented native camelCase fields. Do not mechanically convert those nested DTO keys to snake_case.
+- Semantic audience, event, trigger, completion, and metric definitions are closed contracts. The CLI rejects malformed or unknown semantic fields locally; `--validate` applies the same precise Hermes capability schema without writing.
 - Successful migrated commands return their business payload under `data`; read the matching reference's Response shape before selecting fields.
 
 ## JSON Parameter Format
@@ -375,6 +377,9 @@ ae-cli engage-setting channel list --project-id <projectId>
 5. `engage-flow flow save` is **operation-based** (protocol v2). The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — use `nodes` / `edges` with `operation=build`. A legacy `nodeList`/`edgeList` payload (or a missing `operation`) is rejected with `Unsupported save_flow operation: null`.
 6. Run the lifecycle: `build` (returns `data.result.status = ready_to_preview` or `need_input`) → resolve any `data.result.next_slot` → `preview` (re-issues response fields `data.result.draft_version` + `data.result.confirm_token`) → `commit` (maps those values to request fields `draftVersion` + `confirmToken`) → reads the final ID from `data.result.result.flow_uuid`.
 7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. Custom audience nodes and branches use semantic `targetDefinitionRequest`; Hermes compiles it to the node's stored execution format.
+   Never send `targetClusterQp`. Each audience `event` and `behavior_sequence` must include
+   its own `time_range`; Flow entry dates do not replace that range. Use only properties that
+   resolve through the Flow editor's current project, timezone, and user-entity metadata scope.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -456,6 +461,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/config-item-analysis-report.md` (`engage-scene.report.config-item-analysis`, L3)
 - `references/config-item-strategy-comparison.md` (`engage-scene.report.strategy-comparison`, L3)
 - `references/activity-activity.md` (`engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`)
+- `references/activity-data-detail.md` (`engage-activity.activity-data.detail`, L3)
 - `references/activity-approval.md` (`engage-activity.approval.{submit,approve,reject,cancel}`)
 - `references/activity-topic.md` (`engage-activity.topic.{create,update,remove-task,delete,get,copy}`)
 - `references/activity-activity-type.md` (`engage-activity.activity-type.{list,batch-add,update,batch-delete}`)
@@ -533,7 +539,9 @@ For task draft creation or update, use this workflow:
    `channelType`, `triggerType`, and `eventTriggerType` to `build-save-guide`, then use its
    type-specific semantic event shape. Accumulated events are aggregate conditions, continuous
    events use count/eq with a value of at least 2, ordered events use sequence-step envelopes,
-   and every-completion events use count/eq/1. Never construct persisted QP fields.
+   and every-completion events use count/eq/1. Completion target and experiment main-goal event
+   filters must not use properties whose metadata `select_type` is `datetime`. Never construct
+   persisted QP fields.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 
@@ -551,3 +559,5 @@ Audience creation is not a fixed preflight step. For custom task audiences, use
 `definition_request`. `clientConfig.clientQp` is server-authored and must be omitted from
 Capability requests; partial updates preserve existing server state. Do not assemble raw QP
 manually.
+For a `behavior_sequence`, omit second-step `relative_to_first` or set it to `false`; reserve
+`true` for step 3 or later when the window is measured from step 1.

package/skills/ae-engage/references/activity-data-detail.md

@@ -0,0 +1,61 @@
+# engage-activity.activity-data.detail
+
+Query activity delivery trends through the L3 Capability Gateway.
+
+Mapped command:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input '<json>'
+```
+
+## Input
+
+Required fields:
+
+- `project_id`: project that owns the activity.
+- `activity_id`: activity to query.
+- `start_time`: inclusive start date in `yyyy-MM-dd` format.
+- `end_time`: inclusive end date in `yyyy-MM-dd` format.
+
+Optional fields:
+
+- `time_particle_size`: `T1` (day), `T2` (week), `T3` (month), or `T5` (total). Defaults to `T1`.
+- `source`: `activity` or `topic_and_task`. Defaults to `activity`.
+- `topic_id_list`: selected topic IDs.
+- `task_id_list`: selected standalone task IDs.
+- `request_id`: cancelable query ID. A UUID is generated when omitted.
+
+When `source=topic_and_task` and both ID lists are omitted or empty, the capability selects every topic and standalone task in the activity. When either list is provided, only the explicitly selected resources are queried. Selected resources must belong to the activity and project.
+
+## Recent seven-day topic trend
+
+Use an inclusive seven-day range, `T1`, and `topic_and_task`:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input \
+  '{"project_id":1,"activity_id":"act-1","start_time":"2026-07-25","end_time":"2026-07-31","time_particle_size":"T1","source":"topic_and_task","request_id":"<uuid>"}'
+```
+
+The report exposes the existing activity-page indicators:
+
+- `plan`: planned trigger users.
+- `actualTrigger`: actual push users.
+- `trigger`: successful push users.
+
+It does not expose `view` (actual arrival) or `click`. Use the returned header values instead of treating `trigger` as an actual-arrival metric.
+
+## Output
+
+Successful output contains:
+
+- `data.request_id`: the request ID used by the query.
+- `data.result_generate_time`: ISO-8601 generation time.
+- `data.data.x`: summary/date axis.
+- `data.data.headers`: indicator keys.
+- `data.data.total`: activity totals aligned with `headers`.
+- `data.data.values`: topic or standalone-task rows aligned with `x` and `headers`.
+- `data.data.topic_list`: selected source IDs and names using `topic_id` and `topic_name`.
+
+The first `x`/`total` row is the overall summary. For non-total time grains, subsequent rows are the requested date buckets.
+
+Use `engage-setting.query.cancel` with the same `request_id` to cancel a running query.

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
 

package/skills/ae-experiment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment
-version: 1.0.0
+version: 1.0.1
 description: "Use when managing Atlas AB experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
 ---
 
@@ -14,6 +14,7 @@ AE CLI (`ae-cli`) exposes Atlas AB Experiment capabilities through the `experime
 - Use `--project-id` / `-p` for project-scoped commands.
 - Use `--req` JSON for complex save, status, and delete DTOs.
 - Do not invent experiment IDs, traffic layer IDs, bucket IDs, Feature keys, metric IDs, or payload field names.
+- Bind only metric IDs returned by `experiment metric list`; create and verify a missing metric before saving the experiment.
 - Read commands can run directly after IDs are verified.
 - Write commands require explicit user intent and normally keep the confirmation prompt. Use `--dry-run` before write calls when composing JSON.
 
@@ -22,6 +23,12 @@ Naming and response boundary:
 - CLI command segments and flags use kebab-case.
 - Outer Capability input and all response keys use snake_case.
 - Nested business DTOs passed through `--req` keep their native camelCase fields.
+- **CRITICAL:** `save build-guide` / `save validate` responses recursively snake_case
+  `example_args.req`. Never copy those keys into `--req`. Use camelCase
+  (`expName`, `metricId`, …). Authoritative names:
+  `ae-cli capability inspect experiment.experiment.save` (or the matching final save id)
+  → `input_schema.properties.req`. `save validate` `valid: true` is **not** a final-save
+  schema pass — snake_case `req` can still fail on `experiment … save`.
 - Audience QP is semantic at the CLI boundary: write `targeting.definitionRequest`; read
   `targeting.definition_request`. Never generate or submit `targetConfig`.
 - Metric QP is semantic at the CLI boundary: write `metricDefinition`; read
@@ -52,7 +59,9 @@ Naming and response boundary:
 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`.
-7. Query reports with summary, sample-size, and metric-trend commands.
+7. Query reports with `experiment report summary`, `experiment report sample-size`, and `experiment report metric-trend`.
+
+If an experiment save returns `error_code: METRIC_NOT_FOUND`, list metrics for the same project. Create and verify the metric before retrying; never retry with another invented ID. Metric deletion returns `error_code: METRIC_IN_USE` while an active experiment binding exists.
 
 ## Parameter Conventions
 
@@ -62,7 +71,7 @@ Naming and response boundary:
 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 capability run experiment.report.metric-trend --input '{"project_id":1,"exp_id":"exp_123","metric_id":"metric_1","start_time":"2026-07-01","end_time":"2026-07-07"}'
+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
 ```
 
 Optional global parameters work as in other domains: `--host`, `--mcp-url`, `--format`, `--jq`, `--dry-run`, and `--yes`.
@@ -77,6 +86,10 @@ Open the matching file in `references/` before using a command, especially for w
 
 When a save command returns `next_tool: experiment.save.build-guide`, call the guide first, then `experiment save validate`, then retry the final save capability.
 
+Read [`save_build_guide.md`](references/save_build_guide.md) and
+[`save_validate.md`](references/save_validate.md) before using these helpers. Rebuild
+`--req` in camelCase from `inspect` / skill references; do not paste `example_args.req`.
+
 ### 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`
@@ -87,7 +100,7 @@ When a save command returns `next_tool: experiment.save.build-guide`, call the g
 
 ### Reports
 
-`capability run experiment.report.summary`, `capability run experiment.report.sample-size`, `capability run experiment.report.metric-trend`, `capability run experiment.query.cancel`
+`experiment report summary`, `experiment report sample-size`, `experiment report metric-trend`, `capability run experiment.query.cancel`
 
 ### Metric and Feature
 

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

@@ -9,3 +9,5 @@ ae-cli experiment metric delete --project-id <id> --metric-id <metricId> [--yes]
 Flags:
 - `--project-id`, `-p`: Project ID.
 - `--metric-id`: Metric ID.
+
+Deletion is rejected with `error_code: METRIC_IN_USE` while the metric has an active experiment binding. Remove the metric from the related experiment before retrying.

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

@@ -1,12 +1,12 @@
-# capability run experiment.report.metric-trend
+# experiment report metric-trend
 
 Query experiment metric trend report.
 
 ```bash
-ae-cli capability run experiment.report.metric-trend --input '{"project_id":1,"exp_id":"exp_123","metric_id":"metric_1","start_time":"2026-07-01","end_time":"2026-07-07"}'
+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
 ```
 
-Required input: `project_id`, `exp_id`, `metric_id`, `start_time`, `end_time`.
-Optional input: `request_id`, `force_refresh`.
+Required flags: `--project-id`, `--exp-id`, `--metric-id`, `--start-time`, `--end-time`.
+Optional: `--request-id`, `--force-refresh`.
 
-Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation.
+Response shape: `data.report`, with recursively snake_case keys. Preserve `request_id` for cancellation via `capability run experiment.query.cancel`.

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

@@ -1,11 +1,12 @@
-# capability run experiment.report.summary
+# experiment report summary
 
 Query experiment report summary.
 
 ```bash
-ae-cli capability run experiment.report.summary --input '{"project_id":1,"exp_id":"exp_123","force_refresh":false}'
+ae-cli experiment report summary --project-id 1 --exp-id exp_123
+ae-cli experiment report summary --project-id 1 --exp-id exp_123 --force-refresh true
 ```
 
-Required input: `project_id`, `exp_id`. Optional input: `force_refresh`.
+Required flags: `--project-id`, `--exp-id`. Optional: `--force-refresh`.
 
 Response shape: `data.report`, with recursively snake_case keys.