@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-engage/references/flow-metric-update.md

@@ -32,13 +32,127 @@ The backend uses a clean-and-insert update model: omitted existing metric settin
   - `ab_test`
 - Preserve first-level group keys exactly. Do not convert `ab_test` to `abTest`.
 - Each group value is an array of Hermes metric DTO objects.
-- Use DTO field names from `HermesMetricReqDTO`: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `displayName`, `orderId`, `note`, and `metricParams`.
+- Use DTO field names from `HermesMetricReqDTO`: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `timeCycleDef`, `displayName`, `orderId`, `note`, and `metricParams`.
 - The CLI boundary accepts snake_case nested DTO fields too, but prefer the native camelCase names above in examples and generated payloads.
 - For existing bindings, include `metricSettingId` so Hermes updates that binding instead of treating it as a new binding.
 - For preset metrics, use `metricType: 1` and a real `metricName` discovered from `engage-setting common-metric list/get`.
 - For custom metrics, use `metricType: 2` plus a complete `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, and `displayName`; Hermes creates the custom metric name.
 - Do not invent metric names, event names, property names, QP structures, or metric-setting IDs. Read the existing flow detail and available metric definitions first, then update the complete desired metric map.
 
+Create/save the flow first and obtain its logical `flow_id`, then configure effect metrics with this command. Do not put the global `metric_map` in the flow-save request.
+
+## Custom metric window semantics
+
+Choose the window from the user's intent, not from the number alone:
+
+| User intent | `metricWindowNum` | `metricWindowTimeUnit` | `timeCycleDef` |
+| --- | --- | --- | --- |
+| One day / 24 hours / rolling one day | `1` | `"day"` | Omit |
+| Until the end of the attribution event's calendar day | `1` | `"day"` | `{"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar week | `1` | `"week"` | `{"startDay":1,"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar month | `1` | `"month"` | `{"startDay":1}` |
+
+`timeCycleDef` selects a natural calendar attribution window. The attribution event (such as a trigger, delivery, or click, according to the metric group) anchors the window; conversions must occur after that event and before the next configured cycle boundary. The boundary is exclusive. `1` + `day` alone remains a rolling one-day window. Resolve calendar boundaries in the flow's configured timezone (`tzOffset`), falling back to the backend default when absent. The report display timezone does not redefine the cycle.
+
+For example, with Monday at midnight as the week boundary, a Wednesday 15:00 attribution event counts subsequent conversions before the following Monday 00:00. It does not count Monday or Tuesday conversions before that event. With midnight as the day boundary, a 23:00 attribution event has only the remainder of that day, rather than 24 hours.
+
+Interpret "today", "this week", or "this month" as these windows only when the user means the attribution event's day, week, or month. A request to view results for the current reporting period belongs to report date filters and does not by itself authorize changing metric configuration.
+
+Treat an unqualified "one day" as the existing rolling window. Use midnight, Monday, and the first day of the month for the calendar defaults above. Honor an explicitly requested valid cycle start. "Daily", "weekly", and "monthly" can describe task execution frequency: resolve the context and ask for clarification only when the metric window intent remains ambiguous.
+
+Natural window constraints:
+
+- `metricWindowNum` must be `1`; the unit must be `day`, `week`, or `month`.
+- Day: require `startTime` in 24-hour `HH:mm`; omit `startDay`.
+- Week: require `startDay` from `1` (Monday) to `7` (Sunday) and `startTime` in `HH:mm`.
+- Month: require `startDay` from `1` to `28`; omit `startTime` or use `"00:00"`.
+- An empty `timeCycleDef: {}` is invalid. Without `timeCycleDef`, only rolling `minute`, `hour`, and `day` units are accepted.
+- When switching rolling to calendar, add the matching `timeCycleDef` and set the number/unit together. When switching back, remove `timeCycleDef` entirely and use a valid rolling unit. Preserve the binding's `metricSettingId` and all other desired metrics.
+- These options apply to custom metrics (`metricType: 2`) through `metric update`. Do not use `engage-setting common-metric create/update` to create natural windows.
+- Task support requires a backend deployment containing the task natural-window feature. Do not silently replace an unsupported calendar window with a rolling duration.
+
+### Custom metric payload examples
+
+Each JSON block is a complete illustrative `--metric-map` value for a configuration containing only that metric. The `purchase` event and QP below are examples, not discovered project metadata: substitute a verified project metric QP (as a JSON string) before use. For an existing configuration, merge the chosen metric into the complete current map and preserve existing binding IDs; do not submit these single-metric examples over other configured metrics.
+
+Rolling one day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Rolling one day",
+      "orderId": 1
+    }
+  ]
+}
+```
+
+Current calendar day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Current calendar day",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar week:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "week",
+      "displayName": "Purchase - Current calendar week",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1,
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar month:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "month",
+      "displayName": "Purchase - Current calendar month",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1
+      }
+    }
+  ]
+}
+```
+
 ## Examples
 
 Dry-run updating an existing binding:

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

