@thinkingai/ae-cli 6.1.10 → 6.1.12

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

@@ -24,9 +24,9 @@ ae-cli engage-scene strategy update --project-id <project_id> \
 # Query a strategy's log
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
 
-# Predict custom-audience size (mix QP)
+# Predict custom-audience size
 ae-cli engage-scene strategy predict --project-id <project_id> \
-  --qp '<targetClusterQp JSON string>' \
+  --definition-request '{"type":"condition","conditions":{...}}' \
   --zone-offset 8 \
   [--strategy-uuid <uuid>]
 
@@ -48,7 +48,7 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 | create | `--project-id`, `--payload` | payload = `ConfigStrategyAddDTO`. |
 | update | `--project-id`, `--payload` | payload = `ConfigStrategyModifyDTO` (`strategyUuid` + fields). |
 | log | `--project-id`, `--strategy-uuid` | read. |
-| predict | `--project-id`, `--qp`, `--zone-offset` | Optional `--strategy-uuid`, `--request-id`. read. |
+| predict | `--project-id`, `--definition-request`, `--zone-offset` | Optional `--strategy-uuid`, `--request-id`. read. |
 | batch-copy | `--project-id`, `--config-id`, `--strategy-ids` | `--op-mode` optional (default `batch`). |
 | manage | `--project-id`, `--config-id`, `--action` | Lifecycle actions require `--strategy-uuid-list`; review actions require `--strategy-list`; write. |
 
@@ -67,10 +67,10 @@ ae-cli engage-scene strategy manage --project-id <project_id> --config-id <confi
 - Discover real strategy UUIDs / config IDs first; never invent IDs.
 - **Custom audience (`targetClusterType=1`)** — follow [`scene-strategy-audience.md`](scene-strategy-audience.md) end-to-end:
   1. Preflight every **用户满足** user property and **用户行为** event via `analysis-meta property get` / `event get`; if missing, **stop** and list available properties — never invent or drop.
-  2. Assemble mix QP with **two-block layout**: `totalCFilter.filts[0]` = 用户满足, `totalCFilter.filts[1]` = 用户行为; `totalCFilter.relation` = 且/或 between them. **Never** nest `event` inside user-side `COMPOUND`.
-  3. `JSON.stringify` → `targetClusterQp`; then `strategy create|update`.
+  2. Build an Analysis-compatible semantic condition in `payload.definitionRequest`.
+  3. Reuse the same definition with `strategy predict --definition-request`.
   4. **Do not** call `analysis user-cluster create` unless the user explicitly asks for an existing/named cluster.
-  - Full QP spec + examples A/B/C: [`scene-strategy-audience.md`](scene-strategy-audience.md).
+  - Semantic contract and examples: [`scene-strategy-audience.md`](scene-strategy-audience.md).
 - **`create` requires an enabled template** on the same config item. Enable workflow: `config-param batch-add` → `template create` → `template update` (non-empty `config[]` with real `paramId`) → `template update-status --status 1`. Otherwise `create` returns `TEMPLATE_ENABLE`.
 - `create` output field is `data.strategy_uuid` (not `strategy_id`).
 - `manage` supports `online`, `offline`, `suspend`, `delete`, `approve`, `deny`, and `cancel`; it is a write operation.

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

@@ -5,6 +5,16 @@ Query the details of a single task.
 
 Mapped command: `ae-cli engage-task task get`
 
+For a custom target audience, the response hides persisted `qp` and returns:
+
+- `definition_status`: `AVAILABLE`, `UNAVAILABLE`, or `NOT_APPLICABLE`
+- `definition_request`: the Analysis-compatible semantic audience definition when available
+- `definition_unavailable_reason`: present only when a historical QP cannot be reversed
+
+Reuse `definition_request` as `req.targetConfig.definitionRequest` when updating a task.
+Soft-deleted tasks are treated as unavailable and return `TASK_NOT_FOUND`, matching task-list
+visibility.
+
 ## Flags
 
 | Flag | Type | Required | Description |

package/skills/ae-engage/references/task-submit-approval.md

