@thinkingai/ae-cli 6.0.17 → 6.0.18-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkingai/ae-cli",
-  "version": "6.0.17",
+  "version": "6.0.18-1",
   "description": "CLI tool for ThinkingAI (AE) analytics platform",
   "type": "module",
   "bin": {

package/skills/ae-engage/SKILL.md

@@ -145,14 +145,10 @@ ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
 ae-cli engage +channel_list --project_id <projectId>
 ```
 
-5. The final `--req` for `+save_flow` must be the complete canvas request payload, not an intent description. It must contain at least:
-   - `flowName`
-   - `flowDesc`
-   - `nodeList`
-   - `edgeList`
-6. `nodeList[].config` and `edgeList[].config` must be JSON strings, not JSON objects.
-7. If `targetClusterQp` appears inside a node `config`, its value should usually also be a string produced by `JSON.stringify`, not a raw object.
-8. You must self-check before submitting:
+5. `+save_flow` is **operation-based** (protocol v2). The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — use `nodes` / `edges` with `operation=build`. A legacy `nodeList`/`edgeList` payload (or a missing `operation`) is rejected with `Unsupported save_flow operation: null`.
+6. Run the lifecycle: `build` (returns `ready_to_preview` or `need_input`) → resolve any `need_input` slot → `preview` (re-issues `draftVersion` + `confirmToken`) → `commit` (uses the **preview** `draftVersion` + `confirmToken`) → returns `flowUuid`.
+7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. If `targetClusterQp` appears inside a node `config`, its value is usually a `JSON.stringify`'d string, not a raw object.
+8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
    - `edge.source` and `edge.target` both reference valid nodes
@@ -163,8 +159,8 @@ ae-cli engage +channel_list --project_id <projectId>
 
 - Do not invent a `channelId`
 - Do not fill in branching logic when the user has not provided enough information
-- Do not submit business-semantic nodes directly as final `nodeList` nodes
-- Do not put `config` into `--req` as an object
+- Do not submit business-semantic nodes directly as final `nodes`
+- Do not use the legacy `nodeList` / `edgeList`, and do not omit `operation`
 
 ### Recommended Order
 
@@ -173,9 +169,10 @@ User request
 -> Organize intent
 -> analysis_audience +get_cluster_definition_schema --cluster_type condition
 -> +channel_list --project_id <projectId>
--> Build nodeList / edgeList
+-> Build nodes / edges
 -> Self-check
--> +save_flow
+-> +save_flow operation=build -> (need_input?) -> preview -> commit
+-> +flow_detail (verify)
 ```
 
 For more detailed generation rules, consult these references first:

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

@@ -1,67 +1,114 @@
 # ae-engage `+save_flow`
 
-Create or update a flow canvas draft.
+Create, edit, preview, or commit a flow canvas draft.
 
-Mapped command: `ae-cli engage +save_flow`
+Mapped command: `ae-cli engage +save_flow --project_id <projectId> --req '<req-json>'`
 
-This document is not only meant to explain the `save_flow` interface itself. It provides a complete path **from user requirements to CLI arguments**:
+> **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`.
 
-1. Identify intent first
-2. Then map the intent to the flow canvas `req`
-3. Finally submit through the CLI
+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.
 
 ---
 
 ## 1. General Principles
 
-`+save_flow` does not accept natural language or vague business descriptions directly. It accepts the **final flow canvas request payload that is ready to submit**.
+`+save_flow` does not accept natural language or vague business descriptions directly. It accepts a **flow canvas request whose `req.operation` drives a three-step lifecycle**:
 
-Therefore, you must first organize user requirements into a unified intermediate intent structure, and then generate the payload according to the mapping rules:
-
-- `flowName`
-- `flowDesc`
-- `nodeList`
-- `edgeList`
-- and optional `groupId`、`tzOffset`、`flowUuid`、`parentFlowUuid`、`versionType`
+```text
+build  ──► status = ready_to_preview ──► preview ──► commit ──► flowUuid
+   │                                                              │
+   └──► status = need_input ──► (answer slot, build again)        └──► +flow_detail (verify)
+```
 
-Then call the CLI:
+You still organize user requirements into an intermediate intent first, then map the intent to `nodes` / `edges`, then run the lifecycle.
 
-```bash
-ae-cli engage +save_flow --project_id <projectId> --req '<req-json>'
-```
+- `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).
+- `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>`.
 
 ---
 
 ## 2. Workflow
 
-Use the following five-step workflow:
-
 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 in the project and match real `channelId` values for touchpoint nodes.
