@thinkingai/ae-cli 6.0.51 → 6.0.53

package/skills/ae-dataops/references/dataops-flow-create.md

@@ -1,7 +1,7 @@
 ---
 name: dataops-flow-create
 version: 1.0.0
-description: "Flow creation and configuration: create flows, add task nodes, configure dependencies, save task definitions, configure scheduling, test, and release to production. Trigger keywords: create flow, new workflow, configure schedule, add task node, release, cron, scheduled execution."
+description: "Flow creation and configuration: create flows, manage custom flow parameters, add task nodes, configure dependencies, save task definitions, configure scheduling, test, and release to production. Trigger keywords: create flow, new workflow, configure schedule, add task node, release, cron, scheduled execution."
 metadata:
   requires:
     bins: ["ae-cli"]
@@ -13,22 +13,74 @@ metadata:
 
 Use the `dataops_flow` subcommand to manage flow lifecycle.
 
-**Flow Lifecycle: Create → Configure Nodes → Configure Schedule → Preview Release → Release to PROD → Manual PROD Execution / Online Schedule**
+**Flow Lifecycle: Create → Configure Nodes → Configure Schedule → Preview Release → Release to PROD → Read Back PROD Configuration**
 
 ---
 
 ## Complete Flow Creation Process
 
-Follow these steps in order to create a production-ready flow from scratch.
+Follow the applicable steps for the requested outcome. A DEV-only change stops before release; a request to publish or enable scheduling ends after PROD readback. Manually execute only when the user also requested a run. For scheduled integration, first obtain the intended sync solution from [the integration reference](dataops-integration.md), bind it as an integration task, then configure and release the flow.
 
 ### Step 1: Create Flow
 
 ```bash
 ae-cli dataops_flow +create_flow --spaceCode "${spaceCode}" \
   --flowName "Daily ETL Process" --remark "Process user data"
-# Returns flowCode, required for subsequent steps
+# Default CLI JSON: data.result.flowCode, required for subsequent steps
 ```
 
+### Custom Flow Parameters
+
+These commands manage one custom workflow definition parameter at a time. They do not set temporary execution inputs or replace the complete parameter list. All four require workflow edit permission (`dwWorkflowEdit`) in the containing space; reading PROD parameters has the same requirement.
+
+```bash
+# Read the current DEV custom parameters before editing
+ae-cli dataops_flow +get_flow_params --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode}
+
+# Create text; VARCHAR is the default
+ae-cli dataops_flow +create_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "run_date" \
+  --paramValue "2026-09-08" --remark "Date to process"
+
+# Use an expression already validated with the platform's supported expression syntax
+ae-cli dataops_flow +create_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "derived_date" \
+  --paramDataType EXPRESSION --paramValue "${validatedExpression}"
+
+# Change only the value; preserve type and remark
+ae-cli dataops_flow +update_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "run_date" --paramValue "2026-09-09"
+
+# Rename: originParamKey is the old name and paramKey is the new name
+ae-cli dataops_flow +update_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --originParamKey "run_date" --paramKey "processing_date"
+
+# Explicitly clear the remark
+ae-cli dataops_flow +update_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "processing_date" --remark ""
+
+# Inspect the target above, then preview deletion
+ae-cli dataops_flow +delete_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "processing_date" --dry-run
+
+# Run only after explicit user confirmation
+ae-cli dataops_flow +delete_flow_param --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --paramKey "processing_date" --yes
+
+# Read the published definition separately
+ae-cli dataops_flow +get_flow_params --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --env PROD
+```
+
+- Query defaults to `DEV`; `PROD` is the only other environment. It returns an array containing `paramKey`, `paramValue`, `paramDataType`, `remark`, `paramFormat`, and expression reference metadata. Only custom flow parameters are returned.
+- `flowCode` must be a positive safe integer. Names must match `[a-z][a-z0-9_]{0,39}`; the `ws_` prefix, `env`, and space built-in parameter names are reserved. Built-in parameters cannot be created, updated, or deleted with these commands.
+- `paramValue` is required and non-empty on create; it remains literal, including whitespace. Single-quote literal expressions to prevent shell expansion of `${...}`. Types are `VARCHAR` (text, create default) and `EXPRESSION`. Expression syntax and supported references are validated by Gaia; arbitrary references between custom parameters are not supported.
+- Update accepts `paramValue`, `paramDataType`, and `remark` independently. Omitted fields retain their values; REST/MCP `null` also retains them. `--remark ""` clears the remark. An empty `paramValue` is rejected. Remarks allow up to 200 characters. Supply at least one update field or an actual rename.
+- Omit `originParamKey` for an in-place update. When renaming, it identifies the old name while `paramKey` identifies the new name. Duplicate names, rename conflicts, and missing targets return errors. Renaming does not replace old references in SQL; inspect affected tasks and update their SQL when needed.
+- Writes configure DEV. Adding a parameter to an existing definition, changing value/type/name, and deleting a parameter may stop running DEV debug executions. Remark-only and no-op updates do not stop debug runs. Value/type/name/deletion changes require a later release to affect PROD; a remark update without renaming also updates an existing PROD parameter with the same name.
+- Deletion is `high-risk-write`: inspect, preview, confirm, then use `--yes`. Task references fall back to a same-name space parameter if one exists; otherwise they remain code-parsed references whose source and value fields are null or omitted. Inspect affected SQL through `+get_flow_overview` task parameters. Read parameters again after each write to verify the saved state.
+
 ### Step 2: Create Task Nodes (can be called multiple times)
 
 ```bash
@@ -36,7 +88,7 @@ ae-cli dataops_flow +create_flow --spaceCode "${spaceCode}" \
 ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --taskName "Process User Data" \
   --sql "SELECT * FROM dwd_user"
-# Returns result.taskCode
+# Default CLI JSON: data.result.taskCode
 
 # Create task with upstream dependency
 ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
@@ -145,7 +197,7 @@ ae-cli dataops_flow +save_schedule_config --spaceCode "${spaceCode}" \
 
 **CRON Format** (6 fields): `second minute hour day month weekday`
 - `0 0 */4 * * ?` — Every 4 hours
-- `0 30 8 * * 1-5` — Weekdays at 8:30
+- `0 30 8 ? * MON-FRI` — Weekdays at 8:30 (Quartz)
 
 ### Step 8: Preview Release
 
@@ -155,27 +207,22 @@ ae-cli dataops_flow +preview_release_flow --spaceCode "${spaceCode}" \
   --flowCode ${flowCode}
 ```
 
