@thinkingai/ae-cli 6.0.22 → 6.0.27

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

@@ -4,9 +4,9 @@ Create, edit, preview, or commit a flow canvas draft.
 
 Mapped command: `ae-cli engage +save_flow --project_id <projectId> --req '<req-json>'`
 
-> **Protocol v2 (current).** `save_flow` is now **operation-based**. The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — send `nodes` / `edges` instead. Posting a legacy `nodeList`/`edgeList` payload (or omitting `operation`) makes the backend reject the call with `Unsupported save_flow operation: null`.
+> **Protocol v2 (current).** `save_flow` is now **operation-based**. The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names -- send `nodes` / `edges` instead. Posting a legacy `nodeList`/`edgeList` payload (or omitting `operation`) makes the backend reject the call with `Unsupported save_flow operation: null`.
 
-The CLI passes your `--req` straight through to the backend (it only injects `projectId`). So everything in this document is about building the correct `req` object.
+The CLI injects `projectId` and rejects missing/unsupported `operation` values, legacy `nodeList`/`edgeList` fields, and the removed `sourceFlowUuid` clone mode; otherwise it passes your `--req` through to the backend. So everything in this document is about building the correct `req` object.
 
 ---
 
@@ -22,10 +22,11 @@ build  ──► status = ready_to_preview ──► preview ──► commit
 
 You still organize user requirements into an intermediate intent first, then map the intent to `nodes` / `edges`, then run the lifecycle.
 
-- `build`: assemble/edit a draft from `nodes` + `edges` (or `dsl`, or clone). Returns `ready_to_preview` (with `draftId`, `draftVersion`, `confirmToken`, `preview.mainPath`) or `need_input` (one more slot required).
+- `build`: assemble/edit a draft from `nodes` + `edges` (or topology-only `dsl`). Returns `ready_to_preview` (with `draftId`, `draftVersion`, `confirmToken`, `preview.mainPath`) or `need_input` (one more slot required).
 - `preview`: validate the draft; **re-issues** a fresh `draftVersion` + `confirmToken`.
 - `commit`: finalize the draft into a flow version using the **preview** `draftVersion` + `confirmToken`; returns the final `flowUuid`.
 - Always verify with `ae-cli engage +flow_detail --project_id <projectId> --flow_uuid <flowUuid>`.
+- To copy an existing flow, first call `+flow_detail`, convert the returned `nodeList` / `edgeList` into compact `nodes` / `edges`, then call `operation=build` as normal creation input. Do not pass `sourceFlowUuid`.
 
 ---
 
@@ -34,8 +35,9 @@ You still organize user requirements into an intermediate intent first, then map
 1. Identify the flow intent from the user input and produce a unified intent JSON.
 2. Run `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition` to obtain the condition cluster definition schema for assembling condition-related fields later.
 3. Run `ae-cli engage +channel_list --project_id <projectId>` to get the available channels and match real `channelId` values for touchpoint nodes. For `webhook_push`, also run `ae-cli engage +channel_detail` and use `data.config.paramsList` to build `contentList`.
-4. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
-5. `build` → resolve any `need_input` slot → `preview` → `commit`, then verify with `+flow_detail`.
+4. Query `ae-cli engage +flow_node_config_schema --node_type <type>` before constructing each non-trivial node config, then run `ae-cli engage +validate_flow_node_config --node_type <type> --operation_mode save_flow --config '<config-json-string>'` before placing the config into `nodes` or `nodeConfigs`.
+5. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
+6. `build` → resolve any `need_input` slot → `preview` → `commit`, then verify with `+flow_detail`.
 
 ---
 
@@ -54,7 +56,6 @@ You still organize user requirements into an intermediate intent first, then map
 | `nodes` | array | build | Compact nodes for structured build (see §7) |
 | `edges` | array | build | Compact edges for structured build (see §8) |
 | `dsl` | string | build | Topology-only: lines `node <id> <type>` and `edge <source> -> <target>` |
-| `sourceFlowUuid` | string | build | Clone an existing flow into a new draft |
 | `flowUuid` | string | build | Draft flow UUID for update-draft mode |
 | `parentFlowUuid` | string | build | Base version flow UUID for new-version mode |
 | `userIntent` | string | build | Natural-language intent (optional) |
@@ -69,6 +70,23 @@ You still organize user requirements into an intermediate intent first, then map
 
 `flowUuid` and `parentFlowUuid` are mutually exclusive; when creating a brand-new draft, provide neither.
 