@@ -30,6 +30,9 @@ You still organize user requirements into an intermediate intent first, then map
 
 ---
 
+The current `build` / `preview` / `commit` API does not expose `completionIndicators`.
+Completion-goal editing requires the web editor; CLI JSON passthrough does not add support.
+
 ## 2. Workflow
 
 1. Identify the flow intent from the user input and produce a unified intent JSON.

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

@@ -4,6 +4,8 @@ Create or update a Hermes task draft.
 
 Mapped command: `ae-cli engage-task task save`
 
+To configure custom effect metrics after saving (including rolling or current calendar day/week/month windows), use [Task metric update](task-metric-update.md). Do not embed the global metric map in this save request.
+
 This command is the final write step. Do not use it as the first step in task construction.
 
 Recommended workflow:
@@ -437,6 +439,25 @@ For a main goal (`completionIndicatorType=0`), always include `touch_cycle_num`
 `touch_cycle_num=1` and `touch_cycle_num_unit="day"`. Static Capability validation may accept a
 main goal without these fields, but the Hermes save service rejects it.
 
+### Natural completion-goal windows
+
+Set these fields on `req.controlConfig.completionIndicatorDef.completionIndicators[]`,
+alongside `completionIndicatorType` and the semantic `eventDefinition`:
+
+| Window | `touch_cycle_num` | `touch_cycle_num_unit` | `timeCycleDef` |
+| --- | --- | --- | --- |
+| Current day | 1 | `day` | `{"startTime":"00:00"}` |
+| Current week | 1 | `week` | `{"startDay":1,"startTime":"00:00"}` |
+| Current month | 1 | `month` | `{"startDay":1}` |
+
+Custom day/week times use `HH:mm`. Week `startDay` is 1 (Monday) through 7 (Sunday);
+month `startDay` is 1 through 28. Day windows omit `startDay`; month windows omit
+`startTime` or use `00:00`. Natural windows require count 1 and a nonempty `timeCycleDef`.
+Boundaries use the task timezone; conversions must follow attribution and precede the next boundary.
+
+To return to a rolling window, remove `timeCycleDef` and set a valid `minute`, `hour`,
+or `day` count/unit. Without `timeCycleDef`, `1` + `day` remains a rolling one-day window.
+
 Important constraints that still apply:
 
 - `doNotDisturb.enableDoNotDisturb=true` requires `startTime` and `endTime` in `HH:mm`

package/skills/ae-engage/references/task-metric-update.md

