@thinkingai/ae-cli 6.1.24 → 6.1.25

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

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

@@ -1,7 +1,7 @@
 ---
 name: dataops-table
-version: 1.0.0
-description: "Data table and view management: search tables, view table details, create physical tables/views. Trigger keywords: create table, table creation, view, data dictionary, table details, datatable, DDL."
+version: 1.2.0
+description: "Data table and view management: search and create tables/views, mutate one table field, recycle an entity, list the recycle bin, and permanently delete a recycled entity. Trigger keywords: table, view, column, recycle bin, permanent deletion, data dictionary, DDL."
 metadata:
   requires:
     bins: ["ae-cli"]
@@ -11,16 +11,19 @@ metadata:
 
 > **Prerequisites:** Read [`ae-dataops/SKILL.md`](../SKILL.md) for general rules.
 
-Use the `dataops_datatable` subcommand to manage data tables.
+Use `dataops_datatable` for all commands in this reference, including table/view recycling and permanent deletion.
 
 **Core Rules:**
-- Creating/modifying/deleting workspace task tables **must use dataops_datatable**, prohibited to use dataops_ide
+- Creating/modifying/deleting workspace task tables **must use the commands in this reference**, never `dataops_ide`
 - Use `+dict_search_tables` as the default discovery command for the visible DataOps catalog
 - Use `dataops_ide +search_tables` only when raw engine-side metadata is needed
 - Use `dataops_ide +ide_list_tables` only after catalog/schema are known and you need schema browsing
 - Confirm no table with the same name exists before creation
 - When creating views or data tables, generate DDL according to **Trino DDL specifications**
 - `+create_table` and `+create_view` create objects in the DEV environment only. Publish PROD separately with `+publish_entity`.
+- Field mutation commands resolve one TASK_ENV Hive physical table by `spaceCode + tableName` and change DEV only. Publish PROD separately.
+- Never add, modify, or delete a partition field. Field rename and batch mutation are not supported.
+- Recycling and permanent deletion affect the exact entity's existing DEV and PRODUCT mappings immediately; they are not DEV-only edits awaiting publication.
 
 ---
 
@@ -70,15 +73,131 @@ ae-cli dataops_datatable +publish_entity --spaceCode "${spaceCode}" \
 
 ---
 
