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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.48",
+  "version": "6.1.0-project-role-upsert.1",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "verify:retired-analysis-commands": "node --test test/retired-analysis-commands.test.mjs",
     "verify:retired-api-command": "node --test test/retired-api-command.test.mjs",
     "verify:analysis-common-tools": "node scripts/verify-te-common-tools.mjs",
+    "verify:experiment-tools": "node scripts/verify-te-experiment-tools.mjs && node --import tsx test/experiment/experiment-capability-command.test.mjs",
     "verify:team-tools": "node scripts/verify-te-team-tools.mjs",
     "verify:agent-tools": "node --test test/agent-command-registry.test.mjs && tsx tests/te-agent-credentials.test.ts && tsx tests/te-agent-unified-auth.test.ts && tsx tests/te-agent-conversations.test.ts && tsx tests/te-agent-automations.test.ts && tsx scripts/verify-agent-tools.mjs && npm run verify:approval && npm run verify:agent-distribution && npm run verify:agent-context && npm run verify:sandbox-tools",
     "verify:agent-context": "tsx tests/agent-context-command.test.ts",

package/skills/ae-analysis/SKILL.md

@@ -108,12 +108,24 @@ Before a project-scoped command:
 3. If there are multiple plausible projects, the host is unclear, or no project matches, show the candidates and ask; never guess.
 4. Re-verify after the user changes project, host, or environment.
 
+### Project Semantics
+
+Before answering project-scoped analysis or asset-governance requests, call `ae-cli project-semantic list --project-id <project_id>` once after the project is resolved. This is the governed project semantic catalog. The list is already filtered to active, fresh project semantics and sorted by heat, so do not page or search the database yourself.
+
+If one project semantic is actually adopted to interpret the user's wording, asset selection, metric definition, calculation convention, or project-wide business rule, fetch it with `ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used`. Do not pass `--mark-used` for project semantics that were only inspected or rejected.
+
+For project semantic recommendation, switch to the `ae-project-semantic` skill. This skill only consumes published project semantics during analysis tasks.
+
+Published project semantics are the formal project-wide authority. A current-turn user instruction may request a different analysis, but the result must be labeled as an explicit non-formal deviation rather than silently replacing the published definition.
+
 ### Personal Semantic Preferences
 
 Before answering project-scoped analysis or asset-governance requests, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation after the project is resolved. Keep that lightweight directory in conversation context; do not page it, search the database, or call list again for each question. The backend returns at most 200 entries using `HOT_160_PLUS_RECENT_40` and may return fewer to keep the payload within its size limit.
 
 Use the returned compact catalog only as context. If one item is actually adopted to interpret the user's wording, asset selection, metric preference, or output style, fetch it with `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used`. This also applies when the matched item is being used as the target for an `update`. Do not pass `--mark-used` for items that were only inspected or rejected.
 
+Apply the two catalogs by authority and purpose, not as one flat ranking. Published project semantics define the formal business meaning. Personal semantics supply the current user's defaults, interpretation corrections, asset choices, and output preferences where they do not conflict. If a personal semantic conflicts with a published project semantic, use the project semantic for the formal result and explicitly disclose the difference; never silently overwrite the personal record. If the user explicitly requests the personal alternative for the current task, execute it as a labeled non-formal variation.
+
 The Agent owns the personal preference capture trigger. Choose `context_type` by meaning:
 
 - `preference`: durable interpretation or output preference without an exact asset binding.
@@ -121,12 +133,16 @@ The Agent owns the personal preference capture trigger. Choose `context_type` by
 - `experience`: a confirmed reusable work method without an exact asset binding.
 - `background`: stable personal context without an exact asset binding.
 
-Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. A current-user working definition remains eligible for personal storage even when it would also benefit other users. Store it only as the current user's preference; do not copy the bound asset definition into its content or imply that it is shared authority. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, or standalone metadata facts.
+Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. During a project task, collect durable current-user preferences, stable interpretation corrections, reusable asset-selection choices, recurring output preferences, and current-user working definitions that have not become approved project semantics. A working definition remains eligible for personal storage even when it would also benefit other project users. Store it only as the current user's preference; never describe it as approved project authority or copy a bound asset definition into its content. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, standalone metadata facts, reports, or dashboards as personal preferences.
 
 An explicit stable statement, correction, or confirmation that passes that evidence gate authorizes `personal-semantic-preference add` or `update` without a second "save" confirmation. Compare against the already loaded catalog first; when one existing preference matches, fetch it with `--mark-used`, update that existing preference, and avoid creating a duplicate. Otherwise add a new one. An explicit instruction not to retain it always wins. Delete remains high risk and requires explicit user confirmation.
 