+### Response Fields
+
+Common response fields include:
+
+| Field | Meaning |
+|---|---|
+| `status` | Draft state, such as `need_input`, `ready_to_preview`, `previewed`, or `committed` |
+| `draftId` / `draftVersion` | Server draft identity and version |
+| `selectedMode` | Server-selected authoring mode, such as structured build, wizard, or draft edit |
+| `confidence` / `reason` | Router confidence and explanation for the selected mode |
+| `nextSlot` | One missing slot to answer when `status=need_input` |
+| `preview` | Human-readable preview; use it for user confirmation |
+| `confirmToken` | Token returned by `preview`; required for `commit` |
+| `warnings` / `errors` | Soft warnings and hard validation failures |
+| `supportedOperations` | Server-advertised `build`, `preview`, and `commit` contract |
+| `result` | Commit result, including the final `flowUuid` when committed |
+
 ### Compact node (`nodes[]`)
 
 | Field | Required | Description |
@@ -86,7 +104,7 @@ You still organize user requirements into an intermediate intent first, then map
 | `source` | Yes | Upstream node ID |
 | `target` | Yes | Downstream node ID |
 | `edgeId` | No | Edge ID, unique within the canvas |
-| `sourceBranchId` | No | Branch ID for edges leaving a split/judge node |
+| `sourceBranchId` | No | Branch ID for edges leaving a split/judge node, or a push action node with two branch outgoing edges |
 | `config` | No | Edge business config as JSON string |
 
 ---
@@ -217,36 +235,47 @@ Inside action nodes: `channel_name` → real `channelId`; `content` → `content
 2. Any `branchId` later referenced by `edge.sourceBranchId` must be declared in that node's `config` first.
 3. Every path must eventually end at `exit_flow`.
 4. `config` may be a JSON object or a JSON string. (`targetClusterQp` inside it is usually a `JSON.stringify`'d string — see §9.)
+5. The backend normalizes some compatible input forms before validation: leading apostrophes on field names are stripped, property names are matched case-insensitively when unambiguous, `enableChannelTouchLimits` booleans become `1`/`0`, `targetClusterQp` relation strings `"0"`/`"1"` become numeric values inside the JSON string, and `clusterPredictCount: null` becomes `0`.
 
 ### 7.2 Common Node Types
 
 `single_trigger`, `repeat_trigger`, `event_trigger`, `event_split_flow`, `feature_split_flow`, `ab_split_flow`, `event_judge`, `feature_judge`, `message_push`, `wechat_push`, `webhook_push`, `time_control`, `exit_flow`.
 
+Before writing any config below, call `+flow_node_config_schema` for the exact node type. The backend schema is the source of truth for required fields, defaults, allowed enum values, submit-time requirements, and examples.
+
 ### 7.3 Common `config` Templates
 
+#### `single_trigger`
+
+```json
+{ "targetUserType": 2, "triggerTime": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "targetClusterName": "<existing clusterName>" }
+```
+
+For custom users, use `targetUserType=1` and fill `targetClusterQp` with the QP JSON string returned by the cluster QP workflow. For existing clusters (`targetUserType=2`), fill `targetClusterName` from a real current-project cluster list queried with the flow `tzOffset`; do not fill `targetClusterQp`. `clusterPredictCount` defaults to `0` and `clusterPredictTime` defaults to `""` when omitted.
+
 #### `repeat_trigger`
 
 ```json
