@thinkingai/ae-cli 6.0.48 → 6.1.0-project-role-upsert.1

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

@@ -0,0 +1,22 @@
+# experiment experiment list
+
+Query experiments in a project with optional filters from the existing list API.
+
+```bash
+ae-cli experiment experiment list --project-id <id>
+ae-cli experiment experiment list --project-id <id> --status archive
+ae-cli experiment experiment list --project-id <id> --traffic-layer-id <layer-id> --group-id <group-id> --query-name checkout
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--status`: Optional status filter (`draft`, `testing`, `pending`, `running`, `paused`, `ended`, `archive`). For the dedicated archived list command, prefer `experiment experiment list-archived`.
+- `--traffic-layer-id`: Optional traffic layer ID filter.
+- `--group-id`: Optional business group ID filter.
+- `--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

@@ -0,0 +1,18 @@
+# experiment experiment list-archived
+
+Query archived experiments in a project.
+
+This command reuses the existing experiment list API and hardcodes `status=archive`.
+It only accepts `--project-id`; it does not expose additional filters.
+
+```bash
+ae-cli experiment experiment list-archived --project-id <id>
+```
+
+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

@@ -0,0 +1,12 @@
+# experiment report metric-trend
+
+Query experiment metric trend report.
+
+```bash
+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 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 via `capability run experiment.query.cancel`.

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

@@ -0,0 +1,17 @@
+# experiment operation-log query
+
+Query full operation logs for one experiment.
+
+Returns the complete Atlas experiment operation-log payload, including `remark`,
+`operation_content`, and structured `changes` when present. No field projection.
+
+```bash
+ae-cli experiment operation-log query --project-id <id> --exp-id <exp-id>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--exp-id`: Experiment ID.
+
+Response shape: `data.items` contains the full log records, `data.total` contains
+the count, and item keys are recursively snake_case.

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

@@ -0,0 +1,12 @@
+# experiment report summary
+
+Query experiment report summary.
+
+```bash
+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 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

@@ -0,0 +1,13 @@
+# experiment report sample-size
+
+Query experiment sample-size report.
+
+```bash
+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 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 via `capability run experiment.query.cancel`.

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

@@ -0,0 +1,14 @@
+# experiment feature get
+
+Query Feature detail by key and optional version.
+
+```bash
+ae-cli experiment feature get --project-id <id> --feature-key <key> [--version <versionId>]
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--feature-key`: Feature key.
+- `--version`: Optional Feature version ID.
+
+Response shape: the Feature is in `data.item`, with recursively snake_case keys such as `feature_key` and `target_platform`.

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

@@ -0,0 +1,12 @@
+# experiment feature list
+
+Query Features in a project.
+
+```bash
+ae-cli experiment feature list --project-id <id>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+
+Response shape: `data.items` contains Features, `data.total` contains the count, and item keys are recursively snake_case.

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

@@ -0,0 +1,19 @@
+# experiment feature operation-log query
+
+Query Feature operation logs for one Feature key.
+
+Reuses Hermes `GET /v1/atlas/feature/operationLogs` and returns the generic Atlas
+operation-log payload (`operation_type`, `operation_type_name`, `operator_name`,
+`operation_content`, `operate_time`). This is separate from
+`experiment operation-log query` and does not include experiment-side `changes`.
+
+```bash
+ae-cli experiment feature operation-log query --project-id <id> --feature-key <feature-key>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--feature-key`: Feature key.
+
+Response shape: `data.items` contains the full log records, `data.total` contains
+the count, and item keys are recursively snake_case.

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

@@ -0,0 +1,20 @@
+# experiment feature version-list
+
+List Feature version history for one Feature key.
+
+Reuse the existing Hermes `GET /v1/atlas/feature/versions` API and return the full
+version records, including `version_snapshot`.
+
+Use with `experiment feature get --version <featureVersionId>` to inspect one version.
+
+```bash
+ae-cli experiment feature version-list --project-id <id> --feature-key <feature-key>
+ae-cli experiment feature get --project-id <id> --feature-key <feature-key> --version <featureVersionId>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--feature-key`: Feature key.
+
+Response shape: `data.items` contains version history records, `data.total` contains
+the count, and item keys are recursively snake_case.

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

@@ -0,0 +1,18 @@
+# experiment metric get
+
+Query metric detail.
+
+```bash
+ae-cli experiment metric get --project-id <id> --metric-id <metricId>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--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

@@ -0,0 +1,15 @@
+# experiment metric list
+
+Query metrics in a project.
+
+```bash
+ae-cli experiment metric list --project-id <id>
+```
+
+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/query_traffic_layer_detail.md

@@ -0,0 +1,13 @@
+# experiment traffic-layer get
+
+Query traffic layer detail.
+
+```bash
+ae-cli experiment traffic-layer get --project-id <id> --layer-id <layerId>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--layer-id`: Traffic layer ID.
+
+Response shape: the traffic layer is in `data.item`, with recursively snake_case keys.

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