+Personal capture and project recommendation are independent. Save or update the personal semantic first when its evidence gate is met. If the same content looks reusable as a formal project-wide definition, finish the current task and then ask whether the user wants to recommend it as a project semantic candidate. Do not make project recommendation a prerequisite for personal capture, do not submit a candidate without that user choice, and never approve or publish on behalf of an ordinary user.
+
 After a successful add, update, or delete, merge that response into the conversation's cached directory locally. Do not call list again merely to observe the write.
 
+When a later published project semantic matches a personal semantic, treat the project semantic as formal and allow the personal record to become redundant, expire, or merge through the supported lifecycle. When they conflict, keep the project semantic formal, disclose the conflict, and preserve the personal record unless the user explicitly changes or deletes it. These are consumption and lifecycle rules; do not append them to the stored personal semantic content.
+
 Stale or expired preferences are automatically hidden by list filtering and backend maintenance. Do not look for or invent a separate command for that behavior.
 
 ### C. FUZZY_SEARCH_FALLBACK

package/skills/ae-analysis/references/command_index.md

@@ -248,7 +248,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli project role delete` | project.role.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--role-name` (string; required) — Role name to delete.<br>`--new-role-name` (string; optional) — Role name to migrate users to before deletion. | [project_role_delete.md](project_role_delete.md) |
 | `ae-cli project role get` | project.role.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--role-name` (string; required) — Role name. | [project_role_get.md](project_role_get.md) |
 | `ae-cli project role list` | project.role.list | read | `--company-id` (number; optional) — Company ID. Required when project_id is absent.<br>`--project-id` (number; required) — Numeric project ID.<br>`--visible-only` (boolean; optional) — When true, list roles visible to the current user. | [project_role_list.md](project_role_list.md) |
-| `ae-cli project role upsert` | project.role.upsert | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [project_role_upsert.md](project_role_upsert.md) |
+| `ae-cli project role upsert` | project.role.upsert | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Role payload with role_func_list object items containing function_name and has_power (0 or 1). | [project_role_upsert.md](project_role_upsert.md) |
 | `ae-cli project role-function list` | project.role_function.list | read | `--company-id` (number; optional) — Company ID.<br>`--project-id` (number; required) — Numeric project ID.<br>`--role-name` (string; optional) — Single role name.<br>`--role-names` (json; optional) — Role names JSON array. When omitted, all role functions are returned.<br>`--show-system-func` (boolean; optional) — Whether to include system functions. Default false. | [project_role_function_list.md](project_role_function_list.md) |
 | `ae-cli project role-user list` | project.role_user.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--role-name` (string; required) — Role name. | [project_role_user_list.md](project_role_user_list.md) |
 | `ae-cli project timezone get` | project.timezone.get | read | `--project-id` (number; required) — Numeric project ID. | [project_timezone_get.md](project_timezone_get.md) |

package/skills/ae-analysis/references/personal_semantic_preference_add.md

@@ -16,7 +16,7 @@ Use `preference` for durable interpretation/output preferences, `asset_context`
 
 `--request-id` is an idempotency key; omit it for ordinary interactive use and the CLI will generate one.
 
-This command creates only a current-user preference. Do not reject an otherwise valid personal preference merely because the same content may benefit other users, and do not imply that the saved preference is shared authority.
+This command creates only a current-user preference; it never creates or approves a project semantic. Do not reject an otherwise valid personal preference merely because the same content may benefit other users, and do not imply that the saved preference is shared authority. Keep project-candidate recommendation separate: after personal capture, ask whether to recommend broadly reusable content as a project semantic candidate, and submit nothing without that choice.
 
 Store only the present working preference. Do not append future governance or lifecycle instructions. Do not use this command for company knowledge, standalone metadata facts, reports, dashboards, transient task details, one-off analysis results, or automatic stale/expired preference handling.
 

package/skills/ae-analysis/references/personal_semantic_preference_get.md

@@ -12,6 +12,8 @@ ae-cli personal-semantic-preference get --project-id <project_id> --id <preferen
 
 Input uses `project_id`, `id`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add.
 