+## Workflow D: Add, Modify, or Delete One Field
+
+Read the current DEV table first. Call the command once per field and wait for each actual result before changing the next field.
+
+```bash
+ae-cli dataops_datatable +get_table_detail --spaceCode "${spaceCode}" \
+  --tableName "orders" --manageMode TASK_ENV --env DEV --entityType TABLE
+
+# Add one nullable ordinary field at the end. --dry-run performs a server semantic preview.
+ae-cli dataops_datatable +add_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --fieldType "decimal(18,2)" \
+  --comment "Order amount" --dry-run
+ae-cli dataops_datatable +add_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --fieldType "decimal(18,2)" \
+  --comment "Order amount"
+
+# Change type and comment together. Omit an option to preserve that attribute.
+ae-cli dataops_datatable +modify_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --fieldType "double" \
+  --comment "Order amount in settlement currency" --dry-run
+ae-cli dataops_datatable +modify_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --fieldType "double" \
+  --comment "Order amount in settlement currency"
+
+# Clear only the physical field comment.
+ae-cli dataops_datatable +modify_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --clearComment
+
+# Preview deletion without confirmation. Execute with --yes only after explicit user confirmation.
+ae-cli dataops_datatable +delete_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --dry-run
+ae-cli dataops_datatable +delete_table_field --spaceCode "${spaceCode}" \
+  --tableName "orders" --fieldName "amount" --yes
+```
+
+The semantic preview returns `executable`, `wouldChange`, `plannedDiff`, blockers, and warnings without writing. Execution returns the actual post-readback `outcome`: `CHANGED`, `UNCHANGED`, `PARTIAL`, or `FAILED`. `UNCHANGED` includes a reason. `PARTIAL` and `FAILED` are command failures and exit non-zero.
+
+Partition field mutations are always blocked. Standard TASK_ENV Hive external tables are supported, but `EXTERNAL_FILE_SCHEMA_NOT_VERIFIED` means the external file schema was not validated or rewritten. A type change also reports `DATA_COMPATIBILITY_NOT_VERIFIED`.
+
+---
+
+## Entity Lifecycle: Scope and Safety
+
+These commands accept one TASK_ENV entity in the current space's built-in `te_etl` / `hive` warehouse: an ordinary physical table (including external tables) or an ordinary view. View SQL modification, restore, batch deletion, clearing the whole recycle bin, and cascading dependency deletion are not supported.
+
+Both writes require `--spaceCode`, `--entityId`, and `--name`. The server verifies that the ID and name identify the same current-space entity; a missing ID never falls back to a new same-name object. `--dry-run` sends `preview: true` for validation without deletion, and does not require `--yes`.
+
+`RECYCLE_NAME_CONFLICT` means an old same-name entity already exists in the recycle bin. Inspect the recycle bin and obtain separate explicit authorization before deleting that old entity. Recycling never deletes it automatically. Do not change IDs or retry by name to bypass a conflict.
+
+The recycle-bin list keeps different entity IDs separate even when their names match. Each entry includes `entityId`, `name`, `entityType`, `environments`, and `recycleTime`; totals include `totalCount`, `returnedCount`, and `hasMore`. The server defaults to 100 results, maximum 1000. Refine `--search` if truncated.
+
+An already recycled entity returns `UNCHANGED` with a reason. Permanent deletion accepts only recycled entities, not active or mixed-state entities. Writes return `PREVIEW`, `CHANGED`, `UNCHANGED`, `FAILED`, or `PARTIAL`; actual state changes appear in `diff`. `FAILED` and `PARTIAL` exit non-zero. Re-read the same entity ID after a failure; deletion across storage and metadata is not atomic. Existing physical-table locking is reused, but this does not add a shared lock across all view operations.
+
+Permissions: recycle requires `dwDataTableEdit`, list requires `dwDataTableView`, and permanent deletion requires `dwDeleteTable`. External file deletion remains governed by existing engine behavior; the CLI adds no external-file cleanup action.
+
+### Workflow E: Recycle a Table or View
+
+An ordinary "delete table/view" request follows this workflow only. It does not authorize permanent deletion.
+
+Find the active entity with `+dict_search_tables` and inspect `+get_table_detail`. Verify TASK_ENV scope and the existing DEV/PRODUCT mappings. Copy its exact `entityId` and name; never derive an ID from a name. Then preview:
+
+```bash
+ae-cli dataops_datatable +entity_recycle --spaceCode "${spaceCode}" \
+  --entityId "${entityId}" --name "${name}" --dry-run
+```
+
+Explain the planned changes and that execution immediately affects existing DEV and PRODUCT mappings. Only after explicit user confirmation, execute:
+
+```bash
+ae-cli dataops_datatable +entity_recycle --spaceCode "${spaceCode}" \
+  --entityId "${entityId}" --name "${name}" --yes
+```
+
+Inspect the actual outcome and confirm the exact recycled entity in `+recycle_bin_list`. Report `UNCHANGED` as already recycled, not as a new change. Do not infer completion from a preview, HTTP success, or a name match alone. On `FAILED`, `PARTIAL`, or unverified state, report the observed result, reconcile the same entity ID, and stop without offering permanent deletion.
+
+After actual recycling is confirmed, the Agent may ask:
+
+> The entity is in the recycle bin. Would you like to permanently delete it? This is irreversible and may delete internal table data.
+
+This question belongs in the Agent's reply, not CLI output. Stop here unless the user gives a new explicit confirmation; a successful recycle is not permission to run the next workflow.
+
+### Workflow F: Permanently Delete a Recycled Table or View
+
+Use this workflow only for an explicit permanent-deletion request or a new affirmative answer to the post-recycle question. Never append it automatically to ordinary deletion.
+
+Recycled objects are absent from the active table catalog. List the recycle bin, then copy and verify the exact `entityId`, name, entity type, and affected environments. If the object is active or mixed-state, stop; do not silently recycle it or choose a same-name recycled object.
+
+```bash
+ae-cli dataops_datatable +recycle_bin_list --spaceCode "${spaceCode}" \
+  --search "${name}" --maxResults 100
+```
+
+Preview only the verified recycled object:
+
+```bash
+ae-cli dataops_datatable +recycle_bin_delete --spaceCode "${spaceCode}" \
+  --entityId "${recycledEntityId}" --name "${name}" --dry-run
+```
+
+Explain the irreversible effect, including possible internal table data deletion, and obtain explicit confirmation for this exact target and environment scope before execution. Recycling authorization does not authorize permanent deletion.
+
+```bash
+ae-cli dataops_datatable +recycle_bin_delete --spaceCode "${spaceCode}" \
+  --entityId "${recycledEntityId}" --name "${name}" --yes
+```
+
+Inspect the actual outcome and `diff`, then read the recycle bin again for the same ID. A truncated list or a missing name alone is not proof of deletion. On failure or partial completion, report the observed state and reconcile the same ID before any retry; do not switch to a newly created same-name entity.
+
+---
+
 ## Command Quick Reference
 
