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

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

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

@@ -0,0 +1,20 @@
+# experiment experiment update-group
+
+Update only the business group of one experiment.
+
+Reuses Hermes `POST /v1/atlas/experiment/updateGroup`. This dedicated endpoint
+updates `group_id` only and does not go through full experiment `modify`, so it
+will not rewrite traffic, variants, metrics, or other fields.
+
+```bash
+ae-cli experiment experiment update-group --project-id <id> --exp-id <exp-id> --group-id <group-id>
+ae-cli experiment experiment update-group --project-id <id> --exp-id <exp-id> --group-id 0 --dry-run
+```
+
+Flags:
+- `--project-id`, `-p`: Project ID.
+- `--exp-id`: Experiment ID.
+- `--group-id`: Target business group ID. Use `0` for ungrouped.
+
+Response shape: `data.result` is `true` when the update succeeds. Blank
+`--group-id` is normalized to `0` on the server.

package/skills/ae-experiment-design/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: ae-experiment-design
+description: "Design AE/TE A/B experiments from a business goal through a reviewable draft. Use when the user asks to form an experiment hypothesis, assess metric readiness, choose or create metrics and Features, design groups or traffic, estimate sample size or duration, create an experiment draft, or run readiness and conflict checks. SDK guidance is a conditional branch: enter it only when the user explicitly asks about an A/B experiment SDK, client SDK integration, experiment SDK code generation, or SDK troubleshooting; do not include SDK work in an ordinary experiment-design or draft-creation request."
+---
+
+# AE Experiment Design and Integration
+
+Turn a business objective into an evidence-backed experiment design, an implementation contract, and, when requested and supported, an AE experiment draft.
+
+## Hard boundaries
+
+- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, or application SDKs.
+- Do not infer an SDK request from the fact that an experiment needs implementation. Load SDK references only when the user explicitly asks about an A/B experiment SDK or client SDK integration.
+- Do not copy general tracking SDK documentation into this Skill. Route generic initialization, event reporting, `track`, user identity, user properties, data upload, LogBus, and REST questions to `ae-data-integration-helper` when that Skill is available.
+- Use only the event-metric calculation contracts defined in
+  `metric-readiness.md`. Bind one confirmed primary event metric and do not add
+  unsupported metric roles.
+- Never claim that a platform asset exists, was created, passed a check, or generated project code without a successful `ae-cli` response.
+- Never invent platform IDs, schemas, SDK APIs, versions, defaults, or behavior.
+
+## Progressive disclosure router
+
+Read only the references needed for the current request:
+
+| Request | Required references |
+|---|---|
+| Any AE/TE platform read or write | [`references/platform-operations.md`](references/platform-operations.md) |
+| Create or reuse an experiment draft | [`references/experiment-creation.md`](references/experiment-creation.md) and [`references/platform-operations.md`](references/platform-operations.md) |
+| Metric selection, feasibility, or creation | [`references/metric-readiness.md`](references/metric-readiness.md) |
+| Explicit A/B experiment SDK or client SDK integration request | [`references/sdk-integration.md`](references/sdk-integration.md) |
+| Exact SDK version, dependency, class, or source lookup | [`references/sdk-index.md`](references/sdk-index.md) |
+| Cross-platform Feature, default, fetch, cache, or assignment behavior | [`references/experiment-sdk-contract.md`](references/experiment-sdk-contract.md) |
+| Android, iOS, or JavaScript experiment SDK | [`references/client-experiment-sdk.md`](references/client-experiment-sdk.md) |
+| Server-side assignment or evaluation | [`references/server-experiment-sdk.md`](references/server-experiment-sdk.md) |
+| Server assignment with client rendering | [`references/hybrid-experiment-sdk.md`](references/hybrid-experiment-sdk.md) |
+| Exposure design, deduplication, or metric join | [`references/exposure-contract.md`](references/exposure-contract.md) |
+| SDK retrieval, default, identity, exposure, or debug issue | [`references/sdk-troubleshooting.md`](references/sdk-troubleshooting.md) |
+
+References are a curated fast path, not the whole documentation set.
+
+## Workflow
+
+### 1. Frame the decision
+
+Extract:
+
+- business goal and desired direction;
+- experiment variable and user-visible change;
+- target population and exclusions;
+- decision that the result must support;
+- success threshold.
+
+Convert these into a falsifiable hypothesis. Clarify only missing facts that materially change the design. For a conversion goal, establish the population, denominator or exposure behavior, numerator behavior, attribution window, and analysis unit.
+
+Do not silently invent a target population, conversion definition, or technical platform.
+
+### 2. Resolve the project and evidence
+
+Pass the project gate in `platform-operations.md`. With `ae-cli`, establish candidate exposure and outcome events, assignment identity and join path, timestamps, exact saved-metric definitions, and—when available—baseline and eligible traffic.
+
+If the project is unavailable, accept user-provided schemas or definitions and label all platform-dependent conclusions as unverified.
+
+### 3. Assess metric readiness
+
+Apply `metric-readiness.md`. Classify candidates as `recommended`, `available`,
+`blocked`, or `unverified`; recommend one primary event metric and confirm its
+calculation code before planning sample size or duration.
+
+### 4. Design Feature, assignment, and groups
+
+Define the Feature key, type, typed default, ownership, stable assignment unit, one control group, treatment groups, group values, traffic, allocations, layer, targeting, and exclusions.
+
+Require allocations totaling `1.0`, experiment traffic in `(0, 1]`, type-correct values, a stable exposure-to-outcome identity join, and at least one primary metric. Resolve real Features and layers with `ae-cli` before reuse or creation.
+
+### 5. Calculate sample size and duration
+
+Follow this order: confirm the primary metric and calculation code → obtain its
+baseline, MDE, and any required variance → calculate the sample target with
+[`scripts/calculate_experiment_plan.py`](scripts/calculate_experiment_plan.py)
+→ derive duration from the sample target and effective eligible daily units.
+Apply the preregistered planning policy in `metric-readiness.md`. Use fixed
+`alpha=0.05` and two-sided testing, policy-default `power=0.80`, and Bonferroni
+planning for multiple treatments. Require the MDE type and direction; never
+default MDE to 5% or assume variance for a continuous metric.
+
+When experiment traffic is already confirmed, calculate its duration. When it
+is not confirmed, obtain verified layer capacity and let the script recommend
+the smallest absolute traffic candidate that reaches the target within the
+maximum runtime. Default to at least seven days and full-week alignment. Return
+the actual infeasible duration instead of truncating it. Explain the baseline,
+MDE, power source, allocations, multiplicity rule, traffic evidence, sample
+targets, duration adjustment, and any native-report mismatch. Do not return a
+definitive plan when required evidence is unavailable.
+
+### 6. Materialize the design
+
+For an explicit draft-creation request, follow `experiment-creation.md` and `platform-operations.md`. Create only authorized draft assets, verify the saved result by reading it back, run supported readiness and conflict checks, and return the compact receipt and experiment link defined there.
+
+Submitting, starting, changing live traffic, pausing, ending, or deleting requires separate explicit confirmation. Never turn draft creation into launch.
+
+## Output requirements
+
+- Use the language explicitly requested by the user. Otherwise, use the language of the user's latest substantive message.
+- Localize all user-visible prose, including headings, table headers, field labels, status names, recommendations, warnings, assumptions, and next actions.
+- Keep code, commands, raw IDs, event/property/metric names, Feature keys, SDK/API names, and official enum values unchanged when translation would alter their technical meaning.
+- Treat section names in this Skill as semantic guidance, not literal output text. Do not copy an English heading into a non-English response.
+- For a design request, lead with the experiment recommendation. For a creation, validation, or conflict-check request, lead with the operation outcome.
+- Include only the smallest set of relevant sections; do not reproduce every workflow stage.
+- Separate observed platform evidence, verified documentation, deterministic calculations, design judgments, and unresolved assumptions.
+- Before responding, check every heading, table header, label, and status for unintended mixed-language output.
+
+Treat project resolution, metadata discovery, candidate-event searches, metric comparison, Feature and layer inventory, capability discovery, schema inspection, and command execution as internal working context.
+
+- Do not narrate the execution sequence in the final answer. Omit phrases such as "first load the reference", "now query in parallel", "verified with ae-cli", or "the evidence collection is complete".
+- Do not expose raw commands, capability IDs, request schemas, full candidate lists, or a platform-evidence dump unless the user explicitly asks for the evidence, audit trail, or debugging details.
+- Surface platform evidence only when it changes the design, blocks the operation, reveals a material semantic mismatch, or requires user confirmation. Summarize it in at most three concise bullets by default.
+- Do not repeat the full experiment design after a creation request unless the user explicitly asks for the complete design.
+- Do not expose hidden reasoning. Give the conclusion, the user-relevant basis, and the action result.
+
+## Failure behavior
+
+- Missing project or ambiguous host: show candidates and ask; do not guess.
+- Missing metadata: return the required event, property, identity, and timestamp checklist.
+- Experiment product unavailable:
+  - State that the project has not enabled the experiment product only when an
+    explicit platform entitlement result establishes that fact. A missing
+    capability alone means the experiment capability is unavailable, not that
+    the product was not purchased.
+  - For a design request, tell the user that experiment design can continue,
+    but Feature, layer, metric, and traffic details cannot be verified on the
+    platform. Continue with an offline design and request the baseline, MDE,
+    and eligible daily units when sample-size or duration planning needs them.
+  - For a draft-creation request, lead with the outcome that the experiment
+    draft was not created. Explain that Feature, layer, and draft creation are
+    blocked, preserve the proposed design, and say that platform creation and
+    readiness checks can continue after the product is enabled or the required
+    access is granted.
+- HTTP 403 or equivalent permission denial: state that the current account
+  lacks the required experiment permission, stop dependent writes, and explain
+  that this result does not establish whether the project purchased the
+  experiment product. Ask the project administrator to check both product
+  availability and the user's project permissions.
+- Capability gap without an explicit entitlement or permission result: report
+  that the current environment does not expose the required experiment
+  capability, continue with an offline design when useful, and do not bypass
+  `ae-cli`.
+- For SDK gaps or conflicts, follow `sdk-integration.md`; do not invent exact code.
+- Validation failure: correct documented input or ask for the missing value; do not retry unchanged input.
+- Partial success: report created and failed assets separately and never imply atomic success.