@@ -0,0 +1,45 @@
+# engage-task task submit-approval
+
+Submit an existing draft engagement task for approval. The legacy full save-and-submit request remains supported.
+This is a regular write operation.
+
+> Capability id: `engage-task.task.submit-approval` · Domain: `engage`.
+
+```bash
+ae-cli engage-task task submit-approval --project-id <project_id> --task-id <task_id>
+```
+
+## Parameters
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--project-id` / `-p` | yes | Numeric project ID. |
+| `--task-id` | conditional | Existing draft task ID. Recommended after `task save`. |
+| `--request` | conditional | Legacy `ApprovalSaveAndSubmitDTO` / `OperationTaskOpDTO` JSON (camelCase or snake_case). |
+
+Provide exactly one of `--task-id` or `--request`.
+
+## Output
+
+- `data.task_id`
+
+## Request notes
+
+- Prefer `task save` followed by `submit-approval --task-id`. The server loads the persisted draft, validates its
+  trigger rule, and reuses the existing save-and-submit approval workflow.
+- Do not reconstruct or pass `trigger_rule`. It is an internal persisted field.
+- The legacy `--request` mode remains available for existing callers.
+- Required body fields (server validates): `task_name`, `channel_type`, `channel_id`, `group_content_list`, `target_cluster_type`, `trigger_type`, `completion_indicator_def`, `frequency_limits`, `enable_channel_touch_limits`, `group_id`, `trigger_time_strategy`.
+- Missing `expConfig` is auto-filled as `{"enableExp":false}` (same as activity task create/update).
+- TEXT channel params missing `config` are auto-filled with Slate.js JSON from `value`.
+- For schedule-single (`triggerType=0`), include a future `triggerTime` (and `tzOffset` / `triggerTimeStrategy` as needed).
+- Prefer save → submit by task ID; do not invent `taskId` / `channelId`.
+
+## Common Errors
+
+| code | when |
+|---|---|
+| `APPROVAL_INPUT_INVALID` | neither or both of `task_id` and `request` supplied |
+| `REQUEST_REQUIRED` | `--request` missing or not an object |
+| `REQUEST_FIELDS_REQUIRED` | required body fields absent/blank |
+| `CAPABILITY_EXECUTION_FAILED` | unmapped domain failure; check `invocation_id` / Hermes logs |

package/skills/ae-engage/references/validate-flow-node-config.md

@@ -30,7 +30,7 @@ Use `--operation-mode save_flow` for the current exposed MCP protocol. Use `save
 Important current rules:
 
 - `event_trigger` / `event_judge` A segment: use `periodStart`, `periodEnd`, `periodTimeSymbol`; do not use branch-style `delayTime`.
-- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerRule` on default branches.
+- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerDefinition` on default branches.
 - `event_trigger targetUserType=2` is invalid.
 - Push `OBJ_ARRAY.value` must be a JSON array, not a stringified array.
 - Push `contentList[].content` should be a JSON array, but a JSON-stringified array is accepted for compatibility.

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,8 +23,23 @@ 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
+  `metric_definition`. Never generate or submit `metricConfig`, `calcType`, or `Axxx` codes.
+- 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`.
+- 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`; writes return `data.result`.
+- Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
 - Query cancellation returns `data.success`.
 
 ## Typical Workflow
@@ -34,6 +50,8 @@ Naming and response boundary:
    - `experiment feature list`
    - `experiment metric list`
 2. Create missing assets if needed:
+   - `experiment save build-guide --operation-mode save_metric` when save validation fails or req shape is unclear
+   - `experiment save validate --operation-mode save_metric --req '{...}'` before retrying a failed save
    - `experiment traffic-layer save`
    - `experiment feature save`
    - `experiment metric save`
@@ -41,14 +59,19 @@ 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
 
+- 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**).
+
 ```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 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 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 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`.
@@ -57,6 +80,16 @@ Optional global parameters work as in other domains: `--host`, `--mcp-url`, `--f
 
 Open the matching file in `references/` before using a command, especially for write operations and JSON payloads.
 
+### Save Helpers
+
+`experiment save build-guide`, `experiment save validate`
+
+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`
@@ -67,7 +100,7 @@ Open the matching file in `references/` before using a command, especially for w
 
 ### 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/check_experiment_ready.md

