@thinkingai/ae-cli 6.0.27 → 6.0.29

package/skills/ae-analysis/references/virtual_event_delete.md

@@ -0,0 +1,24 @@
+# analysis-meta virtual-event delete
+
+Use when the user needs to delete a virtual event rule.
+
+Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+
+Command:
+
+```bash
+ae-cli analysis-meta virtual-event delete --project-id <project_id> --v-event-id <v_event_id>
+ae-cli analysis-meta virtual-event delete --dry-run
+```
+
+Capability id: `metadata.virtual_event.delete`.
+
+Input sends `project_id`, `v_event_id`.
+
+Output is the gateway envelope. `data` contains the common-service capability result.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--v-event-id` | Yes | Virtual event ID. |

package/skills/ae-analysis/references/virtual_event_get.md

@@ -0,0 +1,24 @@
+# analysis-meta virtual-event get
+
+Use when the user needs to get virtual event rule.
+
+Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+
+Command:
+
+```bash
+ae-cli analysis-meta virtual-event get --project-id <project_id> --v-event-id <v_event_id>
+ae-cli analysis-meta virtual-event get --dry-run
+```
+
+Capability id: `metadata.virtual_event.get`.
+
+Input sends `project_id`, `v_event_id`.
+
+Output is the gateway envelope. `data` contains the common-service capability result.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--v-event-id` | Yes | Virtual event ID. |

package/skills/ae-analysis/references/virtual_property_create.md

@@ -0,0 +1,24 @@
+# analysis-meta virtual-property create
+
+Use when the user needs to create a SQL virtual event or user property.
+
+Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+
+Command:
+
+```bash
+ae-cli analysis-meta virtual-property create --project-id <project_id> --payload '{}'
+ae-cli analysis-meta virtual-property create --dry-run
+```
+
+Capability id: `metadata.virtual_property.create`.
+
+Input sends `project_id`, `payload`.
+
+Output is the gateway envelope. `data` contains the common-service capability result.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--payload` | Yes | Capability payload JSON. |

package/skills/ae-analysis/references/virtual_property_sql_rule_delete.md

@@ -0,0 +1,25 @@
+# analysis-meta virtual-property sql-rule-delete
+
+Use when the user needs to delete or revoke SQL virtual property rule.
+
+Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+
+Command:
+
+```bash
+ae-cli analysis-meta virtual-property sql-rule-delete --project-id <project_id> --v-prop-id <v_prop_id> --operation <operation>
+ae-cli analysis-meta virtual-property sql-rule-delete --dry-run
+```
+
+Capability id: `metadata.virtual_property.sql_rule_delete`.
+
+Input sends `project_id`, `v_prop_id`, `operation`.
+
+Output is the gateway envelope. `data` contains the common-service capability result.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--v-prop-id` | Yes | Virtual property ID. |
+| `--operation` | No | Delete operation. Use revoke to revoke instead of delete. |

package/skills/ae-analysis/references/virtual_property_sql_rule_update.md