-4. Map the intent JSON to the final `req`: `flowName`, `flowDesc`, `nodeList`, and `edgeList`.
-5. Run `ae-cli engage +save_flow --project_id <projectId> --req '<req-json>'` to submit.
+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`.
 
 ---
 
-## 3. Step One: Intent Identification
+## 3. `req` Schema (authoritative)
 
-### 3.1 Information That Must Be Confirmed First
+`req` accepts these fields (only `operation` is hard-required):
 
-Before generating any `req`, confirm at least these four categories of information:
+| Field | Type | Used in | Notes |
+|---|---|---|---|
+| `operation` | string | all | **Required.** `build` \| `preview` \| `commit` |
+| `flowName` | string | build | Flow name. If it is the only content, returns a `need_input` draft with no default nodes |
+| `flowDesc` | string | build | Flow description, **max 200 characters** |
+| `groupId` | int | build | Flow group ID, default `0` |
+| `tzOffset` | number | build | Timezone offset in hours; defaults to server setting |
+| `versionType` | int | build | `1=current, 2=update, 3=new, 4=test` |
+| `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) |
+| `nodeConfigs` | array | build (edit) | Declarative node config replacements; each item needs `nodeId` + `config` |
+| `deleteNodeIds` | array | build (edit) | Node IDs to delete from the draft |
+| `deleteEdges` | array | build (edit) | Edges to delete (by `edgeId` or `source`+`target`) |
+| `slotAnswer` | object | build (continue) | Answer for the current server-requested slot when status is `need_input` |
+| `draftId` | string | preview, commit, build(continue) | Server draft ID returned by `build` |
+| `expectedVersion` | int | preview, build(edit) | Expected draft version for editing or preview |
+| `draftVersion` | int | commit | Draft version returned by `preview` |
+| `confirmToken` | string | commit | Opaque token returned by **preview** (not build) |
+
+`flowUuid` and `parentFlowUuid` are mutually exclusive; when creating a brand-new draft, provide neither.
+
+### Compact node (`nodes[]`)
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | Yes | Request-local node ID, unique within the request |
+| `type` | Yes | Flow node type (see §7.2) |
+| `config` | No | Full node business config — JSON object or JSON string |
+| `name` | No | Display name |
+| `desc` | No | Node description |
+
+### Compact edge (`edges[]`)
+
+| Field | Required | Description |
+|---|---|---|
+| `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 |
+| `config` | No | Edge business config as JSON string |
+
+---
+
+## 4. Step One: Intent Identification
+
+### 4.1 Information That Must Be Confirmed First
+
+Before building, confirm at least these four categories:
 
 | Item | Description |
 |---|---|
-| business scenario | What kind of flow this is, for example new-user activation, churn win-back, or paid conversion |
-| target users | Who can enter the flow, for example users inactive for the last 14 days or users registered today |
-| touchpoint method | Which channel will be used for outreach, for example Push, WeChat subscription, or Webhook |
-| branching conditions | Whether grouped handling is needed; if so, which conditions define the groups |
+| business scenario | new-user activation, churn win-back, paid conversion, etc. |
+| target users | who can enter the flow |
+| touchpoint method | Push, WeChat subscription, Webhook, etc. |
+| branching conditions | whether grouped handling is needed, and the conditions |
 
-If any of these four categories is missing, do not build `req` directly.
+If any is missing, do not build.
 
-### 3.2 Intent Output Format
+### 4.2 Intent Output Format
 
-First organize the user requirement into the following intent JSON. This JSON is an intermediate representation, not the final `save_flow.req`.
+Organize the user requirement into an intermediate intent JSON (not the final `req`):
 
 ```json
 {
@@ -74,13 +121,7 @@ First organize the user requirement into the following intent JSON. This JSON is
     "schedule": "<string|null>",
     "start_date": "<YYYY-MM-DD|YYYY-MM-DD HH:mm|null>",
     "end_date": "<YYYY-MM-DD|YYYY-MM-DD HH:mm|null>",
-    "trigger_event": {
-      "event": "<string|null>",
-      "op": "<string|null>",
-      "count": "<number|null>",
-      "property_filter": "<object|null>",
-      "time_window": "<string|null>"
-    }
+    "trigger_event": { "event": "<string|null>", "op": "<string|null>", "count": "<number|null>", "property_filter": "<object|null>", "time_window": "<string|null>" }
   },
   "nodes": [
     {
@@ -94,121 +135,41 @@ First organize the user requirement into the following intent JSON. This JSON is
       "condition": "<object|null>",
       "event": "<object|null>",
       "wait_time": "<string|null>",
-      "duration": "<string|null>",
       "split_flow_type": "<1|2|null>",
-      "branches": [
-        {
-          "bid": "b1",
-          "label": "<string>",
-          "condition": "<object|null>",
-          "time_limit": "<string|null>",
-          "percentage": "<number|null>"
-        }
-      ]
+      "branches": [ { "bid": "b1", "label": "<string>", "condition": "<object|null>", "time_limit": "<string|null>", "percentage": "<number|null>" } ]
     }
   ],