package/skills/ae-experiment-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Experiment Design & Integration"
+  short_description: "Design AE experiments with optional SDK guidance"
+  default_prompt: "Use $ae-experiment-design to design an A/B experiment and prepare an AE draft; include SDK guidance only when I explicitly request it."

package/skills/ae-experiment-design/references/client-experiment-sdk.md

@@ -0,0 +1,147 @@
+# Client Experiment SDK
+
+Read this reference for Android, iOS, or browser JavaScript experiment integration. Read `sdk-index.md` first and verify the current main document before producing production code.
+
+## Shared client model
+
+All three verified client pages describe the same model:
+
+- analytics SDK handles data collection;
+- Remote Config retrieves AE configuration;
+- experiment SDK provides typed Feature getters and exposure;
+- automatic exposure is enabled through `automaticExposureTracking`;
+- manual exposure is available when activation does not coincide with the getter;
+- a custom bucket map can override the default assignment subject;
+- custom fetch parameters can be attached to configuration requests;
+- an explicit fetch can refresh experiment information.
+
+## Android
+
+Verified document state: `TDExperiment` 1.0.1, updated 2026-07-24.
+
+Dependencies:
+
+- `TDAnalytics` >= 3.3.6
+- `TDRemoteConfig` >= 1.3.0
+- automatic package: `cn.thinkingdata.android:TDExperiment:1.0.1`
+
+Initialization order:
+
+```java
+TDAnalytics.init(context, "APP_ID", "https://YOUR_SERVER_URL");
+
+TDExperimentConfig config =
+    new TDExperimentConfig("APP_ID", "https://YOUR_SERVER_URL");
+config.automaticExposureTracking = true;
+TDExperiment.init(context, config);
+```
+
+Verified operations:
+
+```java
+TDExperiment.getValueAsString(key);
+TDExperiment.getValueAsDouble(key);
+TDExperiment.getValueAsBoolean(key);
+TDExperiment.getValueAsJson(key);
+TDExperiment.exposure(key);
+TDExperiment.fetch();
+TDExperiment.setCustomBucketId(bucketId);
+TDExperiment.setCustomFetchParams(params);
+```
+
+Use the initialization callback for first-fetch success or error. `TDExperiment.enableLog(true)` enables experiment logging.
+
+The verified page does not show typed-default overloads for Android getters. Keep an application-owned typed control default and verify whether a newer SDK adds overloads.
+
+## iOS
+
+Verified document state: `TDExperiment` 1.0.2, updated 2026-07-24.
+
+Dependencies:
+
+- `ThinkingSDK` >= 3.1.6
+- `TDRemoteConfig` >= 1.3.1
+- CocoaPods: `pod 'TDExperiment', '1.0.2'`
+- minimum deployment target shown by the experiment page: iOS 9.0
+
+Initialization order:
+
+```objective-c
+[TDAnalytics startAnalyticsWithAppId:@"APP_ID"
+                           serverUrl:@"https://YOUR_SERVER_URL"];
+
+TDExperimentConfig *config =
+    [[TDExperimentConfig alloc] initWithAppId:@"APP_ID"
+                                    serverUrl:@"https://YOUR_SERVER_URL"];
+config.automaticExposureTracking = YES;
+[TDExperiment startWithConfig:config];
+```
+
+Verified getters support no-argument defaults and explicit defaults:
+
+```objective-c
+[TDExperiment getValueAsString:key defaultValue:@"default"];
+[TDExperiment getValueAsNumber:key defaultValue:@0];
+[TDExperiment getValueAsBoolean:key defaultValue:NO];
+[TDExperiment getValueAsJson:key defaultValue:@{}];
+```
+
+Other verified operations:
+
+```objective-c
+[TDExperiment exposure:key];
+[TDExperiment fetch];
+[TDExperiment setCustomBucketId:bucketId];
+[TDExperiment setCustomFetchParams:params];
+```
+
+Use `TDExperimentTask` listeners for startup or fetch success and failure. `[TDExperiment enableLog:YES]` enables experiment logging.
+
+## JavaScript
+
+Verified document state: experiment package 1.0.0, updated 2026-07-24.
+
+Dependencies:
+
+- `TDAnalytics` >= 2.6.0
+- `TDRemoteconfig` >= 1.3.0
+- files shown by the page: `thinkingdata.umd.min.js`, `tdremoteconfig.umd.min.js`, `tdexperiment.umd.min.js`
+
+The page initializes analytics first and then the experiment global with:
+
+- `appId`
+- `serverUrl`
+- `automaticExposureTracking`
+- `customBucketId`
+- `customFetchParams`
+- `enableLog`
+- fetch success and failure callbacks
+
+The page shows typed getters, manual exposure, fetch, custom bucket ID, and custom fetch parameters.
+
+### Spelling gate
+
+The verified page spells the global object `TDExpriment`. Treat this as unresolved until the downloaded 1.0.0 package or a newer verified main document confirms the export. Do not silently change it, and do not publish exact JavaScript code based only on the page.
+
+## Remote Config companion behavior
+
+The verified Remote Config pages show:
+
+- local defaults when no remote value is available;
+- value order: remote, local default, then empty;
+- a successful-fetch update listener;
+- status information for strategies changed to `suspend` or `force_offline`;
+- debug/test mode polling every five seconds for test strategies;
+- test-device selection for client send testing.
+
+These are Remote Config behaviors. Do not imply that the experiment SDK itself polls every five seconds in production.
+
+## Client implementation checklist
+
+- Verify all three SDK versions together.
+- Initialize on the documented thread or lifecycle point.
+- Set assignment identity before first fetch or getter.
+- Use a typed control default.
+- Choose automatic or manual exposure, not both.
+- Freeze behavior when a mid-session update would cause flicker.
+- Test control, treatment, no-network, timeout, account switch, and stale-cache cases.