@@ -0,0 +1,24 @@
+# analysis-meta virtual-property sql-rule-update
+
+Use when the user needs to update SQL virtual property rule.
+
+Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
+
+Command:
+
+```bash
+ae-cli analysis-meta virtual-property sql-rule-update --project-id <project_id> --payload '{}'
+ae-cli analysis-meta virtual-property sql-rule-update --dry-run
+```
+
+Capability id: `metadata.virtual_property.sql_rule_update`.
+
+Input sends `project_id`, `payload`.
+
+Output is the gateway envelope. `data` contains the common-service capability result.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project-id` | Yes | Numeric project ID. |
+| `--payload` | Yes | Capability payload JSON. |

package/skills/ae-capability/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ae-capability
+version: 1.2.0
+description: "AE/TE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, dry-run a capability, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields."
+---
+
+# ae-capability
+
+Use this skill for progressive capability discovery and generic gateway invocation. Prefer a domain-specific curated command when one exists; use `ae-cli capability ...` for discovery and long-tail capabilities.
+
+## Decision Order
+
+1. Use a domain skill and its curated command when it directly covers the task.
+2. Otherwise search the capability catalog.
+3. Inspect the selected capability before constructing input.
+4. Dry-run with real input when helpful.
+5. Run after dry-run succeeds; obtain chat confirmation only for delete capabilities.
+
+Never guess a capability ID, input field, enum value, resource ID, or project ID.
+
+## Skill references
+
+Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → `dry-run` → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.
+
+Create or keep a standalone reference only when at least one applies: L2 hard bar, easily confused with neighbors, `high-risk-write` delete workflow, or multi-step orchestration. Domain skills may inline one-line summaries in overview matrices (e.g. `analysis_gateway_assets.md`). See [`capability-command-admission` §10](../../docs/capability-command-admission.md).
+
+## Commands
+
+```bash
+# List summaries for one capability namespace.
+ae-cli capability list --domain <domain>
+
+# Search capability IDs and descriptions. All terms must match.
+ae-cli capability search "<terms>" --domain <domain>
+
+# Read input_schema, risk, auth, output, and dry-run support.
+ae-cli capability inspect <capability-id>
+
+# Validate and preview input without execution.
+ae-cli capability dry-run <capability-id> --input '<json-object>'
+
+# Execute after inspection (and dry-run when input is non-trivial).
+ae-cli capability run <capability-id> --input '<json-object>'
+```
+
+`--input` accepts:
+
+- An inline JSON object.
+- A JSON file path.
+- `@<path>`.
+- `-` to read JSON from stdin.
+
+The capability namespace is inferred from `<capability-id>` for `inspect`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing.
+
+## Risk Levels (aligned with lark-cli)
+
+| `risk` | Meaning | Chat confirmation before `run`? | CLI `[y/N]` without `--yes`? |
+| --- | --- | --- | --- |
+| `read` | Query / list / inspect | No | No |
+| `write` | Create, update, share, and other ordinary writes | No | No |
+| `high-risk-write` | Delete or remove resources | **Yes** | **Yes** |
+
+Legacy values such as `create`, `update`, or `delete` are normalized to this three-tier model (`delete` → `high-risk-write`; `create`/`update` → `write`).
+
+## Safety
+
+- `list`, `search`, `inspect`, and `dry-run` never execute business mutations.
+- `capability run` inspects metadata before execution when `--yes` is absent.
+- Only `high-risk-write` requires chat confirmation before `capability run ... --yes`.
+- `read` and `write` may run directly after inspect/dry-run.
+- Use `--yes` on delete runs only after the user explicitly authorizes execution in chat.
+- Global `--dry-run` on `capability run` calls the gateway dry-run endpoint instead of execute.
+
+## High-Risk Confirmation Workflow (Agent)
+
+Applies only when `inspect` shows `risk=high-risk-write`.
+
+User intent (for example "delete this space") is **not** execution authorization. Do not pass `--yes` just because the user stated the desired action.
+
+1. Run `capability inspect` and `capability dry-run` with the final input.
+2. **Stop in the same turn.** Do not call `capability run` in the same turn as dry-run.
+3. Summarize in chat: capability ID, `project_id`, key input fields, and `risk=high-risk-write`.
+4. Ask the user to confirm execution. Prefer `AskUserQuestion` when that tool is available; otherwise ask in plain text and wait for the user's **next message**.
+5. Only after the user replies with explicit authorization (for example `confirm`, `execute`, or `yes`) run `capability run ... --yes` with the same input as dry-run.
+
+For `risk=write`, run directly after a successful dry-run; no chat confirmation gate.
+
+Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do not work in Agent Bash; chat confirmation is the real gate for `high-risk-write`.
+
+## Output
+
+- `list` returns `{ domain, count, capabilities }`.
+- `search` returns `{ domain, query, count, capabilities }`.
+- `inspect`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.
+
+## Examples
+
+```bash
+ae-cli capability search "dashboard list" --domain analysis
+ae-cli capability inspect analysis.dashboard.list
+ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
+ae-cli capability run analysis.dashboard.list --input input.json
+```

package/skills/ae-community/SKILL.md

@@ -214,4 +214,4 @@ Structured multi-step reports (MCP tool chains) — open the linked reference fo
 
 ## Write operations
 
-Most community commands are **read-only**. If new write-capable commands are added later, confirm user intent and use `--yes` where the CLI marks **`risk: write`**.
+Most community commands are **read-only**. If new write-capable commands are added later, confirm user intent and use `--yes` where the CLI marks **`risk: high-risk-write`**.

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

@@ -236,10 +236,10 @@ ae-cli dataops_integration +stop_sync_solution --spaceCode "${spaceCode}" \
 - **Datasource component template**: `+get_datasource_component_template` requires only `--componentName`. It returns component metadata, `requiredFields`, `optionalFields`, `envJsonExampleObject`, and `importantNotes`.
 - **Datasource list**: `+list_space_datasources` requires `--spaceCode`; `--datasourceName` and `--componentName` are optional filters. It returns datasource summary fields including `datasourceId`, `dataSourceComponentName`, `dataSourceName`, `dataSourceRemark`, `dataSourceStatus`, `connectStatus`, `syncTaskNum`, and `sharedConfig`.
 - **Datasource detail**: `+get_datasource_detail` requires `--spaceCode` and `--datasourceName`. It returns `datasourceId`, `dataSourceComponentName`, `dataSourceName`, `dataSourceRemark`, `dataSourceStatus`, `connectStatus`, `syncTaskNum`, `sharedConfig`, masked `connectConfig`, `connectFails`, and `lastConnectTime`.
-- **Datasource creation**: `+add_datasource` creates directly after the CLI write confirmation. `envJsonList` must be a JSON array string using keys from the component template `requiredFields`; `sharedConfig=true` uses one config for DEV/PROD, while `sharedConfig=false` requires two configs (DEV, PROD).
+- **Datasource creation**: `+add_datasource` creates directly (`risk: write`, no CLI confirmation). `envJsonList` must be a JSON array string using keys from the component template `requiredFields`; `sharedConfig=true` uses one config for DEV/PROD, while `sharedConfig=false` requires two configs (DEV, PROD).
 - **Datasource connection test**: `+test_datasource_connect` requires `--spaceCode` and `--datasourceName`. It tests the saved datasource config and returns `datasourceName`, `connectStatus`, `connectFails`, `lastConnectTime`, and `nextAction`.
-- **Datasource modification**: `+modify_datasource` creates no preview; it updates only provided optional fields after the CLI write confirmation. Use `--envJsonList` with the same JSON array format as `+add_datasource`.
-- **Datasource online**: `+online_datasource` requires `--spaceCode` and `--dataSourceNames`. It executes after the CLI write confirmation and returns `failDataSources` and `successDataSourceNames`.
+- **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 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`.

