@thinkingai/ae-cli 6.0.46 → 6.0.48-customer.1

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

@@ -66,12 +66,14 @@ Each mapped system field carries a value spec, enforced at both inspect (warning
 | Field | Value spec | On violation (convert) |
 | --- | --- | --- |
 | `#account_id` / `#distinct_id` | Non-empty string, at most 128 characters | Row error `MISSING_USER_ID` (absent) / `USER_ID_TOO_LONG` (>128) |
-| `#event_name` | `^[a-z][a-z0-9_]{0,49}$` (lowercase snake_case, letter-leading, ≤50 chars) | Row error `INVALID_EVENT_NAME` |
+| `#event_name` | `^[A-Za-z][A-Za-z0-9_]{0,49}$` (letter-leading letters/digits/underscore, ≤50 chars; lowercase by default, uppercase kept only on user request) | Row error `INVALID_EVENT_NAME` |
 | `#time` | One of the supported formats, within 3 years back / 3 days forward | Row error `INVALID_TIME` / `TIME_OUT_OF_RANGE` |
 | `#ip` | Valid IPv4 or IPv6. Event data only | Field skip `INVALID_IP`; a private/LAN IP is kept and reported — AE cannot geolocate it |
 | `#zone_offset` | Integer -12..14 (or an IANA name for `zone_offset_value`). Event data only | Row error `INVALID_ZONE_OFFSET` |
 | `#uuid` | Standard 36-character UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Both data kinds | Field skip `INVALID_UUID` |
 
+Event-name case is decided entirely by the mapping, never by the CLI — the CLI performs no case conversion and has no flag for it. The name AE receives is the source `event_name_field` value (or `default_event_name` when there is no event column), optionally replaced by a `value_mapping.event_name` target; `data-integration plan --event-name` passes each name through unchanged. Lowercase is the default: lowercase the name when writing the mapping (a `value_mapping.event_name` entry such as `Purchase` → `purchase`, or a lowercase `default_event_name`). To keep uppercase, skip that lowercasing: leave a legal uppercase source value unmapped so it passes through, write an uppercase `value_mapping.event_name` target only when the source value is not itself a legal name (e.g. `购买` → `Purchase`), or write an uppercase `default_event_name` / `--event-name`.
+
 A field skip is not a row failure: the row is kept with its other fields, and the count is reported in `manifest.output.skipped_fields` so the agent tells the user at the end. `#uuid` is never auto-generated — it comes only from a mapped source column.
 
 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.
@@ -147,7 +149,8 @@ Values with an explicit offset or `Z` are parsed by the JavaScript `Date` constr
 - 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.
+- Event names begin with a letter and are at most 50 characters; lowercase is the default, uppercase is kept only when the user asks to preserve it.
+- Property names are lowercase snake_case (letter-leading, 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`, `object`, or `array_row`.
 - Text is at most 2 KB; numbers stay within -9E15..9E15.

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

@@ -22,6 +22,28 @@ Classification order:
 
 Aggregated metrics, pivot tables, cross-tabs, model outputs, free-form documents, and records without real identity/time should normally use local analysis.
 
+### Time coverage is not native granularity
+
+A parseable time column establishes only when the rows are stamped, not what period each metric
+covers. A daily report and a cumulative snapshot both look like one row per user per point in time,
+so they satisfy every condition above and are then ingested as per-period events — inflating totals
+in a way that stays invisible in ratios, because numerator and denominator scale together.
+
+Native granularity must come from the user, a data dictionary, or a complete period structure in the
+data itself. Do not infer it from the file name, the first/last date, the interval between rows, or
+the row count; none of those is evidence.
+
+When the data carries numeric columns and any of the following holds, ask the user to state whether
+each row's value is the amount that occurred in that period or the total accumulated up to that
+point, and do not proceed until they answer:
+
+- Paired start/end time columns (`start_date`/`end_date`, `period_begin`/`period_end`).
+- Values for one identity that never decrease over time.
+- Column names carrying a to-date sense (`cumulative`, `total`, `ltv`, `累计`, `总`).
+
+An unanswered question, a cumulative snapshot, or overlapping periods route to local analysis
+instead.
+
 ## Route to local analysis
 
 Choose local analysis when:
@@ -29,6 +51,7 @@ 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.
+- The rows are a cumulative snapshot, or their native granularity could not be established.
 - Conversion would invent semantics or discard important structure.
 - The user declines an uncertain mapping or destination.
 

package/skills/ae-dataops/SKILL.md

@@ -20,6 +20,7 @@ The AE Data Development and Operations domain provides capabilities for data war
 | `dataops_flow` | Flow creation, node deletion, and orchestration | `dataops-flow-create` |
 | `dataops_flow` | Flow execution and monitoring | `dataops-flow-monitor` |
 | `dataops_operations` | Operations instance search, details, and task logs | `dataops-flow-monitor` |
+| `dataops_operations` | Backfill job creation, full draft update, deletion, execution, plans, stop, and rerun | `dataops-backfill` |
 | `dataops_ide` | Data exploration and SQL queries | `dataops-query` |
 | `dataops_integration` | Datasource and data integration | `dataops-integration` |
 
@@ -63,6 +64,7 @@ You must understand the following key concepts before use, otherwise errors are
 |----|--------|-------------|
 | **executeId** | Returned by `dataops_flow +execute_flow` | Early stop handle before the scheduler `flowInstanceId` is available |
 | **flowInstanceId** | Returned by `dataops_operations +search_flow_instances` | Operations perspective instance inspection and stop |
+| **jobId** | Returned by `dataops_operations +create_backfill_job` or `+search_backfill_jobs` | Persistent backfill job detail and lifecycle actions |
 
 ### Environment and Defaults
 
@@ -73,6 +75,8 @@ You must understand the following key concepts before use, otherwise errors are
 | `dataops_operations +get_flow_instance_detail` | Instance detail | Inspect one instance DAG and task statuses |
 | `dataops_operations +get_task_instance_detail` | Task detail/logs | Inspect one task and include logs only when needed |
 | `dataops_operations +stop_flow_instance` | Instance stop | Stop by exactly one of `executeId` or `flowInstanceId` |
+| `dataops_operations +list_backfill_flows` | Backfill source discovery | Returns eligible PROD flows and whether ST is required |
+| `dataops_operations +search_backfill_jobs` | Backfill job search | Filter persistent jobs and obtain `jobId` |
 
 ### Schema Naming Rules
 
@@ -92,6 +96,8 @@ You must understand the following key concepts before use, otherwise errors are
 Create DEV Flow → Create/Update DEV SQL, Integration, Workflow Instance Check, or Task Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
+Backfill lifecycle: Discover eligible PROD flow → Create or fully update DRAFT job → Run explicitly → Search / inspect plans → Stop or rerun the complete job; delete only after target inspection
+
 ### CRON Format (6 fields)
 
 `second minute hour day month weekday` — Note: one more "second" field than standard 5-field format.
@@ -115,6 +121,7 @@ Choose the appropriate scenario skill based on user intent to get complete step-
 | Create flow, add or delete nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, delete task node, release, cron, scheduled execution |
 | View execution status, troubleshoot failures, view logs | `dataops-flow-monitor` | execute flow, running instance, monitor, logs, stop, DAG, troubleshoot |
 | Search operation instances across a space | `dataops-flow-monitor` | operations instance, flow instance search, status statistics, owner statistics |
+| Create or operate a persistent multi-date backfill job | `dataops-backfill` | backfill, fill historical data, base date range, backfill plans, stop backfill, rerun backfill |
 | Create datasource, configure sync solution, execute sync | `dataops-integration` | datasource, sync, integration, field mapping, data ingestion, MySQL, ClickHouse, DatabricksJdbc |
 | Browse metadata, search tables, execute SQL queries | `dataops-query` | query, SQL, data exploration, search tables, view table structure, IDE, catalog, select |
 | Create tables and views | `dataops-table` | create table, table creation, view, data dictionary, table details, DDL |
@@ -155,13 +162,16 @@ Flow orchestration is divided into two scenario skills: **creation and configura
 
 **Lifecycle: DEV configuration and preview → Release to PROD → PROD manual execution and operations troubleshooting**
 
-Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md).
+Detailed creation/configuration commands live in [`references/dataops-flow-create.md`](references/dataops-flow-create.md). Detailed execution, monitoring, operation instance, task log, and stop commands live in [`references/dataops-flow-monitor.md`](references/dataops-flow-monitor.md). Persistent multi-date backfill jobs live in [`references/dataops-backfill.md`](references/dataops-backfill.md).
 
 Key constraints:
 - Create and update tasks in DEV, preview/release before PROD execution.
 - Treat `+delete_task` as high-risk: verify the target with `+get_flow_overview`, preview with `--dry-run`, and use `--yes` only after explicit user confirmation. Deletion affects DEV; release the flow to apply it to PROD.
 - `+execute_flow` always runs PROD; it returns `executeId` for early stop.
 - Prefer `flowInstanceId` from operations search for stable inspection and troubleshooting.
+- A backfill job is persistent and batches multiple base dates; do not emulate it by looping `+execute_flow`.
+- Create and run backfill jobs as separate steps. `+rerun_backfill_job` reruns the complete job, not only failed plans.
+- `+update_backfill_job` replaces a DRAFT job's complete configuration; inspect the job first and do not treat it as a partial patch. Treat `+delete_backfill_job` as high-risk and preview it with `--dry-run` before confirmation.
 - Reference workspace parameters in task SQL as `${paramKey}`.
 
 ---

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

@@ -0,0 +1,135 @@
+---
+name: dataops-backfill
+version: 1.0.0
+description: "Backfill job lifecycle: discover eligible PROD flows, create or update drafts, delete jobs, run jobs, inspect plans, stop running jobs, and rerun complete jobs."
+metadata:
+  requires:
+    bins: ["ae-cli"]
+---
+
+# DataOps Backfill Jobs
+
+> **Prerequisites:** Read [`ae-dataops/SKILL.md`](../SKILL.md) for authentication, output, and safety rules.
+
+A backfill job is a persistent operations object that runs one PROD task flow for multiple base dates. It is not a single manual flow execution and is not a retry of an existing failed flow instance.
+
+## Lifecycle
+
+### 1. Discover an eligible PROD flow
+
+```bash
+ae-cli dataops_operations +list_backfill_flows --spaceCode "${spaceCode}"
+```
+
+Use only a returned flow whose `completeDataInfo.canRun` is true. When `completeDataInfo.hasSt` is true, pass `--stTime` while creating the job.
+
+### 2. Create a draft
+
+Always pass the backfill date range. For manual selection, also pass `--completeDates`; every selected date must be inside that inclusive range.
+
+```bash
+# Range mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07"
+
+# Custom-date mode
+ae-cli dataops_operations +create_backfill_job --spaceCode "${spaceCode}" \
+  --jobName "Selected dates" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-07" \
+  --completeDates '["2026-08-01","2026-08-03"]'
+```
+
+Creation returns a `DRAFT` job and does not run it. Defaults are `jobType=TASK_ALL`, `failureStrategy=END`, `parallel=true`, `reverse=false`, `step=1`, and `unit=DAY`. For `TASK_ONLY`, `TASK_PRE`, or `TASK_POST`, also pass `--startNode`.
+
+### 3. Update a draft when needed
+
+Update is a complete replacement, not a partial patch. Inspect the DRAFT job first, then pass `--jobId`, `--jobName`, `--flowCode`, and the complete date and strategy configuration just as for creation. Updating does not run the job.
+
+```bash
+ae-cli dataops_operations +update_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --jobName "Revised August backfill" --flowCode ${flowCode} \
+  --startDate "2026-08-01" --endDate "2026-08-10" \
+  --failureStrategy END --parallel true --reverse false
+```
+
+### 4. Run the draft explicitly
+
+```bash
+ae-cli dataops_operations +run_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+### 5. Search jobs and inspect plans
+
+```bash
+ae-cli dataops_operations +search_backfill_jobs --spaceCode "${spaceCode}" \
+  --status "RUNNING,FAIL,SUCCESS" --pageNum 1 --pageSize 20
+
+ae-cli dataops_operations +get_backfill_job_detail --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Detail returns the job and its plans together. A draft has an empty plan list.
+
+### 6. Stop, rerun, or delete
+
+Stopping affects every unfinished plan in the running job. Inspect the job, preview the request, obtain explicit confirmation, and then pass `--yes`.
+
+```bash
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+# After explicit confirmation, execute the same target; the CLI prompts before dispatch.
+ae-cli dataops_operations +stop_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Rerun applies to every plan only when the job is `FAIL` or `STOP`. A `SUCCESS` job cannot be rerun. Rerun reuses the same job and does not create a new backfill job. The CLI does not support rerunning only failed plans.
+
+```bash
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +rerun_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+Deletion is high-risk. The server accepts only supported `DRAFT`, `FAIL`, or `SUCCESS` jobs. Inspect the exact target and preview the scoped request before confirmation; the CLI sends only `spaceCode` and `jobId` and does not pre-query or guess state.
+
+```bash
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId} --dry-run
+ae-cli dataops_operations +delete_backfill_job --spaceCode "${spaceCode}" \
+  --jobId ${jobId}
+```
+
+## Command Reference
+
+| Command | Purpose | Flags |
+|---|---|---|
+| `+list_backfill_flows` | List eligible PROD flows | `--spaceCode` |
+| `+create_backfill_job` | Create a draft | `--spaceCode` `--jobName` `--flowCode` `--startDate` `--endDate`; optional in-range `--completeDates`, scope, failure, parallel, order, and ST flags |
+| `+update_backfill_job` | Replace a DRAFT job's complete configuration | `--spaceCode` `--jobId` `--jobName` `--flowCode` and the same complete configuration as create |
+| `+delete_backfill_job` | Delete a supported job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+run_backfill_job` | Run a draft | `--spaceCode` `--jobId` |
+| `+search_backfill_jobs` | Search jobs | `--spaceCode` plus optional keyword, date, type, status, owner, sort, and paging filters |
+| `+get_backfill_job_detail` | Get job and plans | `--spaceCode` `--jobId` |
+| `+stop_backfill_job` | Stop a running job | `--spaceCode` `--jobId`; high-risk, requires confirmation or `--yes` |
+| `+rerun_backfill_job` | Rerun the complete job | `--spaceCode` `--jobId` |
+
+Statuses are `DRAFT`, `RUNNING`, `STOP`, `FAIL`, `SUCCESS`, and `READY_STOP`. Range units are `DAY`, `WEEK`, and `MONTH`. Custom dates must be a non-empty JSON array of unique `yyyy-MM-dd` strings inside the configured date range.
+
+## Transport Status
+
+Transition status: transitional
+
+Owning module: Gaia operations
+
+Current transport: DataOps CLI REST
+
+Covered tools: `operations_list_backfill_flows`, `operations_create_backfill_job`, `operations_update_backfill_job`, `operations_delete_backfill_job`, `operations_run_backfill_job`, `operations_search_backfill_jobs`, `operations_get_backfill_job_detail`, `operations_stop_backfill_job`, and `operations_rerun_backfill_job`
+
+Gateway target: TBD after the DataOps operations Capability Gateway schema review
+
+Review after: 2026-11-20
+
+Exit condition: Migrate these commands after Gaia exposes equivalent capabilities and the command contract tests pass against the Capability Gateway transport.

package/skills/ae-engage/SKILL.md

@@ -585,6 +585,9 @@ For task draft creation or update, use this workflow:
    and every-completion events use count/eq/1. Completion target and experiment main-goal event
    filters must not use properties whose metadata `select_type` is `datetime`. Never construct
    persisted QP fields.
+   Select the audience by delivery side: server-side channels allow custom (`1`) or existing (`2`)
+   and reject all users (`3`); `client_push` (`channelType=3`) allows custom (`1`) or all users (`3`)
+   and rejects existing (`2`). Do not infer audience support from `triggerType` alone.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 

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

@@ -36,12 +36,16 @@ compounds when reusing `definition_request`; flattening them changes audience se
 For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
 from the third step onward when its window must be measured from step 1.
 
-For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
+For server-side existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
 ```bash
 ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cluster_name>"]'
 ```
 
+Server-side channels allow custom (`1`) or existing (`2`) audiences and reject all users (`3`).
+`client_push` (`channelType=3`) allows custom (`1`) or all users (`3`) and rejects existing (`2`).
+Always pass `channelType` in `context` so the guide can validate this matrix.
+
 4. Build the final grouped `save_task.req`.
 5. Submit with `ae-cli engage-task task save --project-id <projectId> --req '{...}'`.
 

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

@@ -245,6 +245,12 @@ Use the guide to decide which audience shape applies:
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
 - `targetClusterType=3`: all users, forbids `definitionRequest` and `clusterKey`
 
+Audience availability depends on delivery side:
+
+- Server-side channels support `targetClusterType=1` (custom) and `2` (existing), but not `3` (all users).
+- `client_push` (`channelType=3`) supports `targetClusterType=1` (custom) and `3` (all users), but not `2` (existing).
+- Determine the delivery side from the selected real channel; do not infer audience support from `triggerType` alone.
+
 For a custom audience, pass the semantic definition directly. Do not create an intermediate
 cluster or copy persisted QP.
 

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

@@ -79,7 +79,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
 > When a localized label is needed, inspect `src/tracking/i18n` and use the existing resource key/value; do not invent translations from the model.
 > If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.
-> Only identifier fields like `event_name`, `prop_name` remain in English snake_case (canonical format).
+> Only identifier fields like `event_name`, `prop_name` remain in English. Property names are `snake_case`; event names are lowercase by default, uppercase only when the user asks to preserve it.
 > This skill only cares about command behavior, not internal implementation.
 
 ---
@@ -210,7 +210,7 @@ Based on user selection, determine source material type and record to `meta.sour
    | Severity | Examples | Handling | User Action |
    |---|---|---|---|
    | 🔧 **Minor** (auto-fixable) | `display_name` duplicate, `array_row` sub-property inconsistency, event name duplicate | `--fix` auto-fixes, writes to `draft.json`. Inform user of what was fixed. | None (informed) |
-   | ⚠️ **Medium** (needs confirmation) | snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
+   | ⚠️ **Medium** (needs confirmation) | property name snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |
    | 🛑 **Severe** | File cannot be parsed, or events array is empty after import | Reject. Tell user the specific issue. User fixes **original file** and re-imports. | Fix original file |
 
    **Medium issue confirmation format**:
@@ -219,7 +219,7 @@ Based on user selection, determine source material type and record to `meta.sour
 
    | # | Issue | Location | Current | Suggested |
    |---|-------|----------|---------|------------|
-   | 1 | snake_case | event_name | UserLogin | user_login |
+   | 1 | snake_case | event_name | UserLogin | user_login (keep UserLogin only if the user asked to preserve case) |
    | 2 | snake_case | prop_name | vipLevel | vip_level |
    | 3 | invalid type | property "level" | integer | number |
 
@@ -242,7 +242,7 @@ Based on user selection, determine source material type and record to `meta.sour
    - **Events**: Player interaction actions (click/swipe/trigger), scene transitions, game state changes (start/pause/end), business flow nodes (purchase/upgrade/unlock)
    - **Event Properties**: Action parameters (bullet type/enemy level/item ID), state values (score/HP/coins), context (level ID/difficulty/mode)
    - **User Properties**: Persistent state (level/experience/VIP/cumulative spend)
-5. Map extracted results to AE naming conventions (`snake_case` event names + `display_name` in user's language)
+5. Map extracted results to AE naming conventions (event names lowercase by default, uppercase only on request; property names `snake_case`; + `display_name` in user's language)
 6. Confirm extracted results with user, supplement missing items
 
 **Business Dimension Confirmation**:
@@ -386,7 +386,7 @@ When the user selects the **Data sample / file profile** option (`source_type =
 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).