-Do not use this command as a keyword search or asset catalog lookup. Do not call it repeatedly for every catalog row. Do not use `--mark-used` for a candidate that turns out not to match the user's intent or is only inspected and then rejected.
+Do not use this command as a keyword search, project semantics lookup, or asset catalog lookup. Do not call it repeatedly for every catalog row. Do not use `--mark-used` for a candidate that turns out not to match the user's intent or is only inspected and then rejected.
+
+When a published project semantic conflicts with the personal item, the project semantic is the formal definition. Fetch and mark the personal item only when it materially affects the response, such as an explicitly requested non-formal alternative; never silently use it to override the project semantic.
 
 Output is the gateway envelope. `data.preference` contains the full personal preference, including content, complete ordered `resource_refs`, and revision. When `--mark-used` is set, the backend increments `heat_count` and updates `last_used_at` for that record.

package/skills/ae-analysis/references/personal_semantic_preference_list.md

@@ -12,8 +12,10 @@ ae-cli personal-semantic-preference list --project-id <project_id>
 
 Input uses `project_id` only. Do not add pagination parameters: the backend returns a compact catalog intended for agent context.
 
-Do not use this command for shared knowledge, metadata catalogs, report/dashboard lists, or complete asset discovery. It only returns the current user's personal semantic preferences in the current project.
+Do not use this command for project semantics, shared knowledge, metadata catalogs, report/dashboard lists, or complete asset discovery. It only returns the current user's personal semantic preferences in the current project.
 
 Output is the gateway envelope. `data.items[]` contains only `id`, `context_type`, `title`, truncated `summary`, limited `keywords`, `resource_ref_count`, distinct `resource_types`, and `revision`; it deliberately omits content, full asset references, heat, and timestamps. `data.returned_count` is at most 200, `data.truncated` says whether entries were omitted, and `data.selection_policy` is `HOT_160_PLUS_RECENT_40`: up to 160 highest-heat items plus up to 40 recently changed items not already selected. The backend may return fewer items to keep the data payload within 64 KiB.
 
 If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used` before using its full content. Do not mark an item used when it was only inspected or rejected.
+
+Compare a likely match with the published project semantic catalog. Published project semantics remain the formal project-wide authority; personal items provide current-user defaults and working interpretations. If they conflict, use the project semantic for the formal result, explicitly disclose the personal difference, and do not mark the personal item used unless the user explicitly adopts it as a labeled alternative.

package/skills/ae-analysis/references/personal_semantic_preference_update.md

@@ -12,7 +12,7 @@ ae-cli personal-semantic-preference update --project-id <project_id> --id <prefe
 
 The update replaces all editable fields. Include the full intended `title`, `summary`, `content`, keywords, and asset bindings rather than a partial patch. `asset_context` requires 1 to 50 complete ordered `resource_refs`; other context types cannot contain non-empty refs.
 
-This command updates only the current-user preference. Do not block the update merely because the same content may benefit other users, and do not imply that the saved preference is shared authority.
+This command updates only the current-user preference; it does not update, approve, or publish project semantics. Do not block the update merely because the same content may benefit other users, and do not imply that the saved preference is shared authority. Keep project-candidate recommendation separate and ask before submitting it.
 
 Keep future governance and lifecycle handling out of the stored content. Do not use this command for shared knowledge, standalone metadata facts, reports, dashboards, transient task details, one-off analysis results, or automatic stale/expired preference handling.
 

package/skills/ae-analysis/references/project_role_upsert.md

@@ -8,12 +8,42 @@ Command:
 
 ```bash
 ae-cli project role upsert --project-id <project_id> --payload <payload>