-  "edges": [
-    {
-      "source": "n1",
-      "target": "n2",
-      "branch": "<branch label|null>"
-    }
-  ]
+  "edges": [ { "source": "n1", "target": "n2", "branch": "<branch label|null>" } ]
 }
 ```
 
-### 3.3 Field Meaning
-
-- `entry`
-  Describes how users enter the flow.
-- `nodes`
-  Describes business-semantic nodes; they are not yet final canvas nodes.
-- `edges`
-  Describes the connection relationships at the business-semantics level.
-- `channel_name`
-  Keep it as a semantic field first, then match a real `channelId` from the project channel list later.
-- `branches`
-  Only describes branch semantics; later it will be materialized into `node.config.branchList` and `edge.sourceBranchId`.
+`channel_name` stays semantic here; match it to a real `channelId` later. `branches` later materialize into `node.config.branchList` and `edge.sourceBranchId`.
 
 ---
 
-## 4. Step Two: Required CLI Queries
+## 5. Step Two: Required CLI Queries
 
-### 4.1 Query the Cluster Definition Schema
-
-Run:
+### 5.1 Cluster Definition Schema
 
 ```bash
 ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
 ```
 
-Purpose:
-- Prepare the basis for building QP for condition nodes, audience nodes, and entry nodes
-- Help generate `targetClusterQp`
-- Help generate `triggerRule.events`
-
-This step does not return final nodes directly. It provides the rule foundation for expressing conditions as QP or event conditions.
+Provides the basis for `targetClusterQp` and `triggerRule.events`.
 
-### 4.2 Query Project Channels
-
-Run:
+### 5.2 Project Channels
 
 ```bash
 ae-cli engage +channel_list --project_id <projectId>
 ```
 
-Purpose:
-- Get the available channels in the project
-- Match a real `channelId` for touchpoint nodes based on `channel_name` in the intent
-- Determine whether the node should be `message_push`, `wechat_push`, or `webhook_push` based on the channel type
-
-If `channel_name` does not have an exact match, use this priority:
+Match a real `channelId` for touchpoint nodes (priority: exact name match → keyword match → fallback by node/channel type). For `webhook_push`, also call `ae-cli engage +channel_detail` and drive `contentList` from `data.config.paramsList`.
 
-1. exact name match
-2. name keyword match
-3. fallback match by node type and channel type
+**The channel must be enabled.** A node referencing a disabled channel (`channelStatus = 2`) fails with `disabled_channel: channelId must reference an enabled channel`, and `build` stalls on a `need_input` channel slot. Enable it first via `ae-cli engage +update_channel_status --status 1` (write op — requires explicit user intent).
 
 ---
 
-## 5. Step Three: Map the Intent to `req`
-
-### 5.1 Top-Level `req` Structure
-
-The object passed to `--req` should have the following structure:
-
-```json
-{
-  "flowName": "<string>",
-  "flowDesc": "<string>",
-  "groupId": 0,
-  "tzOffset": 8,
-  "flowUuid": "<string, optional>",
-  "parentFlowUuid": "<string, optional>",
-  "versionType": 1,
-  "nodeList": [],
-  "edgeList": []
-}
-```
-
-Notes:
-- `projectId` does not need to be written into `--req` manually; the CLI injects it from `--project_id`
-- `flowUuid` and `parentFlowUuid` are mutually exclusive
-- When creating a new draft, neither of these fields should be provided
-
-### 5.2 Sources of Top-Level Fields
-
-| `req` Field | Source |
-|---|---|
-| `flowName` | Intent field `flow_name` |
-| `flowDesc` | Intent field `flow_desc`; use an empty string or a short description if absent |
-| `groupId` | Default `0`, unless the business requirement specifies a group |
-| `tzOffset` | User timezone or project default timezone; a common value is `8` |
-| `nodeList` | Generated from intent `entry` plus `nodes` |
-| `edgeList` | Generated from intent `edges` and branch structure |
-
----
-
-## 6. Step Four: Map Intent Nodes to Canvas Nodes
+## 6. Step Three: Map Intent Nodes to Canvas Nodes
 
 ### 6.1 Entry Node Mapping
 
@@ -218,11 +179,11 @@ Notes:
 | `repeat_trigger` | `repeat_trigger` |
 | `event_trigger` | `event_trigger` |
 
-The entry node must always be the only entry node in `nodeList`.
+There must be exactly one entry node.
 
 ### 6.2 Business Node Mapping
 
-| Intent-node semantic meaning | Canvas node `type` |
+| Intent semantics | Canvas node `type` |
 |---|---|
 | Behavioral split | `event_split_flow` |
 | Feature split | `feature_split_flow` |
@@ -231,641 +192,323 @@ The entry node must always be the only entry node in `nodeList`.
 | Feature judgment | `feature_judge` |
 | Push touchpoint | `message_push` |
 | WeChat touchpoint | `wechat_push` |
-| Webhook / other external touchpoint | `webhook_push` |
+| Webhook / external touchpoint | `webhook_push` |
 | Wait | `time_control` |
 | End | `exit_flow` |
 
 ### 6.3 Condition Field Mapping
 
-Condition-related semantics cannot be copied into `req` as-is. They must be materialized in the following way:
-
 | Semantic type | Target field |
 |---|---|
-| Audience segmentation condition | `targetClusterQp` |
-| Feature judgment condition | `targetClusterQp` |
-| Feature split branch condition | `targetClusterQp` |
-| Event trigger condition | `triggerRule[].events[]` |
-| Behavioral judgment condition | `triggerRule[].events[]` |
-| Behavioral split branch condition | `triggerRule[].events[]` |
-
-In short:
-- Conditions that judge by audience or property usually map to `targetClusterQp`
-- Conditions that judge whether an event happened, or how many times it happened, usually map to `triggerRule.events`
+| Audience segmentation / feature judgment / feature split branch | `targetClusterQp` |
+| Event trigger / behavioral judgment / behavioral split branch | `triggerRule[].events[]` |
 
 ### 6.4 Touchpoint Node Mapping
 
-These fields inside action-semantic nodes:
-
-- `channel_name`
-- `content`
-- `languages`
-
-need to be materialized into the push-node `config`:
-
-- `channel_name` -> match to a real `channelId`
-- `content` -> place into `contentList`
-- `languages` -> determine whether multilingual `contentList` entries should be generated
+Inside action nodes: `channel_name` → real `channelId`; `content` → `contentList`; `languages` → whether to generate multilingual `contentList` entries.
 
 ---
 
-## 7. Step Five: How to Build `nodeList`
-
-Each item in `nodeList` has the following structure:
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `id` | string | Yes | Unique node ID within the request |
-| `name` | string | Yes | Display name of the node |
-| `type` | string | Yes | Node type |
-| `config` | string | Yes | **JSON string** whose top level must be a JSON object |
-| `desc` | string | No | Node description |
+## 7. Step Four: Build `nodes`
 
 ### 7.1 Most Important Rules
 
-1. `config` must be a string, not an object.
-2. `node.id` must be unique.
-3. Any `branchId` later referenced by `edge.sourceBranchId` in split or judgment nodes must be defined in `config` first.
-4. Every path must eventually end at `exit_flow`.
+1. `node.id` must be unique within the request.
+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.)
 
 ### 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`