@@ -0,0 +1,151 @@
+# Task metric update
+
+Use this reference to configure, add, or replace effect metric settings for an operation task.
+
+Mapped CLI command: `ae-cli engage-task metric update`
+
+Mapped capability: `engage-task.metric.update`
+
+## Required input
+
+- `--project-id`
+- `--task-id`
+- `--metric-map '<metric_map_json>'`
+
+## Workflow and parameter guidance
+
+1. Create/save the task first and obtain its `task_id`. The task-save request does not configure global effect metrics through `metricMap`.
+2. Read task details with `ae-cli engage-task task get --project-id <project_id> --task-id <task_id>` and use the grouped `metric_map` as the update baseline. `metric list` returns a flat list without group membership, so it cannot reconstruct this map. If the grouped configuration is unavailable, do not guess groups or treat the flat list as an empty configuration.
+3. Build the complete desired `metric_map`. This is a clean-and-insert update: omitted settings may be deleted, so preserve each binding's original group, all other desired metrics, and existing `metricSettingId` values. Select the binding to change by its setting ID, not by its display name.
+4. Use `--dry-run` on the assembled request before applying the explicitly requested configuration change. After applying, read task details again and compare the groups, binding IDs, and window fields with the intended configuration.
+
+`metric_map` is an object with target-user group keys `trigger`, `view`, and `click`, each containing an array of Hermes metric DTOs. Use native camelCase DTO fields: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `timeCycleDef`, `displayName`, `orderId`, `note`, and `metricParams`. Nested snake_case fields are also accepted at the CLI boundary.
+
+For a custom metric use `metricType: 2`, a complete verified `metricQp` JSON string, the window fields, `displayName`, and `orderId`; Hermes creates the custom metric name. For preset metrics use `metricType: 1` and a real `metricName` from `engage-setting common-metric list/get`. Do not invent event names, metric names, QP structures, or binding IDs. Both custom and preset bindings require `displayName` and `orderId`. Do not use `metricId` in place of `metricSettingId`.
+
+```bash
+ae-cli --dry-run engage-task metric update \
+  --project-id <project_id> \
+  --task-id <task_id> \
+  --metric-map '<complete_metric_map_json>'
+```
+
+Replace the placeholders with discovered IDs and the complete desired JSON map. Apply the same command without `--dry-run` only for an authorized configuration change.
+
+## Custom metric window semantics
+
+Choose the window from the user's intent, not from the number alone:
+
+| User intent | `metricWindowNum` | `metricWindowTimeUnit` | `timeCycleDef` |
+| --- | --- | --- | --- |
+| One day / 24 hours / rolling one day | `1` | `"day"` | Omit |
+| Until the end of the attribution event's calendar day | `1` | `"day"` | `{"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar week | `1` | `"week"` | `{"startDay":1,"startTime":"00:00"}` |
+| Until the end of the attribution event's calendar month | `1` | `"month"` | `{"startDay":1}` |
+
+`timeCycleDef` selects a natural calendar attribution window. The attribution event (such as a trigger, delivery, or click, according to the metric group) anchors the window; conversions must occur after that event and before the next configured cycle boundary. The boundary is exclusive. `1` + `day` alone remains a rolling one-day window. Resolve calendar boundaries in the task's configured timezone (`tzOffset`), falling back to the backend default when absent. The report display timezone does not redefine the cycle.
+
+For example, with Monday at midnight as the week boundary, a Wednesday 15:00 attribution event counts subsequent conversions before the following Monday 00:00. It does not count Monday or Tuesday conversions before that event. With midnight as the day boundary, a 23:00 attribution event has only the remainder of that day, rather than 24 hours.
+
+Interpret "today", "this week", or "this month" as these windows only when the user means the attribution event's day, week, or month. A request to view results for the current reporting period belongs to report date filters and does not by itself authorize changing metric configuration.
+
+Treat an unqualified "one day" as the existing rolling window. Use midnight, Monday, and the first day of the month for the calendar defaults above. Honor an explicitly requested valid cycle start. "Daily", "weekly", and "monthly" can describe task execution frequency: resolve the context and ask for clarification only when the metric window intent remains ambiguous.
+
+Natural window constraints:
+
+- `metricWindowNum` must be `1`; the unit must be `day`, `week`, or `month`.
+- Day: require `startTime` in 24-hour `HH:mm`; omit `startDay`.
+- Week: require `startDay` from `1` (Monday) to `7` (Sunday) and `startTime` in `HH:mm`.
+- Month: require `startDay` from `1` to `28`; omit `startTime` or use `"00:00"`.
+- An empty `timeCycleDef: {}` is invalid. Without `timeCycleDef`, only rolling `minute`, `hour`, and `day` units are accepted.
+- When switching rolling to calendar, add the matching `timeCycleDef` and set the number/unit together. When switching back, remove `timeCycleDef` entirely and use a valid rolling unit. Preserve the binding's `metricSettingId` and all other desired metrics.
+- These options apply to custom metrics (`metricType: 2`) through `metric update`. Do not use `engage-setting common-metric create/update` to create natural windows.
+- Task support requires a backend deployment containing the task natural-window feature. Do not silently replace an unsupported calendar window with a rolling duration.
+
+### Custom metric payload examples
+
+Each JSON block is a complete illustrative `--metric-map` value for a configuration containing only that metric. The `purchase` event and QP below are examples, not discovered project metadata: substitute a verified project metric QP (as a JSON string) before use. For an existing configuration, merge the chosen metric into the complete current map and preserve existing binding IDs; do not submit these single-metric examples over other configured metrics.
+
+Rolling one day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Rolling one day",
+      "orderId": 1
+    }
+  ]
+}
+```
+
+Current calendar day:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "day",
+      "displayName": "Purchase - Current calendar day",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar week:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "week",
+      "displayName": "Purchase - Current calendar week",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1,
+        "startTime": "00:00"
+      }
+    }
+  ]
+}
+```
+
+Current calendar month:
+
+```json
+{
+  "trigger": [
+    {
+      "metricType": 2,
+      "metricQp": "{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}",
+      "metricWindowNum": 1,
+      "metricWindowTimeUnit": "month",
+      "displayName": "Purchase - Current calendar month",
+      "orderId": 1,
+      "timeCycleDef": {
+        "startDay": 1
+      }
+    }
+  ]
+}
+```
+
+## Related interfaces
+
+- [Task save](save-task.md): create or update the task draft before configuring effect metrics.
+- [Flow metric update](flow-metric-update.md): the equivalent flow canvas configuration.
+- [Task metric detail](task-metric-detail.md): query metric reports; this is separate from configuration.