+ae-cli project role upsert --validate --project-id <project_id> --payload <payload>
 ae-cli project role upsert --dry-run --project-id <project_id> --payload <payload>
 ```
 
 Capability id: `project.role.upsert`.
 
-Input sends `project_id`, `payload`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+Input sends `project_id`, `payload`. Payload keys must use snake_case.
+
+## Payload contract
+
+`role_func_list` is required and must be a non-empty array of objects. Every item requires:
+
+- `function_name`: non-empty string. Resolve valid values with `ae-cli project function list` instead of guessing IDs or sending numeric function IDs.
+- `has_power`: integer `0` or `1` only. Use `1` to select the function and `0` to leave it unselected.
+
+For role creation, omit `role_name` and provide `role_desc` with 1 to 80 characters. For an update, provide the existing `role_name`; `role_desc` may remain omitted for compatibility.
+
+Functions omitted from `role_func_list` are completed by the service with their permission metadata and `has_power=0`. Do not attempt to replace an object item with a number or string.
+
+Create example:
+
+```bash
+ae-cli project role upsert \
+  --project-id 196 \
+  --payload '{"role_desc":"Data analyst","role_func_list":[{"function_name":"viewReport","has_power":1}]}'
+```
+
+Update example:
+
+```bash
+ae-cli project role upsert \
+  --project-id 196 \
+  --payload '{"role_name":"custom_role","role_func_list":[{"function_name":"viewReport","has_power":1}]}'
+```
+
+Run with `--validate` first when constructing the payload dynamically. Invalid item types, missing fields, an empty list, or a `has_power` value outside `0` and `1` return a validation error before the role is saved.
 
 Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
 
@@ -21,4 +51,4 @@ Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Role save payload matching RoleSaveRequestDTO in snake_case. |
+| `--payload` | Yes | Role payload with a non-empty `role_func_list` object array; each item contains `function_name` and `has_power` (`0` or `1`). |

package/skills/ae-engage/SKILL.md

@@ -398,6 +398,8 @@ When the user wants to "create a flow / generate a flow canvas / save a flow", d
 3. Build condition-related nodes with semantic `targetDefinitionRequest` and
    `triggerDefinition` objects. Resolve real event and property names through Analysis metadata;
    do not create an intermediate cluster merely to obtain persisted QP.
+   For `ab_split_flow` indicators, use `indicatorsDef[].eventDefinition`; always provide the
+   aggregate `operator`/`value` and every event-property filter's `operator`/`values`.
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
 

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

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

package/skills/ae-experiment/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ae-experiment
+version: 1.0.1
+description: "Use when managing Atlas AB experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
+---
+
+# ae-experiment
+
+AE CLI (`ae-cli`) exposes Atlas AB Experiment capabilities through the `experiment` domain.
+
+## Global Rules
+
+- Prefer `ae-cli experiment <command>` for Atlas AB Experiment work.
+- 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.
+
+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.
+- Event-property comparisons belong in `metricDefinition.filters`, using
+  `{relation,items:[{field,operator,values}]}`. Never put comparison fields directly on
+  `metricDefinition`, and never submit raw `filts`, `calcuSymbol`, or `ftv` fields.
+- For metric aggregations `sum` / `avg` / `max` / `distinct_count`, `metricDefinition.property`
+  is **required** and must be a concrete available event property from Analysis metadata.
+  Never create property aggregations without `property` (for example `metric_avg_no_property_*`).
+- Preset event aggregations `total_count` / `user_count` / `active_days` omit `property`.
+- Experiment metric creation does not support `avg_per_user` / `A105`.
+- Resolve event and property names with Analysis metadata before saving semantic definitions.
+- Lists return `data.items` and `data.total`; detail commands return `data.item`.
+- Readiness returns `data.readiness`; reports return `data.report`; save guides return `data.guide`; save dry-run validation returns `data.validation`; writes return `data.result`.
+- Query cancellation returns `data.success`.
+
+## Typical Workflow
+
+1. Discover reusable assets:
+   - `experiment bucket list`
+   - `experiment traffic-layer list`
+   - `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`
+3. Create or patch the experiment draft with `experiment experiment save`.
+   Use `experiment experiment update-metrics` when replacing metric bindings or assigning guardrail roles.
+4. Check readiness with `experiment experiment ready-check`.
+5. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
+6. Move status with `experiment experiment manage`.
+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**).
+- Public experiment metric roles are `primary`, `secondary`, and `guardrail`. The internal `observation` role is currently unavailable for saves. Guardrail is a binding role; updating metrics replaces the full binding list.
+
+```bash
+ae-cli experiment experiment get --project-id 1 --exp-id exp_123
+ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
+ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
+ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07
+```
+
+Optional global parameters work as in other domains: `--host`, `--mcp-url`, `--format`, `--jq`, `--dry-run`, and `--yes`.
+
+## References
+
+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`, `experiment experiment update-metrics`, `capability run experiment.experiment.save-submit`, `experiment experiment list`, `experiment experiment list-archived`, `experiment experiment get`, `experiment experiment ready-check`, `experiment experiment conflict-check`, `experiment experiment manage`, `experiment experiment update-group`, `experiment experiment batch-delete`, `experiment operation-log query`
+
+Read [`manage_guardrail_metrics.md`](references/manage_guardrail_metrics.md) before assigning or replacing metric roles.
+
+### Traffic Layer and Buckets
+
+`experiment traffic-layer save`, `experiment traffic-layer get`, `experiment traffic-layer list`, `experiment traffic-layer batch-delete`, `experiment bucket list`
+
+### Reports
+
+`experiment report summary`, `experiment report sample-size`, `experiment report metric-trend`, `capability run experiment.query.cancel`
+
+### Metric and Feature
+
+`experiment metric save`, `experiment metric get`, `experiment metric list`, `experiment metric delete`, `experiment feature save`, `experiment feature update-status`, `experiment feature get`, `experiment feature list`, `experiment feature version-list`, `experiment feature operation-log query`, `experiment feature batch-delete`, `experiment feature whitelist list`, `experiment feature whitelist save`, `experiment feature whitelist update-status`, `experiment feature whitelist batch-delete`
+
+Read [`manage_feature_whitelist.md`](references/manage_feature_whitelist.md) before querying or changing Feature whitelist rules.

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