-{ "targetUserType": 1, "startDate": "<YYYY-MM-DD>", "endDate": "<YYYY-MM-DD>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "crontab": "0 00 09 * * ?", "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterName": null, "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "targetClusterQp": "<JSON.stringify(qp)>" }
+{ "targetUserType": 1, "startDate": "<YYYY-MM-DD>", "endDate": "<YYYY-MM-DD>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "crontab": "0 00 09 * * ?", "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterName": null, "targetClusterQp": "<JSON.stringify(qp)>" }
 ```
 
-`entry.segment` → `targetClusterQp`; `entry.schedule` → `crontab` (common default `0 00 09 * * ?`).
+`entry.segment` → `targetClusterQp`; `entry.schedule` → `crontab` (common default `0 00 09 * * ?`). `clusterPredictCount` defaults to `0` and `clusterPredictTime` defaults to `""` when omitted. For existing clusters (`targetUserType=2`), fill `targetClusterName` from a real current-project cluster list queried with the flow `tzOffset`; do not fill `targetClusterQp`.
 
 #### `event_trigger`
 
 ```json
-{ "triggerType": 3, "targetUserType": 1, "realtime": 0, "clusterRefresh": 12, "clusterRefreshTime": null, "startDate": "<YYYY-MM-DD HH:mm>", "endDate": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "triggerRule": [ { "periodStart": "<startDate>", "periodEnd": "<endDate>", "periodTimeSymbol": "TS02", "dayStartTime": null, "startDay": null, "eventTriggerType": 0, "zoneoffset": 8, "events": [] } ], "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterQp": "<JSON.stringify(qp) or null>" }
+{ "triggerType": 3, "targetUserType": 1, "startDate": "<YYYY-MM-DD HH:mm>", "endDate": "<YYYY-MM-DD HH:mm>", "flowEndDate": "<YYYY-MM-DD HH:mm>", "triggerRule": [ { "periodStart": "<startDate>", "periodEnd": "<endDate>", "periodTimeSymbol": "TS02", "eventTriggerType": 0, "events": [] } ], "entryControlLimits": { "enableMultEntry": false, "disableConcurrentEntry": false }, "targetClusterQp": "<JSON.stringify(qp) or null>" }
 ```
 
-`entry.trigger_event` → `triggerRule[0].events`; generate `targetClusterQp` only when `entry.segment` exists.
+`entry.trigger_event` → `triggerRule[0].events`; generate `targetClusterQp` only when `entry.segment` exists. `triggerType` supports `3`, `4`, and `5`; `targetUserType=2` existing cluster is not supported for `event_trigger`; use `1` custom or `3` all users. For non-branch trigger rules, use `periodStart` / `periodEnd` / `periodTimeSymbol`. `realtime`, `clusterRefresh`, `clusterRefreshTime`, `clusterPredictTime`, and `triggerRule[].zoneoffset` can be omitted and are defaulted by the backend.
 
 #### `event_split_flow`
 
 ```json
-{ "splitFlowType": 1, "branchList": [ { "branchId": "<branchId>", "branchName": "<label>", "branchType": 1, "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": "<0 or -1>", "zoneoffset": 8, "events": [] } ] } ] }
+{ "splitFlowType": 1, "branchList": [ { "branchId": "<branchId>", "branchName": "<label>", "branchType": 1, "targetClusterType": 3, "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": "<0|-1|1|2>", "events": [] } ] } ] }
 ```
 
-`time_limit` → `delayTimeSymbol` + `delayTime`; `0` = happened, `-1` = not happened. Fallback branch keeps only `{ "branchId": "<branchId>", "branchType": 2 }`.
+`time_limit` → `delayTimeSymbol` + `delayTime`; `0` = happened, `-1` = not happened. For `branchType=1`, fill `targetClusterType`; use `3` for all users. If `targetClusterType` is not `3`, fill `clusterKey`. `occasionKeys` is optional, but each item must contain at least four colon-separated parts. Fallback branch keeps only `{ "branchId": "<branchId>", "branchType": 2 }` and must omit `triggerRule`.
 
 #### `feature_split_flow`
 
@@ -265,10 +294,10 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `event_judge`
 
 ```json
-{ "transferType": 1, "meetBranchId": "<meetBranchId>", "notMeetBranchId": "<notMeetBranchId>", "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": 0, "zoneoffset": 8, "events": [] } ] }
+{ "transferType": 1, "meetBranchId": "<meetBranchId>", "notMeetBranchId": "<notMeetBranchId>", "triggerRule": [ { "periodStart": "<YYYY-MM-DD HH:mm>", "periodEnd": "<YYYY-MM-DD HH:mm>", "periodTimeSymbol": "TS02", "eventTriggerType": 0, "events": [] } ] }
 ```
 
-`wait_time` → `delayTimeSymbol` + `delayTime` (default `30 minute` if unspecified).
+`event_judge` is a non-branch flow task. Use `periodStart`, `periodEnd`, and `periodTimeSymbol` in the A segment; use `delayTime` / `delayTimeSymbol` only for a B segment when the schema/example requires it. `eventTriggerType` supports `0`, `1`, and `2`.
 
 #### `feature_judge`
 
@@ -279,10 +308,10 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 #### `message_push` / `webhook_push`
 
 ```json