package/skills/ae-experiment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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"
+version: 1.0.2
+description: "Use when managing Atlas AB or external experiments, traffic layers, Features, metrics, buckets, and experiment reports through ae-cli"
 ---
 
 # ae-experiment
@@ -61,10 +61,11 @@ Naming and response boundary:
    - `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`.
+4. For an external experiment, use `experiment external-experiment save-submit` instead. It submits directly and does not use Features, traffic layers, allocation, targeting, or experiment cycles.
+5. Check readiness with `experiment experiment ready-check`.
+6. For a non-mutex traffic layer, run `experiment experiment conflict-check` before submit (needs `feature_key_list` from context or `experiment get`).
+7. Move status with `experiment experiment manage`.
+8. 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.
 
@@ -98,10 +99,16 @@ Read [`save_build_guide.md`](references/save_build_guide.md) and
 
 ### 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`
+`experiment experiment save`, `experiment experiment update-metrics`, `experiment external-experiment save-submit`, `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.
 
+### External Experiment
+
+`experiment external-experiment save-submit`
+
+Read [`save_submit_external_experiment.md`](references/save_submit_external_experiment.md) before creating or updating an external experiment.
+
 ### Traffic Layer and Buckets
 
 `experiment traffic-layer save`, `experiment traffic-layer get`, `experiment traffic-layer list`, `experiment traffic-layer batch-delete`, `experiment bucket list`

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

@@ -0,0 +1,52 @@
+# experiment external-experiment save-submit
+
+Create or update and submit an external experiment. This is the typed L2 wrapper for
+`experiment.experiment.save-submit`; it always sends `expType: "external"`.
+
+```bash
+ae-cli experiment external-experiment save-submit \
+  --project-id 1 \
+  --exp-name "Partner onboarding test" \
+  --bucket-id "#user_id" \
+  --start-time "2026-09-01T00:00:00+08:00" \
+  --end-time "2026-09-15T00:00:00+08:00" \
+  --supposition "The new onboarding improves activation." \
+  --groups '[{"expGroupName":"control","isControl":1},{"expGroupName":"variant","isControl":0}]' \
+  --metrics '[{"metricId":"activation_rate","metricRole":"primary"}]' \
+  --dry-run
+```
+
+`--dry-run` validates the external submit shape without persisting: required
+time bounds, Feature-only fields that are forbidden here, group shape, and
+primary metric presence. The final submit also checks that metric IDs exist and
+that each metric event supports the selected bucket property.
+
+External experiments are evaluated from exposure events reported by the caller. They
+do not configure Features, traffic layers, allocation, targeting, or `expCycle`.
+Choose an existing `bucket_id` whose property is available in the events used by every
+bound metric. The server requires at least two named groups, exactly one control group,
+and at least one existing primary metric.
+
+Status is calculated from the submitted time range: a future start time becomes
+`pending`, a current range becomes `running`, and an elapsed end time becomes `ended`.
+No `end_time` creates a long-running experiment. When the scheduled job is active, a
+pending experiment enters `running` at its start time and a running experiment enters
+`ended` at its end time. `experiment experiment manage` permits only
+`pending → running`, `running → ended`, and `ended → archive`; manually entering
+`running` or `ended` replaces the corresponding time boundary with the current time.
+
+For an update, first call `experiment experiment get`. An already submitted external
+experiment can be updated only while `pending` or `running`; its hypothesis and time
+range may change, and group descriptions may change. Keep its name, business group,
+description, bucket, metric bindings, group count, group names, control markers,
+allocations, and group values unchanged. Include every returned group unchanged,
+including its `expGroupId`, `allocation`, and `expGroupValue`; the CLI rejects an
+update that omits a group ID. Omitting `--end-time` represents a long-running
+experiment, so preserve the current end time whenever it should remain scheduled.
+
+Transition status: L2
+Owning module: Hermes Atlas experiment capability gateway
+Current transport: Capability Gateway `experiment.experiment.save-submit`
+Gateway target: `experiment.experiment.save-submit`
+Review after: 2027-02-28
+Exit condition: Remove this wrapper if the Gateway exposes a dedicated external-experiment capability or the typed fields no longer match the Atlas external-experiment contract.

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Design AE 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
@@ -9,7 +9,7 @@ Turn a business objective into an evidence-backed experiment design, an implemen
 
 ## Hard boundaries
 
-- Use `ae-cli` for every AE/TE platform interaction. Do not substitute raw HTTP, browser automation, direct database queries, or application SDKs.
+- Use `ae-cli` for every AE 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
@@ -24,7 +24,7 @@ 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) |
+| Any AE 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) |

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

@@ -1,6 +1,6 @@
 # Platform Operations
 
-Read this reference before any AE/TE platform interaction.
+Read this reference before any AE platform interaction.
 
 ## Hard boundary
 

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

@@ -1,6 +1,6 @@
 ---
 name: ae-experiment-insight
-description: "Diagnose and interpret AE/TE A/B experiments from configuration and report evidence through a defensible decision. Use when the user asks what an experiment means, whether it can roll out, why a result is not significant, why group sizes or exposure are wrong, why treatment results conflict, whether the report is trustworthy, or what to do next. Covers SRM, duration sufficiency, novelty effects, metric conflicts, missing or anomalous data, design reasonableness, data reliability, metric interpretation, trend and segment analysis, root-cause hypotheses, and rollout recommendations. All platform discovery and reads must use ae-cli."
+description: "Diagnose and interpret AE A/B experiments from configuration and report evidence through a defensible decision. Use when the user asks what an experiment means, whether it can roll out, why a result is not significant, why group sizes or exposure are wrong, why treatment results conflict, whether the report is trustworthy, or what to do next. Covers SRM, duration sufficiency, novelty effects, metric conflicts, missing or anomalous data, design reasonableness, data reliability, metric interpretation, trend and segment analysis, root-cause hypotheses, and rollout recommendations. All platform discovery and reads must use ae-cli."
 ---
 
 # AE Experiment Insight and Diagnosis
@@ -9,7 +9,7 @@ Validate the evidence before interpreting the effect. Produce a decision only wh
 
 ## Platform and reference routing
 
-Use `ae-cli` for every AE/TE platform interaction and follow
+Use `ae-cli` for every AE platform interaction and follow
 [`references/platform-operations.md`](references/platform-operations.md);
 never substitute another platform access path.
 

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

@@ -1,6 +1,6 @@
 # Platform Operations
 
-Read this reference before retrieving any AE/TE experiment evidence.
+Read this reference before retrieving any AE experiment evidence.
 
 ## Hard boundary
 

package/skills/ae-generate-tracking-code/SKILL.md

@@ -299,6 +299,7 @@ From the plan file, read:
 - `meta.client_sdk_type` — client SDK type (if `client_only` or `both`)
 - `meta.server_language` — server language (if `server_only` or `both`)
 - `meta.user_identity` — user identity config (used to generate `login()` / `identify()` calls)
+- `user_properties` — user property pool (each entry's `name` + `update_type`, used to generate `user_set` / `user_setOnce` / `user_add` calls)
 
 **Determine list of platforms to generate code for**:
 ```