@@ -12,4 +12,6 @@ Flags:
 
 Use this before `experiment experiment manage` moves an experiment to `pending`, `testing`, or `running`.
 
+Common `groups` failure: `atlas.service.error.experiment.group.allocation.invalid`. Rule: each `groups[].allocation` must be an **integer**, and **sum = 100 exactly** (for example `34 + 33 + 33 = 100`).
+
 Response shape: the readiness result is in `data.readiness`, with recursively snake_case keys.

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

@@ -11,3 +11,9 @@ Flags:
 - `--exp-id`: Experiment ID.
 
 Response shape: the experiment is in `data.item`, with recursively snake_case keys such as `exp_id` and `feature_key_list`.
+
+When targeting contains reversible QP, it is returned as
+`targeting.definition_request` with `targeting.definition_status=AVAILABLE`.
+An absent definition is `NOT_APPLICABLE`; a historical unsupported definition is
+`UNAVAILABLE` with `definition_unavailable_reason`. The internal `target_config`
+field is never returned.

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

@@ -16,3 +16,7 @@ Flags:
 - `--query-name`: Optional fuzzy match against experiment name (`exp_name LIKE`). Does not match `exp_id`.
 
 Response shape: `data.items` contains the experiments, `data.total` contains the count, and item keys are recursively snake_case.
+
+Targeting follows the same semantic projection as detail:
+`targeting.definition_request` plus `targeting.definition_status`; internal
+`target_config` is not returned.

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

@@ -13,3 +13,6 @@ Flags:
 - `--project-id`, `-p`: Project ID.
 
 Response shape: `data.items` contains the archived experiments, `data.total` contains the count, and item keys are recursively snake_case.
+
+Targeting is returned through `targeting.definition_request` and
+`targeting.definition_status`; internal `target_config` is not returned.

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.

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

@@ -1,12 +1,13 @@
-# capability run experiment.report.sample-size
+# experiment report sample-size
 
 Query experiment sample-size report.
 
 ```bash
-ae-cli capability run experiment.report.sample-size --input '{"project_id":1,"exp_id":"exp_123","start_time":"2026-07-01","end_time":"2026-07-07","by_hour":false}'
+ae-cli experiment report sample-size --project-id 1 --exp-id exp_123 --start-time 2026-07-01 --end-time 2026-07-07
+ae-cli experiment report sample-size --project-id 1 --exp-id exp_123 --start-time 2026-07-01 --end-time 2026-07-07 --by-hour true
 ```
 
-Required input: `project_id`, `exp_id`, `start_time`, `end_time`.
-Optional input: `request_id`, `force_refresh`, `by_hour`.
+Required flags: `--project-id`, `--exp-id`, `--start-time`, `--end-time`.
+Optional: `--request-id`, `--force-refresh`, `--by-hour`.
 
-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_metric_detail.md

@@ -11,3 +11,8 @@ Flags:
 - `--metric-id`: Metric ID.
 
 Response shape: the metric is in `data.item`, with recursively snake_case keys.
+
+Reversible QP is returned as `metric_definition` with
+`metric_definition_status=AVAILABLE`. Missing QP is `NOT_APPLICABLE`; unsupported
+historical QP is `UNAVAILABLE` with `metric_definition_unavailable_reason`.
+Internal `metric_config` and `calc_type` are never returned.

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

@@ -10,3 +10,6 @@ Flags:
 - `--project-id`, `-p`: Project ID.
 
 Response shape: `data.items` contains metrics, `data.total` contains the count, and item keys are recursively snake_case.
+
+Each item uses `metric_definition` and `metric_definition_status`. Internal
+`metric_config` and `calc_type` are never returned.

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