package/skills/ae-engage/SKILL.md

@@ -228,12 +228,12 @@ Commands that accept date parameters usually use `yyyy-MM-dd`, for example `--st
 
 ## Write Operation Reminder
 
-The following commands are write operations. Confirm that the user intent is explicit before executing them:
+High-risk delete commands (`risk: high-risk-write`) require explicit user authorization before execution. Ordinary write commands (`risk: write`) do not:
 
-- Channels and config channels: `+add_channel`, `+delete_channel`, `+update_channel_status`, `+delete_config_channel`, `+update_config_channel_status`
-- Strategies and config items: `+delete_config_item`, `+copy_config_template`, `+manage_strategy`
-- Flows: `+save_flow`, `+modify_flow_base_info`, `+manage_flow`, `+delete_flow`
-- Tasks: `+save_task`, `+manage_task`
+- Channels and config channels: `+add_channel` (write), `+delete_channel` (high-risk-write), `+update_channel_status` (write), `+delete_config_channel` (high-risk-write), `+update_config_channel_status` (write)
+- Strategies and config items: `+delete_config_item` (high-risk-write), `+copy_config_template` (write), `+manage_strategy` (write)
+- Flows: `+save_flow` (write), `+modify_flow_base_info` (write), `+manage_flow` (write), `+delete_flow` (high-risk-write)
+- Tasks: `+save_task` (write), `+manage_task` (write)
 
 For task draft creation or update, use this workflow:
 

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

@@ -97,7 +97,8 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
    - If the project is missing, ambiguous, or has no `appId`, ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".
 2. **SERVER_URL** — Data ingestion endpoint (**different from web URL**; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
    - If `meta.project_id` is known, you may try `ae-cli analysis_meta +get_project_config --project_id <project_id>` once.
-   - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, or equivalent ingestion endpoint field.
+   - Use the returned value only if the response explicitly contains a receiver URL field such as `serverUrl`, `pushUrl`, `push_url`, `receiverUrl`, `publicUrl`, `publicReceiverAddress`, `privateReceiverAddress`, or equivalent ingestion endpoint field.
+   - If both `publicReceiverAddress` and `privateReceiverAddress` are present, prefer `publicReceiverAddress` as `SERVER_URL` for generated snippets unless the user explicitly needs an internal/private-network receiver.
    - If a value is found, ask: **"I found SERVER_URL `<url>` for project `<projectId>`. Use it? yes / enter new value"**
    - ⚠️ "Public URL" only shows if previously filled in; if empty, this field won't display
    - Solution: ask ops for the URL, or **skip this step** (use `SERVER_URL` or `PUSH_URL` placeholder in code)
@@ -507,6 +508,20 @@ Upload list rules:
 - Include generated debug scripts if the user selected the debug option.
 - Do not upload files inserted directly into the user's project; only upload generated output artifacts.
 
+### Attachment upload compatibility
+
+The Agent attachment backend accepts a limited document MIME set. Code/config artifacts such as `.java`, `.kt`, `.swift`, `.m`, `.ets`, `.cs`, `.py`, `.go`, `.ts`, `.js`, `.php`, and `.json` may be rejected if uploaded directly.
+
+Before running `ae-cli agent +add-attachment`, prepare the upload list as follows:
+- Keep every original generated file unchanged under `.ae-cli/output/`.
+- For each generated text artifact whose extension may be unsupported by the attachment backend, create an upload-only sibling copy by appending `.txt` to the filename.
+  - Example: `.ae-cli/output/java-sdk.java` → `.ae-cli/output/java-sdk.java.txt`
+  - Example: `.ae-cli/output/daemon.json` → `.ae-cli/output/daemon.json.txt`
+- The `.txt` copy must have identical content to the original file. Do not wrap it in markdown fences, do not add headers, and do not change line endings intentionally.
+- Upload the `.txt` compatibility copies instead of the unsupported originals.
+- Keep `.md`, `.txt`, and `.csv` artifacts in the upload list as-is.
+- In the final response, list the original deliverable paths first, then mention any `.txt` compatibility copies used only for attachment upload.
+
 If upload succeeds, include the attachment upload result in the final response and tell the user the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, keep the local `.ae-cli/output/` files and tell the user the upload did not complete.
 
 ### All snippets

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -247,6 +247,22 @@ Upload list must include:
 
 Only upload generated output artifacts. Do not upload files inserted directly into the user's project.
 
+### Upload Compatibility for Code and Config Files
+
+The attachment upload endpoint accepts a limited document MIME set. Many generated tracking artifacts are valid text files but have extensions that may be rejected by the backend when uploaded directly, including `.java`, `.kt`, `.swift`, `.m`, `.ets`, `.cs`, `.py`, `.go`, `.ts`, `.js`, `.php`, and `.json`.
+
+Before calling `ae-cli agent +add-attachment`, build an upload-safe file list:
+
+1. Keep the original generated files unchanged in `.ae-cli/output/`.
+2. For each unsupported text artifact, create a sibling upload-only copy with `.txt` appended to the original filename.
+   - `.ae-cli/output/android-sdk-java.java` → `.ae-cli/output/android-sdk-java.java.txt`
+   - `.ae-cli/output/daemon.json` → `.ae-cli/output/daemon.json.txt`
+3. Copy the content exactly. Do not add markdown fences, comments, titles, or any extra bytes beyond the original text content.
+4. Upload the `.txt` compatibility copies instead of the unsupported originals.
+5. Upload already-supported text artifacts such as `.md`, `.txt`, and `.csv` directly.
+
+The final deliverable list should still point users to the original generated files. Mention the `.txt` files only as attachment-upload compatibility copies.
+
 If upload succeeds, report that the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, preserve the local output files and report the upload failure separately.
 
 ---
@@ -325,7 +341,7 @@ After generation, perform language style checks on each output file:
 
 #### Step 5: Upload Generated Artifacts
 
-Upload all generated `.ae-cli/output/` artifacts to the Agent attachment library using `ae-cli agent +add-attachment --yes --files '<json-array>'`.
+Prepare upload compatibility copies for unsupported code/config extensions, then upload the safe file list to the Agent attachment library using `ae-cli agent +add-attachment --yes --files '<json-array>'`.
 
 ---
 

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

@@ -82,7 +82,7 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > Determine `<user_lang>` from user's input language: Chinese→`zh`, English→`en`, Japanese→`ja`, Korean→`ko`. Other languages default to `en`.
 > All subsequent CLI commands must be prefixed with `AE_LANG=<user_lang>` to ensure CLI output and generated xlsx headers match the user's language.
 
-Collect the following **5 items** sequentially, **do NOT ask all at once**:
+Collect the following **4 items** sequentially, **do NOT ask all at once**:
 
 ### Item 1 — Application Scenario
 
@@ -122,15 +122,16 @@ Reply with number(s), e.g. 1 or 1,3. Select up to 2.
 ```
 
 Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