@@ -639,7 +640,7 @@ Validation steps:
 ### After validation passes
 
 - Remind user to commit changes (if any `insert` was used)
-- Remind user to call `login()` / `identify()` in code to associate user IDs
+- Remind user to call `login()` / `identify()` (associate user IDs) and `user_set` / `user_setOnce` / `user_add` (set user properties) at the right business moments
 - Remind user to copy daemon.json to LogBus2 conf/ directory
 
 ### Validation failure

package/skills/ae-generate-tracking-code/references/client-sdk-insert.md

@@ -111,7 +111,7 @@ Wait for user confirmation, then proceed to Stage 1.
 
 ## User Properties
 - File: <path>:<line>
-- user_set / user_setOnce / user_add
+- user_set / user_setOnce / user_add / user_append
 
 ## Event Group: <tag>
 - <event_name>: <file>:<line> [Business action: <business meaning>]

package/skills/ae-generate-tracking-code/references/datax-config.md

@@ -1,6 +1,6 @@
 # Mode D — DataX job.json
 
-> **Terminology**: 数据源类型 = data source type | 连接信息 = connection info | 库表名 = database/table name | 查询条件 = query condition | reader 插件 = reader plugin | columnMapping = column-to-property mapping | push_url = TE receiver URL
+> **Terminology**: 数据源类型 = data source type | 连接信息 = connection info | 库表名 = database/table name | 查询条件 = query condition | reader 插件 = reader plugin | columnMapping = column-to-property mapping | push_url = AE receiver URL
 
 ## Ask User
 1. Data source type (MySQL / Oracle / PostgreSQL / OSS / HDFS / Other)

