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

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-analysis/references/user_tag_create.md

@@ -6,7 +6,7 @@ Do not use it for uploaded-ID tags; use `user-tag create-id`. A successful creat
 
 The response reports this directly: `computation.triggered_automatically=true`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow `next_action`; when it is `poll_get`, invoke `next_capability_id` with the exact `next_input` returned by the command.
 
-Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The tag type comes from `definition_request.type`.
+Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type`.
 
 `tag_name` is a machine identifier: 1-80 characters, starts with a letter, and contains only letters, digits, or underscores. `display_name` is 1-80 characters. The CLI rejects violations before dispatch.
 
@@ -23,3 +23,25 @@ First/last tag for this month:
 ```bash
 ae-cli analysis user-tag create --project-id <project_id> --tag-name latest_platform_this_month --display-name "Latest Platform This Month" --definition-request '{"type":"first_last","first_last":{"event":"login","occurrence":"last","property":"platform","time_range":{"mode":"recent","unit":"month","value":1}}}'
 ```
+
+Periodic refresh can be configured in this same create operation. It is separate from the initial computation. Omitted scheduling flags leave periodic refresh disabled; supplying a schedule enables it. `--enable-auto-refresh true` requires a schedule on create. Do not combine `--enable-auto-refresh false` with a schedule, or pass both schedule forms.
+
+Append one of these options to the create command:
+
+```bash
+# Every day at 02:30 in the tag timezone
+--auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Monday and Sunday at 09:00 (ISO weekdays: 1=Monday, 7=Sunday)
+--auto-refresh-schedule '{"frequency":"weekly","time":"09:00","weekdays":[1,7]}'
+
+# The 1st and 15th of each month at 06:00
+--auto-refresh-schedule '{"frequency":"monthly","time":"06:00","month_days":[1,15]}'
+
+# Custom Quartz schedule, including multiple executions per day
+--auto-refresh-cron '0 0/30 8-18 * * ? *'
+```
+
+`time` uses 24-hour `HH:mm`. `month_days` accepts 1-31; dates absent from a month are skipped. Weekly/monthly schedules require their respective day array; other frequencies reject those fields. The structured form preserves the page's daily/weekly/monthly frequency selection. Cron uses the page's custom schedule mode and preserves every cron field.
+
+Schedules use the tag timezone. Use the existing `--zone-offset` only with an offset supported by the project; omit it to use the project's default behavior. Inspect `user-tag get` for `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset` after creation.

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

@@ -24,12 +24,20 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+
+Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
 ```json
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Percentile example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+```
+
 ## First/last tag
 
 Required: `event`, `occurrence=first|last`, and exactly one value source: `calculation` or `property`. `time_range` and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Supplying neither or both value sources is rejected before execution. Use the semantic time mappings in [`audience_models.md`](audience_models.md) for dynamic ranges such as today, this month, or a fixed start date through today.

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

@@ -2,11 +2,11 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
 
 The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
-Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `tag_name` is an existing exact identifier and cannot be renamed by update.
 
@@ -17,3 +17,15 @@ ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level
 
 ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-cron '0 30 2 * * ? *'
 ```
+
+Omitting scheduling flags preserves the existing enable state and schedule, including during a definition update. Omitting `--zone-offset` preserves the saved tag timezone. `--enable-auto-refresh true` can reuse an existing saved plan; if none exists, provide a new schedule. `--enable-auto-refresh false` disables periodic refresh. Do not combine false with a schedule or pass both schedule forms. Structured schedule fields and timezone rules are described in [user_tag_create.md](user_tag_create.md).
+
+```bash
+# Enable daily refresh in one update
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Disable periodic refresh
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --enable-auto-refresh false
+```
+
+Read `user-tag get` after updating to verify `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset`. Schedule-only updates return `computation.status=not_triggered` and `next_action=none`.

package/skills/ae-data-integration/SKILL.md