+   - Naming: `snake_case` property names, event names lowercase by default (uppercase only on request) + `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).
@@ -656,7 +656,7 @@ Draft
 **Property types** (enum): `string` / `number` / `bool` / `datetime` /
 `object` (single object, with sub-properties) / `array_row` (object array, supports `parent.child` nesting) / `array_string` (string array)
 
-**Naming rules**: Event names / property names must be `snake_case`; use `display_name` field for human-readable names.
+**Naming rules**: Property names must be `snake_case`; event names are lowercase by default, and uppercase is kept only when the user asks to preserve it. Use `display_name` for human-readable names.
 
 ### 1.2 Merge Source Materials
 
@@ -817,7 +817,8 @@ AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae
 |---|---|---|
 | Display name uniqueness | Within same property pool, `display_name` must not repeat | ✅ Add distinguishing prefix |
 | Object array consistency | Same `array_row` across different events must have identical sub-properties | ✅ Fill missing sub-properties |
-| snake_case | Event/property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Property name snake_case | Property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |
+| Event name format | Event names match `^[A-Za-z][A-Za-z0-9_]*$`; lowercase by default, uppercase kept on request | ❌ Manual fix needed |
 | Property name uniqueness | Property names must not repeat | ❌ Manual fix needed |
 | Event name uniqueness | Event names must not repeat | ✅ Remove later duplicates |
 
@@ -1255,7 +1256,7 @@ Continue append (without fixing) / Modify draft / Switch to replace?
 
 #### Conflict Type B: Same-name events (advisory)
 
-AE merge-by-name: Same-name events are not overwritten; new-name events are added.
+AE merge-by-name: Same-name events are not overwritten; new-name events are added. Event names are case-sensitive (`Purchase` ≠ `purchase`) — changing only the case creates a new event, not a rename.
 
 **Detection logic**:
 

package/skills/ae-generate-tracking-plan/references/business-dimension-mapping.md

@@ -434,7 +434,7 @@
 
 - 必须有 ≥2 个自定义属性
 - 必须标注事件标签（模块归属）和采集端
-- 命名符合 snake_case
+- 命名符合 snake_case（事件名默认小写，用户要求保留大写时按用户要求）
 
 ---
 

package/skills/ae-kb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-kb
 version: 1.0.0
-description: "AE/TE knowledge base CLI manual for creating, querying, LLM-powered ask, listing accessible knowledge bases, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source display names, JSON payload shapes, or URL formats."
+description: 'AE/TE knowledge base CLI manual for creating, importing read-only compiled snapshots, querying, LLM-powered ask, listing accessible knowledge bases and their sources, deterministic index/grep/read retrieval, checking status, uploading, compiling, schema generation, URL sources, source deletion, and knowledge base deletion. Use when the user asks to manage TE/AE/ThinkingEngine knowledge bases, import a compiled Markdown ZIP snapshot, upload documents or URLs to a knowledge base, query knowledge, ask knowledge bases with an LLM, list accessible knowledge bases or source metadata, inspect knowledge base indexes, search knowledge base pages, read a specific knowledge base page, check knowledge base status, generate schemas, compile knowledge, remove sources, or delete a knowledge base. To choose which knowledge base is worth searching, use the ae-kb-discovery skill first; this skill runs the retrieval once a target is chosen. Must use ae-cli kb commands and must not guess knowledge base names, scopes, page paths, source IDs, source display names, JSON payload shapes, or URL formats.'
 ---
 
 # ae-kb
@@ -14,11 +14,11 @@ ae-cli kb +<command> [options]
 
 ## Global Rules
 
-- Use this skill for TE/AE knowledge base tasks: create, query, ask with LLM, list accessible knowledge bases, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
+- Use this skill for TE/AE knowledge base tasks: create, import a compiled snapshot, query, ask with LLM, list accessible knowledge bases and their sources, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
 - **Searching a knowledge base for an answer is the most common task. If that is what you are doing, go straight to [Explore Knowledge Base Pages](#explore-knowledge-base-pages) and read [`references/query-workflow.md`](references/query-workflow.md) first — it is the retrieval procedure. The other commands below are for managing knowledge bases, not answering from them.**
 - Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
-- Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
+- Do not invent knowledge base names, scopes, source IDs, source display names, or JSON payloads. Ask the user or query known context when values are missing.
 - When building a `--sources` ref (or `+read --source`), copy the exact `scope` and `name` from `+list` output — run `ae-cli kb +list` first when the scope of a named knowledge base is unknown.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.
 - Successful commands return JSON by default. Use `--format table` only when a table is easier for a human to scan. Envelope may include optional `_notice.host_compat`.
@@ -33,16 +33,19 @@ ae-cli kb +<command> [options]
 | `+ask` | read | LLM-powered Q&A over knowledge bases; for multi-page synthesis or multi-hop questions. |
 | `+ask-status` | read | Query the current status of an ask execution by `--execution-id` without polling. |
 | `+list` | read | List accessible knowledge bases filtered by buildStatus (default: compiled). |
+| `+list-sources` | read | List source metadata for one knowledge base so exact source identifiers can be discovered safely. |
 | `+index` | read | List accessible knowledge bases and their `index.md` navigation maps. |
 | `+grep` | read | Keyword-search knowledge base pages and return matched lines with context. |
 | `+read` | read | Read a full knowledge base page, a line window, or (with `--outline`) only the page heading tree. |
 | `+new` | write | Create a new personal or company knowledge base. |
+| `+import` | write | Import a compiled Markdown ZIP as a personal read-only snapshot. |
+| `+import-status` | read | Query one snapshot import task by `--request-id` without polling. |
 | `+add` | write | Upload local files, a non-recursive directory, or HTTP(S) pages converted to markdown. |
 | `+url` | write | Upload a URL source directly with optional display name and parsing instruction. |
 | `+schema` | write | Generate the compile schema for a knowledge base. |
 | `+compile` | write | Compile a knowledge base in incremental or full mode. |
 | `+status` | read | Query the current status of a knowledge base. |
-| `+rm-source` | write | Delete one source file from a knowledge base by display name. |
+| `+rm-source` | high-risk-write | Delete one source from a knowledge base by stable ID; exact display name is legacy compatibility only. |
 | `+remove` | write | Delete an entire knowledge base. |
 
 ## Common Workflows
@@ -67,6 +70,36 @@ Optional fields:
 - `--project-id`: optional project ID to bind.
 - `--project-name`: optional project display name.
 
+### Import a Compiled Snapshot
+
+Use `+import` only for a ZIP whose root contains `index.md` and at least one
+`wiki/**/*.md` page. The server validates all archive paths, limits, UTF-8 text, and Wiki links.
+
+```bash
+ae-cli kb +import \
+  --file ./knowledge-base.zip \
+  --name "Imported handbook" \
+  --description "Compiled documentation snapshot" \
+  --tags '["docs","handbook"]'
+
+# The submission returns requestId + queued. Query one snapshot later:
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- The result is always a `personal` read-only snapshot; there is no `--scope`, `--force`, or replace option.
+- Imported snapshots support list, Index/Wiki reading, grep/read, Ask, and deletion. They do not expose source, Schema, usage, compile, member, settings, ownership-transfer, or company-publish operations.
+- The ZIP is limited to 50 MB and supports Markdown text only. Local images, attachments, other binaries, broken Wiki links, and ambiguous Wiki links are rejected by the server.
+- Submission returns `{requestId, status: "queued"}` immediately. It does not wait for ZIP validation or publication.
+- `+import-status` returns one of `queued`, `running`, `succeeded`, or `failed`; success includes `knowledgeBaseId`, and failure includes a stable error code/message.
+- If a `requestId` was returned, query it before retrying. If no request ID was received, run `ae-cli kb +list` before retrying the same name. A repeated same-name import is rejected.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Import API
+- Current transport: authenticated KB external REST through `kbUpload` for submission and `kbApi` for status lookup.
+- Gateway target: TBD (`kb.snapshot.import` proposed)
+- Review after: 2026-12-01
+- Exit condition: migrate to a typed Gateway capability when the equivalent multipart import capability is available, or remove this command if dynamic Gateway execution provides the same file-handling and output contract.
+
 ### Upload Files or Directories
 
 Use `+add` when sources are local files, local directories, or pages that should be fetched and converted to markdown before upload.