package/skills/ae-generate-tracking-code/references/logbus-config.md

@@ -1,6 +1,6 @@
 # LogBus2 Configuration Generation
 
-> **Terminology**: LogBus2 = log sync tool (Go-based, v2) | LoggerConsumer = writes events to local log files | 日志同步工具 = log sync tool | daemon.json = LogBus2 config file | push_url = TE receiver/data ingestion URL | app_id = AE project APP_ID | file_patterns = glob patterns for log files | unit_remove = file deletion unit (day/hour) | offset_remove = file deletion offset | 重命名 = rename (causes re-upload) | runtime 目录 = runtime directory (stores progress snapshots) | JSON line = JSONL format (one JSON per line)
+> **Terminology**: LogBus2 = log sync tool (Go-based, v2) | LoggerConsumer = writes events to local log files | 日志同步工具 = log sync tool | daemon.json = LogBus2 config file | push_url = AE receiver/data ingestion URL | app_id = AE project APP_ID | file_patterns = glob patterns for log files | unit_remove = file deletion unit (day/hour) | offset_remove = file deletion offset | 重命名 = rename (causes re-upload) | runtime 目录 = runtime directory (stores progress snapshots) | JSON line = JSONL format (one JSON per line)
 
 LogBus2 is AE's official log sync tool, used together with LoggerConsumer (server-side SDK).
 