@@ -0,0 +1,39 @@
+# experiment save build-guide
+
+Build a read-only save guide for feature, traffic layer, experiment, or metric saves.
+
+```bash
+ae-cli experiment save build-guide --project-id <id> --operation-mode save_experiment
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--operation-mode`: `save_feature`, `save_traffic_layer`, `save_experiment`, or `save_metric`.
+
+## CRITICAL — do not copy `example_args.req` keys verbatim
+
+Guide responses are recursively snake_cased for display. That wrongly rewrites nested DTO
+placeholders inside `data.guide.example_args.req` (for example `expName` → `exp_name`,
+`metricId` → `metric_id`).
+
+Those snake_case keys are **not** valid `--req` fields for the final save commands.
+
+Authoritative field names:
+
+| Mode | Inspect / final save | Nested `--req` style |
+| --- | --- | --- |
+| `save_experiment` | `experiment.experiment.save` | camelCase (`expName`, `trafficLayerId`, …) |
+| `save_metric` | `experiment.metric.save` | camelCase (`metricId`, `metricDefinition`, …) |
+| `save_feature` | `experiment.feature.save` | camelCase (`featureKey`, `targetPlatform`, …) |
+| `save_traffic_layer` | `experiment.traffic-layer.save` | camelCase (`bucketId`, `layerName`, …) |
+
+Before composing `--req`:
+
+1. Read `data.guide.required_fields` / `mode_rules` for **what** is required (names there may
+   already be camelCase).
+2. Treat `example_args.req` as structure-only placeholders; **rename keys to camelCase**.
+3. Prefer `ae-cli capability inspect <final-save-capability-id>` `input_schema.properties.req`
+   when unsure.
+4. Then run `experiment save validate` and the final `experiment … save`.
+
+Response shape: `data.guide`.

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

@@ -16,6 +16,12 @@ Flags:
 - Capability input uses outer `project_id`; nested `req` fields remain native camelCase. Hermes overwrites `req.projectId` with the outer project ID.
 - Never call this with `req=null`, `req={}`, or a modify payload containing only `expId`; those are terminal validation failures.
 - On `valid=false`, do not retry the same payload. Fix the reported field(s) or ask the user for missing input.
+- **Do not** paste `save build-guide` / `save validate` `example_args.req` keys into `--req`.
+  Those responses snake_case nested placeholders (`exp_name`). Final save requires camelCase
+  (`expName`, `expSupposition`, `trafficLayerId`, `featureKeyList`, `metrics[].metricId`, …).
+  If unsure, run `ae-cli capability inspect experiment.experiment.save` and copy
+  `input_schema.properties.req` field names. `save validate` may return `valid: true` for
+  snake_case `req` and still fail here with `unknown field …`.
 
 Response shape is `data.result`. Object keys inside the result are recursively snake_case. A create commonly returns the new experiment ID as `data.result`; a patch commonly returns `true`.
 
@@ -26,12 +32,17 @@ Nested payload fields must match the server DTO types, not just the visible CLI
 | Field | Correct shape | Incorrect shape |
 | --- | --- | --- |
 | `featureKeyList` | `["payment_color"]` | `[{"featureKey":"payment_color"}]` |
+| `allocation` | integer (e.g. `20`) | `20.5`, `33.33` |
+| `groups[].allocation` | integer; all groups sum to `100` (e.g. `34+33+33`) | `33.33`, or sum `99`/`101` |
 | `groups[].expGroupValue` | `"[\"green\"]"` | `["green"]` |
 | `metrics` | `[{"metricId":"payment","metricRole":"primary"}]` | `["payment"]` |
 
 - `featureKeyList` is an array of Feature key strings, not Feature objects. For feature experiments, pass one Feature key string.
+- `allocation` (experiment-level) and `groups[].allocation` are validated at the CLI interface: **integers only, decimals rejected** (for example `33.33` fails before save).
+- `groups[].allocation` rule: each value must be an **integer**, and the **sum of all group allocations must equal `100` exactly** (for example `34 + 33 + 33 = 100`, not `33 + 33 + 33 = 99` and not decimal thirds).
 - `groups[].expGroupValue` is a JSON-encoded string of a string array. Pass a string whose content is a JSON array, not a native JSON array.
 - `metrics` is an array of metric binding objects. Each object contains `metricId` and `metricRole`.