-{ "channelId": "<matched channelId>", "channelType": "<matched channelType>", "enableChannelTouchLimits": false, "isOccasionUp": false, "contentList": [ { "pushLanguageCode": "default", "content": [] } ], "processType": 1 }
+{ "channelId": "<matched channelId>", "channelType": "<matched channelType>", "contentList": [ { "pushLanguageCode": "default", "content": [] } ] }
 ```
 
-`channel_name` → real `channelId`; `content` → the param that best matches body text. When the param `type = TEXT`, also add `{ "config": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"<same as value>\"}]}]" }`. First `contentList` entry must use `"pushLanguageCode": "default"`; generate extra languages per `languages`.
+`channel_name` → real `channelId`; `content` → the param that best matches body text. `processType` defaults to `1`, `enableChannelTouchLimits` defaults to `0`, and `isOccasionUp` defaults to `false`. `enableChannelTouchLimits` may be supplied as a boolean for compatibility, but `normalizedConfigObject` will convert it to `1` or `0`. When the param `type = TEXT`, also add `{ "config": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"<same as value>\"}]}]" }`. `contentList[].content` should be a JSON array; validation also accepts a JSON-stringified array for compatibility. When the param `type = OBJ_ARRAY`, `value` must be a JSON array, and the item must copy the complete child field definition from `query_channel_detail data.config.paramsList[].objArray`. First `contentList` entry must use `"pushLanguageCode": "default"`; generate extra languages per `languages`.
 
 #### `wechat_push`
 
@@ -296,6 +325,8 @@ Fallback branch keeps only `branchId` + `branchType: 2`.
 { "controlType": 1, "timeUnit": "<minute|hour|day>", "timeUnitNum": "<number>" }
 ```
 
+`controlType=1` requires `timeUnit` + `timeUnitNum`; `2` requires `timePointStr`; `3` requires `rollTimeDayNum` + `timePointStr`; `4` requires `fixedDay` + `timePointStr`; `5` requires `relativeMonthLastDayNum` + `timePointStr`.
+
 `30 minutes` → `minute`+`30`; `2 hours` → `hour`+`2`; `1 day` → `day`+`1`.
 
 #### `exit_flow`
@@ -325,14 +356,17 @@ Minimum usable `config`: `{}`.
 | `single_trigger` / `repeat_trigger` / `event_trigger` | 1 | do not provide |
 | `event_split_flow` / `feature_split_flow` / `ab_split_flow` | one per branch | the corresponding `branchList[].branchId` |
 | `event_judge` / `feature_judge` | 2 | `meetBranchId` and `notMeetBranchId` |
-| `message_push` / `wechat_push` / `webhook_push` / `time_control` | 1 | do not provide |
+| `message_push` / `wechat_push` / `webhook_push` | 1 or 2 | omit for 1 outgoing edge; for 2 outgoing edges, use the node config's `meetBranchId` and `notMeetBranchId` |
+| `time_control` | 1 | do not provide |
 | `exit_flow` | 0 | do not provide |
 
 ### 8.4 Rules
 
 1. `source` / `target` must reference existing `node.id` values.
-2. Only edges leaving split/judge nodes carry `sourceBranchId`, and it must be a `branchId` already declared in the upstream node `config`.
-3. The graph must be a DAG (no cycles).
+2. Edges leaving split/judge nodes carry `sourceBranchId`. Push action nodes (`message_push`, `wechat_push`, `webhook_push`) may also carry `sourceBranchId` when they have exactly two outgoing edges.
+3. For push action nodes with one outgoing edge, omit `meetBranchId` / `notMeetBranchId`; if present, the backend ignores them.
+4. For push action nodes with two outgoing edges, set both `config.meetBranchId` and `config.notMeetBranchId`, and make the two `edge.sourceBranchId` values match them.
+5. The graph must be a DAG (no cycles).
 
 ---
 
@@ -436,7 +470,7 @@ ae-cli engage +save_flow --project_id 1 --req '{
   "flowDesc": "New user welcome flow",
   "groupId": 0, "tzOffset": 8, "versionType": 1,
   "nodes": [
-    { "id": "n1", "type": "single_trigger", "name": "Enter", "config": {} },
+    { "id": "n1", "type": "single_trigger", "name": "Enter", "config": { "targetUserType": 2, "triggerTime": "2026-03-31 19:00", "flowEndDate": "2026-04-04 18:00", "targetClusterName": "cohort_20260331_182643" } },
     { "id": "n2", "type": "exit_flow", "name": "End", "config": {} }
   ],
   "edges": [ { "source": "n1", "target": "n2" } ]
@@ -483,6 +517,7 @@ Output the complete `req` JSON for debugging plus a clear failure reason.
 | Symptom | Cause | Fix |
 |---|---|---|
 | `Unsupported save_flow operation: null` | Legacy `nodeList`/`edgeList` payload, or `operation` missing | Put `operation` = `build`/`preview`/`commit` in `req`, use `nodes`/`edges` |
+| `Flag --req.sourceFlowUuid is no longer supported` | Removed clone mode from an older protocol | Call `+flow_detail`, convert detail `nodeList`/`edgeList` into compact `nodes`/`edges`, then create with `operation=build` |
 | operation rejected (`SAVE`/`DRAFT`/`SUBMIT`/`mode`/`action`…) | Wrong field or wrong enum | `operation` is at `req.operation`; enum is only `build`/`preview`/`commit` |
 | `invalid_qp_relation: QP relation must be number 0 or 1` | `relation` sent as string | Use integer `0`/`1` |
 | `invalid_qp_leaf: QP property leaf must contain columnType/columnDesc` | userCondition leaf missing fields | Add `columnType` + `columnDesc` |