-
-### 7.3 Example: Simplest Node
+`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`.
 
-```json
-{
-  "id": "node_1",
-  "name": "One-Time Scheduled Entry",
-  "type": "single_trigger",
-  "config": {
-    "triggerTime": "2026-04-10 06:35",
-    "flowEndDate": "2026-04-11 06:35"
-  }
-}
-```
-
-### 7.4 Common `config` Templates
-
-The templates below are the most important references when you assemble `req` directly. Build them as objects first, then wrap them with `JSON.stringify` before placing them into `nodeList[].config`.
+### 7.3 Common `config` Templates
 
 #### `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, "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "targetClusterQp": "<JSON.stringify(qp)>" }
 ```
 
-Rules: 
-- `entry.segment` -> `targetClusterQp`
-- `entry.schedule` -> `crontab`
-- Common default value: `0 00 09 * * ?`
+`entry.segment` → `targetClusterQp`; `entry.schedule` → `crontab` (common default `0 00 09 * * ?`).
 
 #### `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, "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>" }
 ```
 
-Rules: 
-- `entry.trigger_event` -> `triggerRule[0].events`
-- Generate `targetClusterQp` only when `entry.segment` exists
-- When `segment` is absent, `targetClusterQp` may be `null`
+`entry.trigger_event` → `triggerRule[0].events`; generate `targetClusterQp` only when `entry.segment` exists.
 
 #### `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, "triggerRule": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": "<0 or -1>", "zoneoffset": 8, "events": [] } ] } ] }
 ```
 
-Rules: 
-- When `branch.condition` is an event condition, map it to `triggerRule[].events[]`
-- `time_limit` -> `delayTimeSymbol` + `delayTime`
-- Use `0` for happened and `-1` for not happened
-- For the fallback branch, keep only: 
-
-```json
-{
-  "branchId": "<branchId>",
-  "branchType": 2
-}
-```
+`time_limit` → `delayTimeSymbol` + `delayTime`; `0` = happened, `-1` = not happened. Fallback branch keeps only `{ "branchId": "<branchId>", "branchType": 2 }`.
 
 #### `feature_split_flow`
 
 ```json
-{
-  "splitFlowType": 1,
-  "branchList": [
-    {
-      "branchId": "<branchId>",
-      "branchName": "<label>",
-      "branchType": 1,
-      "realtime": 0,
-      "clusterRefresh": 12,
-      "clusterPredictCount": null,
-      "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>",
-      "targetClusterQp": "<JSON.stringify(qp)>"
-    }
-  ]
-}
+{ "splitFlowType": 1, "branchList": [ { "branchId": "<branchId>", "branchName": "<label>", "branchType": 1, "realtime": 0, "clusterRefresh": 12, "clusterPredictCount": null, "clusterPredictTime": "<YYYY-MM-DD HH:mm:ss>", "targetClusterQp": "<JSON.stringify(qp)>" } ] }
 ```
 
-Rules: 
-- Property or tag condition -> `targetClusterQp`
-- For the fallback branch, also keep only `branchId` plus `branchType: 2`
+Fallback branch keeps only `branchId` + `branchType: 2`.
 
 #### `ab_split_flow`
 
 ```json
-{
-  "branchList": [
-    {
-      "branchId": "<branchId>",
-      "branchName": "Control Group",
-      "branchType": 1,
-      "order": 1,
-      "percentageInExperiment": 34
-    },
-    {
-      "branchId": "<branchId>",
-      "branchName": "Experiment Group A",
-      "branchType": 2,
-      "order": 2,
-      "percentageInExperiment": 33
-    }
-  ],
-  "indicatorsDef": [],
-  "activateIndicatorsDef": null
-}
+{ "branchList": [ { "branchId": "<branchId>", "branchName": "Control Group", "branchType": 1, "order": 1, "percentageInExperiment": 34 }, { "branchId": "<branchId>", "branchName": "Experiment Group A", "branchType": 2, "order": 2, "percentageInExperiment": 33 } ], "indicatorsDef": [], "activateIndicatorsDef": null }
 ```
 
-Rules: 
-- If the user does not provide percentages, you may split them evenly
-- For three groups, you can use `34/33/33`
-
 #### `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": [ { "delayTimeSymbol": "<minute|hour|day>", "delayTime": "<number>", "eventTriggerType": 0, "zoneoffset": 8, "events": [] } ] }
 ```
 
-Rules: 
-- `node.event` -> `triggerRule[].events[]`
-- `wait_time` -> `delayTimeSymbol` + `delayTime`
-- If no wait duration is specified, you may default to `30 minute`
+`wait_time` → `delayTimeSymbol` + `delayTime` (default `30 minute` if unspecified).
 
 #### `feature_judge`
 
 ```json