+When translating this prompt, preserve the numeric prefixes and line breaks exactly. Every visible option MUST be on its own line and MUST begin with `1 -`, `2 -`, `3 -`, etc. Never place two numbered options in the same paragraph or visual line. If a Markdown renderer may collapse soft line breaks, use Markdown hard line breaks (two trailing spaces before newline) rather than blank lines. Translation may change only the option text, not the numbering prefix or one-option-per-line structure.
 
 User can multi-select (max 2). Interpret numbers by the **visible list shown to the user**, not by the non-sandbox canonical list.
 
-Canonical source material options:
+Canonical source material options (non-sandbox numbering):
 
-- **Product document** (local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
-- **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
-- **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
-- **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
+1. **Product document** ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
+2. **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
+3. **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties
+4. **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)
 
 Based on user selection, determine source material type and record to `meta.source_type`:
 
@@ -143,8 +144,29 @@ Based on user selection, determine source material type and record to `meta.sour
 | Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: template → codebase → prd → chat) |
 
 **Follow-up questions** (ask in selection order):
-- Product doc → if not in a sandbox environment, ask **"What is the product document path? You can provide one or more paths, separated by commas or newlines (local paths, URLs, image files, or folders)"**
-- Product doc → if in a sandbox environment, ask **"What is the product document path? You can provide one or more sandbox workspace paths, uploaded attachment paths, URLs, image files, or folders. You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available."**
+- Product doc → if not in a sandbox environment, ask exactly:
+  ```text
+  What is the product document path?
+
+  You can provide one or more items, separated by commas or newlines:
+  1. Local file path
+  2. URL
+  3. Image file path
+  4. Folder path
+  ```
+- Product doc → if in a sandbox environment, ask exactly:
+  ```text
+  What is the product document path?
+
+  You can provide one or more items, separated by commas or newlines:
+  1. Sandbox workspace path
+  2. Uploaded attachment path
+  3. URL
+  4. Image file path
+  5. Folder path
+
+  You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available.
+  ```
 - Detailed description → If too vague, follow up on core features, user behaviors, business flows, monetization
 - Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic
 - Pre-built template → display matching templates for user confirmation

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

@@ -5,8 +5,8 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table sql-write --project-id <project_id> --operation create --table-name datatable_<project_id>_<name> --columns '<columns_json>' --qp '<qp_json>' --zone-offset 8 --strategy overwrite --yes
-ae-cli metadata data-table sql-write --project-id <project_id> --operation update --data-table-id <id> --columns '<columns_json>' --qp '<qp_json>' --yes
+ae-cli metadata data-table sql-write --project-id <project_id> --operation create --table-name datatable_<project_id>_<name> --columns '<columns_json>' --qp '<qp_json>' --zone-offset 8 --yes
+ae-cli metadata data-table sql-write --project-id <project_id> --operation update --data-table-id <id> --columns '<columns_json>' --qp '<qp_json>' --strategy overwrite --update-cron '0 0 * * * ?' --yes
 ```
 
 ## Parameters