@@ -0,0 +1,12 @@
+# experiment traffic-layer list
+
+Query traffic layers in a project.
+
+```bash
+ae-cli experiment traffic-layer list --project-id <id>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+
+Response shape: `data.items` contains traffic layers, `data.total` contains the count, and item keys are recursively snake_case.

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

@@ -0,0 +1,210 @@
+# experiment experiment save
+
+Progressively create or patch an experiment draft.
+
+```bash
+ae-cli experiment experiment save --project-id <id> --req '<json>'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--req`: Experiment save request JSON object.
+
+## Contract
+
+- Call shape is top-level `projectId` plus a non-empty `req` object. In CLI form, `--project-id` supplies the top-level project ID.
+- 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`.
+
+## Payload Type Contract
+
+Nested payload fields must match the server DTO types, not just the visible CLI dry-run body shape.
+
+| 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
+
+### Create Draft
+
+Blank or missing `req.expId` creates a draft.
+
+Required:
+- `expName`
+
+Optional while drafting:
+- `expType` (blank defaults to `feature`)
+- `groupId`
+- `trafficLayerId`
+- `allocation`
+- `expSalt`
+- `expSupposition`
+- `expDesc`
+- `isExpSharing`
+- `bucketId`
+- `expCycle`
+- `groups`
+- `featureKeyList`
+- `metrics`
+- `targeting`
+
+Success returns the created `expId`.
+
+```bash
+ae-cli experiment experiment save --project-id 1 --req '{"expName":"Homepage CTA draft"}'
+```
+
+### Patch Draft
+
+Non-blank `req.expId` patches an existing draft by merging the request with current experiment detail.
+
+Required:
+- `expId`
+- At least one changed field besides `expId`
+
+Merge behavior:
+- Omitted fields keep their current values.
+- Non-null scalar/object fields replace current values.
+- Non-empty `groups`, `featureKeyList`, `metrics`, and non-null `targeting` replace saved values.
+- Empty lists are not a reliable clear operation. Do not use empty arrays to clear bindings unless the backend contract is confirmed separately.
+
+Success returns `true`; continue using the input `expId`.
+
+```bash
+ae-cli experiment experiment save --project-id 1 --req '{"expId":"exp_123","allocation":20}'
+```
+
+## Field Notes
+
+- `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` (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 (`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`; 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`
+  JSON or any `Cxx`/`Axxx` code. Resolve event and property names with Analysis
+  metadata first.
+- Avoid redundant adjacent `compound` groups with the same `relation`. Hermes
+  safely flattens those groups when an Atlas experiment is saved or submitted so
+  the generated cluster QP stays within the backend layer limit. Different
+  relations are always preserved.
+
+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
+
+Patch a Feature binding. `featureKeyList` is a string array:
+
+```bash
+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. `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
+ae-cli experiment experiment save --project-id 2 --req '{"expId":"e024","metrics":[{"metricId":"payment","metricRole":"primary"}]}'
+```
+
+## Dry-run Limitation
+
+`--dry-run` calls the Capability Gateway preview endpoint. It validates the outer input contract but does not guarantee that every nested DTO business rule will pass execution.
+
+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`.
+
+## Verified Related CLI Commands
+
+Use only these confirmed ae-cli commands when composing or checking a save payload:
+
+- `experiment experiment get`: optional; use only when patching an existing `expId` and you need to inspect saved fields.
+- `experiment bucket list`: find `bucketId`.
+- `experiment traffic-layer list`: find shared `trafficLayerId`.
+- `experiment feature list`: find `featureKey`.
+- `experiment metric list`: find `metricId`.
+- `experiment traffic-layer save`: create a missing traffic layer.
+- `experiment feature save`: create a missing Feature.
+- `experiment metric save`: create a missing metric.
+- `experiment experiment ready-check`: verify completeness before moving to `pending`, `testing`, or `running`.
+
+## Completion
+
+After a successful save, output the experiment detail link in this form, substituting the returned or input `expId` and actual project ID:
+
+```markdown
+[View experiment](/#/atlas/experiment/detail?expId=<expId>&currentProjectId=<projectId>)
+```
+
+After every successful save, call:
+
+```bash
+ae-cli experiment experiment ready-check --project-id <id> --exp-id <expId>
+```
+
+Use readiness failures to decide the next patch. Do not report the experiment save work as complete until readiness has been checked.

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

@@ -0,0 +1,13 @@
+# experiment feature save
+
+Create or update a Feature.
+
+```bash
+ae-cli experiment feature save --project-id <id> --req '<json>'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--req`: Feature save request JSON object.
+
+Create mode requires `featureKey`, `type`, and `targetPlatform`. Modify mode uses `id` or `update=true`.

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

@@ -0,0 +1,91 @@
+# experiment metric save
+
+Create or update a metric.
+
+```bash
+ae-cli experiment metric save --project-id <id> --req '<json>'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--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.
+- 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:
+  - 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)
+
+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`.
+
+### 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
+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",
+    "filters":{
+      "relation":"and",
+      "items":[{"field":"amount","operator":"gt","values":[10]}]
+    }
+  }
+}'
+```
+
+### Wrong example (avg without property — rejected)
+
+```json
+{
+  "metricId": "metric_avg_no_property_actual_20260729_144230",
+  "metricDefinition": {
+    "type": "event",
+    "event": "payment",
+    "aggregation": "avg"
+  }
+}
+```
+
+Filters use the semantic `filters` tree with `relation=and|or` and items containing
+`field`, `operator`, and `values`. For the frontend example `gold > 10`, use:
+
+```json
+{"filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}
+```

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

@@ -0,0 +1,16 @@
+# capability run experiment.experiment.save-submit
+
+Create or update a complete experiment and submit it in one call.
+
+```bash
+ae-cli capability run experiment.experiment.save-submit --input '{"project_id":1,"req":{...}}'
+```
+
+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_traffic_layer.md

@@ -0,0 +1,13 @@
+# experiment traffic-layer save
+
+Create or update a traffic layer.
+
+```bash
+ae-cli experiment traffic-layer save --project-id <id> --req '<json>'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--req`: Traffic layer save request JSON object.
+
+Create mode requires `bucketId`, `layerName`, and `layerType` in the request. Modify mode requires `layerId`.

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`.