-{
-  "transferType": 1,
-  "meetBranchId": "<meetBranchId>",
-  "notMeetBranchId": "<notMeetBranchId>",
-  "clusterPredictCount": null,
-  "clusterPredictTime": "",
-  "targetClusterQp": "<JSON.stringify(qp)>"
-}
+{ "transferType": 1, "meetBranchId": "<meetBranchId>", "notMeetBranchId": "<notMeetBranchId>", "clusterPredictCount": null, "clusterPredictTime": "", "targetClusterQp": "<JSON.stringify(qp)>" }
 ```
 
 #### `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>", "enableChannelTouchLimits": false, "isOccasionUp": false, "contentList": [ { "pushLanguageCode": "default", "content": [] } ], "processType": 1 }
 ```
 
-Rules: 
-- `channel_name` -> match a real `channelId`
-- `content` -> fill the parameter that best matches body text, content, or message
-- When the parameter `type = TEXT`, also add: 
-
-```json
-{
-  "config": "[{\"type\":\"paragraph\",\"children\":[{\"text\":\"<same as value>\"}]}]"
-}
-```
-
-Multilingual Rules:
-- The first entry must always use `"pushLanguageCode": "default"`
-- Generate additional language versions according to `languages`
-- Each language uses the same `content[]` structure; only `value` changes
+`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`.
 
 #### `wechat_push`
 
 ```json
-{
-  "channelId": "<matched channelId>",
-  "enableChannelTouchLimits": false,
-  "isOccasionUp": false,
-  "contentList": [
-    {
-      "pushLanguageCode": "default",
-      "content": [
-        {
-          "key": "lang",
-          "type": "STRING",
-          "required": true,
-          "paramType": 2,
-          "name": "Language",
-          "value": "default"
-        },
-        {
-          "key": "page",
-          "type": "STRING",
-          "required": true,
-          "paramType": 2,
-          "name": "Destination Page",
-          "value": ""
-        },
-        {
-          "key": "miniprogramState",
-          "type": "STRING",
-          "required": true,
-          "paramType": 2,
-          "name": "Version",
-          "value": ""
-        }
-      ]
-    }
-  ],
-  "processType": 1
-}
+{ "channelId": "<matched channelId>", "enableChannelTouchLimits": false, "isOccasionUp": false, "contentList": [ { "pushLanguageCode": "default", "content": [ { "key": "lang", "type": "STRING", "required": true, "paramType": 2, "name": "Language", "value": "default" }, { "key": "page", "type": "STRING", "required": true, "paramType": 2, "name": "Destination Page", "value": "" }, { "key": "miniprogramState", "type": "STRING", "required": true, "paramType": 2, "name": "Version", "value": "" } ] } ], "processType": 1 }
 ```
 
 #### `time_control`
 
 ```json
-{
-  "controlType": 1,
-  "timeUnit": "<minute|hour|day>",
-  "timeUnitNum": "<number>"
-}
+{ "controlType": 1, "timeUnit": "<minute|hour|day>", "timeUnitNum": "<number>" }
 ```
 
-Common parsing examples: 
-- `30 minutes` -> `minute` + `30`
-- `2 hours` -> `hour` + `2`
-- `1 day` -> `day` + `1`
+`30 minutes` → `minute`+`30`; `2 hours` → `hour`+`2`; `1 day` → `day`+`1`.
 
 #### `exit_flow`
 
-Minimum usable `config`: 
-
-```json
-{}
-```
+Minimum usable `config`: `{}`.
 
 ---
 
-## 8. Step Six: How to Build `edgeList`
-
-Each item in `edgeList` has the following structure:
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `source` | string | Yes | upstream node ID |
-| `target` | string | Yes | downstream node ID |
-| `edgeId` | string | No | edge ID |
-| `sourceBranchId` | string | No | used for edges leaving split or judgment nodes |
-| `config` | string | No | JSON string |
+## 8. Step Five: Build `edges`
 
-### 8.1 Regular Edges
+### 8.1 Regular Edge
 
 ```json
-{
-  "source": "node_1",
-  "target": "node_2"
-}
+{ "source": "node_1", "target": "node_2" }
 ```
 
-### 8.2 Branch Edges
+### 8.2 Branch Edge
 
 ```json