@@ -15,18 +15,70 @@ ae-cli metadata data-table sql-write --project-id <project_id> --operation updat
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--operation` | Yes | `create` or `update`. |
-| `--columns` | Yes | Column definitions JSON array. Preferred fields are `column_name`, `column_type`, and `column_desc`; CLI also accepts `name`, `type`, and `display_name` aliases. |
-| `--qp` | Yes | SQL data table query plan JSON. |
+| `--columns` | Yes | Column definitions JSON array. Preferred fields are `column_name`, `column_type`, and `column_desc`; CLI also accepts `name`, `type`, and `display_name` aliases. Must match SQL output column names. |
+| `--qp` | Yes | `SqlDatatableDef` JSON object (see below). |
 | `--data-table-id` | For update | Existing data table ID. |
 | `--table-name` | For create | Technical table name. Use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable name. |
 | `--remarks` | No | Table remarks. |
 | `--zone-offset` | No | Time zone offset in hours. For example, UTC+8 is `8` and UTC-5 is `-5`. Valid range: -12 to 14. |
-| `--strategy` | No | `overwrite` or `insert`. |
-| `--update-cron` | No | Scheduled update cron. |
+| `--strategy` | For update | `overwrite` or `insert`. Ignored for create. |
+| `--update-cron` | For update | Scheduled update cron. Ignored for create. |
+
+## QP contract (`SqlDatatableDef`)
+
+`--qp` must be a JSON object with this shape. **Do not** pass a top-level `sql` field.
+
+```json
+{
+  "taSqlVo": {
+    "sql": "select '1' as id, 'demo' as name",
+    "sqlVoParams": []
+  },
+  "taSqlView": {}
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `taSqlVo` | Yes | SQL entity definition (`TaSqlVo`). |
+| `taSqlVo.sql` | Yes | SELECT statement. Output columns must appear in `--columns`. |
+| `taSqlVo.sqlVoParams` | No | Dynamic SQL parameters. Use `[]` when none. |
+| `taSqlView` | No | SQL view (`TaSqlView`). Use `{}` when no dynamic view params. |
+| `taSqlView.sqlViewParams` | No | View dynamic parameters. |
+
+Inspect the live schema:
+
+```bash
+ae-cli capability inspect metadata.data_table.sql_write
+```
+
+## Create example
+
+```bash
+ae-cli metadata data-table sql-write \
+  --project-id 1 \
+  --operation create \
+  --table-name datatable_1_orders_dim \
+  --display-name "Orders dim" \
+  --columns '[{"name":"id","type":"string","display_name":"id"},{"name":"name","type":"string","display_name":"name"}]' \
+  --qp '{"taSqlVo":{"sql":"select '\''1'\'' as id, '\''demo'\'' as name","sqlVoParams":[]},"taSqlView":{}}' \
+  --zone-offset 8 \
+  --dry-run
+
+ae-cli metadata data-table sql-write \
+  --project-id 1 \
+  --operation create \
+  --table-name datatable_1_orders_dim \
+  --display-name "Orders dim" \
+  --columns '[{"name":"id","type":"string","display_name":"id"},{"name":"name","type":"string","display_name":"name"}]' \
+  --qp '{"taSqlVo":{"sql":"select '\''1'\'' as id, '\''demo'\'' as name","sqlVoParams":[]},"taSqlView":{}}' \
+  --zone-offset 8
+```
 
 ## Decision Rules
 
-- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
-- Keep `columns` and `qp` as valid JSON; do not pass raw SQL unless the server schema requires it inside `qp`.
+- This is a write command; use `--dry-run` before non-dry-run execution.
+- Keep `columns` and `qp` as valid JSON. `qp` must follow `SqlDatatableDef`; dry-run validates structure but does not execute SQL.
 - If you provide a table name, it must include the project segment, for example `datatable_2_orders_sql`.
+- If execute fails with `CAPABILITY_EXECUTION_FAILED`, fix qp structure first, then retry with a valid query before investigating backend SQL/Presto issues.

package/skills/ae-team/SKILL.md

@@ -21,7 +21,7 @@ Global parameters:
 | `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
 | `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli team +<command> --host <url>`. |
-| `--yes` | Skip confirmation for write operations. |
+| `--yes` | Skip confirmation for `high-risk-write` (delete) operations. |
 | `--dry-run` | Show request details without executing. |
 
 Output and errors:

package/skills/ae-analysis/references/folder_members.md

@@ -1,15 +0,0 @@
-# analysis folder members
-
-Use when the user needs to inspect folder members.
-
-Do not use to modify members. Use `folder share`.
-
-Command:
-
-```bash
-ae-cli analysis folder members --project-id <project_id> --folder-id <folder_id>
-```
-
-Input sends `project_id` and `folder_id`.
-
-Output is the gateway envelope. `data` contains folder members.

package/skills/ae-analysis/references/project_space_members.md

@@ -1,15 +0,0 @@
-# analysis project-space members
-
-Use when the user needs to inspect project-space members.
-
-Do not use to modify members. Use `project-space share`.
-
-Command:
-
-```bash
-ae-cli analysis project-space members --project-id <project_id> --space-id <space_id>
-```
-
-Input sends `project_id` and `space_id`.
-
-Output is the gateway envelope. `data` contains project-space members.