@@ -107,7 +140,17 @@ Generate the schema first when the knowledge base needs a compile schema.
 ae-cli kb +schema --name engineering-handbook
 ```
 
-Use `--force` only to recover a stuck `generating` status. Use `--model` only when the user provides the model display name.
+Use `--force` only when `+status` reports `schema_generating` and the user explicitly wants to replace the current generation attempt. The replacement may consume additional tokens. Use `--model` only when the user provides the model display name.
+
+To add one-time guidance for this generation without changing stored knowledge base metadata, pass `--custom-instructions`. The server trims the value, treats whitespace-only input as absent, and accepts up to 10,000 Unicode characters. Do not include secrets or credentials.
+
+```bash
+ae-cli kb +schema \
+  --name engineering-handbook \
+  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"
+```
+
+Use `--dry-run` to inspect the request body before sending it. While generation is running, a request without `--force` is idempotent only when it supplies no new model or effective custom instructions; otherwise it fails with `KB_SCHEMA_GENERATION_IN_PROGRESS`. With `--force`, the selected model and custom instructions apply to the replacement attempt. Invalid text fails with `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID`.
 
 Compile after sources and schema are ready:
 
@@ -213,9 +256,34 @@ ae-cli kb +read \
   --limit 60
 ```
 
+### List Sources
+
+List sources first to discover the stable identifier for the intended source:
+
+```bash
+ae-cli kb +list-sources --name engineering-handbook
+```
+
+Copy the exact `id` from the response into `+rm-source`. Do not guess a source ID from a local filename, URL, display name, or an older upload response.
+
+- Transition status: transitional
+- Owning module: te-claude External Knowledge Base Sources API
+- Current transport: authenticated KB external REST through `kbApi`.
+- Gateway target: TBD (`kb.source.list` proposed)
+- Review after: 2026-12-03
+- Exit condition: migrate to a typed Gateway capability when an equivalent source-list capability is available, or remove this command if dynamic Gateway execution provides the same discoverability and safe output contract.
+
 ### Remove One Source
 