-{
-  "source": "node_split",
-  "target": "node_a",
-  "sourceBranchId": "branch_a"
-}
+{ "source": "node_split", "target": "node_a", "sourceBranchId": "branch_a" }
 ```
 
-### 8.3 Most Important Rules
-
-1. `source` and `target` must reference existing `node.id` values
-2. Only edges leaving split or judgment nodes need `sourceBranchId`
-3. The graph must be a DAG and cannot contain cycles
-4. For split nodes, `sourceBranchId` must come from a branchId already declared in the corresponding node `config`
+### 8.3 Standard Outgoing-Edge Rules
 
-### 8.4 Standard Outgoing-Edge Rules
-
-| node type | Number of outgoing edges | `sourceBranchId` rule |
+| node type | Outgoing edges | `sourceBranchId` |
 |---|---|---|
 | `single_trigger` / `repeat_trigger` / `event_trigger` | 1 | do not provide |
-| `event_split_flow` / `feature_split_flow` / `ab_split_flow` | one per branch | use the corresponding `branchList[].branchId` |
-| `event_judge` / `feature_judge` | 2 | use `meetBranchId` and `notMeetBranchId` respectively |
+| `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 |
 | `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).
+
 ---
 
-## 9. Step Seven: Graph Constraint Checks
+## 9. QP Validation Rules (high-frequency pitfalls)
 
-Before submitting, you must self-check:
+When a node config carries a QP (`targetClusterQp`, `triggerRule[].events[]`, etc.), the v2 backend validates it strictly:
 
-1. `nodeList` is not empty
-2. There must be exactly one entry node
-3. There must be at least one `exit_flow`
-4. Each `exit_flow` must have exactly one incoming edge and no outgoing edges
-5. Each `node.id` must be unique
-6. Every edge must reference existing nodes
-7. The entire graph must be acyclic
+1. **`relation` must be integer `0` or `1`** — not the string `"0"`/`"1"`. Applies to `totalCFilter.relation`, `eventCondition.relation`, `filts[].relation`. Error: `invalid_qp_relation: QP relation must be number 0 or 1`.
+2. **`userCondition` leaves must include `columnType` and `columnDesc`** — `columnName`/`selectType`/`tableType`/`calcuSymbol`/`ftv` alone is not enough. Error: `invalid_qp_leaf: QP property leaf must contain columnType/columnDesc`. (Even legacy stored QPs that omit these now fail.)
+3. **`taPropQuota` must include `quotaDesc`, `quota`, `analysisParams`** — giving only `analysis`/`analysisDesc` fails with `required_by_minimal_valid`. Minimal passing shape: `{ "analysis": ..., "analysisDesc": ..., "quota": "", "quotaDesc": "", "analysisParams": "" }`. Applies to both `triggerRule.events[].taPropQuota` and the entry node's `eventCondition.taPropQuota`.
 
-If a split node uses `splitFlowType = 2`, also ensure:
-- Paths from different branches must not converge again into the same node
-- Each branch should independently lead to its own `exit_flow`
+`targetClusterQp` is usually a `JSON.stringify`'d string, e.g. `{ "targetClusterQp": "{\"totalCFilter\":{\"relation\":1,\"filts\":[]}}" }`.
 
----
+### 9.1 Operator codes (`uceCalcuSymbol` / `calcuSymbol`)
+
+Condition leaves use string operator codes, not literal operators:
 
-## 10. Step Eight: CLI Submission
+| Code | Meaning | Value type |
+|---|---|---|
+| `C00` | equals | all |
+| `C01` | not equals | all |
+| `C02` / `C020` | less than / less than or equal | number |
+| `C03` / `C030` | greater than / greater than or equal | number |
+| `C04` / `C05` | has value / no value | all |
+| `C06` / `C060` | range / date range | number / date |
+| `C07` / `C08` | contains / does not contain | string |
+| `C09` / `C10` | true / false | bool |
+| `C11` / `C12` | regex match / not match | string |
 
-### 10.1 Top-Level Flags
+### 9.2 Event-count condition (`A200`) — `invalid_preset_count_expression`
 
-| Flag | Type | Required | Description |
-|---|---|---|---|
-| `--project_id` / `-p` | number | Yes | Project ID |
-| `--req` | json | Yes | final request-body object |
+For an event condition that counts occurrences with an **empty `taPropQuota`** (analysis `A200`, the default "count" case), the backend treats it as a *preset count* and is strict:
+
+- `uceCalcuSymbol` **must be `C030`** (greater-than-or-equal), and
+- `num` **must be `"1"`** (string).
 
-### 10.2 Actual CLI Submission Structure
+Any other operator/number with an empty quota fails with `invalid_preset_count_expression: A200 empty quota means preset count and must use C030 with num=1`.
 
-The CLI will organize the input as:
+A working event-condition leaf (used inside `triggerRule[].events[]` for `event_judge` / `event_trigger` / `event_split_flow`):
 
 ```json
 {
-  "projectId": 1,
-  "req": {
-    "projectId": 1,
-    "...": "..."
+  "conditionType": "event",
+  "eventCondition": {
+    "eventName": "ta@active_user",
+    "eventDesc": "用户活跃",
+    "eventType": "event",
+    "uceCalcuSymbol": "C030",
+    "num": "1",
+    "taPropQuota": { "analysis": "A200", "analysisDesc": "次数", "quota": "", "quotaDesc": "", "analysisParams": "" },
+    "recentDay": "0-30",
+    "startTime": "",
+    "endTime": "",
+    "filts": [],
+    "relation": 1
   }
 }
 ```
 
-In other words:
-- The top-level `projectId` comes from `--project_id`
-- `req.projectId` is also injected automatically by the CLI
+Wrap the leaves with `{ "totalCFilter": { "filts": [ ... ], "relation": 1 } }`, then `JSON.stringify` for `targetClusterQp`.
 
-### 10.3 Minimum Working Example
-
-```bash
-ae-cli engage +save_flow \
-  --project_id 1 \
-  --req '{
-    "flowName": "Welcome Flow",
-    "flowDesc": "New user welcome flow",
-    "groupId": 0,
-    "tzOffset": 8,
-    "nodeList": [
-      {
-        "id": "node_1",
-        "name": "Enter Flow",
-        "type": "single_trigger",
-        "config": "{}"
-      },
-      {
-        "id": "node_2",
-        "name": "End",
-        "type": "exit_flow",
-        "config": "{}"
-      }
-    ],
-    "edgeList": [
-      {
-        "source": "node_1",
-        "target": "node_2"
-      }
-    ]
-  }'
-```
-
-### 10.4 Output Requirements After Successful Creation
-
-Prerequisite:
-- The flow canvas was created successfully and returned the new canvas `flowUuid`
-
-On success, you must:
-- Show the creation result to the user, including at least key information such as the canvas name
-- Output a **clickable Markdown link**
-
-Link-generation Rules:
-- Use standard Markdown link syntax and do not place it inside a code block
-- The URL must start with `/#/`
-- Do not add a domain name or any domain placeholder
-- Replace the `flowUuid` returned by `save_flow` and the `projectId` used for this creation into the URL
+---
 