+Inspect `data.releaseStatus` in the default CLI JSON: `READY` permits the requested release; `NO_CHANGES` means skip submission and inspect PROD. For `CHECK_FAILED` or `FAILED`, report the message and failed change items and stop before publishing or executing. Check that the preview contains only the intended changes.
+
 ### Step 9: Release to Production and Verify
 
 ```bash
 ae-cli dataops_flow +release_flow --spaceCode "${spaceCode}" \
   --flowCode ${flowCode}
 
-# Manually trigger PROD execution when verification is needed
-ae-cli dataops_flow +execute_flow --spaceCode "${spaceCode}" \
-  --flowCode ${flowCode}
+# Read the published definition without starting a run
+ae-cli dataops_flow +get_flow_overview --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --env PROD
+```
 
-# Check execution status
-ae-cli dataops_operations +search_flow_instances --spaceCode "${spaceCode}" \
-  --keyword "${flowCode}" --pageSize 20
+Check `data.result.releaseStatus`, not outer `ok` or action `status`: `FAILED`, `CHECK_FAILED`, `FAIL`, `PART_SUCCESS`, and `TABLE_FAIL` are not successful publication. Stop and report their details. `TO_RELEASE`, `RELEASING`, or `SUBMITTED` means completion is unverified; retain `data.result.packageCode` and do not resubmit the release.
 
-# Inspect one instance and task logs when troubleshooting
-ae-cli dataops_operations +get_flow_instance_detail --spaceCode "${spaceCode}" \
-  --flowCode ${flowCode} --flowInstanceId ${flowInstanceId}
-ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
-  --flowCode ${flowCode} --flowInstanceId ${flowInstanceId} \
-  --taskInstanceId ${taskInstanceId} --includeLog true
-```
+Confirm the PROD overview has `data.success=true` and compare its visible `schedule`, `dag`, and `flowParams` with the requested changes, including CRON and task presence/type when applicable. Even a release response of `SUCCESS` needs this readback. The overview does not expose task SQL or the integration task's `syncId`; retain the create/update result and release preview as evidence, and state this readback limit instead of claiming those fields were independently verified in PROD. If publication is pending, make read-only checks within a finite deadline; on expiry or unavailable evidence, report the package/flow IDs and what remains unverified. A release-only request ends here. For an explicitly requested manual run, continue with [execution and completion checks](dataops-flow-monitor.md#workflow-c-manual-execution-and-stop).
 
 ---
 
@@ -195,7 +242,11 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 | `+delete_task` | Delete one DEV task node after confirmation | `--spaceCode` `--flowCode` `--taskCode` `--yes` |
 | `+add_task_relation` | Add DEV dependency | `--spaceCode` `--flowCode` `--preTaskCode` `--taskCode` |
 | `+save_schedule_config` | Save DEV schedule config | `--spaceCode` `--flowCode` `--enabled` `[--cron]` |
-| `+get_task_params` | View DEV task parameter list | `--spaceCode` `--flowCode` `--taskCode` |
+| `+get_flow_params` | List custom workflow parameters | `--spaceCode` `--flowCode` `[--env DEV\|PROD]` |
+| `+create_flow_param` | Create one DEV custom parameter | `--spaceCode` `--flowCode` `--paramKey` `--paramValue` `[--paramDataType VARCHAR\|EXPRESSION]` `[--remark]` |
+| `+update_flow_param` | Update or rename one DEV custom parameter | `--spaceCode` `--flowCode` `--paramKey` `[--originParamKey]` `[--paramValue]` `[--paramDataType]` `[--remark]` |
+| `+delete_flow_param` | Delete one DEV custom parameter after confirmation | `--spaceCode` `--flowCode` `--paramKey` `--yes` |
+| `+get_flow_overview` | View DEV/PROD flow definitions and all task parameter references | `--spaceCode` (`--flowCode` or `--flowName`) `[--env DEV\|PROD]` |
 | `+execute_flow` | Manual PROD execution | `--spaceCode` `--flowCode` `[--baseDate]` |
 | `dataops_operations +get_flow_instance_detail` | View operations instance DAG and task statuses | `--spaceCode` `--flowCode` `--flowInstanceId` |
 | `dataops_operations +get_task_instance_detail` | View operations task detail and optional logs | `--spaceCode` `--flowCode` `--flowInstanceId` (`--taskInstanceId` or `--taskCode` or `--taskName`) `[--includeLog]` |
@@ -207,14 +258,14 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 - **Parameter Reference**: Reference workspace parameters in tasks using `${paramKey}` (e.g., `${ws_run_date}`)
 - **Execution**: `+execute_flow` requires `--spaceCode` and `--flowCode`; `--baseDate` is optional and maps to runtime parameter `bd`. It always runs PROD and returns `action/result/status`; `result` includes `flowCode`, `executeId`, `operationStatus`, `nextAction`, and optional `flowInstanceId`.
 - **Schedule config**: `+save_schedule_config` requires `--spaceCode`, `--flowCode`, and `--enabled`. `--cron` is required only when `--enabled true`; omit it when disabling scheduling. It returns `action/result/status`; `result` includes `enabled`, `flow`, `message`, and `cron` only when enabled.
-- **Release preview**: `+preview_release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `flowCode`, `releaseStatus`, `message`, and `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries may include `changed`, `contentCompare`, and `targetTable`.
+- **Release preview**: `+preview_release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `flowCode`, `releaseStatus`, `message`, and `changes`. Each change may include `scheduleConfigChange` and `tasks`; `scheduleConfigChange.diff.old.parameters` and `.new.parameters` show the flow parameter comparison. Parameter-only changes use the existing flow configuration release. Task entries may include `changed`, `contentCompare`, and `targetTable`.
 - **Release**: `+release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `action/result/status`; `result` includes `flowCode`, `releaseStatus`, `message`, optional `packageCode`, and optional `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries include `changed`.
 - **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, workflow instance check, and task instance check create/update commands. Omit `--preTasks` on update to preserve existing dependencies; pass `--preTasks '[]'` to clear them; pass a non-empty array to replace them.
 - **Retry policy**: All four task types accept `--failRetryTimes`, `--failRetryInterval`, and `--failRetryUnit`. Create defaults to `3`, `5`, and `MINUTE`. Update preserves every omitted retry field. `MINUTE` is the only supported unit.
 - **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; SQL hooks, dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
 - **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; omitted SQL hooks, dependencies, and retry fields keep existing values. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
 - **Task dependency**: `+add_task_relation` requires `--spaceCode`, `--flowCode`, `--preTaskCode`, and `--taskCode`. `preTaskCode` is upstream and `taskCode` is downstream. It returns `action/result/status`; `result` includes `status`, `flowCode`, `preTaskCode`, `taskCode`, and `message`.