@@ -499,16 +534,17 @@ Output the complete `req` JSON for debugging plus a clear failure reason.
 ## 13. Most Common Mistakes
 
 1. **Legacy `nodeList`/`edgeList`** — use `nodes`/`edges` with `operation=build`.
-2. **Time units must be lowercase** — `day`, `hour`, `minute`, `week`, `month` (not `DAY`/`HOUR`).
-3. **Do not invent `channelId`** — get it from `ae-cli engage +channel_list`.
-4. **Define branch IDs before referencing them** — `edge.sourceBranchId` must already exist in the upstream node `config`.
-5. **`targetClusterQp` is usually a string** — `JSON.stringify` the QP object.
-6. **TEXT rich-text `config` must also be a string** — not an object.
-7. **`commit` uses preview's token/version** — not build's.
-8. **Do not merge branches again when `splitFlowType = 2`**.
+2. **Removed clone mode** — do not pass `sourceFlowUuid`; copy flows via `+flow_detail` and a fresh `operation=build` request.
+3. **Time units must be lowercase** — `day`, `hour`, `minute`, `week`, `month` (not `DAY`/`HOUR`).
+4. **Do not invent `channelId`** — get it from `ae-cli engage +channel_list`.
+5. **Define branch IDs before referencing them** — `edge.sourceBranchId` must already exist in the upstream node `config`; for two-edge push action nodes, use `meetBranchId` and `notMeetBranchId`.
+6. **`targetClusterQp` is usually a string** — `JSON.stringify` the QP object.
+7. **TEXT rich-text `config` must also be a string** — not an object.
+8. **`commit` uses preview's token/version** — not build's.
+9. **Do not merge branches again when `splitFlowType = 2`**.
 
 ---
 
 ## 14. One-Sentence Summary
 
-Drive `+save_flow` as a state machine — `build` (`nodes`/`edges`, not `nodeList`/`edgeList`) → resolve any `need_input` slots → `preview` (take its fresh `draftVersion` + `confirmToken`) → `commit` → verify with `+flow_detail`; keep QP `relation` integer, fill `columnType`/`columnDesc` on userCondition leaves and `quotaDesc`/`quota`/`analysisParams` on `taPropQuota`, and ensure touchpoint channels are enabled before referencing them.
+Drive `+save_flow` as a state machine — `build` (`nodes`/`edges`, not `nodeList`/`edgeList` or `sourceFlowUuid`) → resolve any `need_input` slots → `preview` (take its fresh `draftVersion` + `confirmToken`) → `commit` → verify with `+flow_detail`; keep QP `relation` integer, fill `columnType`/`columnDesc` on userCondition leaves and `quotaDesc`/`quota`/`analysisParams` on `taPropQuota`, and ensure touchpoint channels are enabled before referencing them.

package/skills/ae-engage/references/validate-flow-node-config.md

@@ -1,7 +1,7 @@
 # ae-engage +validate_flow_node_config
 
 
-Validate a single node configuration before saving a flow.
+Validate and normalize a single node configuration before placing it into a `save_flow` request.
 
 Mapped command: `ae-cli engage +validate_flow_node_config`
 
@@ -9,15 +9,38 @@ Mapped command: `ae-cli engage +validate_flow_node_config`
 
 | Flag | Type | Required | Description |
 |------|------|------|------|
-| `--node_type` | string | Yes | node type |
-| `--config` | string | Yes | node config JSON string |
-| `--operation_mode` | string | Yes | validation mode |
+| `--node_type` | string | Yes | Flow node type |
+| `--config` | string | Yes | Node config JSON object encoded as a string |
+| `--operation_mode` | string | Yes | Validation mode |
+
+## When To Use
+
+Use this after `+flow_node_config_schema` and before passing a config into `+save_flow`.
+
+The command validates one node config only; it does not validate the full canvas topology. It returns:
+
+- `valid`: whether the candidate config passed validation
+- `normalizedConfigObject`: backend-normalized config with defaulted fields
+- `errors`: hard validation failures to fix before calling `+save_flow`
+- `warnings`: issues that depend on live channel/template/config data
+
+Use `--operation_mode save_flow` for the current exposed MCP protocol. Use `save_submit_flow` only when you intentionally want stricter submit-time checks.
+
+Important current rules:
+
+- `event_trigger` / `event_judge` A segment: use `periodStart`, `periodEnd`, `periodTimeSymbol`; do not use branch-style `delayTime`.
+- `event_split_flow` branch segment: use `delayTime`, `delayTimeSymbol`, `targetClusterType`; omit `triggerRule` on default branches.
+- `event_trigger targetUserType=2` is invalid.
+- Push `OBJ_ARRAY.value` must be a JSON array, not a stringified array.
+- Push `contentList[].content` should be a JSON array, but a JSON-stringified array is accepted for compatibility.
+- Compatible inputs are normalized before validation: apostrophe-prefixed field aliases, case-insensitive property aliases, `enableChannelTouchLimits` booleans, string `"0"`/`"1"` QP relations inside `targetClusterQp`, and `clusterPredictCount: null`.
+- Missing defaults such as `clusterPredictCount`, `clusterPredictTime`, `processType`, and `zoneoffset` may be filled in `normalizedConfigObject`.
 
 ## Enum Notes
 
 ### `--node_type`
 