-Use `+rm-source` only when the source display name is known exactly.
+Use `+rm-source --id` with the exact ID returned by the current `+list-sources` response. This is a `high-risk-write`; keep the interactive confirmation unless the user has explicitly authorized `--yes`.
+
+```bash
+ae-cli kb +rm-source \
+  --name engineering-handbook \
+  --id cm-source-id
+```
+
+`--display-name` is retained for legacy compatibility only when a stable source ID is unavailable:
 
 ```bash
 ae-cli kb +rm-source \
@@ -223,7 +291,7 @@ ae-cli kb +rm-source \
   --display-name kb-1780046712-guide.md
 ```
 
-If the user only gives a loose source name, do not guess. Ask for the exact uploaded display name.
+If the user only gives a loose source name, do not guess a source ID. Run `+list-sources`, identify the intended row from returned metadata, and ask only when multiple rows remain ambiguous.
 
 ### Delete a Knowledge Base
 
@@ -316,6 +384,30 @@ ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."]
 ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]'
 ```
 
+### `+import`
+
+```bash
+ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]
+```
+
+- `--file`: required local `.zip` file.
+- `--name`: required personal knowledge-base name, up to 30 characters.
+- `--description`: optional, up to 200 characters.
+- `--tags`: optional JSON array, max 2 unique tags, each up to 15 characters.
+- `--project-id`: optional project binding.
+- Scope and terminal build state are generated by the server and cannot be supplied by the client.
+- Output: `{requestId, status: "queued"}`. Use `+import-status`; the command does not poll.
+
+### `+import-status`
+
+```bash
+ae-cli kb +import-status --request-id <requestId>
+```
+
+- `--request-id`: required ID returned by `+import`.
+- Output: `{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}`.
+- Returns a single snapshot and does not poll. A failed import is returned as `status: "failed"` with its stable error code/message; an unknown or inaccessible request exits non-zero.
+
 ### `+url`
 
 ```bash