-Output template:
+## 10. Step Six: Graph Constraint Checks
 
-[Open Canvas](/#/hermes/flow/detail?flowUuid=<replace-with-actual-flowUuid>&currentProjectId=<replace-with-actual-projectId>)
+Before `preview`/`commit`, self-check:
 
-Correct example:
+1. `nodes` is not empty; exactly one entry node; at least one `exit_flow`.
+2. Each `exit_flow` has exactly one incoming edge and no outgoing edges.
+3. Each `node.id` is unique; every edge references existing nodes; the graph is acyclic.
+4. **Every terminal branch must use its own dedicated `exit_flow` node** — do not let multiple upstream nodes point at one shared `exit_flow`. A flow with N terminal paths needs N separate `exit_flow` nodes (otherwise the backend rejects the shared exit). Error: `... branch must use its own dedicated exit ...`.
+5. If a split node uses `splitFlowType = 2`, different branches must not converge into the same node; each branch leads to its own `exit_flow`.
 
-[Open Canvas](/#/hermes/flow/detail?flowUuid=0006_831135755&currentProjectId=1)
+---
 
-Common mistakes:
-- `❌ {domain}/#/hermes/flow/...`: do not add a domain placeholder
-- `❌` putting the link inside a code block ````` : links inside code blocks are not clickable
-- `❌ /#/hermes/flow/detail?flowUuid=...`: do not output a plain-text URL; you must use the `[text](URL)` format
+## 11. Step Seven: Run the Lifecycle (CLI)
 
-### 10.5 Output Requirements After Failed Creation
+### 11.1 Flags
 
-On failure, you must:
-- Output the complete request-body JSON for debugging
-- Clearly describe the failure reason
+| Flag | Type | Required | Description |
+|---|---|---|---|
+| `--project_id` / `-p` | number | Yes | Project ID |
+| `--req` | json | Yes | operation-based request object |
 
-Suggested output structure:
+The CLI injects `projectId` into both the top level and `req`; you do not write `req.projectId` yourself.
 
-```json
-{
-  "projectId": "<actual projectId>",
-  "req": {
-    "...": "complete save_flow request body"
-  }
-}
-```
+### 11.2 `need_input` Continuation
 
----
+`need_input` is a **soft prompt**, not a hard error:
 
-## 11. Most Common Mistakes
+- **`errors` empty + `nextSlot` present** → server needs one more node config (trigger / channel / targetCluster). Answer with `operation=build` + `draftId` + `expectedVersion` + `slotAnswer`. If `nextSlot.targetNodeId` is present, `slotAnswer.nodeConfig` may contain only `config`; otherwise include `nodeId` or `id`.
+- **`errors` non-empty** → hard validation failure. Fix `nodes`/`edges` and `build` again (a new `draftId` is issued; the stale draft is cleaned by TTL).
 
-### 11.1 `--req` Is an Object, but `node.config` / `edge.config` Are Strings
+### 11.3 Minimal Working Example
 
-Correct:
+```bash
+# 1) build
+ae-cli engage +save_flow --project_id 1 --req '{
+  "operation": "build",
+  "flowName": "Welcome Flow",
+  "flowDesc": "New user welcome flow",
+  "groupId": 0, "tzOffset": 8, "versionType": 1,
+  "nodes": [
+    { "id": "n1", "type": "single_trigger", "name": "Enter", "config": {} },
+    { "id": "n2", "type": "exit_flow", "name": "End", "config": {} }
+  ],
+  "edges": [ { "source": "n1", "target": "n2" } ]
+}'
+# → status = ready_to_preview, draftId = D, draftVersion = V0, confirmToken = T0
 
-```json
-{
-  "id": "node_1",
-  "name": "entry",
-  "type": "single_trigger",
-  "config": "{}"
-}
-```
+# 2) preview (re-issues draftVersion V1 + confirmToken T1)
+ae-cli engage +save_flow --project_id 1 --req '{ "operation": "preview", "draftId": "D", "expectedVersion": 0 }'
 
-Incorrect:
+# 3) commit (use the preview draftVersion + confirmToken)
+ae-cli engage +save_flow --project_id 1 --req '{ "operation": "commit", "draftId": "D", "draftVersion": 1, "confirmToken": "T1" }'
+# → status = committed, result = flowUuid
 
-```json
-{
-  "id": "node_1",
-  "name": "entry",
-  "type": "single_trigger",
-  "config": {}
-}
+# 4) verify
+ae-cli engage +flow_detail --project_id 1 --flow_uuid <flowUuid>
 ```
 
-### 11.2 Time Units Must Be Lowercase
+> ⚠️ `commit` must use the `draftVersion` **and** `confirmToken` returned by **preview**, not by build. Build's values cause a token/version mismatch.
 
-Inside `time_control`, use:
+### 11.4 Output After Successful Commit
 
-- `day`
-- `hour`
-- `minute`
-- `week`
-- `month`
+The committed flow has `status = 0` (draft) — `commit` only freezes the draft into a flow version, it does **not** start delivery. To actually run it, enable it separately via `ae-cli engage +manage_flow` (with explicit user intent).
 
-Do not write `DAY`, `HOUR`, or `MINUTE`.
+Show the user the canvas name and a **clickable Markdown link**:
 
-### 11.3 Do Not Invent `channelId`
+- Standard Markdown link syntax, not inside a code block.
+- URL starts with `/#/`, no domain prefix.
+- Substitute the real `flowUuid` and `projectId`.
 
-For node types such as `message_push`, `wechat_push`, and `webhook_push`, `channelId` must come from:
+Template: `[Open Canvas](/#/hermes/flow/detail?flowUuid=<flowUuid>&currentProjectId=<projectId>)`
 
-```bash
-ae-cli engage +channel_list --project_id <projectId>
-```
+Correct example: `[Open Canvas](/#/hermes/flow/detail?flowUuid=0006_831135755&currentProjectId=1)`
 
-### 11.4 Define branch IDs Before Referencing Them
+Common mistakes: adding a domain placeholder; putting the link inside a code block; outputting a plain-text URL instead of `[text](URL)`.
 
-If an edge uses:
+### 11.5 Output After Failure
 
-```json
-{ "sourceBranchId": "branch_a" }
-```
-
-then `"branch_a"` must already exist in the corresponding upstream node `config`.
-
-### 11.5 `targetClusterQp` Is Usually Also a String
+Output the complete `req` JSON for debugging plus a clear failure reason.
 
-Although `targetClusterQp` appears inside the JSON object of node `config`, its value is usually not a raw object. It is typically the QP object converted into a string with `JSON.stringify`.
-
-Illustration:
+---
 
-```json
-{ "targetClusterQp": "{\"totalCFilter\":{\"relation\":\"1\",\"filts\":[]}}" }
-```
+## 12. Common Validation Errors
 
-### 11.6 Rich-Text `config` for `TEXT` Parameters Must Also Be a String
+| 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` |
+| 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` |
+| `required_by_minimal_valid` | `taPropQuota` missing fields | Add `quotaDesc` + `quota` + `analysisParams` |
+| `invalid_preset_count_expression` | Event count condition (`A200`) with empty quota uses wrong operator/num | Use `uceCalcuSymbol = C030` + `num = "1"` (see §9.2) |
+| `... branch must use its own dedicated exit ...` | Multiple paths share one `exit_flow` | Give every terminal branch its own `exit_flow` node (see §10.4) |
+| `disabled_channel: channelId must reference an enabled channel` | Channel status = 2 | `+update_channel_status --status 1` first |
+| commit token/version mismatch | Used build's `confirmToken`/`draftVersion` | Use the values returned by **preview** |
+| `flowDesc` rejected | Over 200 chars | Trim to ≤ 200 |
+| `config` rejected as object where string expected | Wrong shape for `targetClusterQp` / TEXT rich-text | `JSON.stringify` those inner values |
 
-If a push parameter uses `TEXT`, the inner rich-text `config` must not be an object. It must be stringified JSON. This is easy to miss.
+---
 
-### 11.7 Do Not Merge Branches Again When `splitFlowType = 2`
+## 13. Most Common Mistakes
 
-"Enter whenever conditions are met" means users may enter multiple branches at the same time. In that case, later paths should not share the same downstream node, otherwise the semantics easily conflict.
+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`**.
 
 ---
 
-## 12. One-Sentence Summary
-
-To build `+save_flow` input parameters reliably, do not jump directly from natural language to `req`. Follow this path instead:
+## 14. One-Sentence Summary
 
-**User requirement -> intent JSON -> schema and channel completion -> `nodeList` / `edgeList` -> `ae-cli engage +save_flow`.**
+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.