@@ -0,0 +1,11 @@
+# experiment experiment batch-delete
+
+Batch delete experiments.
+
+```bash
+ae-cli experiment experiment batch-delete --project-id <id> --exp-ids '["exp_1","exp_2"]' [--yes]
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--exp-ids`: Experiment ID list as JSON array.

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

@@ -0,0 +1,11 @@
+# experiment feature batch-delete
+
+Batch delete Features.
+
+```bash
+ae-cli experiment feature batch-delete --project-id <id> --req '<json>' [--yes]
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--req`: Feature delete request JSON object.

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

@@ -0,0 +1,11 @@
+# experiment traffic-layer batch-delete
+
+Batch delete traffic layers.
+
+```bash
+ae-cli experiment traffic-layer batch-delete --project-id <id> --layer-ids '["layer_1","layer_2"]' [--yes]
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--layer-ids`: Traffic layer ID list as JSON array.

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

@@ -0,0 +1,11 @@
+# capability run experiment.query.cancel
+
+Cancel a running experiment report query.
+
+```bash
+ae-cli capability run experiment.query.cancel --input '{"request_id":"<id>"}'
+```
+
+Required input: `request_id`.
+
+Response shape: `data.success`.

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

@@ -0,0 +1,17 @@
+# experiment experiment ready-check
+
+Check whether an experiment can enter online status transitions.
+
+```bash
+ae-cli experiment experiment ready-check --project-id <id> --exp-id <expId>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--exp-id`: Experiment ID.
+
+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/check_experiment_traffic_layer_conflict.md

@@ -0,0 +1,37 @@
+# experiment experiment conflict-check
+
+Pre-submit check for cross-layer Feature conflicts on a **non-mutex** traffic layer.
+
+Reuse the existing Hermes `trafficLayerConflictCheck` API. Do **not** call this command for mutex traffic layers.
+
+## Workflow
+
+1. Ensure you already have the Feature keys for the current experiment:
+   - Editing an existing draft: call `experiment experiment get` and read `feature_key_list`.
+   - Creating a new experiment: reuse the Feature keys already chosen in the current workflow.
+2. Call conflict-check with the selected non-mutex `traffic-layer-id`.
+3. Interpret the response before `save-submit`:
+   - `data.features` non-empty: some Features are not enabled.
+   - `data.experiments` non-empty: same Features are active on other traffic layers.
+   - both empty: no conflict signal from this check.
+
+```bash
+ae-cli experiment experiment conflict-check \
+  --project-id <id> \
+  --feature-key-list '["checkout_color"]' \
+  --traffic-layer-id <layer-id>
+
+ae-cli experiment experiment conflict-check \
+  --project-id <id> \
+  --feature-key-list '["checkout_color"]' \
+  --traffic-layer-id <layer-id> \
+  --exp-id <exp-id>
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--feature-key-list`: Required JSON string array of Feature keys selected by the current experiment.
+- `--traffic-layer-id`: Required selected non-mutex traffic layer ID.
+- `--exp-id`: Optional current experiment ID when editing an existing draft (excludes self from conflicts).
+
+Response shape: `data.experiments` and `data.features`, with recursively snake_case item keys.

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

@@ -0,0 +1,13 @@
+# experiment metric delete
+
+Delete a metric.
+
+```bash
+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/manage_experiment.md

@@ -0,0 +1,17 @@
+# experiment experiment manage
+
+Manage experiment status.
+
+```bash
+ae-cli experiment experiment manage --project-id <id> --exp-id <expId> --target-status <status> [--remark <text>]
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--exp-id`: Experiment ID.
+- `--target-status`: One of `draft`, `testing`, `pending`, `running`, `paused`, `ended`, `archive`.
+- `--remark`: Optional operation remark.
+
+When target status is `pending`, `testing`, or `running`, Hermes performs a ready check before changing status.
+
+Response shape: the operation or blocking readiness result is in `data.result`, with object keys recursively converted to snake_case.

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

@@ -0,0 +1,11 @@
+# experiment feature update-status
+
+Update Feature status.
+
+```bash
+ae-cli experiment feature update-status --project-id <id> --req '<json>'
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--req`: Feature status request JSON object.

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

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

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

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

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

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

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

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