-- **Task parameters**: `+get_task_params` requires `--spaceCode`, `--flowCode`, and `--taskCode`; it has no optional flags. It queries DEV and returns `data` as an array. Items include fields such as `paramKey`, `paramType`, `paramDataType`, `paramFrom`, and built-in flags like `isBd`.
+- **Flow and task parameters**: `+get_flow_overview` requires `dwWorkflowEdit` and supports DEV (default) or PROD. It returns all custom flow definitions in `flowParams` and task references in `dag.tasks[].taskParams`, including source, definition value, type, description, and built-in flags. Expressions remain literal; task references retain `paramDataType=QUOTE`. Source is `FLOW` or `SPACE` for configured parameters. A code-parsed reference without a configured source remains visible with null or omitted `paramFrom` and `paramValue` fields; either form means no configured source/value. Empty parameter lists are arrays. Use the selected environment to compare unpublished DEV changes with PROD.
 - **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
 - **Workflow instance check tasks**: `checkItems` is required and replaces the complete check item list. Create defaults `relation/checkInterval/checkTime` to `AND/5/3`; update preserves omitted scalar values. This command creates `FLOW_CHECK`, not task-instance `TASK_CHECK`.
 - **Task instance check tasks**: `checkItems` is required and replaces the complete check item list. Each item identifies a target using `flowCode` and `taskCode`. Create defaults `relation/checkInterval/checkTime` to `AND/10/3`; update preserves omitted scalar values. This command creates `TASK_CHECK`.
@@ -228,7 +279,7 @@ Owning module: gaia-mcp workflow
 
 Current transport: DataOps CLI REST
 
-Covered workflow tools: `flow_create_workflow_instance_check_task`, `flow_update_workflow_instance_check_task`, `flow_create_task_instance_check_task`, `flow_update_task_instance_check_task`, and `flow_delete_task`
+Covered workflow tools: `flow_create_workflow_instance_check_task`, `flow_update_workflow_instance_check_task`, `flow_create_task_instance_check_task`, `flow_update_task_instance_check_task`, `flow_delete_task`, `flow_get_flow_params`, `flow_create_flow_param`, `flow_update_flow_param`, and `flow_delete_flow_param`
 
 Gateway target: TBD after DataOps workflow Gateway schema review
 

package/skills/ae-dataops/references/dataops-flow-monitor.md

@@ -18,6 +18,23 @@ Use `dataops_flow` to execute and control flows. Use `dataops_operations` for sp
 - **flowInstanceId** — Operations workflow instance ID returned by `dataops_operations +search_flow_instances`; use it for operations detail, task logs, and stop
 - **Instance list queries PROD environment by default** (unlike other tools which default to DEV)
 
+In the default CLI JSON, take `executeId` from `data.result.executeId` and an already available `flowInstanceId` from `data.result.flowInstanceId`. Otherwise select `data.instances[]` from operations search and keep its `flowCode` and `flowInstanceId` together. Instance detail supplies `data.taskInstances[].taskInstanceId` for task inspection; a definition's `taskCode` is not a task instance ID.
+
+### Status fields are command-specific
+
+The paths below are relative to the command payload, as used by CLI `--jq`. Prefix them with `.data` when reading the default JSON envelope with an external jq command.
+
+| Command | Execution status path | Trigger path |
+|---|---|---|
+| `+list_flows` | `.flows[].latestProductionInstance.flowInstanceStatus` | `.flows[].latestProductionInstance.historyCmd` |
+| `+search_flow_instances` | `.instances[].status` | `.instances[].triggerType` |
+| `+get_flow_instance_detail` | `.flowInstance.status`; task states in `.taskInstances[].status` | `.flowInstance.triggerType` |
+| `+get_task_instance_detail` | `.status` | Use its flow instance |
+
+`flowStatus` is the workflow definition state, such as `RELEASED`, not execution completion. `flowScheduleStatus` is a separate scheduling state; neither it nor the latest-flow summary replaces inspection of a specific run.
+
+If the selected instance's execution status is missing, null, or unknown, stop status-based polling and inspect the same read command without `--jq`. A missing field projects to null without a jq error; `ok:true` does not make that status usable. If the raw status remains unavailable, report uncertainty rather than treating it as running or successful. Do not apply this rule to legitimately nullable fields such as `endTime`.
+
 ---
 
 ## Workflow A: Find and View Flow Execution Status
@@ -43,6 +60,17 @@ ae-cli dataops_operations +get_flow_instance_detail --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --flowInstanceId ${flowInstanceId}
 ```
 
+`flowKeyword` must be a discovered flow name, remark, or instance ID; search does not match `flowCode`. Filter returned instances by the exact `flowCode` and the requested execution/base date, following `hasMore` when needed. For a newly submitted run, compare the submission time and prior instance list; if several candidates still match, report ambiguity instead of inspecting an arbitrary latest instance.
+
+Once the intended instance is verified, keep its `flowInstanceId` fixed and poll its detail, not all matching instances. A previous instance's `SUCCESS` cannot prove that the requested run completed. If the current CLI cannot correlate `executeId` to one instance confidently, retain the execution handle and report the limitation.
+
+```bash
+# Inspect only the previously verified instance; reuse these IDs while polling.
+ae-cli dataops_operations +get_flow_instance_detail --spaceCode "${spaceCode}" \
+  --flowCode "${flowCode}" --flowInstanceId "${flowInstanceId}" \
+  --jq '{flowInstanceId: .flowInstance.flowInstanceId, status: .flowInstance.status}'
+```
+
 ---
 
 ## Workflow B: Troubleshoot Task Failures
@@ -56,31 +84,35 @@ ae-cli dataops_operations +get_flow_instance_detail --spaceCode "${spaceCode}" \
 ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --flowInstanceId ${flowInstanceId} \
   --taskInstanceId ${taskInstanceId} --includeLog true
-
-# Step 3: Re-execute after fixing
-ae-cli dataops_flow +execute_flow --spaceCode "${spaceCode}" \
-  --flowCode ${flowCode}
 ```
 