package/skills/ae-experiment-design/references/experiment-creation.md

@@ -0,0 +1,108 @@
+# Experiment Draft Creation
+
+Use this reference when the user asks to create, save, or reuse an A/B experiment draft.
+
+## Execution boundary
+
+- Perform every platform read or write through `ae-cli`.
+- Discover and inspect the current capability before constructing input.
+- Do not assume Feature, layer, metric, group, targeting, duration, or traffic fields before inspecting the current schema.
+
+## Creation contract gate
+
+Before writing a draft, establish the minimum semantic contract:
+
+1. verified project ID and host;
+2. experiment variable and the user-visible or system behavior that changes;
+3. experiment goal and one primary metric with an exact feasible definition;
+4. target population and material exclusions;
+5. stable assignment unit and identity join path;
+6. one control group and at least one treatment group, with typed Feature values and allocations totaling `1.0`;
+7. experiment traffic, targeting, and a resolved layer or explicit new-layer plan;
+8. Feature ownership, key, type, and typed default;
+9. when the draft requires a duration, a confirmed sample target and
+   formula-derived duration.
+
+Do not create a prose-only shell that leaves the experiment variable, group behavior, primary metric, target population, or assignment identity undefined. Ask one focused question at a time when a missing answer materially changes the draft.
+
+## Design heuristics are not platform facts
+
+Use these only as recommendations and verify that the identity exists and remains stable:
+
+- pre-login experience: usually `#distinct_id` or a stable device identity;
+- authenticated user experience: usually `#user_id`;
+- account-wide B2B behavior: an account identity;
+- device-specific rendering or performance: a device identity.
+
+Do not silently choose an assignment identity. Explain the material identity risk and obtain confirmation when more than one viable identity changes who receives a consistent experience.
+
+## Authorization gate
+
+A draft write is authorized when either condition holds:
+
+- the user reviewed the proposed design and then explicitly asked to create or confirmed creation; or
+- the user's current request explicitly says to create and already provides an exact, complete creation contract.
+
+If the design contains recommended or inferred choices that the user has not reviewed and those choices materially affect assignment, audience, behavior, metrics, or traffic, show a compact plan summary and ask for confirmation before writing.
+
+Do not ask for redundant confirmation when the user has already confirmed the unchanged plan. Design-only language is not authorization to create. Draft authorization never authorizes submit, start, live traffic changes, pause, end, or delete.
+
+## Resolution and idempotency
+
+Before creating assets:
+
+1. resolve the project;
+2. search for exact or likely duplicate experiment drafts;
+3. inspect any likely duplicate before deciding to reuse it;
+4. resolve the exact Feature, layer, and metrics;
+5. verify definitions, types, defaults, ownership, status, and remaining traffic;
+6. identify existing active or draft experiments that may interact with the same Feature, layer, audience, or identity.
+
+Reuse only an exact semantic match. Similar names are not enough. If an exact-match draft already exists, reuse it and report that outcome instead of creating a duplicate.
+
+An empty list is not proof of no conflict. Only a supported conflict check can justify a user-facing "no conflict" result.
+
+## Materialization sequence
+
+Use the inspected schemas and execute only the steps required for this design:
+
+1. create or reuse an exact metric when its definition is complete;
+2. create or reuse an inactive Feature with the correct type and default;
+3. create or reuse a compatible layer with verified assignment identity and sufficient traffic;
+4. assemble experiment name, falsifiable hypothesis, Feature bindings, groups, allocations, traffic, targeting, metrics, and any required schedule fields;
+5. validate or dry-run once when appropriate under `platform-operations.md`;
+6. save the experiment as a draft;
+7. read back the draft and verify its persisted fields;
+8. run supported readiness and conflict checks;
+9. return a concise creation receipt and experiment-detail link.
+
+Do not claim atomic success when supporting assets were created but the experiment save failed. Report created, reused, failed, and unresolved assets separately.
+Immediately before saving, revalidate the creation contract against the inspected schema and ensure no proposed ID is being presented as an existing platform ID.
+
+## Post-save verification
+
+A successful write response is not sufficient by itself. Read back the saved or reused draft and verify, when returned by the platform:
+
+- actual experiment ID and name;
+- project ID;
+- draft status;
+- Feature and layer bindings;
+- group names, values, and allocations;
+- experiment traffic and targeting;
+- primary event metric and calculation code.
+
+Run readiness and conflict checks only when supported. Report each check separately and do not translate "not run" into "passed".
+
+## User-visible completion
+
+Return an operation receipt, not the discovery log. Include:
+
+- created, reused, partially completed, blocked, or failed;
+- experiment name, actual ID, and draft status;
+- control and treatment values and allocations;
+- experiment traffic and primary metric;
+- readiness and conflict results that actually ran;
+- at most three material blockers or semantic risks;
+- the clickable experiment-detail link required by `SKILL.md`.
+
+Do not expose raw candidate lists, capability discovery, request schemas, commands, or internal execution narration unless the user explicitly asks for an audit or debugging view.