-| Command | Purpose | Key Flags |
-|---------|---------|-----------|
-| `+dict_search_tables` | DataOps table catalog search, default 50 results | `--spaceCode` `--search` `--maxResults` |
-| `+get_table_detail` | DataOps catalog detail | `--spaceCode` `--tableName` `--manageMode` `--env` `--entityType TABLE|VIEW` |
-| `+create_table` | Create DataOps physical table in DEV | `--spaceCode` `--ddl` |
-| `+create_view` | Create DataOps view in DEV | `--spaceCode` `--ddl` |
-| `+publish_entity` | Publish table/view from DEV to PROD | `--spaceCode` `--name` `[--entityId]` `[--entityType]` |
+| Command | Purpose | Risk | Key Flags |
+|---------|---------|------|-----------|
+| `ae-cli dataops_datatable +dict_search_tables` | DataOps table catalog search, default 50 results | read | `--spaceCode` `--search` `--maxResults` |
+| `ae-cli dataops_datatable +get_table_detail` | DataOps catalog detail | read | `--spaceCode` `--tableName` `--manageMode` `--env` `--entityType TABLE\|VIEW` |
+| `ae-cli dataops_datatable +create_table` | Create DataOps physical table in DEV | write | `--spaceCode` `--ddl` |
+| `ae-cli dataops_datatable +create_view` | Create DataOps view in DEV | write | `--spaceCode` `--ddl` |
+| `ae-cli dataops_datatable +publish_entity` | Publish table/view from DEV to PROD | write | `--spaceCode` `--name` `[--entityId]` `[--entityType]` |
+| `ae-cli dataops_datatable +add_table_field` | Append one ordinary field in DEV | write | `--spaceCode` `--tableName` `--fieldName` `--fieldType` `[--comment]` |
+| `ae-cli dataops_datatable +modify_table_field` | Change one ordinary field type and/or comment in DEV | write | `--spaceCode` `--tableName` `--fieldName` `[--fieldType]` `[--comment\|--clearComment]` |
+| `ae-cli dataops_datatable +delete_table_field` | Delete one ordinary field in DEV | high-risk-write | `--spaceCode` `--tableName` `--fieldName`; `--yes` after confirmation |
+| `ae-cli dataops_datatable +entity_recycle` | Move one table/view and its DEV/PRODUCT mappings to the recycle bin | high-risk-write | `--spaceCode` `--entityId` `--name`; `--yes` after confirmation |
+| `ae-cli dataops_datatable +recycle_bin_list` | Find recycled entities by ID, including same-name objects | read | `--spaceCode` `[--search]` `[--maxResults]` |
+| `ae-cli dataops_datatable +recycle_bin_delete` | Permanently delete one recycled entity | high-risk-write | `--spaceCode` `--entityId` `--name`; `--yes` after confirmation |
 
 ## Parameter Notes
 
@@ -87,5 +206,18 @@ ae-cli dataops_datatable +publish_entity --spaceCode "${spaceCode}" \
 - **create_table**: Requires `--spaceCode` and `--ddl`; no optional flags. Creates a DataOps physical table in DEV only. The backend parses Trino-compatible DDL and saves TASK_ENV metadata in the default workspace warehouse (`repo=te_etl`, `catalog=hive`). Publish by name with `+publish_entity --name <tableName>`.
 - **create_view**: Requires `--spaceCode` and `--ddl`; no optional command flags. Creates a DataOps view in DEV only. The backend saves TASK_ENV metadata through the DataView save flow in the default workspace warehouse (`repo=te_etl`, `catalog=hive`). Publish by name with `+publish_entity --name <viewName>`. Keep the literal `${env}` placeholder when referencing current-space task tables, for example `ws_${spaceCode}_${env}`.
 - **publish_entity**: Requires `--spaceCode` and `--name`. Publishes one existing TASK_ENV table/view from DEV to PROD. Optional `--entityId` disambiguates same-name matches; optional `--entityType TABLE|VIEW` validates the resolved type. Returns `action/result/status`; result includes published ids/names and `ONLINE` status, or `errorType`/`candidates`/`errors`.
+- **add_table_field**: Requires an exact table and field name plus one complete Trino-compatible `--fieldType`. Optional `--comment` sets the physical column comment. An identical existing definition returns `UNCHANGED`; a conflicting existing field returns `FIELD_ALREADY_EXISTS`.
+- **modify_table_field**: Requires at least one of `--fieldType`, `--comment`, or `--clearComment`. `--comment` and `--clearComment` are mutually exclusive. A missing field returns `FIELD_NOT_FOUND`; the command never adds or upserts it.
+- **delete_table_field**: High-risk write. Run the semantic preview first, obtain explicit user confirmation, and only then use `--yes`. A missing field returns `FIELD_NOT_FOUND`.
+- **field mutation result**: Only the target field and attributes that actually changed appear in `diff`. None of the three field mutation commands accepts `entityId`, `expectedVersion`, environment, rename, position, default value, `NOT NULL`, or a field array.
 - **schema naming**: DEV environment uses `ws_${spaceCode}_dev`, PROD environment uses `ws_${spaceCode}_product`. Do not hardcode either schema in current-space view DDL; use `ws_${spaceCode}_${env}` with literal `${env}`.
 - **Table name rule**: `^[a-z][0-9a-z_]{0,127}$`
+
+## Transitional Status
+
+- Transition status: transitional
+- Owning module: gaia-mcp-datatable
+- Current transport: Gaia CLI REST
+- Gateway target: TBD
+- Review after: 2026-12-04
+- Exit condition: Equivalent Gateway capabilities preserve semantic preview, single-field input, exact entity-ID lifecycle operations, recycle-bin discovery, deletion confirmation, and structured actual outcomes.