+Report the failed task, historical instance/base date, and relevant log evidence first. These commands cannot rerun only failed nodes of that historical instance. Do not substitute `+execute_flow` (a new whole-flow PROD run) or a backfill job for that request. If the user explicitly requests a new whole-flow run, establish its business date, release any required DEV fixes using [the release workflow](dataops-flow-create.md#step-8-preview-release), and continue below; pass `--baseDate` for a requested historical date rather than assuming today's date is equivalent.
+
 ---
 
 ## Workflow C: Manual Execution and Stop
 
 ```bash
-# Manually trigger PROD execution
+# Run only when the user requested a new whole-flow PROD execution
 ae-cli dataops_flow +execute_flow --spaceCode "${spaceCode}" \
   --flowCode ${flowCode}
-# Returns executeId
+# data.result.operationStatus=SUCCESS means accepted; retain data.result.executeId
 
 # Monitor recent executions
 ae-cli dataops_operations +search_flow_instances --spaceCode "${spaceCode}" \
   --keyword "${flowKeyword}" --startDate "${startDate}" --endDate "${endDate}" --pageSize 20
 
-# Stop execution if necessary (irreversible)
+# Stop only when requested, using the verified execution handle
 ae-cli dataops_operations +stop_flow_instance --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --executeId ${executeId}
 ```
 
+An accepted execution is not a completed run. Inspect `data.result.operationStatus`; a non-`SUCCESS` result stops the submission path. Once the instance is identified, read `data.flowInstance.status` from `+get_flow_instance_detail`: `SUCCESS` is successful execution, `FAIL` is failure, and `STOP` or `PAUSE` is not success. `RUNNING` and `READY_PAUSE` are unfinished flow instance states. Task detail uses `data.status`; instance detail uses `data.taskInstances[].status`. A successful read of a failed instance is still a successful query.
+
+For `+search_flow_instances --status`, use only `RUNNING,SUCCESS,FAIL,READY_PAUSE,PAUSE,STOP`. `WAITING` filtering is not supported by the current backend; an empty result with that filter does not establish that no work is waiting. Do not infer support from a different command's scheduling or download status.
+
+When completion is requested, set a finite polling deadline and use read-only instance queries. Stop on a terminal/paused state, an actionable error, or the deadline; then report the IDs, last observed state, and relevant failure evidence. A temporarily absent instance or a timeout does not authorize another `+execute_flow`; retain the original `executeId` and report uncertain correlation or completion. Read the instance again after a stop request to distinguish stop acceptance from an observed `STOP` state.
+
 ---
 
 ## Workflow D: View Flow Structure
@@ -107,19 +139,19 @@ ae-cli dataops_flow +get_flow_overview --spaceCode "${spaceCode}" \
 | `dataops_operations +get_flow_instance_detail` | Operations instance DAG and task statuses | `--spaceCode` `--flowCode` `--flowInstanceId` |
 | `dataops_operations +get_task_instance_detail` | Operations task detail and optional logs | `--spaceCode` `--flowCode` `--flowInstanceId` (`--taskInstanceId` or `--taskCode` or `--taskName`) `[--includeLog]` |
 | `dataops_operations +stop_flow_instance` | Stop a running execution | `--spaceCode` `--flowCode` exactly one of `--executeId` or `--flowInstanceId` |
-| `+get_task_params` | DEV task parameter list | `--spaceCode` `--flowCode` `--taskCode` |
 | `+update_flow` | Update DEV workflow name and/or remark | `--spaceCode` `--flowCode` `[--flowName]` `[--remark]` |
 
 ## Parameter Notes
 
 - **Execution**: `+execute_flow` requires `--spaceCode` and `--flowCode`; `--baseDate` is optional and maps to runtime parameter `bd`. It always runs PROD and returns `action/result/status`; `result` includes `flowCode`, `executeId`, `operationStatus`, `nextAction`, and optional `flowInstanceId`.
 - **Stop flow instance**: `dataops_operations +stop_flow_instance` requires `--spaceCode`, `--flowCode`, and exactly one of `--executeId` or `--flowInstanceId`. `--executeId` comes from `dataops_flow +execute_flow`; `--flowInstanceId` comes from `dataops_operations +search_flow_instances`. It returns `success`, `selector`, and selector-specific stop result fields.
-- **Flow overview**: `+get_flow_overview` requires `--spaceCode` and either `--flowCode` or exact `--flowName`; `--flowCode` takes precedence. `--env` defaults to `DEV`; use `PROD` to include latest production instance fields when available. It returns `success`, `env`, `resolvedBy`, `flow`, `schedule`, `dag`, and `summary`.
+- **Flow overview**: `+get_flow_overview` requires `--spaceCode` and either `--flowCode` or exact `--flowName`; `--flowCode` takes precedence. `--env` defaults to `DEV`; use `PROD` to include latest production instance fields when available. It requires `dwWorkflowEdit` in both environments and returns `success`, `env`, `resolvedBy`, `flow`, `flowParams`, `schedule`, `dag`, and `summary`. `flowParams` contains all custom flow parameters, including unused ones; `dag.tasks[].taskParams` contains each task's references with `paramKey`, `paramType`, `paramDataType`, `paramFrom`, `paramValue`, `paramDesc`, and built-in flags such as `isBd`. Both lists use the selected environment and are empty arrays when no parameters exist. Definition values preserve expression text: a FLOW reference to `p=${bd}` keeps `paramDataType=QUOTE` and `paramValue=${bd}`; it is not an execution date.
 - **Flow update**: `+update_flow` requires `--spaceCode`, `--flowCode`, and at least one of `--flowName` or `--remark`. It returns `action/result/status`; `result` is an array with items containing `flowCode`, `operationStatus`, `nameChanged`, and optional `flowName`.
 - **High-frequency release flows**: `+list_high_frequency_release_flows` requires `--spaceCode`; `--days`, `--topN`, `--minCount`, and `--status` are optional. Defaults are `days=30`, `topN=10`, and `status=SUCCESS`. It returns `period`, `filters`, `flows`, `returnedCount`, and `nextAction`; flow items include `rank`, `flowCode`, `flowName`, `releaseCount`, `lastReleaseTime`, and `avgIntervalHours`.
-- **Operations instance search**: `dataops_operations +search_flow_instances` requires `--spaceCode`; `--keyword`, `--startDate`, `--endDate`, `--status`, `--pageNum`, and `--pageSize` are optional. `--keyword` fuzzy-matches `flowName` or `flowCode`. `pageNum` defaults to `1`; `pageSize` defaults to `20` and maxes at `100`. It returns `totalCount`, `returnedCount`, `pageNum`, `pageSize`, `hasMore`, `instances`, `statusCounts`, `triggerTypeCounts`, and `ownerCounts`.
-- **Task instance detail**: `dataops_operations +get_task_instance_detail` requires `--spaceCode`, `--flowCode`, `--flowInstanceId`, and one selector: `--taskInstanceId`, `--taskCode`, or exact `--taskName`. Prefer `--taskInstanceId` because retries can create multiple instances with the same task code/name. `--includeLog` is optional and defaults to `false`. It returns `success`, `flowInstanceId`, `taskCode`, `taskName`, `taskInstanceId`, `status`, `task`, `taskInstance`, `definition`, and `log` only when requested.
+- **Operations instance search**: `dataops_operations +search_flow_instances` requires `--spaceCode`; `--keyword`, `--startDate`, `--endDate`, `--status`, `--pageNum`, and `--pageSize` are optional. `--keyword` fuzzy-matches instance ID, workflow name, or workflow remark, not `flowCode`; filter the returned `flowCode` exactly. `pageNum` defaults to `1`; `pageSize` defaults to `20` and maxes at `100`. It returns `totalCount`, `returnedCount`, `pageNum`, `pageSize`, `hasMore`, `instances`, `statusCounts`, `triggerTypeCounts`, and `ownerCounts`.
+- **Flow instance detail**: `dataops_operations +get_flow_instance_detail` requires `dwOMInstanceView` and returns the historical execution snapshot in `flowInstance.instanceParamMap`. A missing snapshot is null or omitted; the server does not substitute current parameter definitions. Later definition changes do not change historical execution values.
+- **Task instance detail**: `dataops_operations +get_task_instance_detail` requires `--spaceCode`, `--flowCode`, `--flowInstanceId`, and one selector: `--taskInstanceId`, `--taskCode`, or exact `--taskName`. Prefer `--taskInstanceId` because retries can create multiple instances with the same task code/name. It requires `dwOMInstanceView`. `--includeLog` is optional and defaults to `false`; when enabled, `log.params` contains the task's historical actual execution values. It returns `success`, `flowInstanceId`, `taskCode`, `taskName`, `taskInstanceId`, `status`, `task`, `taskInstance`, `definition`, and `log` only when requested.
 - **env**: `DEV` (development) | `PROD` (production, instance list defaults to PROD)
 - **flow list paging**: `+list_flows` requires `--spaceCode`; `--keyword`, `--pageNum`, and `--pageSize` are optional. It returns `flows`, `totalCount`, `returnedCount`, `pageNum`, `pageSize`, and `hasMore`; flow items include `latestProductionInstance` only when available. `pageSize` defaults to `20` and maxes at `100`.
-- **Task parameters**: `+get_task_params` requires `--spaceCode`, `--flowCode`, and `--taskCode`; it has no optional flags. It queries DEV and returns `data` as an array. Items include fields such as `paramKey`, `paramType`, `paramDataType`, `paramFrom`, and built-in flags like `isBd`.
-- **Task Status**: `success` / `failure` / `running` / `waiting`
+- **Task parameter sources**: Read `dag.tasks[].taskParams` from `+get_flow_overview`. `paramFrom=FLOW` means a flow definition supplies the value; `SPACE` means a space parameter does. A code-parsed reference remains in the list when neither source exists; its `paramFrom` and `paramValue` fields are null or omitted, both meaning no configured source/value. Deleting a flow parameter falls back to a same-name space parameter, or to code-parsed status. Unpublished DEV changes do not alter PROD values or sources.
+- **Task Status**: `WAITING` / `RUNNING` / `SUCCESS` / `FAIL` / `STOP` / `PAUSE`; only `SUCCESS` means successful completion.

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

@@ -16,14 +16,17 @@ Use the `dataops_integration` subcommand to manage datasources and sync solution
 **Core Rules:**
 - Configuration parameters differ significantly between preset repositories (te_etl) and non-preset repositories, must strictly follow templates
 - sourceConfig/sinkConfig/channelConfig/fieldsMapping are all JSON strings
-- Sync solution updates are not partial patches: call `+get_sync_detail --withParams true` first, then submit complete sourceConfig and sinkConfig JSON. Pass channelConfig and fieldsMapping when keeping or updating them
+- Sync solution updates are not partial patches. The current detail command returns a summary, not complete editable configs; follow [Update an Existing Sync Solution](#workflow-d-update-an-existing-sync-solution).
 - Test datasource connection before creating sync solution
 - `sinkConfig.dataSaveMode` codes are fixed: `1 = APPEND_DATA` (insert/append new data; UI label `插入新数据`), `2 = OVERWRITE` (`DROP_DATA`; UI label `覆盖写入`). Never describe `dataSaveMode=1` as overwrite; use `2` for overwrite.
+- Integration `--dry-run` only previews the local request. It does not validate nested JSON, permissions, connections, or execution readiness on the server.
 
 ---
 
 ## Workflow A: Create Datasource
 
+Use the selected component's returned template. The values in angle brackets below are illustrative; replace them with the user's real connection settings before execution. For MySQL, `jdbcUrl` and the separate `database` field are both required.
+
 ```bash
 # Step 1: View supported datasource component types. No spaceCode is required.
 ae-cli dataops_integration +list_datasource_components
@@ -34,18 +37,22 @@ ae-cli dataops_integration +get_datasource_component_template \
 
 # Step 3: Create datasource
 ae-cli dataops_integration +add_datasource --spaceCode "${spaceCode}" \
-  --componentName "MySQL" --dataSourceName "Production MySQL" \
+  --componentName "MySQL" --dataSourceName "${datasourceName}" \
   --sharedConfig true \
-  --envJsonList '[{"host":"localhost","port":3306,"username":"root","password":"xxx"}]'
+  --envJsonList '[{"jdbcUrl":"jdbc:mysql://<host>:3306/<database>","database":"<database>","username":"<username>","password":"<password>"}]'
 
 # Step 4: Test the saved datasource connection by name.
 ae-cli dataops_integration +test_datasource_connect --spaceCode "${spaceCode}" \
-  --datasourceName "Production MySQL"
+  --datasourceName "${datasourceName}"
 ```
 
+Read back the exact datasource name with `+get_datasource_detail`. Creation does not prove connectivity: require `connectStatus=SUCCESS` from the connection test and inspect `connectFails` otherwise. For `+online_datasource`, inspect both `successDataSourceNames` and `failDataSources`; a successful command envelope can contain individual failures.
+
 ---
 
-## Workflow B: Create Sync Solution (Complete Process)
+## Workflow B: Create Sync Solution
+
+Resolve the source/sink identities and source selection (table, filtered table, or custom query), target table and field mapping, and intended write mode before saving. Daily frequency does not imply append or overwrite: settle `dataSaveMode` from the user's intent, including the supported upsert keys when upsert is selected. Ask only for choices that remain unresolved after discovery. Use `+get_sync_detail --withParams true` for an existing solution's `usedParams` before deciding whether a manual run needs `baseDate` (`bd`).
 
 ### Step 1: View Available Datasources
 
@@ -63,6 +70,8 @@ ae-cli dataops_integration +list_sync_datasources --spaceCode "${spaceCode}" --e
 
 ### Step 2: Browse Source Table Structure
 
+Current limitation: `+list_datasource_databases` cannot discover databases for a `te_etl@...` datasource because the backend requires `bizClassify`, which this CLI command does not expose. Report that step as unsupported; do not invent a flag or bypass the CLI through an undocumented API. The commands below cover ordinary external datasources. A catalog value must come from trusted configuration or discovery, not a guessed default.
+
 ```bash
 # List databases under datasource
 ae-cli dataops_integration +list_datasource_databases --spaceCode "${spaceCode}" \
@@ -70,38 +79,38 @@ ae-cli dataops_integration +list_datasource_databases --spaceCode "${spaceCode}"
 
 # List tables under database
 ae-cli dataops_integration +list_datasource_tables --spaceCode "${spaceCode}" \
-  --datasourceId "${datasourceId}" --database "test"
+  --datasourceId "${datasourceId}" --database "${database}"
 # For catalog-based sources such as Databricks, add --catalog "${catalog}".
 
 # Get table structure (columns and partitionColumns)
 ae-cli dataops_integration +get_table_structure --spaceCode "${spaceCode}" \
-  --datasourceId "${datasourceId}" --database "test" --tablePath "users"
+  --datasourceId "${datasourceId}" --database "${database}" --tablePath "${tablePath}"
 # For catalog-based sources such as Databricks, add --catalog "${catalog}".
 ```
 
 ### Step 3: Create Sync Solution
 
-**Key: Must strictly follow JSON templates below to generate parameters**
+Generate the four JSON strings from the templates below with real discovered values, then place them in the shell variables used here. `sourceConfig.datasourceId` must equal `--srcDatasourceId`; `sinkConfig.datasourceId` must equal `--sinkDatasourceId`. Use the same selected `spaceCode` throughout. Do not execute template IDs or table names. Gaia fills `gatewayConfig` from the selected space on creation; do not supply a guessed `companyId` or copy another space's gateway settings.
 
 ```bash
 ae-cli dataops_integration +add_sync_solution --spaceCode "${spaceCode}" \
-  --syncName "MySQL to Preset Repository Sync" \
+  --syncName "${syncName}" \
   --srcComponent "MySQL" --srcDatasourceId "${mysqlDatasourceId}" \
   --sinkComponent "te_etl" --sinkDatasourceId "te_etl@TASK_ENGINE_TRINO" \
-  --sourceConfig '{"component":"MySQL","datasourceId":"xxx","database":"test","tablePath":"users","batchSize":1000}' \
-  --sinkConfig '{"component":"te_etl","datasourceId":"te_etl@TASK_ENGINE_TRINO","database":"","tablePath":"ods_users_mysql","tableType":"PHYSICAL_TABLE","bizClassify":"CURRENT","dbBizType":"TASK_ENV_DB","authedSpace":"","partitionKeys":[],"dataSaveMode":1,"batchSize":20000}' \
-  --channelConfig '{"limitType":"0","gatewayConfig":{"engineFlag":"TASK_ENGINE_TRINO","companyId":1,"appDefinition":"APP_GAIA","bizFlag":"BIZ_GAIA_TASK_RELEASE","repoCode":"te_etl","spaceCode":"default"}}' \
-  --fieldsMapping '{"mapping":[{"source":{"name":"id","type":"int","manual":false,"partitionKey":false,"primaryKey":false,"shardingKey":false,"sortingKey":false,"upsertKey":false},"target":{"name":"id","type":"int","manual":false,"partitionKey":false,"primaryKey":false,"shardingKey":false,"sortingKey":false,"upsertKey":false}}]}'
+  --sourceConfig "${sourceConfigJson}" --sinkConfig "${sinkConfigJson}" \
+  --channelConfig "${channelConfigJson}" --fieldsMapping "${fieldsMappingJson}"
 ```
 
-### Step 4: Execute Sync
+On creation, take `syncId` from `data.result.syncId` in the default CLI JSON envelope, then read `+get_sync_detail` for that exact ID. This verifies the saved identity and exposed summary fields; it does not prove all original JSON fields or a successful run. Preserve the submitted complete configuration when later edits may be needed.
+
+### Step 4: Execute Sync Only When Requested
 
 ```bash
 # Manually execute sync solution
 ae-cli dataops_integration +exec_sync_solution --spaceCode "${spaceCode}" \
   --syncId "${syncId}" --baseDate "${baseDate}"
 
-# List manual sync runs
+# Read back the submitted taskId among manual sync runs
 ae-cli dataops_integration +list_sync_runs --spaceCode "${spaceCode}" \
   --syncId "${syncId}" --limit 20
 
@@ -110,10 +119,32 @@ ae-cli dataops_integration +stop_sync_solution --spaceCode "${spaceCode}" \
   --syncId "${syncId}" --taskId "${taskId}"
 ```
 
+Execution returns `data.result.taskId` and `data.result.status`. The outer `ok:true` and `data.status=SUCCESS` acknowledge the action, not completed data movement. Match that exact `taskId` in `data.runs[]` from `+list_sync_runs`; do not use the newest row without matching its ID. Run states are `WAIT`, `RUNNING`, or `RETRY` while active; `FINISHED` is successful completion, `FAILED` is failure, and `KILLED` is termination. After a stop request, read back the same task instead of treating the stop response as proof of termination. If the task is missing, has an unknown status, or remains active beyond the available wait, report the original `syncId/taskId` and last observed state; do not submit another run to obtain a clearer result.
+
+---
+
+## Workflow C: Schedule Daily Sync Without a Manual Run
+
+For an intent such as "sync this MySQL table daily, publish it, but do not run it now":
+
+1. Complete datasource/solution discovery and configuration above, including target write mode and required date parameters. Reuse the exact existing solution when it already matches the intent.
+2. Follow [Create or Modify Integration Sync Task](dataops-flow-create.md#step-3-create-or-modify-integration-sync-task): create or select the intended flow and bind its DEV integration node to the real `syncId`.
+3. Follow [Configure Schedule](dataops-flow-create.md#step-7-configure-schedule), using the requested daily time and the platform's configured timezone. Resolve an unspecified or ambiguous time/timezone before setting the schedule.
+4. Preview the release, check its business result, and release using [Release to Production and Verify](dataops-flow-create.md#step-9-release-to-production-and-verify). Read `+get_flow_overview --env PROD` for the same `flowCode` and verify the visible integration node, dependencies, enabled schedule, and CRON. The overview does not expose the node's `syncId`; retain the create/update result's `taskCode/syncId` and available release-preview evidence for the binding, and state this readback limit.
+5. Finish with the saved `syncId`, published `flowCode`, verified visible PROD configuration, and the fact that no manual execution was submitted. Do not call `+exec_sync_solution` or `+execute_flow` for this intent. Publication establishes configuration readiness, not the success of a future scheduled run.
+
+## Workflow D: Update an Existing Sync Solution
+
+First inspect the exact `syncId` with `+get_sync_detail --withParams true`. Its `source`, `sink`, and `fieldMapping` are summaries; `withParams` adds `usedParams`, not complete editable `sourceConfig`, `sinkConfig`, `channelConfig`, or `fieldsMapping`. Do not reverse-engineer a replacement payload from those summaries.
+
+Use `+save_sync_solution` only when a trusted, complete original configuration for that same solution is available, such as the retained creation payload, and there is no indication it has since changed. Change the requested values in that configuration and preserve the remaining fields, including channel settings and field mappings. If the original is unavailable or stale, report the current CLI/backend capability gap and request the complete current configuration; do not guess it or create a replacement solution. After saving, read back the same `syncId` and verify the exposed changed fields, explicitly identifying any fields the summary cannot verify.
+
 ---
 
 ## JSON Configuration Templates
 
+These examples show structure, not real resource identities. Replace `ds-id`, database/table names, field names/types, and sample query/filter values from the selected resources. Keep component-specific key names and JSON value types. The MySQL query source intentionally omits `database` and `tablePath`.
+
 ### Preset Repository as Source (sourceConfig)
 
 ```json
@@ -228,22 +259,18 @@ MySQL Sink requires non-empty `database` and `tablePath` and must not contain a
 `1000` to `10000`; omit it to use default `1000`. Strings, enum names, decimals,
 booleans, `null`, and out-of-range values are rejected.
 
-### channelConfig (must include gatewayConfig when source or target involves preset repository)
+### channelConfig
+
+For a new solution, Gaia generates `gatewayConfig` from its space. The minimal no-limit example is:
 
 ```json
 {
-  "limitType": "0",
-  "gatewayConfig": {
-    "engineFlag": "TASK_ENGINE_TRINO",
-    "companyId": 1,
-    "appDefinition": "APP_GAIA",
-    "bizFlag": "BIZ_GAIA_TASK_RELEASE",
-    "repoCode": "te_etl",
-    "spaceCode": "default"
-  }
+  "limitType": "0"
 }
 ```
 
+For updates, preserve the complete trusted original channel settings. If `gatewayConfig` is omitted, Gaia retains the existing gateway settings or derives them from the space; never fabricate tenant or space values.
+
 ### fieldsMapping (bidirectional column mapping)
 
 ```json
@@ -310,12 +337,12 @@ booleans, `null`, and out-of-range values are rejected.
 - **Datasource modification**: `+modify_datasource` creates no preview; it updates only provided optional fields (`risk: write`). Use `--envJsonList` with the same JSON array format as `+add_datasource`.
 - **Datasource online**: `+online_datasource` requires `--spaceCode` and `--dataSourceNames`. It executes directly (`risk: write`) and returns `failDataSources` and `successDataSourceNames`.
 - **Sync datasources**: `+list_sync_datasources` requires `--spaceCode`; `--env` is optional and defaults to `DEV`. It returns `sourceComponentSet` and `sinkComponentSet`, grouped by component, with `dataSourceList` and `supportableComponent`.
-- **Datasource databases**: `+list_datasource_databases` requires `--spaceCode` and `--datasourceId`; `--catalog` and `--env` are optional, and `--env` defaults to `DEV`. It returns an array of objects with `databaseName`.
+- **Datasource databases**: `+list_datasource_databases` requires `--spaceCode` and `--datasourceId`; `--catalog` and `--env` are optional, and `--env` defaults to `DEV`. It returns an array of objects with `databaseName`. Current `te_etl@...` database discovery is unsupported because the CLI lacks the required `bizClassify` parameter.
 - **Datasource tables**: `+list_datasource_tables` requires `--spaceCode`, `--datasourceId`, and `--database`; `--catalog` and `--env` are optional, and `--env` defaults to `DEV`. It returns table metadata including `database`, `tableName`, `tableType`, `tableComment`, `engine`, `disabled`, `disabledReasons`, `sameVersion`, and `supportSharding`.
 - **Datasource table structure**: `+get_table_structure` requires `--spaceCode`, `--datasourceId`, `--database`, and `--tablePath`; `--catalog` and `--env` are optional, and `--env` defaults to `DEV`. It returns `columns` and `partitionColumns`.
 - **Sync solution list**: `+list_sync_solutions` requires only `--spaceCode`. It returns sync metadata including `syncId`, `syncName`, source/sink datasource and table fields, last execution/schedule status codes, owner, remark, and timestamps.
-- **Sync detail**: `+get_sync_detail` requires `--spaceCode` and `--syncId`; `--withParams` is optional and defaults to `false`. It returns source, sink, field mapping, last execution/schedule status, owner, and `nextAction`; `withParams=true` also returns `usedParams`.
-- **Sync update**: `+save_sync_solution` requires `--spaceCode`, `--syncId`, `--sourceConfig`, and `--sinkConfig`; `--syncName`, `--channelConfig`, `--fieldsMapping`, and `--remark` are optional. `syncName` is accepted for compatibility but ignored; the current name is preserved. `sourceConfig` and `sinkConfig` must be complete JSON strings from `+get_sync_detail --withParams true`; pass complete `channelConfig` and `fieldsMapping` when keeping or updating them.
+- **Sync detail**: `+get_sync_detail` requires `--spaceCode` and `--syncId`; `--withParams` is optional and defaults to `false`. It returns source, sink, and field mapping summaries, last execution/schedule status, owner, and `nextAction`; `withParams=true` also returns `usedParams`. It does not return complete editable configs.
+- **Sync update**: `+save_sync_solution` requires `--spaceCode`, `--syncId`, `--sourceConfig`, and `--sinkConfig`; `--syncName`, `--channelConfig`, `--fieldsMapping`, and `--remark` are optional. `syncName` is accepted for compatibility but ignored; the current name is preserved. `sourceConfig` and `sinkConfig` must be complete JSON strings from a trusted original configuration, not reconstructed from `+get_sync_detail`; pass complete `channelConfig` and `fieldsMapping` when keeping or updating them. Follow [the update workflow](#workflow-d-update-an-existing-sync-solution) when the original configuration is unavailable.
 - **Sync runs**: `+list_sync_runs` requires `--spaceCode` and `--syncId`; `--limit` is optional and defaults to `20`. It returns `runs`, `returnedCount`, `limit`, and `nextAction`; each run includes `taskId`, `execType`, `status`, `execTime`, `channelMode`, and `submitter`.
 - **Stop sync run**: `+stop_sync_solution` requires `--spaceCode`, `--syncId`, and `--taskId`. Use `taskId` from `+list_sync_runs` for an active run. It returns `action`, `result` with `execStatus`, `syncId`, and `taskId`, and top-level `status`.
 
@@ -354,7 +381,7 @@ Sharded cluster:
 
 1. **Table name rule**: When writing to preset repository, if table name not specified, use `ods_${source_table_name}_${component_name_lowercase}`
 2. **tablePath**: PostgreSQL uses `schema.table_name`, other components use table name directly
-3. **Preset repository database is empty**, non-preset repository database is required
-4. **channelConfig**: Must include gatewayConfig when involving preset repository
+3. **Database**: Preset repository configurations use an empty database. External table-mode source/sink configurations require a database; MySQL custom query sources must omit database and the other table-only fields.
+4. **channelConfig**: Gaia builds gatewayConfig from the selected space on creation. Preserve trusted channel settings on update; do not guess companyId or copy gateway settings from another space.
 5. **Field mapping**: Each field object must include manual/partitionKey/primaryKey/shardingKey/sortingKey/upsertKey properties
 6. **Conditional required parameters**: Some components (e.g., MongoDB) have additional required fields based on mode, see "Component Conditional Required Parameters" above

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

@@ -61,24 +61,41 @@ ae-cli dataops_ide +search_tables --spaceCode "${spaceCode}" --searchKey "user"
 
 ## Workflow C: Execute SQL Query (Download-Centered Async Flow)
 
-Use this flow for exactly one read-only SQL query. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly. The query semantics are preserved, but the result remains platform-bounded; when present, `downloadRowLimit` reports that cap. This is not an unlimited or full export.
+Use this flow for exactly one read-only SQL query. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly. The result remains platform-bounded; when present, `downloadRowLimit` reports that cap. This is not an unlimited or full export.
+
+For a question such as "how many orders yesterday?", first discover the table and date/count columns, establish DEV/PROD and the business date/time zone, and use an aggregate query when appropriate. Ask only about unresolved choices that change the answer. The existing query endpoint performs platform parameter replacement; single-quote any literal `${...}` intended for the platform so the shell does not expand it first.
 
 ```bash
 # Step 1: Submit SQL and create a download task. Defaults: repoCode=te_etl, engineType=TASK_ENGINE_TRINO.
 ae-cli dataops_ide +submit_sql_query --spaceCode "${spaceCode}" --repoCode "te_etl" \
-  --sql "SELECT * FROM hive.ws_default_dev.dwd_user LIMIT 10" \
+  --sql "${verifiedReadOnlySql}" \
   --engineType "TASK_ENGINE_TRINO"
 
-# Step 2: Poll the download task status by spaceCode/downloadTaskId. Rows are not returned through MCP/CLI.
+# Step 2: Continue only when submission returned data.downloadTaskId, not data.status=REJECTED.
+# Poll the same download task. Rows are not returned through MCP/CLI.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId}
 
 # Step 3: CLI-only streaming save after downloadStatus=SUCCESS. The target is replaced only after the stream completes.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId} --downloadTo "./result.zip"
 
-# (Optional) Cancel the download task.
+# Optional: cancel only when requested, not automatically when the local wait budget expires.
 ae-cli dataops_ide +cancel_sql_query --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId}
 ```
 
+Read the actual business state even when outer `ok:true` is present:
+
+| Response | Next action |
+|---|---|
+| Submit `data.status=REJECTED` or no `data.downloadTaskId` | Report the returned reason/requestId; do not invent an ID or start polling |
+| Status `data.downloadStatus=WAITING/RUNNING/FAILED_RETRY` | Continue bounded polling of the same ID; do not resubmit SQL |
+| Status `UNKNOWN` | Recheck the same task within the wait budget; unresolved is not success or proof that it never ran |
+| Status `FAILED/CANCELLED` | Stop and report the message and task ID; do not silently resubmit |
+| Status `SUCCESS` | Download if the user needs the result; status alone is not the result data |
+
+After `--downloadTo`, require a returned `data.localFile` and inspect the actual ZIP contents. Use a fresh local target; do not assume the internal filename, encoding, delimiter, or headers. For a data question, read the result and answer using its real values and agreed scope; do not end by giving only a download task ID or asking the user to read the file. For an export request, provide the saved file and disclose any result limit. If downloading or reading fails, report that boundary without inventing rows.
+
+When the wait budget expires, return the original `downloadTaskId` and latest observed status with the status command needed to continue. Do not equate a locally timed-out wait with a cancelled or failed server task.
+
 ---
 
 ## Command Quick Reference