+- Every `metricId` must come from `experiment metric list` for the same project. If save returns `error_code: METRIC_NOT_FOUND`, create the metric with `experiment metric save`, verify it, and then retry the experiment save.
 
 ## Modes
 
@@ -88,12 +99,44 @@ ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allo
 
 - `isExpSharing=1` uses a shared traffic layer from `experiment traffic-layer list`; pick a `trafficLayerId` whose available idle traffic can cover `allocation`.
 - `isExpSharing=0` uses exclusive traffic with `bucketId`; select the bucket with `experiment bucket list`.
-- `allocation` is optional during draft construction, but before readiness it must be greater than `0` and no more than `100`.
+- `allocation` (experiment-level) is the experiment's share of the traffic layer. It is optional during draft construction, but before readiness it must be greater than `0` and no more than `100`. **Integer only** (for example `20`); decimals such as `20.5` are rejected at the CLI interface.
+- `groups[].allocation` (group-level): **integer only; sum must equal `100` exactly**. Example for 3 groups: `34 + 33 + 33 = 100`. Decimals such as `33.33` are rejected at the CLI interface before save.
 - `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, total allocation must equal `100`, and each `expGroupValue` must be a non-empty JSON string array.
+- 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.
 - `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`
+  JSON or any `Cxx`/`Axxx` code. Resolve event and property names with Analysis
+  metadata first.
+
+Semantic audience example:
+
+```json
+{
+  "targeting": {
+    "definitionRequest": {
+      "type": "condition",
+      "conditions": {
+        "relation": "and",
+        "items": [
+          {"type": "user", "field": "country", "operator": "eq", "values": ["CN"]},
+          {
+            "type": "event",
+            "event": "purchase",
+            "operator": "gte",
+            "value": 2,
+            "aggregation": "sum",
+            "property": "amount",
+            "time_range": {"mode": "recent", "unit": "day", "value": 7}
+          }
+        ]
+      }
+    }
+  }
+}
+```
 
 ## Payload Examples
 
@@ -103,12 +146,18 @@ Patch a Feature binding. `featureKeyList` is a string array:
 ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","featureKeyList":["payment_color"]}'
 ```
 
-Patch groups. `expGroupValue` is a JSON-encoded string, not a native array:
+Patch groups. `expGroupValue` is a JSON-encoded string, not a native array. `groups[].allocation` must be integers that sum to exactly `100`:
 
 ```bash
 ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","groups":[{"expGroupName":"control","isControl":1,"allocation":50,"expGroupValue":"[\"green\"]"},{"expGroupName":"variant","isControl":0,"allocation":50,"expGroupValue":"[\"red\"]"}]}'
 ```
 