@@ -36,6 +36,7 @@ Use this skill when the user wants to bring a **local data file** (CSV/TSV/TXT/J
 | Generate / upload a project-level tracking plan (source material is PRD / chat / template / code; deliverable is a real platform tracking plan) | ae-generate-tracking-plan |
 | Upload documents / URLs to a knowledge base | ae-kb |
 | Reports / dashboards / queries / governance on data already in AE | ae-analysis |
+| Dimension / dictionary data (a stable-entity lookup — city / product / device) to load as a dimension table bound to a property | ae-metadata |
 
 This skill also produces a tracking-plan draft (`source_type: data`) as a governance prerequisite; that draft is an input to ae-generate-tracking-plan, not a substitute for its five-phase platform plan.
 
@@ -43,7 +44,7 @@ This skill also produces a tracking-plan draft (`source_type: data`) as a govern
 
 Walk the four submodules in order. Each submodule is its own reference; follow it and come back here for the next step.
 
-1. **Source — business identification.** Read [references/source-inspect.md](references/source-inspect.md). Profile every file fully, infer its business meaning using business-doc / user-prompt priors, then pick a branch via [references/ue-routing.md](references/ue-routing.md).
+1. **Source — business identification.** Read [references/source-inspect.md](references/source-inspect.md). Profile every file fully, infer its business meaning using business-doc / user-prompt priors, then pick a branch via [references/ue-routing.md](references/ue-routing.md): UE ingestion, dimension routing ([references/dimension-routing.md](references/dimension-routing.md)), or local analysis.
 2. **Reuse check.** If the profile is `ue_eligible`, read [references/reuse.md](references/reuse.md) and match the recommended mapping against the handoff index. `reuse` searches the current directory's `.ae-cli/data-integration/` upward, then `~/.ae-cli/data-integration/`, so a package written elsewhere is still found. A match proposes a frozen package; after one explicit confirmation, run the returned `transform.mjs` command and jump to Sink (step 5). No match → continue.
 3. **Tracking plan.** Read [references/tracking-plan.md](references/tracking-plan.md). The plan is generated from the mapping (`plan --mapping`), so confirm the recommended mapping's key system fields with the user first — `mode`, `#account_id`/`#distinct_id`, `#time` + timezone, `#event_name`, `#ip`/`#uuid` (see [references/transform.md](references/transform.md) steps 1–5) — then generate the event/property plan and get a single explicit confirmation from the user before touching data. The plan is a separate, required deliverable from the transform mapping: a user who supplies a column→field mapping directly has **not** completed this step, so build the plan from the confirmed mapping anyway. `user_set` still requires a plan (no events; every property becomes a user property). This step runs for **every** file: a second or later file merges its new events and properties into the existing project plan (tracking-plan.md step 4) — an existing plan is never a reason to skip it.
 4. **Transform.** Read [references/transform.md](references/transform.md). Map columns to AE system fields and properties, convert, and quarantine dirty rows per [references/ue-mapping.md](references/ue-mapping.md).

package/skills/ae-data-integration/references/dimension-routing.md

@@ -0,0 +1,36 @@
+# Dimension routing
+
+Use this reference after [ue-routing.md](ue-routing.md) has classified the file as dimension data — a stable-entity lookup with no row-level identity or event time. It covers the handoff to ae-metadata; this skill does not ingest dimension data itself.
+
+## What dimension data is
+
+Judge by content, never by file extension — CSV / TSV / TXT / JSON / JSONL / XLS / XLSX can all be dimension data. The classification signals live in [ue-routing.md](ue-routing.md): no row-level identity, no row-level event time, finite entity enumeration, and a join key shared with event data.
+
+Dimension data is not the only file that fails UE prerequisites. Aggregates, pivot tables, and cumulative snapshots also lack identity/time, but those are local-analysis material, not dictionaries. The tell is the entity shape and the join key: a dimension table maps one entity code to its attributes (`city_code` → name / level), while an aggregate summarizes many rows into one measure.
+
+Low confidence is a proposal, never a silent decision — ask the user instead of routing automatically.
+
+## Handoff to ae-metadata
+
+Extract the dimension sheet / file to CSV, then hand the following commands to ae-metadata. The sequence lists entry points only; full flags live in ae-metadata's references.
+
+Bind prerequisite (confirm before creating the table):
+
+- The table binds to an existing property (`property_name` + `property_scope` = user or event). That property usually appears once event/user data is uploaded first (e.g. events carrying `city_code`), so dimension binding is a second-phase action after data lands.
+- If the target property does not exist yet, create it first via ae-analysis metadata or a tracking plan. Never invent a property name.
+
+Entry command sequence:
+
+```bash
+# 1. Extract the dimension sheet/file to CSV (metadata upload accepts CSV only,
+#    purpose data_table.csv)
+ae-cli analysis input-file upload --project-id <id> --purpose data_table.csv --file <dim.csv>
+# 2. Create + bind in one step (or split into csv-write + bind-existing)
+ae-cli metadata property create-and-bind-csv-dimension-table --project-id <id> \
+  --property-name <p> --property-scope user|event --input-file-id ifile_xxx
+# 3. Later dictionary changes (add/update/delete):
+ae-cli metadata data-table csv-write --operation incremental_update|replace_update \
+  --data-table-id <id> --input-file-id ifile_xxx
+```
+
+Binding model: AE attaches a dimension table to a user/event property, turning it into a dict property whose values join through the table's key column to expand `--dict-columns`. See ae-metadata's dimension-table reference for the full flags.

package/skills/ae-data-integration/references/local-analysis.md

@@ -1,5 +1,7 @@
 # Local analysis
 
+Dimension / dictionary data (a stable-entity lookup with a join key) is not local-analysis material — it routes to ae-metadata as a dimension table. See [ue-routing.md](ue-routing.md) and [dimension-routing.md](dimension-routing.md).
+
 Keep the source on the local machine. Generated scripts and reports belong under `.ae-cli/data-integration/runs/<run-id>/` with restrictive permissions.
 Set the directory to `0700` and generated scripts/reports to `0600`.
 

package/skills/ae-data-integration/references/source-inspect.md

@@ -63,7 +63,7 @@ Summarize both — report the shape of the distribution and the names of the val
 - **Excel date cells** — a cell whose number format is a date or date+time is read as the wall-clock timestamp shown in Excel, not as the Excel serial number stored behind it, so the column infers as `datetime` and can serve as the time field. Inspect lists every such column in a warning. Treat that warning as a question to the user, not as a note: the same column profiled as `number` before this behavior existed, so if any part of this file was already sent to AE, the property may have been received as a number and its type is now locked — it cannot be changed to datetime, and the column has to be re-sent under a new property name. Ask whether the column was uploaded before, and only map it once the user answers. Elapsed-duration formats (`[h]:mm:ss` and the equivalent built-ins) are durations rather than points in time and stay `number`.
 - **Excel formula cells** — a spreadsheet stores a formula and, next to it, the result Excel last computed. That cached result is the value: it is read normally, including a result of `0` or `""`, which are real values and not blanks. This tool never evaluates a formula and never guesses a result, so a cell holding a formula the file never computed has nothing to upload; it is read as missing and counted, as is an Excel error value (`#N/A`, `#DIV/0!`, …). Inspect reports the counts per column in a warning and `convert` repeats them in `manifest.output.unreadable_cells`. Report them: the rows are kept and the record count is unchanged, so this is the only explanation for a column that is empty in AE while the spreadsheet looks full. When a column that matters reads as missing this way, ask the user to recalculate and re-export in Excel, or to export values instead of formulas, before uploading. This covers XLSX; a legacy `.xls` workbook goes through a different parser and is not counted here.
 - **Merged cells, hidden rows, and hidden columns** — a sheet maintained by hand merges a label down the rows it covers (`区域` spanning one region's block). Excel keeps that value on the block's first row only and stores every row below it as an empty cell, so a column that looks full on screen arrives mostly missing, and the AE property built from it would be empty for most events. The same worksheet may also hide a row inside a data block or hide a whole column. None of this travels with a row, so inspect scans the worksheet structure separately and reports it under `xlsx_structure`: `merged_ranges` with `merged_range_samples` (references such as `A3:A5`, never cell text), `merged_covered_cells` per column, `hidden_rows` with `hidden_row_samples` (source row numbers as Excel numbers them), and `hidden_columns` by header name. The default read is unchanged, so the report is a question for the user, and each answer is a flag: `--fill-merged-cells` copies each block's value into the cells its own range covers — bounded to the range, never overwriting a value that is there and never inventing one when the block's own cell is empty, so it is not a forward fill; `--exclude-hidden-rows` leaves hidden rows out. Neither is on by default: those cells really are empty in the file, and a row hidden inside a data block may still be real data — unlike a hidden *worksheet* (below), which is excluded by default. Hidden columns have no flag at all; when the user confirms one is not data, list it in the mapping's `exclude_columns`. Both flags are carried into the recommended mapping as `fill_merged_cells` / `exclude_hidden_rows`, which is what makes `convert` read the rows inspect profiled — `convert` has no read flags of its own — and `convert` repeats the findings in `manifest.output.xlsx_structure`, the only record of a layout the converted rows no longer show. This covers XLSX; a legacy `.xls` workbook is not scanned, so ask the user about merged labels and hidden rows there instead of trusting silence.
-- **Hidden worksheets** — a worksheet hidden in the workbook is left out of the `--data-set` candidates and out of `--merge-sheets`, because a sheet the file does not show is usually scratch space, a lookup table, or a superseded draft rather than rows anyone meant to upload. Inspect lists each one under `excluded_sheets` (with `reason: hidden`); report those names to the user, since they are the only explanation for a row count lower than the workbook appears to hold. Their headers are also left out of `header_consistency`, so a stale hidden draft cannot make a mergeable workbook look ragged. A hidden sheet stays readable when the user names it in `--data-set` — the command then warns on stderr that the selected sheet is hidden. Only pass a hidden sheet after the user says that is what they want. When *every* worksheet is hidden there is no candidate left, and inspect fails with `LOCAL_DATA_ALL_DATA_SETS_HIDDEN` whose hint lists the hidden sheets; treat that as a question about which sheet holds the real data, not as an unreadable file. This detection covers XLSX only: a legacy `.xls` workbook's sheet list is unfiltered, so a hidden sheet there still appears as a candidate and is still merged — for `.xls`, ask the user to confirm the sheet list instead of trusting it.
+- **Hidden worksheets** — a worksheet hidden in the workbook is left out of the `--data-set` candidates and out of `--merge-sheets`, because a sheet the file does not show is usually scratch space or a superseded draft rather than rows anyone meant to upload, but a hidden sheet can also be a dimension / dictionary table that is meant to be loaded, and that goes through dimension routing instead of being dismissed as scratch. Inspect lists each one under `excluded_sheets` (with `reason: hidden`); report those names to the user, since they are the only explanation for a row count lower than the workbook appears to hold. Their headers are also left out of `header_consistency`, so a stale hidden draft cannot make a mergeable workbook look ragged. A hidden sheet stays readable when the user names it in `--data-set` — the command then warns on stderr that the selected sheet is hidden. Only pass a hidden sheet after the user says that is what they want. When *every* worksheet is hidden there is no candidate left, and inspect fails with `LOCAL_DATA_ALL_DATA_SETS_HIDDEN` whose hint lists the hidden sheets; treat that as a question about which sheet holds the real data, not as an unreadable file. This detection covers XLSX only: a legacy `.xls` workbook's sheet list is unfiltered, so a hidden sheet there still appears as a candidate and is still merged — for `.xls`, ask the user to confirm the sheet list instead of trusting it.
 - **Excel sheets** — `--merge-sheets` streams every visible worksheet in file order instead of a single selected sheet; otherwise ask which sheet/`--data-set` to use. Inspect also reports `header_consistency` (`all_same` or `different`) across a workbook's sheets, with `header_details` listing each sheet's header row when they differ; prefer `--merge-sheets` only when headers match. Matching headers establish a shared structure, not disjoint rows: a detail sheet and a summary sheet, or `1月` and `1月修订版`, usually carry identical headers and would be merged and reported twice over. Before merging, confirm with the user that the sources are mutually exclusive partitions (one month per sheet, no overlap) rather than overlapping, revised, or derived views of the same rows, and show each sheet's row count and time coverage range in that confirmation so an overlap is visible. The same rule applies to repeated `--input-file`.
 - **Multi-file type conflicts** — when the same column has different inferred types across files, present each conflict and resolve with `--type-resolutions` on `convert` (see [transform](transform.md)).
 

package/skills/ae-data-integration/references/ue-routing.md

@@ -20,7 +20,7 @@ Classification order:
 5. Rows that mix track and user-profile facts in one file use `mixed` with a `record_type_field`; require explicit review.
 6. Low-confidence output is a proposal, never silent approval.
 
-Aggregated metrics, pivot tables, cross-tabs, model outputs, free-form documents, and records without real identity/time should normally use local analysis.
+Aggregated metrics, pivot tables, cross-tabs, model outputs, and free-form documents should normally use local analysis. Records without real identity/time are checked against dimension routing next and fall to local analysis only if they are not a stable-entity lookup.
 
 ### Time coverage is not native granularity
 
@@ -44,6 +44,22 @@ point, and do not proceed until they answer:
 An unanswered question, a cumulative snapshot, or overlapping periods route to local analysis
 instead.
 
+## Route to dimension table
+
+A dimension / dictionary table describes stable entities (city, product, device): a lookup that maps an entity code to its attributes. It has no row-level identity or event time, so it fails the UE prerequisites above, but it is not local-analysis material either — it belongs in AE as a dimension table bound to a property.
+
+Classification order (UE first, dimension second, local analysis last):
+
+1. Satisfy the UE must-holds above → UE ingestion wins; never route an identity/time-bearing file here.
+2. Fail the UE prerequisites **and** match most of these dimension signals → dimension routing:
+   - No row-level identity: no `account_id` / `distinct_id` column. A `code` / `id` / `no` key is an entity code, not a user identity.
+   - No row-level event time: no `#time` column. If time exists, it is an effective / expiry interval, not an event occurrence.
+   - Finite enumeration: few rows, each describing one entity's attributes (code → name / level), not facts accumulating over time.
+   - A join key: a column shared with event data (`city_code`, `sku_id`, `device_id`) whose values are descriptive attributes, not measures.
+3. Otherwise → local analysis.
+
+See [references/dimension-routing.md](references/dimension-routing.md) for the handoff.
+
 ## Route to local analysis
 
 Choose local analysis when:

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.