-Common node types include:
+Schema-backed node types include:
 
 - `single_trigger`
 - `repeat_trigger`
@@ -27,15 +50,10 @@ Common node types include:
 - `message_push`
 - `wechat_push`
 - `webhook_push`
-- `config_push`
-- `tag`
 - `time_control`
 - `feature_split_flow`
 - `event_split_flow`
-- `trigger_prop_split_flow`
-- `percent_split_flow`
 - `ab_split_flow`
-- `race_split_flow`
 - `exit_flow`
 
 ### `--operation_mode`

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

@@ -94,14 +94,14 @@ After user responds, record to `meta.scenario` and generate `meta.plan_name`.
 
 Before asking, decide whether the current runtime is an agent sandbox. The agent may judge this from runtime context such as sandbox-provisioned `cli-token.json`, restricted filesystem access, or absence of the user's local files. Do not ask the user just to decide sandbox visibility.
 
-Product document and Codebase are local-material options. **Hide both options in sandbox environments**. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
+Product document is available in sandbox environments **only for files that are readable inside the sandbox workspace**, including files the user attaches/uploads into the conversation workspace. It cannot read arbitrary local paths outside the sandbox unless those files are mounted or attached. Codebase is a local-material option and must be hidden in sandbox environments unless the codebase is already present in the readable workspace. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
 
 If **not** in a sandbox environment, ask exactly:
 
 ```text
 Choose your source material (up to 2):
 
-1 - Product document (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 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
@@ -114,10 +114,11 @@ If in a sandbox environment, ask exactly:
 ```text
 Choose your source material (up to 2):
 
-1 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
-2 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
+1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
+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
 
-Reply with number(s), e.g. 1 or 1,2. Select up to 2.
+Reply with number(s), e.g. 1 or 1,3. Select up to 2.
 ```
 
 Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
@@ -126,7 +127,7 @@ User can multi-select (max 2). Interpret numbers by the **visible list shown to
 
 Canonical source material options:
 
-- **Product document** (local path, image file, or folder; hidden in sandbox) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+- **Product document** (local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
 - **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 - **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 - **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
@@ -142,7 +143,8 @@ Based on user selection, determine source material type and record to `meta.sour
 | Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: template → codebase → prd → chat) |
 
 **Follow-up questions** (ask in selection order):
-- Product doc → ask **"What is the product document path? You can provide one or more paths, separated by commas or newlines (local paths, URLs, image files, or folders)"**
+- Product doc → if not in a sandbox environment, ask **"What is the product document path? You can provide one or more paths, separated by commas or newlines (local paths, URLs, image files, or folders)"**
+- Product doc → if in a sandbox environment, ask **"What is the product document path? You can provide one or more sandbox workspace paths, uploaded attachment paths, URLs, image files, or folders. You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available."**
 - Detailed description → If too vague, follow up on core features, user behaviors, business flows, monetization
 - Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic
 - Pre-built template → display matching templates for user confirmation

package/skills/ae-metadata/references/metadata_data_table_csv_write.md

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table csv-write --project-id <project_id> --operation create --input-file-id <input_file_id> --data-table-name <name> --columns '<columns_json>' --yes
+ae-cli metadata data-table csv-write --project-id <project_id> --operation create --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>' --yes
 ae-cli metadata data-table csv-write --project-id <project_id> --operation incremental_update --data-table-id <id> --input-file-id <input_file_id> --yes
 ae-cli metadata data-table csv-write --project-id <project_id> --operation replace_update --data-table-id <id> --input-file-id <input_file_id> --yes
 ```
@@ -18,12 +18,14 @@ ae-cli metadata data-table csv-write --project-id <project_id> --operation repla
 | `--operation` | Yes | `create`, `incremental_update`, or `replace_update`. |
 | `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
 | `--data-table-id` | For updates | Existing data table ID. |