@@ -325,9 +417,14 @@ ae-cli kb +url --name "<name>" --url "https://example.com/page" [--display-name
 ### `+schema`
 
 ```bash
-ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"]
+ae-cli kb +schema --name "<name>" [--force] [--model "<model displayName>"] [--custom-instructions "<one-time guidance>"]
 ```
 
+- `--custom-instructions`: Optional per-run schema-generation guidance. It is not persisted; whitespace-only input is omitted. The server allows at most 10,000 Unicode characters and rejects disallowed control characters. Do not include secrets or credentials.
+- `--force`: Replace the current attempt only when schema generation is already running and the user explicitly requests the replacement. The selected model and custom instructions apply to the new attempt, which may consume additional tokens.
+- `--dry-run`: Shows the same `customInstructions` request field that execution will send.
+- Errors: `KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID` means the field failed validation. `KB_SCHEMA_GENERATION_IN_PROGRESS` means generation is active and a request without `--force` supplied a new model or effective custom instructions.
+
 ### `+compile`
 
 ```bash
@@ -340,12 +437,26 @@ ae-cli kb +compile --name "<name>" [--mode incremental|full]
 ae-cli kb +status --name "<name>"
 ```
 
+### `+list-sources`
+
+```bash
+ae-cli kb +list-sources --name "<name>"
+```
+
+- `--name`: required knowledge base name.
+- Output: Safe source metadata including the stable `id` needed by `+rm-source`; raw paths, hashes, credentials, and source content are not returned.
+- Copy the exact `id` from the current response before deleting a source; never guess it.
+
 ### `+rm-source`
 
 ```bash
-ae-cli kb +rm-source --name "<name>" --display-name "<uploaded source display name>"
+ae-cli kb +rm-source --name "<name>" --id "<source-id>"
 ```
 
+- `--id`: preferred stable source identifier copied from `+list-sources`.
+- `--display-name`: legacy compatibility selector used only when an ID is unavailable.
+- If both are supplied, `--id` wins. The command removes one source only.
+
 ### `+remove`
 
 ```bash