@thinkingai/ae-cli 6.1.11 → 6.1.12

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/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`.
 
@@ -36,6 +42,7 @@ Nested payload fields must match the server DTO types, not just the visible CLI
 - `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
 

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

@@ -8,10 +8,14 @@ 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`.

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

package/skills/ae-experiment-design/references/platform-operations.md

@@ -9,7 +9,7 @@ All platform operations must use `ae-cli`. Do not call raw APIs, use browser aut
 Use curated commands when their contract is known. Use the Capability Gateway for experiment capabilities that do not yet have a curated command:
 
 ```bash
-ae-cli capability search "<terms>" [--project-id <id>]
+ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
 ae-cli capability inspect <capability-id> --project-id <id>
 ae-cli capability validate <capability-id> --input '<json-object>'
 ae-cli capability dry-run <capability-id> --input '<json-object>'
@@ -30,10 +30,16 @@ After every `ae-cli` invocation, inspect stderr and `_notice.host_compat`. If a
 
 ## Project gate
 
-Resolve an unverified project through:
+When the user supplies a project ID, resolve it directly:
 
 ```bash
-ae-cli analysis project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
+ae-cli project info get --project-id <id>
+```
+
+When the user supplies only a project name, search and disambiguate:
+
+```bash
+ae-cli project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
 ```
 
 Reuse a project only when its ID and host were verified in the same continuous conversation. If multiple projects match, stop and ask the user to choose.

package/skills/ae-experiment-insight/references/platform-operations.md

@@ -9,7 +9,7 @@ All platform discovery and reads must use `ae-cli`. Do not call raw APIs, use br
 Use the Capability Gateway when no curated experiment command exists:
 
 ```bash
-ae-cli capability search "<terms>" [--project-id <id>]
+ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
 ae-cli capability inspect <capability-id> --project-id <id>
 ae-cli capability run <capability-id> --input '<json-object>'
 ```
@@ -22,10 +22,16 @@ After every `ae-cli` invocation, inspect stderr and `_notice.host_compat`. If pr
 
 ## Resolution gates
 
-Resolve the project first:
+When the user supplies a project ID, resolve it directly:
 
 ```bash
-ae-cli analysis project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
+ae-cli project info get --project-id <id>
+```
+
+When the user supplies only a project name, search and disambiguate:
+
+```bash
+ae-cli project info list --query "<project name>" --fields '["project_id","project_name"]' --limit 20 --offset 0
 ```
 
 Then discover experiment list/get capabilities and resolve the exact experiment by verified ID or exact-match name. If multiple candidates remain, ask the user.