-| `--data-table-name` | For create | Technical data table name. |
+| `--data-table-name` | No | Optional technical data table name. If supplied, use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable table name. |
 | `--description` | No | Table description. |
-| `--columns` | No | Column definitions JSON array. |
+| `--columns` | No | Column definitions JSON array. Preferred fields are `column_name`, `select_type`, and `column_desc`; CLI also accepts `name`, `type`, and `display_name` aliases. |
 
 ## Decision Rules
 
 - Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- Do not invent `input_file_id` or `data_table_id`; use upload/list outputs.
+- If you provide `--data-table-name`, it must include the project segment, for example `datatable_2_orders`.
 - This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.

package/skills/ae-metadata/references/metadata_data_table_sql_write.md

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table sql-write --project-id <project_id> --operation create --table-name <name> --columns '<columns_json>' --qp '<qp_json>' --strategy overwrite --yes
+ae-cli metadata data-table sql-write --project-id <project_id> --operation create --table-name datatable_<project_id>_<name> --columns '<columns_json>' --qp '<qp_json>' --zone-offset 8 --strategy overwrite --yes
 ae-cli metadata data-table sql-write --project-id <project_id> --operation update --data-table-id <id> --columns '<columns_json>' --qp '<qp_json>' --yes
 ```
 
@@ -15,13 +15,13 @@ ae-cli metadata data-table sql-write --project-id <project_id> --operation updat
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--operation` | Yes | `create` or `update`. |
-| `--columns` | Yes | Column definitions JSON array. |
+| `--columns` | Yes | Column definitions JSON array. Preferred fields are `column_name`, `column_type`, and `column_desc`; CLI also accepts `name`, `type`, and `display_name` aliases. |
 | `--qp` | Yes | SQL data table query plan JSON. |
 | `--data-table-id` | For update | Existing data table ID. |
-| `--table-name` | For create | Technical table name. |
+| `--table-name` | For create | Technical table name. Use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable name. |
 | `--remarks` | No | Table remarks. |
-| `--zone-offset` | No | Time zone offset such as `+08:00`. |
+| `--zone-offset` | No | Time zone offset in hours. For example, UTC+8 is `8` and UTC-5 is `-5`. Valid range: -12 to 14. |
 | `--strategy` | No | `overwrite` or `insert`. |
 | `--update-cron` | No | Scheduled update cron. |
 
@@ -29,3 +29,4 @@ ae-cli metadata data-table sql-write --project-id <project_id> --operation updat
 
 - This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
 - Keep `columns` and `qp` as valid JSON; do not pass raw SQL unless the server schema requires it inside `qp`.
+- If you provide a table name, it must include the project segment, for example `datatable_2_orders_sql`.

