@thinkingai/ae-cli 6.1.14 → 6.1.16

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

@@ -0,0 +1,142 @@
+# UE mapping contract
+
+The mapping version is `ae-local-data-mapping/v1`.
+
+Required structure:
+
+```json
+{
+  "version": "ae-local-data-mapping/v1",
+  "source": {
+    "sha256": "<source-sha256>",
+    "format": "csv",
+    "data_set": "$"
+  },
+  "mode": "track",
+  "confidence": "high",
+  "account_id_field": "user_id",
+  "time": {
+    "field": "event_time",
+    "format": "auto",
+    "source_timezone": "Asia/Shanghai"
+  },
+  "event_name_field": "event_name",
+  "properties": [
+    { "source": "amount", "target": "amount", "type": "number" }
+  ]
+}
+```
+
+Use `distinct_id_field` when no account field exists. `mixed` requires `record_type_field`. Track requires `event_name_field` or a reviewed `default_event_name`. `source.format` is one of `csv`, `tsv`, `json`, `jsonl`, `xls`, `xlsx`. For a multi-file template mapping, `source.sha256` may be the wildcard `*`.
+
+## Record types
+
+Every record carries a `#type`. `mode: 'mixed'` resolves the type per row via `record_type_field`; otherwise the mode fixes it (`track` or `user_set`). The `record_type_field` values are normalized case- and underscore-insensitively, with `event`→`track` and `user`/`userset`→`user_set` aliases.
+
+| `#type` | Meaning | Requires `#event_name` |
+| --- | --- | :---: |
+| `track` | Report an event into the event table | Yes |
+| `user_set` | Overwrite user properties (create if missing) | No |
+| `user_setOnce` | Initialize a property only when empty | No |
+| `user_add` | Increment numeric user properties | No |
+| `user_unset` | Clear user property values | No |
+| `user_del` | Delete the user from the user table | No |
+| `user_append` | Append elements to list properties | No |
+| `user_uniq_append` | Append elements with deduplication | No |
+
+## System fields
+
+Top-level `#` fields map from named source columns. The user confirms each mapping; never infer it from a column name alone — a `user_id` column can be either an anonymous or a login ID, and only the user knows which.
+
+| Field | Plain-language meaning | Required |
+| --- | --- | :---: |
+| `#distinct_id` | Anonymous visitor ID (device/cookie/visitor) — identifies unauthenticated traffic | At least one of `#distinct_id` / `#account_id` |
+| `#account_id` | Login/account ID (database `user_id`, phone, member ID) — identifies authenticated users | At least one of `#distinct_id` / `#account_id` |
+| `#time` | Event/profile occurrence time; AE bins data by it | Yes |
+| `#event_name` | What the user did (`purchase`, `login`) | Only for `track` |
+| `#ip` | Client IP; AE resolves geo from it | No |
+| `#uuid` | Short-window deduplication ID | No |
+
+`#zone_offset` is a preset property that tells AE the data's UTC offset (whole hours, -12..14) so `#time` is interpreted correctly. Unlike the fields above it lives **inside `properties`**, not at the top level. Provide it via `zone_offset_value` (a whole-hour integer such as `8` for UTC+8; an IANA name is also accepted and resolved to its offset at conversion time — sub-hour zones round to the nearest whole hour and DST zones reflect the offset then in effect, so historical data crossing a DST boundary should use `zone_offset_field`) or `zone_offset_field` (a source column carrying the offset per row); the two are mutually exclusive. Rows whose `zone_offset_field` value is missing or not an integer in -12..14 are quarantined.
+
+Mapping keys: `account_id_field`, `distinct_id_field`, `time.field`, `event_name_field` (or a reviewed `default_event_name`), `ip_field`, `uuid_field`. Inspect surfaces every identity-shaped column in `identity_candidates` (name, `account`/`distinct` kind, unique and missing ratios) so the agent can present all candidates for confirmation. When the required identity column is absent, use an explicit `account_id_value`/`distinct_id_value` placeholder or `random_pool` — a user decision, never invented.
+
+## Output record shape
+
+System fields sit at the top level; every mapped property is nested under `properties`.
+
+```json
+{ "#type": "track", "#time": "2026-08-10 10:00:00.000", "#account_id": "u-1", "#event_name": "purchase", "properties": { "amount": 99.9, "channel": "app" } }
+```
+
+```json
+{ "#type": "user_set", "#time": "2026-08-10 10:00:00.000", "#distinct_id": "d-1", "properties": { "user_level": 5, "user_tag": "vip" } }
+```
+
+`track` requires `#event_name`; user-profile types (`user_set`, `user_add`, …) do not.
+
+## Optional overlay fields
+
+All fields below are optional and are explicit user decisions — never invent them.
+
+| Field | Shape | Effect |
+| --- | --- | --- |
+| `time_format` | `string` (strptime pattern) | Overrides auto-detection for `time.field`; used for ambiguous US/EU dates |
+| `value_mapping` | `{ account_id? / distinct_id? / event_name? / record_type?: {original: replacement} }` | Exact-key replacement per system field (business-data keys map to AE-name values). A value with no matching key keeps its original text and fails validation, so confirm every distinct value is covered or excluded |
+| `account_id_value` / `distinct_id_value` | `string` | Fixed placeholder identity (≤128 chars). Applies to every row when the corresponding `*_field` is absent; when the field exists, fills only the rows whose column is empty |
+| `random_pool` | `{ account_ids?: string[], distinct_ids?: string[] }` | Synthesizes a random identity when the source field is absent |
+| `exclude_columns` | `string[]` | Source columns skipped when building properties |
+| `flatten_rules` | `{ outColumn: 'dot.path' }` | Nested flatten map. NDJSON/JSON paths are from the record root (`user_info.name`); CSV/TSV paths are `<column>.<cell-relative path>` into a JSON-encoded object cell (`user_profile.name`) — add the source column to `exclude_columns` when flattening it |
+| `headers` | `string[]` | User-confirmed column names for a headerless file; presence means the first row is data. Never use inspect's `col_1..col_N` placeholders — infer names from each column's values, confirm them with the user, then write them here |
+| `missing_time` | `'now'` | Fill a missing/empty `#time` with the current time, for user-profile rows only (explicit user decision; track rows are never filled) |
+| `ip_field` | `string` | Source column emitted as the top-level `#ip` system field (client IP; AE resolves geo) |
+| `uuid_field` | `string` | Source column emitted as the top-level `#uuid` system field (short-window deduplication ID) |
+| `zone_offset_value` | `number` (integer -12..14) or IANA `string` | Emits the fixed `#zone_offset` preset property inside `properties`. An IANA name resolves to its integer UTC offset |
+| `zone_offset_field` | `string` | Source column whose per-row integer value (-12..14) is emitted as `#zone_offset`; missing/non-integer rows are quarantined. Mutually exclusive with `zone_offset_value` |
+| `event_meta` | `{ <event-name>: { desc?: string, tag?: string } }` | Per-event business description and `event_tag` for the tracking plan, keyed by AE event name. Inferred from the data and user context; the user supplies anything not inferable — never leave them empty |
+
+Each `properties` entry may also carry `value_mapping` (per-property exact-key replacement), `transform` (one of `stringify`, `number`, `boolean`, `json`), `time_format` (only meaningful for `type: 'datetime'`), and `desc` (business description for the tracking plan; inferred, or user-provided when not inferable). Container columns (`object`/`list`) whose values arrive as JSON text — JSON-encoded CSV cells, or flattened NDJSON leaves — must set `transform: 'json'` so conversion parses the text back into a native object/array; it is a safe no-op when the value already arrived native.
+
+## Time formats
+
+Values with an explicit offset or `Z` are parsed by the JavaScript `Date` constructor (authoritative). Other values are matched against 21 formats; a `time_format` field overrides the match.
+
+| Category | Example | Auto-detected |
+| --- | --- | :---: |
+| Standard AE | `2024-01-15 10:30:00.123` / `2024-01-15 10:30:00` | Yes |
+| ISO 8601 | `2024-01-15T10:30:00` / with `.SSS` / with offset | Yes |
+| Unix epoch | `1705314600` (seconds) / `1705314600000` (milliseconds) | Yes |
+| Slash-separated | `2024/01/15 10:30:00` / `2024/01/15` | Yes |
+| Dot-separated | `2024.01.15 10:30:00` / `2024.01.15` | Yes |
+| Compact digits | `20240115103000` / `202401151030` / `20240115` | Yes |
+| English month names | `15 Jan 2024 10:30:00` / `January 15 2024 10:30:00` / `Jan 15 2024 10:30:00` | Yes |
+| Chinese date | `2024年1月15日` / `2024年1月15日 10:30:00` / `2024年1月15日 10时30分00秒` | Yes |
+| US format | `01/15/2024 10:30:00` (MM/DD/YYYY) | No — use `time_format` |
+| EU format | `15/01/2024 10:30:00` (DD/MM/YYYY) | No — use `time_format` |
+
+## Data rules
+
+- **Ingestion time window.** The receiver accepts event/profile times from 3 years before to 3 days after the server time; the CLI enforces this range. Client-side reporting has a tighter window (10 days before to 3 days after); historical data beyond the window needs AE support to extend it.
+- **Property type locking.** A property's type is locked on first receipt, and properties sharing a name across events are one property — later reports must use the same type. Values whose type mismatches the locked type are dropped silently, so review an inferred type before committing it.
+- **Quote stripping.** Paired single or double quotes around a cell value are stripped (`'user_001'` → `user_001`); a single-sided quote is kept as data (SQL exports often quote every value).
+- **Column name sanitization.** Recommended mapping auto-names properties: accents are stripped, camelCase is split to snake_case, everything is lowercased, and illegal characters become `_`; a digit-leading name is prefixed `field_`, and a name with nothing recognizable falls back to `field_N`. Review these targets — especially the `field_N` fallbacks — and rename before converting.
+- **Object sub-property keys.** Object and list-of-object keys follow the same naming rules as property names (lowercase snake_case, letter-leading, at most 50 chars, no `#`). A key that does not — for example a Chinese key inside a JSON cell such as `{"等级":"金牌"}` — quarantines the whole row, so confirm object keys before converting.
+
+## Review checklist
+
+- Source SHA-256 and data-set ID match the inspection result (or the mapping uses the `*` wildcard for multi-file).
+- Identity values remain strings and are at most 128 characters.
+- Source timezone is an IANA name derived from user/project context.
+- `#zone_offset`, when set, is a whole-hour integer in -12..14 (or an IANA name/column that resolves to one) and is emitted inside `properties`, never at the top level.
+- Event/property names are lowercase snake_case, begin with a letter, and are at most 50 characters.
+- Target property names are unique and do not collide with UE system fields.
+- Types are one of `string`, `number`, `boolean`, `datetime`, `list`, or `object`.
+- Text is at most 2 KB; numbers stay within -9E15..9E15.
+- Lists contain at most 500 strings (255 bytes each) or 500 objects.
+- Objects contain at most 100 legal sub-properties; nested values follow the same type limits.
+- A conversion rule does not hide a real type conflict.
+- Event/profile times fall within the receiver window: previous 3 years through next 3 days.
+- Do not fabricate UUIDs, identities, times, or events; `#ip`/`#uuid` map from named source columns only (`ip_field`/`uuid_field`).
+- `value_mapping`, `random_pool`, and fixed `account_id_value`/`distinct_id_value` came from an explicit user decision and match the actual distinct values/columns.
+
+`user_set` output for the same identity is ordered by time so receiver application order is deterministic. Conversion applies whole-row quarantine: any error on a row — identity, time, event, record type, or a single property (type coercion, size/limit) — drops the entire row. The row is written to `invalid.rows.jsonl` with its error codes, counted in `manifest.output.invalid_records`, and the manifest is blocked until reviewed. The failed rows are re-reportable without re-sending valid rows: fix the mapping, then run `convert --input-file <same-source> --mapping <fixed-mapping> --salvage-from <invalid.rows.jsonl>`. The salvage run re-processes only the listed row numbers against the same source, emits a `valid.ue.jsonl` containing only the newly fixed rows, and writes a new `invalid.rows.jsonl` with whatever still fails — so the loop repeats (feeding each round's `invalid.rows.jsonl` into the next `--salvage-from`) until no rows fail or the user stops.

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

@@ -0,0 +1,35 @@
+# UE routing
+
+Use this reference after `data-integration inspect`.
+
+## Route to UE ingestion
+
+All of these must hold:
+
+- A real `#account_id` or `#distinct_id` source is present.
+- A real time column is parseable; no synthetic time is permitted.
+- The records are event facts or user-property snapshots rather than aggregates.
+- Field-level records can be represented without losing essential meaning.
+
+Classification order:
+
+1. A legal explicit `#type` wins (all eight record types — `track`, `user_set`, `user_setOnce`, `user_add`, `user_unset`, `user_del`, `user_append`, `user_uniq_append`).
+2. An event/action field implies `track`.
+3. Repeated users across a time series imply `track`; without an event field, propose a normalized file/Sheet name and require review.
+4. One row per user with snapshot-like fields implies `user_set`.
+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.
+
+## Route to local analysis
+
+Choose local analysis when:
+
+- The user wants insights, not project ingestion.
+- UE identity or time prerequisites are missing.
+- Each row is an aggregate rather than a user/event record.
+- Conversion would invent semantics or discard important structure.
+- The user declines an uncertain mapping or destination.
+
+Explain the reason briefly. Do not frame local analysis as an error.

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

@@ -62,7 +62,7 @@ Trigger when a user asks about:
 - **Configuration**: Debug mode / data validation / retry strategy
 - **Troubleshooting**: Upload failures / missing data / format errors
 
-**Do NOT trigger**: Inline Q&A within `ae-generate-tracking-plan` or `ae-generate-tracking-code` sessions (those skills have their own workflows).
+**Do NOT trigger**: Inline Q&A within `ae-generate-tracking-plan` or `ae-generate-tracking-code` sessions (those skills have their own workflows). Offline local-file import (CSV / Excel / JSONL → AE) is owned by the `ae-data-integration` skill — route those requests there instead of answering with LogBus / RESTful guidance.
 
 ## Workflow
 

package/skills/ae-dataops/SKILL.md

@@ -173,7 +173,7 @@ Detailed metadata browsing, SQL query, async download, and cancel workflows live
 Key constraints:
 - IDE is query-only; create/modify/delete tables with `dataops_datatable`.
 - Prefer `dataops_datatable +dict_search_tables` for table discovery unless raw engine metadata or schema browsing is required.
-- SQL query submission creates a download task; rows are not returned inline.
+- Submit exactly one read-only SQL query. It creates a platform-bounded download task; rows are not returned inline and the result is not an unlimited or full export.
 
 ---
 

package/skills/ae-dataops/references/dataops-query.md

@@ -61,7 +61,7 @@ ae-cli dataops_ide +search_tables --spaceCode "${spaceCode}" --searchKey "user"
 
 ## Workflow C: Execute SQL Query (Download-Centered Async Flow)
 
-Use this flow for SQL query execution. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly.
+Use this flow for exactly one read-only SQL query. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly. The query semantics are preserved, but the result remains platform-bounded; when present, `downloadRowLimit` reports that cap. This is not an unlimited or full export.
 
 ```bash
 # Step 1: Submit SQL and create a download task. Defaults: repoCode=te_etl, engineType=TASK_ENGINE_TRINO.
@@ -72,7 +72,7 @@ ae-cli dataops_ide +submit_sql_query --spaceCode "${spaceCode}" --repoCode "te_e
 # Step 2: Poll the download task status by spaceCode/downloadTaskId. Rows are not returned through MCP/CLI.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId}
 
-# Step 3: CLI-only local save after downloadStatus=SUCCESS. Use a .zip suffix.
+# Step 3: CLI-only streaming save after downloadStatus=SUCCESS. The target is replaced only after the stream completes.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId} --downloadTo "./result.zip"
 
 # (Optional) Cancel the download task.
@@ -104,8 +104,8 @@ ae-cli dataops_ide +cancel_sql_query --spaceCode "${spaceCode}" --downloadTaskId
 - **Table search**: `+search_tables` requires `--spaceCode` and `--searchKey`. `--connType`, `--repoCode`, and `--size` are optional and default to `SPACE`, `te_etl`, and `20`. It returns `items`, `searchKey`, `size`, `totalCount`, `tableCount`, `viewCount`, `returnedCount`, `hasMore`, and `nextAction`.
 - **Table detail**: `+ide_get_table_detail` requires `--spaceCode`, `--catalog`, `--schema`, and `--tableName`. `--connType`, `--repoCode`, `--engineType`, `--entityType`, and `--includeDdl` are optional and default to `SPACE`, `te_etl`, `TASK_ENGINE_TRINO`, auto-detect, and `false`. It returns identity, storage metadata, columns, partitions, partition keys, optional layout fields, and `tableDdl` only when requested.
 - **Schema info**: `+get_schema_info` requires `--spaceCode`, `--catalog`, and `--schema`. `--connType` and `--repoCode` are optional and default to `SPACE` and `te_etl`. It returns only `schema`, `tableNum`, and `viewNum`.
-- **SQL submit**: `+submit_sql_query` requires `--spaceCode` and `--sql`. `--repoCode` and `--engineType` are optional and default to `te_etl` and `TASK_ENGINE_TRINO`. On success it returns `requestId`, `spaceCode`, `repoCode`, `downloadTaskId`, `downloadStatus`, `downloadApi`, `downloadParams`, and `nextAction`; rows are never returned.
-- **SQL status**: `+get_sql_query_status` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. `--downloadTo` is CLI-only; after `downloadStatus=SUCCESS` it saves the result zip and adds `localFile`. It returns status/progress metadata, `nextAction`, `downloadApi`, and `downloadParams`; rows are never returned.
+- **SQL submit**: `+submit_sql_query` requires `--spaceCode` and exactly one read-only query in `--sql`. `--repoCode` and `--engineType` are optional and default to `te_etl` and `TASK_ENGINE_TRINO`. On success it returns task metadata and, when exposed by Gaia, `downloadRowLimit`; rows are never returned and the result remains platform-bounded.
+- **SQL status**: `+get_sql_query_status` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. `--downloadTo` is CLI-only; after `downloadStatus=SUCCESS` it streams the result zip to a temporary sibling file, publishes it only after completion, and adds `localFile`. It returns status/progress metadata, `nextAction`, `downloadApi`, and `downloadParams`; rows are never returned.
 - **SQL cancel**: `+cancel_sql_query` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. It returns cancellation request metadata such as `downloadCancelStatus`.
 - **engineType**: `TASK_ENGINE_TRINO` (default, interactive queries) | `TASK_ENGINE_STARROCKS` (high-concurrency analytics)
 - **entityType**: optional `TABLE` or `VIEW` hint. Omit it unless the target type must be forced.

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

@@ -21,7 +21,8 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 | 埋点模板 | Tracking Plan Template | Pre-built industry/genre xlsx templates |
 | 方案名称 | Plan Name | User-facing plan identifier |
 | 应用场景 | Application Scenario | One-sentence description of what the app does |
-| 素材来源 | Source Material Type | prd / chat / codebase / template |
+| 素材来源 | Source Material Type | prd / chat / codebase / template / data |
+| 数据样本 / 文件画像 | Data Sample / File Profile | Column→property mapping source from an `ae-data-integration` inspect profile (`source_type: data`) |
 | 业务维度 | Business Dimension | Revenue model, core loop, functional entries, currency system |
 | 收入模型 | Revenue Model | IAA / IAP / mixed / subscription / commission |
 | 核心循环 | Core Loop | Core gameplay loop (e.g. "grind stages → earn coins → gacha for heroes") |
@@ -115,8 +116,9 @@ Choose your source material (up to 2):
 3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 5 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template
+6 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
 
-Reply with number(s), e.g. 1,5 or 4. Select up to 2.
+Reply with number(s), e.g. 1,5 or 4. Select up to 2 (option 6 is single-source).
 ```
 
 If in a sandbox environment, ask exactly:
@@ -128,8 +130,9 @@ Choose your source material (up to 2):
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
+5 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
 
-Reply with number(s), e.g. 1,4 or 3. Select up to 2.
+Reply with number(s), e.g. 1,4 or 3. Select up to 2 (option 5 is single-source).
 ```
 
 Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
@@ -153,8 +156,10 @@ Based on user selection, determine source material type and record to `meta.sour
 | Codebase only | `codebase` | Scan source code, extract events/properties from business logic |
 | Template only | `template` | Provide built-in template selection |
 | Existing plan only | `existing_plan` | Import xlsx as baseline (see "Modify Existing Tracking Plan Flow" below) |
+| Data sample only | `data` | Read the inspect profile (`ae-local-data-profile/v1`), map columns → events/properties (see "Data-path (source_type = data)" below) |
 | Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: existing_plan → template → codebase → prd → chat) |
 | Existing plan + Pre-built template | **NOT allowed** | Both provide event baselines; semantic conflict |