package/skills/ae-generate-tracking-code/references/modes.md

@@ -18,7 +18,7 @@ Server-side always gets the following regardless of `insert` or `snippet`:
 | Deliverable | Description |
 |---|---|
 | LoggerConsumer code | Server SDK writes to local log files |
-| `.ae-cli/output/daemon.json` | LogBus2 config (reads logs and uploads to TE) |
+| `.ae-cli/output/daemon.json` | LogBus2 config (reads logs and uploads to AE) |
 
 **Note: LogBus v1 is deprecated. Use LogBus2 for all scenarios.**
 

package/skills/ae-generate-tracking-code/references/server-sdk-insert.md

@@ -1,6 +1,6 @@
 # Server-side Code Insertion (LoggerConsumer + LogBus2)
 
-> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to TE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 依赖管理 = dependency management
+> **Terminology**: 服务端 SDK = server-side SDK | 代码插入 = code insertion/injection | LoggerConsumer = writes events to local log files (recommended for production) | LogBus2 = log sync tool that reads local logs and uploads to AE | 架构 = architecture | 异步上报 = async upload | 批量上传 = batch upload | 重试策略 = retry strategy | 公共属性 = super property (公共事件属性; never "超级属性") | 用户属性 = user property | 依赖管理 = dependency management
 
 ## Architecture
 
@@ -91,7 +91,7 @@ Wait for user confirmation, then proceed to Stage 1.
 
 ## User Properties
 - File: <path>:<line>
-- user_set / user_setOnce / user_add
+- user_set / user_setOnce / user_add / user_append
 
 ## Event Group: <tag>
 - <event_name>: <file>:<symbol> or SKIP (already present)
@@ -120,9 +120,9 @@ Insertion point: entry file static block / start of main function
 
 ### Batch 2: Super Properties + User Properties
 
-Generate based on `meta.user_identity`:
-- `user_set` / `user_setOnce`: user property upload
-- `login()` call: on user login
+Generate:
+- `user_set` / `user_setOnce` / `user_add` / `user_append`: user property upload, based on `draft.user_properties[]` (each entry's `name` + `update_type`)
+- `login()` call: on user login, based on `meta.user_identity`
 
 ### Batch 3..N: Events grouped by event_tag
 

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -69,7 +69,7 @@ You must call the corresponding API to **enable** them after or during initializ
 
 ```<lang>
 // Call after user login
-<user_set / user_setOnce code>
+<user_set / user_setOnce / user_add / user_append code>
 ```
 ```
 
@@ -161,7 +161,7 @@ Show each event individually, each as its own block for easy copying.
 <setSuperProperties code>
 
 // ==================== User Properties ====================
-<user_set code>
+<user_set / user_setOnce / user_add / user_append code>
 
 // ==================== Event Group: <tag> ====================
 // <event_name> - <event_desc>
@@ -280,7 +280,7 @@ If upload succeeds, report that the files are available from the file/attachment
    - **Integrate SDK** section (npm package name / CDN URL / integration methods)
    - **Initialization** section (init API signature and example code)
    - **Track** section (event upload API and examples)
-   - **User Properties** section (user_set / user_setOnce / user_add API)
+   - **User Properties** section (user_set / user_setOnce / user_add / user_append API)
 
 3. **⚠️ Do not skip Step 0** — even if you've generated code for the same platform before, must re-read latest docs every time