package/skills/ae-metadata/references/metadata_property_dimension_table_create_and_bind_csv.md

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata property create-and-bind-csv-dimension-table --project-id <project_id> --property-name <name> --property-scope user --input-file-id <input_file_id> --data-table-name <table_name> --columns '<columns_json>' --yes
+ae-cli metadata property create-and-bind-csv-dimension-table --project-id <project_id> --property-name <name> --property-scope user --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>' --yes
 ```
 
 ## Parameters
@@ -16,15 +16,17 @@ ae-cli metadata property create-and-bind-csv-dimension-table --project-id <proje
 | `--property-name` | Yes | Property technical name. |
 | `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
 | `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
-| `--data-table-name` | No | Technical data table name. |
+| `--data-table-name` | No | Optional technical data table name. If supplied, use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable table name. |
 | `--description` | No | Table description. |
-| `--columns` | No | Column definitions JSON array. |
+| `--columns` | No | Column definitions JSON array. Preferred fields are `column_name`, `select_type`, and `column_desc`; CLI also accepts `name`, `type`, and `display_name` aliases. |
 | `--timestamp-join-format` | No | Timestamp join format. |
 | `--dict-columns` | No | Dictionary column names JSON array. |
 
 ## Decision Rules
 
 - Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- Do not invent `input_file_id`; use the value returned by upload.
+- If you provide `--data-table-name`, it must include the project segment, for example `datatable_2_user_dict`.
 - Use this one-step command when the user wants a new CSV dimension table bound to a property.
 - This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.

package/dist/auth-I2G7OAU2.js

@@ -1,19 +0,0 @@
-import {
-  clearToken,
-  getAuthStatus,
-  getToken,
-  loadToken,
-  resolveHost,
-  saveToken,
-  validateToken
-} from "./chunk-U6QPKCN3.js";
-import "./chunk-WPXHCP4A.js";
-export {
-  clearToken,
-  getAuthStatus,
-  getToken,
-  loadToken,
-  resolveHost,
-  saveToken,
-  validateToken
-};

package/dist/chunk-FPE5LGVU.js

@@ -1,105 +0,0 @@
-import {
-  getToken,
-  load,
-  loadCliToken,
-  save
-} from "./chunk-U6QPKCN3.js";
-import {
-  getActiveHost,
-  getFallbackCliToken,
-  listHosts,
-  logger,
-  safeJsonParse
-} from "./chunk-WPXHCP4A.js";
-
-// src/core/cli-token.ts
-var CLI_TOKEN_GENERATE_PATH = "/v1/ta/cli/token/generate";
-var _cliTokenCache = /* @__PURE__ */ new Map();
-async function generateCliToken(hostUrl) {
-  const accessToken = await getToken(hostUrl);
-  const base = hostUrl.replace(/\/+$/, "");
-  const url = `${base}${CLI_TOKEN_GENERATE_PATH}`;
-  const resp = await fetch(url, {
-    method: "GET",
-    headers: {
-      "Authorization": `bearer ${accessToken}`
-    }
-  });
-  if (!resp.ok) {
-    throw new Error(`CLI token generate HTTP error: ${resp.status} ${resp.statusText}`);
-  }
-  const data = safeJsonParse(await resp.text());
-  if (data.return_code !== 0) {
-    throw new Error(`CLI token generate error: ${data.return_message || "unknown"} (code: ${data.return_code})`);
-  }
-  const cliToken = data.data?.userSecret;
-  if (!cliToken) {
-    throw new Error("CLI token generate error: empty userSecret in response");
-  }
-  return cliToken;
-}
-function persistCliTokenIfPossible(hostUrl, cliToken) {
-  const existing = load(hostUrl);
-  if (!existing) {
-    logger.info(`cli-token: no secure-store session for ${hostUrl}, keeping token in-process only`);
-    return;
-  }
-  save(hostUrl, { ...existing, cliToken });
-}
-function clearPersistedCliToken(hostUrl) {
-  const existing = load(hostUrl);
-  if (existing?.cliToken) {
-    save(hostUrl, { ...existing, cliToken: void 0 });
-  }
-}
-async function getCliToken(hostOverride) {
-  const hostUrl = hostOverride || getActiveHost();
-  const cached = _cliTokenCache.get(hostUrl);
-  if (cached) {
-    return cached;
-  }
-  const storedToken = loadCliToken(hostUrl);
-  if (storedToken) {
-    _cliTokenCache.set(hostUrl, storedToken);
-    logger.info(`Using persisted CLI token (secure-store) for ${hostUrl}`);
-    return storedToken;
-  }
-  const fallbackToken = getFallbackCliToken(hostUrl);
-  if (fallbackToken) {
-    _cliTokenCache.set(hostUrl, fallbackToken);
-    logger.info(`Using sandbox-provisioned CLI token (fallback file) for ${hostUrl}`);
-    return fallbackToken;
-  }
-  return mintCliToken(hostUrl);
-}
-async function mintCliToken(hostUrl) {
-  logger.info(`Generating CLI token for ${hostUrl}`);
-  const cliToken = await generateCliToken(hostUrl);
-  _cliTokenCache.set(hostUrl, cliToken);
-  persistCliTokenIfPossible(hostUrl, cliToken);
-  logger.info(`CLI token generated, cached, and persisted for ${hostUrl}`);
-  return cliToken;
-}
-function clearCliToken(hostUrl) {
-  if (hostUrl) {
-    _cliTokenCache.delete(hostUrl);
-    clearPersistedCliToken(hostUrl);
-    return;
-  }
-  _cliTokenCache.clear();
-  for (const { url } of listHosts()) {
-    clearPersistedCliToken(url);
-  }
-}
-function setCliTokenManual(token, hostUrl) {
-  _cliTokenCache.set(hostUrl, token);
-  persistCliTokenIfPossible(hostUrl, token);
-  logger.info(`CLI token set for ${hostUrl}`);
-}
-
-export {
-  getCliToken,
-  mintCliToken,
-  clearCliToken,
-  setCliTokenManual
-};

package/dist/cli-token-6AGEDJF4.js

@@ -1,14 +0,0 @@
-import {
-  clearCliToken,
-  getCliToken,
-  mintCliToken,
-  setCliTokenManual
-} from "./chunk-FPE5LGVU.js";
-import "./chunk-U6QPKCN3.js";
-import "./chunk-WPXHCP4A.js";
-export {
-  clearCliToken,
-  getCliToken,
-  mintCliToken,
-  setCliTokenManual
-};