+| Data sample + any other | **NOT allowed** | Data sample is a standalone single-source path |
 
 **Follow-up questions** (ask in follow-up order defined in Multi-Source Combination Rules below):
 - Product doc → if not in a sandbox environment, ask exactly:
@@ -184,6 +189,7 @@ Based on user selection, determine source material type and record to `meta.sour
 - Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic
 - Pre-built template → display matching templates for user confirmation
 - Modify existing tracking plan → ask **"Please provide the xlsx file path of your existing tracking plan"**, then follow the flow below
+- Data sample → ask **"Please provide the path of the inspect profile JSON (or the run directory containing it)"**, then read the `ae-local-data-profile/v1` product and follow the "Data-path (source_type = data)" flow below
 
 **Modify Existing Tracking Plan Flow** (when user selects this option):
 
@@ -363,6 +369,49 @@ Use the baseline source's inference method as primary. Supplementary sources (es
 }
 ```
 
+### Data-path (source_type = data) — condensed single-gate flow
+
+When the user selects the **Data sample / file profile** option (`source_type = data`), the flow diverges from the standard 5-item anchor. This path **maps table columns → events/properties** instead of inventing events from business understanding, and uses a **single confirmation gate** instead of the 5-segment Refine loop.
+
+**What to skip** (only Item 1 — Application Scenario and Item 2 — Data sample are collected):
+
+- **Item 3 (SDK Integration Config)** → skip. `meta.sdk_integration_mode = "none"` (data ingested via RESTful / LogBus / DataX, no SDK). No SDK auto-track events are injected (Phase 1.4 already skips `none`).
+- **Item 4 (User Identity System)** → skip the visitor-ID strategy question. Derive `meta.user_identity` from the inspect profile's `identity_candidates` instead (e.g. a `distinct_id` / `account_id` column), `account_id_source: "user_account"` when an account column exists, otherwise `"none"`.
+- **Business Dimension confirmation** → skip. Mapping is driven by columns, not by revenue model / core loop. `meta.business_dimension` stays empty.
+
+**Draft construction (replaces Phase 1.1/1.2/1.3 for the data path)**:
+
+1. **Read the inspect profile**: the `ae-local-data-profile/v1` JSON product (columns / types / samples / UE eligibility / mapping confidence). If it is not present or is stale, re-run `ae-cli data-integration inspect` for the source file first.
+2. **Event model determination** (reuse UE routing): single-table single-event `track` / single-table multi-event (event-name column) / single-table `user_set` / mixed. The agent may propose **splitting one table into multiple events** (e.g. an ad table split by `campaign_type` into `ad_show` / `ad_click`); such proposals MUST be confirmed in the gate.
+3. **Column → property mapping draft**:
+   - Identify system columns first: time field, `distinct_id` / `account_id`, event-name column, user-property-name column.
+   - Map the remaining columns to event properties / user properties / super properties.
+   - Naming: `snake_case` event/property names + `display_name` + `desc` + `event_tag` (language follows the user's input).
+   - Type inference: CSV columns default to `string`; infer `number` / `bool` / `datetime` / enum from field name + value distribution + business doc/prompt priors. **Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate** (do not ask column-by-column beforehand).
+4. **Single confirmation gate** (replaces Phase 2, see below).
+5. **Merge with existing plan** (reuse Phase 4.1/4.2 conflict detection).
+6. **Persist**: `.ae-cli/draft.json` → xlsx → upload (`sdk_integration_mode = none`).
+
+**Single confirmation gate (one round, one summary table)**:
+
+Present ONE merged table covering all of the following in a single message, then wait for a single reply:
+
+- **Event list**: `event_name` / `display_name` / `desc` / `event_tag` / `platform`.
+- **Property list**: `name` / `display_name` / `type` / `desc` / `source`, with uncertain types highlighted (marked "to-confirm").
+- **Field scope**: default to plan-internal fields only; include a **full-import switch** for bringing all source columns in.
+- **Unrecognized / dirty data handling**: how unmapped columns, null values, and unparseable rows are treated.
+- **Same-name property type conflicts**: flagged inline in the gate (see Phase 4.2 Type A).
+
+User replies once: `ok` (accept all), or targeted edits — rename / retype / add / remove individual columns or events. After the gate is confirmed, jump to Phase 3 (project token) then Phase 4 (merge + upload); do NOT enter the 5-segment Refine loop.
+
+**dry-run mode**:
+
+When the user requests dry-run (or the caller passes `data-integration plan --dry-run`), produce the draft preview + column→property mapping summary ONLY:
+
+- Show the single confirmation gate table (events + properties + field scope + unrecognized-data handling) and the mapping result, but do NOT write `.ae-cli/draft.json`.
+- Do NOT generate xlsx, do NOT archive to `plans/`, do NOT upload to AE.
+- State explicitly that nothing was persisted; the user can approve a real run afterwards.
+
 ### Item 3 — SDK Integration Config (client + server combined)
 
 Ask: **"What is your client platform? (multi-select OK, e.g. Android + iOS) Will you integrate a server-side SDK?"**
@@ -822,6 +871,8 @@ AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<templ
 
 ## Phase 2 — Refine (5-segment loop)
 
+> **Data path (`source_type = data`)**: skip this 5-segment loop entirely — use the single confirmation gate defined in "Data-path (source_type = data)" instead.
+
 In order, one conversation round per segment:
 
 1. **sdk_config (SDK config + User identity, combined)** — Show SDK integration mode, platform/language, visitor ID strategy, account ID source, corresponding SDK calls

package/skills/ae-metadata/SKILL.md

@@ -83,4 +83,3 @@ ae-cli analysis input-file purpose list --project-id 1
 ## Related Skills
 
 - **`ae-analysis`**: `analysis-meta event get` / `analysis-meta property get` for detail, and `analysis-meta event list` / `analysis-meta property list` to discover names.
-- **Dev workflow**: `.cursor/skills/te-cli-capability-gateway` — inspect gateway schema when adding new metadata capabilities.

package/dist/chunk-3FY3RJ26.js

@@ -1,293 +0,0 @@
-import {
-  logger
-} from "./chunk-JHENBQ5B.js";
-
-// src/core/json-utils.ts
-import fs from "fs";
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-var JSONbig = require2("json-bigint");
-var jsonParser = JSONbig({ storeAsString: true });
-var INTEGER_TOKEN = /^-?(?:0|[1-9]\d*)$/;
-function normalizeParsedNumbers(lossless, native) {
-  if (typeof lossless === "string" && typeof native === "number") {
-    if (INTEGER_TOKEN.test(lossless) && !Number.isSafeInteger(native)) {
-      return lossless;
-    }
-    return native;
-  }
-  if (Array.isArray(lossless) && Array.isArray(native)) {
-    for (let index = 0; index < lossless.length; index++) {
-      lossless[index] = normalizeParsedNumbers(lossless[index], native[index]);
-    }
-    return lossless;
-  }
-  if (lossless !== null && native !== null && typeof lossless === "object" && typeof native === "object") {
-    for (const key of Object.keys(lossless)) {
-      lossless[key] = normalizeParsedNumbers(lossless[key], native[key]);
-    }
-  }
-  return lossless;
-}
-function safeJsonParse(text) {
-  const lossless = jsonParser.parse(text);
-  return normalizeParsedNumbers(lossless, JSON.parse(text));
-}
-function safeReadJsonFile(filePath) {
-  const content = fs.readFileSync(filePath, "utf-8");
-  return safeJsonParse(content);
-}
-
-// src/core/url-utils.ts
-function normalizeUrl(url) {
-  if (!url) return url;
-  if (!url.startsWith("http://") && !url.startsWith("https://")) {
-    url = `https://${url}`;
-  }
-  return url.replace(/\/$/, "");
-}
-
-// src/core/config.ts
-import fs3 from "fs";
-import path from "path";
-
-// src/core/sandbox-runtime.ts
-import { homedir } from "os";
-import { join } from "path";
-import fs2 from "fs";
-var LINUX_SANDBOX_RUNTIME_ROOT = "/home/ta/te_agent_ta";
-function getDefaultSandboxRuntimeRoot() {
-  if (process.platform === "linux") {
-    return LINUX_SANDBOX_RUNTIME_ROOT;
-  }
-  return homedir();
-}
-function getSandboxRuntimeRoot() {
-  return process.env.SANDBOX_RUNTIME_ROOT || getDefaultSandboxRuntimeRoot();
-}
-function getSandboxAeConfigDir() {
-  return join(getSandboxRuntimeRoot(), ".ae-config");
-}
-function getSandboxCliTokenFilePath() {
-  return join(getSandboxAeConfigDir(), "cli-token.json");
-}
-function isAeSandboxRuntime() {
-  if (process.env.SANDBOX_RUNTIME_ROOT) {
-    return true;
-  }
-  try {
-    if (fs2.existsSync(getSandboxCliTokenFilePath())) {
-      return true;
-    }
-  } catch {
-  }
-  return false;
-}
-
-// src/core/config.ts
-var CONFIG_DIR = path.join(process.env.HOME || "", ".ae-cli");
-var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function sandboxCliTokenCandidatePaths() {
-  const paths = [getSandboxCliTokenFilePath()];
-  const homeFallback = path.join(process.env.HOME || "", ".ae-config", "cli-token.json");
-  if (!paths.includes(homeFallback)) {
-    paths.push(homeFallback);
-  }
-  return paths;
-}
-function readSandboxCliTokenEntry() {
-  for (const file of sandboxCliTokenCandidatePaths()) {
-    if (!fs3.existsSync(file)) continue;
-    try {
-      const data = safeReadJsonFile(file);
-      if (data && typeof data === "object" && !Array.isArray(data)) {
-        const url = data.url;
-        const token = data.token ?? data["cli-token"];
-        if (url && token) {
-          return { url, token };
-        }
-      }
-    } catch {
-    }
-  }
-  return null;
-}
-function forceMigrateFromFallback() {
-  const entry = readSandboxCliTokenEntry();
-  if (!entry) return null;
-  return { [entry.url]: entry.token };
-}
-function getFallbackCliToken(hostUrl) {
-  const store = forceMigrateFromFallback();
-  if (!store) return null;
-  if (hostUrl && store[hostUrl]) return store[hostUrl];
-  const entries = Object.values(store);
-  if (entries.length === 1) return entries[0];
-  return null;
-}
-function ensureDir() {
-  if (!fs3.existsSync(CONFIG_DIR)) fs3.mkdirSync(CONFIG_DIR, { recursive: true });
-}
-function dedupeNormalizedHosts(config) {
-  const hosts = {};
-  for (const [url, entry] of Object.entries(config.hosts)) {
-    const key = normalizeUrl(url);
-    if (!hosts[key]) {
-      hosts[key] = entry;
-    }
-  }
-  return {
-    activeHost: config.activeHost ? normalizeUrl(config.activeHost) : "",
-    hosts
-  };
-}
-function configNeedsNormalization(config) {
-  if (config.activeHost && normalizeUrl(config.activeHost) !== config.activeHost) return true;
-  const keys = Object.keys(config.hosts);
-  if (keys.some((url) => normalizeUrl(url) !== url)) return true;
-  return new Set(keys.map(normalizeUrl)).size !== keys.length;
-}
-function loadConfig() {
-  try {
-    if (fs3.existsSync(CONFIG_FILE)) {
-      const raw = safeReadJsonFile(CONFIG_FILE);
-      if (raw.defaultHost && !raw.activeHost) {
-        const migrated = dedupeNormalizedHosts(migrateConfig(raw));
-        saveConfig(migrated);
-        return migrated;
-      }
-      const rawConfig = raw;
-      if (configNeedsNormalization(rawConfig)) {
-        const config = dedupeNormalizedHosts(rawConfig);
-        saveConfig(config);
-        return config;
-      }
-      return rawConfig;
-    }
-  } catch (err) {
-    logger.error(`Error loading config: ${err.message}`);
-    console.error(`Error loading config: ${err.message}`);
-  }
-  return { activeHost: "", hosts: {} };
-}
-function migrateConfig(old) {
-  const hosts = {};
-  const oldHost = old.defaultHost;
-  if (old.hosts) {
-    for (const [key, val] of Object.entries(old.hosts)) {
-      const url = normalizeUrl(key.startsWith("http") ? key : `https://${key}`);
-      hosts[url] = val;
-    }
-  }
-  const activeHost = normalizeUrl(oldHost.startsWith("http") ? oldHost : `https://${oldHost}`);
-  if (!hosts[activeHost]) {
-    hosts[activeHost] = { label: "default" };
-  }
-  return { activeHost, hosts };
-}
-function saveConfig(config) {
-  ensureDir();
-  fs3.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
-  logger.info(`Config saved: activeHost=${config.activeHost}, hosts=${Object.keys(config.hosts).length}`);
-}
-function getActiveHost() {
-  const sandboxHost = readSandboxCliTokenEntry()?.url;
-  if (sandboxHost) return sandboxHost;
-  const config = loadConfig();
-  return config.activeHost || "";
-}
-function setActiveHost(url) {
-  url = normalizeUrl(url);
-  const config = loadConfig();
-  if (!config.hosts[url]) {
-    throw new Error(`Host ${url} is not in the configured hosts list. Add it first.`);
-  }
-  config.activeHost = url;
-  saveConfig(config);
-}
-function addHost(url, label) {
-  url = normalizeUrl(url);
-  label = normalizeLabel(label);
-  const config = loadConfig();
-  assertUniqueHostLabel(config, label, url);
-  config.hosts[url] = { label };
-  if (!config.activeHost) {
-    config.activeHost = url;
-  }
-  saveConfig(config);
-}
-function updateHostLabel(url, label) {
-  url = normalizeUrl(url);
-  label = normalizeLabel(label);
-  const config = loadConfig();
-  if (!config.hosts[url]) {
-    throw new Error(`Host is not configured: ${url}`);
-  }
-  assertUniqueHostLabel(config, label, url);
-  config.hosts[url].label = label;
-  saveConfig(config);
-}
-function normalizeLabel(label) {
-  const normalized = label.trim();
-  if (!normalized) {
-    throw new Error("Label cannot be empty.");
-  }
-  return normalized;
-}
-function assertUniqueHostLabel(config, label, excludeUrl) {
-  const duplicate = Object.entries(config.hosts).find(([url, entry]) => url !== excludeUrl && entry.label === label);
-  if (duplicate) {
-    throw new Error(`Label already exists: ${label}. Rename the existing label first: ${duplicate[0]}`);
-  }
-}
-function removeHost(url) {
-  url = normalizeUrl(url);
-  const config = loadConfig();
-  delete config.hosts[url];
-  if (config.activeHost === url) {
-    const remaining = Object.keys(config.hosts);
-    config.activeHost = remaining.length > 0 ? remaining[0] : "";
-  }
-  saveConfig(config);
-}
-function listHosts() {
-  const config = loadConfig();
-  return Object.entries(config.hosts).map(([url, entry]) => ({
-    url,
-    label: entry.label,
-    active: url === config.activeHost
-  }));
-}
-function resolveHostSelector(env) {
-  const raw = env.trim();
-  const selector = raw.startsWith("http://") || raw.startsWith("https://") ? normalizeUrl(raw) : raw;
-  const hosts = listHosts();
-  const byUrl = hosts.find((host) => host.url === selector);
-  if (byUrl) return { status: "found", host: byUrl };
-  const byLabel = hosts.filter((host) => host.label === raw);
-  if (byLabel.length === 1) return { status: "found", host: byLabel[0] };
-  if (byLabel.length > 1) return { status: "duplicate-label", matches: byLabel };
-  return { status: "not-found", hosts };
-}
-function getConfigDir() {
-  return CONFIG_DIR;
-}
-
-export {
-  safeJsonParse,
-  safeReadJsonFile,
-  normalizeUrl,
-  getSandboxRuntimeRoot,
-  isAeSandboxRuntime,
-  getFallbackCliToken,
-  loadConfig,
-  saveConfig,
-  getActiveHost,
-  setActiveHost,
-  addHost,
-  updateHostLabel,
-  removeHost,
-  listHosts,
-  resolveHostSelector,
-  getConfigDir
-};