+Three-group even split example:
+
+```bash
+ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","groups":[{"expGroupName":"control","isControl":1,"allocation":34,"expGroupValue":"[\"A\"]"},{"expGroupName":"variant_b","isControl":0,"allocation":33,"expGroupValue":"[\"B\"]"},{"expGroupName":"variant_c","isControl":0,"allocation":33,"expGroupValue":"[\"C\"]"}]}'
+```
+
 Patch metrics. `metrics` is an object array:
 
 ```bash
@@ -122,6 +171,7 @@ ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","metrics
 If execution reports a DTO type mismatch after a clean dry-run, inspect nested field types first:
 
 - `featureKeyList` must be a string array.
+- `groups[].allocation` must be an integer, and all group allocations must sum to exactly `100`.
 - `groups[].expGroupValue` must be a JSON-encoded string.
 - `metrics` must be an object array with `metricId` and `metricRole`.
 

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

@@ -8,6 +8,72 @@ ae-cli experiment metric save --project-id <id> --req '<json>'
 
 Flags:
 - `--project-id`, `-p`: Project ID.
-- `--req`: Metric save request JSON object.
+- `--req`: Metric save request JSON object (**camelCase** keys such as `metricId`, `metricDefinition`).
 
 Create mode requires metric identifiers and metric configuration. Modify mode uses `update=true`.
+
+Do not paste `save build-guide` / `save validate` `example_args.req` keys (`metric_id`, …) into
+`--req`. Those responses snake_case nested placeholders; final save requires camelCase.
+See [`save_build_guide.md`](save_build_guide.md) / [`save_validate.md`](save_validate.md).
+
+## Semantic Metric Contract
+
+- Supply metric QP as `req.metricDefinition`.
+- Never submit internal `metricConfig`, `calcType`, or an `Axxx` calculation code.
+- Experiment metrics currently accept event definitions only.
+- Supported aggregations:
+  - Event-count (no property): `total_count`, `user_count`, `active_days`
+  - Property-based (**`property` REQUIRED**): `sum`, `avg`, `max`, `distinct_count`
+
+### Property rule (mandatory)
+
+When `aggregation` is `sum`, `avg`, `max`, or `distinct_count`:
+
+1. Resolve the event's available properties with Analysis metadata first
+   (`ae-cli analysis-meta property list` / `get` for that event).
+2. Pass one concrete available property name in `metricDefinition.property`.
+3. Do **not** invent placeholder metrics without a property (for example
+   `metric_avg_no_property_*`). Hermes rejects property aggregations with a blank
+   or missing `property`.
+
+When `aggregation` is `total_count`, `user_count`, or `active_days`, omit `property`.
+
+### Correct example (avg with property)
+
+```bash
+ae-cli experiment metric save --project-id 1 --req '{
+  "metricId":"startup_style_payment_avg_20260729",
+  "metricName":"Startup style payment avg",
+  "createType":"event",
+  "goalDirection":"up",
+  "metricDesc":"Average payment amount",
+  "metricDefinition":{
+    "type":"event",
+    "event":"payment",
+    "aggregation":"avg",
+    "property":"amount"
+  }
+}'
+```
+
+### Wrong example (avg without property — rejected)
+
+```json
+{
+  "metricId": "metric_avg_no_property_actual_20260729_144230",
+  "metricDefinition": {
+    "type": "event",
+    "event": "payment",
+    "aggregation": "avg"
+  }
+}
+```
+
+### Event-count example (no property)
+
+```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"}}'
+```
+
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`.

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

@@ -8,6 +8,9 @@ ae-cli capability run experiment.experiment.save-submit --input '{"project_id":1
 
 Input fields: `project_id` and `req`. The outer input is snake_case; fields inside `req` keep the native camelCase DTO shape.
 
+Custom audiences use semantic `req.targeting.definitionRequest`. Never pass the
+internal `targetConfig` field or hand-write `Cxx`/`Axxx` codes.
+
 Response shape: `data.result`, with object keys recursively converted to snake_case.
 
 Prefer `experiment experiment save` for progressive draft construction.

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

@@ -0,0 +1,33 @@
+# experiment save validate
+
+Dry-run helper for save payloads. Does **not** persist data.
+
+```bash
+ae-cli experiment save validate --project-id <id> --operation-mode save_experiment --req '{"expName":"Demo"}'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--operation-mode`: `save_feature`, `save_traffic_layer`, `save_experiment`, or `save_metric`.
+- `--req`: Candidate save request object. **Must use native camelCase DTO keys.**
+
+## CRITICAL — `valid: true` is not a save schema pass
+
+`experiment.save.validate` checks operation-mode / outer helper contract. It does **not**
+fully enforce the final save capability `input_schema`.
+
+Consequences:
+
+- `--req '{"exp_name":"Demo"}'` can return `valid: true`.
+- The same payload fails on `experiment experiment save` with `unknown field exp_name`.
+
+Rules:
+
+1. Never submit snake_case DTO keys in `--req` (`exp_name`, `metric_id`, `feature_key`, …).
+2. Do not trust `data.validation.example_args.req` key casing; rebuild with camelCase.
+3. After `valid: true`, still use camelCase and prefer
+   `ae-cli … save --dry-run` / `capability inspect` before a real write.
+4. On final save `INVALID_CAPABILITY_INPUT` / `unknown field`, fix casing — do not widen
+   the payload with more snake_case keys.
+
+Response shape: `data.validation`.