@thinkingai/ae-cli 6.0.30 → 6.0.31

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

@@ -10,16 +10,17 @@ Recommended workflow:
 
 1. `ae-cli engage +channel_list --project_id <projectId>`
 2. `ae-cli engage +build_task_save_guide --project_id <projectId> --req '{...}'`
-3. If the guide indicates QP-derived fields are needed, call:
+3. If the guide indicates an audience or QP-derived fields are needed, create the audience directly and read it back:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 4. Build the final grouped `req`
 5. `ae-cli engage +save_task --project_id <projectId> --req '{...}'`
 
-The audience schema query is not a fixed preflight step. Call it only when the guide indicates that you must construct:
+Audience creation is not a fixed preflight step. Use direct create/get only when the guide indicates that you must construct:
 
 - `targetConfig.qp`
 - `triggerConfig.triggerRule`
@@ -98,22 +99,23 @@ Use the guide to determine:
 - current handoff template
 - whether the current payload is already close to submit-ready
 
-### 2.3 Query Audience Condition Schema Only When Needed
+### 2.3 Create and Read the Audience Only When Needed
 
-If the guide indicates that QP-derived fields are needed, run:
+If the guide indicates that an audience or QP-derived fields are needed, run:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
-Use the returned schema to build:
+Prefer the returned `cluster_name`/`clusterKey`. Only when required, use the server-authored definition to build:
 
 - `targetConfig.qp`
 - `triggerConfig.triggerRule`
 - `clientConfig.clientQp`
 - `completionIndicatorDef.event`
 
-Do not call this command by default for every task. It is conditional, not mandatory.
+Do not create an audience by default for every task. It is conditional, not mandatory.
 
 ### 2.4 Build Final `req` and Save
 
@@ -191,10 +193,11 @@ Use the guide to decide which audience shape applies:
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
 - `targetClusterType=3`: all users, forbids both `qp` and `clusterKey`
 
-If `qp` is required, construct it from:
+If `qp` is required, create/read a server-authored audience and copy the saved definition rather than building raw QP:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 ### 4.4 `triggerConfig`
@@ -210,10 +213,10 @@ Rules:
 
 - `triggerType=6` is not supported
 - use the guide for cron format and wrong-example checks
-- if `triggerRule` is needed, build it from:
+- if `triggerRule` is needed, copy it from the saved server-authored audience definition:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 ### 4.5 `controlConfig`
@@ -222,10 +225,10 @@ Minimum required field:
 
 - `completionIndicatorDef`
 
-When the guide points to event-based completion or experiment-driven main-goal rules, use:
+When the guide points to event-based completion or experiment-driven main-goal rules, use the saved server-authored audience definition:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 to build `completionIndicatorDef.event`.
@@ -243,10 +246,10 @@ Important constraints that still apply:
 
 Use this block only when client-side conditions are needed.
 
-If `clientConfig.clientQp` is required, build it from:
+If `clientConfig.clientQp` is required, copy it from the saved server-authored audience definition:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 Only call that schema query when the guide explicitly shows that the field is needed.
@@ -260,7 +263,7 @@ Before submission, verify:
 1. `channelId` comes from a real channel query.
 2. `build_task_save_guide` has already been called for the current scenario or partial draft.
 3. `fieldRules.channelContentSchema` was used as the source of truth for content structure.
-4. Any required QP-derived fields were built from `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition`.
+4. Any required QP-derived fields came from `analysis user-cluster get`, never from hand-built raw QP.
 5. `targetClusterType` matches the presence or absence of `clusterKey` / `qp`.
 6. `triggerType` matches the provided scheduling or event fields.
 7. `completionIndicatorDef` is present and structurally valid for the current scenario.
@@ -280,10 +283,11 @@ ae-cli engage +build_task_save_guide --project_id 1 --req '{"context":{"triggerT
 ae-cli engage +save_task --project_id 1 --req '{...final grouped req...}'
 ```
 
-If the guide indicates QP-derived fields are needed, insert:
+If the guide indicates an audience or QP-derived fields are needed, insert direct create/get:
 
 ```bash
-ae-cli analysis_audience +get_cluster_definition_schema --cluster_type condition
+ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
 ```
 
 before building the final `req`.
@@ -301,4 +305,4 @@ This command is a write operation.
 - Do not invent `channelId`, `clusterKey`, audience definitions, or content keys
 - Do not use `taskId` for a non-draft task
 - Do not pass `occasionKeys`; Hermes derives them from content
-- Do not call the audience schema query as a reflex; call it only when guide output says QP-derived fields are needed
+- Do not call the semantic cluster definition builder as a reflex; call it only when guide output says QP-derived fields are needed

package/skills/ae-engage/references/segment-list-query.md

@@ -0,0 +1,18 @@
+# engage-task segment-list query
+
+Query segments created from or associated with an engagement task.
+
+> Capability id: `engage-task.segment-list.query` · Domain: `engage`.
+
+```bash
+ae-cli engage-task segment-list query --project-id <project-id> --task-id <task-id>
+```
+
+## Parameters
+
+- `--project-id` / `-p`: Numeric project ID.
+- `--task-id`: Engagement task ID.
+
+## Output
+
+Returns `items` and `total`. Each item includes cluster identity, display name, user count, refresh status, and `analysis_visible`.

package/skills/ae-engage/references/task-operation-log-query.md

@@ -0,0 +1,23 @@
+# engage-task operation-log query
+
+Use this command to query an engagement task's operation records and runtime application logs.
+
+> Capability id: `engage-task.operation-log.query` · Domain: `engage`.
+
+```bash
+ae-cli engage-task operation-log query --project-id <project-id> --task-id <task-id>
+```
+
+## Parameters
+
+- `--project-id` / `-p`: Required numeric project ID.
+- `--task-id`: Required engagement task ID.
+
+## Output
+
+The result contains two arrays:
+
+- `operation_records`: User and system operations such as creation, modification, approval, sending, pausing, and completion. Each item contains `operation_type_name`, `operator_name`, `operate_time`, and optional `target_name`.
+- `app_logs`: Runtime application logs for triggered tasks. Each item contains `operation_type`, `operation_type_name`, `operator_name`, and `operate_time`. This array is empty when the task has no runtime application logs.
+
+The task must belong to the supplied project. This is a read-only command and supports `--dry-run`.

package/skills/ae-engage/references/version-list.md

@@ -0,0 +1,18 @@
+# engage-flow version list
+
+List current, historical, new, update, and test versions for a flow.
+
+> Capability id: `engage-flow.version.list` · Domain: `engage`.
+
+```bash
+ae-cli engage-flow version list --project-id <project-id> --flow-id <flow-id>
+```
+
+## Parameters
+
+- `--project-id`, `-p`: Numeric project ID.
+- `--flow-id`: Flow ID whose versions should be listed.
+
+## Output
+
+Returns `items` containing flow version metadata and `total` containing the number of returned versions.

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

@@ -498,7 +498,7 @@ After all `.ae-cli/output/` files are generated, upload every generated output f
 Use the existing attachment command:
 
 ```bash
-ae-cli agent +add-attachment --yes --files '<json-array-of-generated-output-files>'
+ae-cli agent +add-attachment --files '<json-array-of-generated-output-files>'
 ```
 
 Upload list rules:

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

@@ -236,7 +236,7 @@ AE Debug mode requires the device ID to be added in AE Admin before data can be
 After all snippet output files are written, upload generated output artifacts to the Agent attachment library:
 
 ```bash
-ae-cli agent +add-attachment --yes --files '<json-array-of-generated-output-files>'
+ae-cli agent +add-attachment --files '<json-array-of-generated-output-files>'
 ```
 
 Upload list must include:
@@ -341,7 +341,7 @@ After generation, perform language style checks on each output file:
 
 #### Step 5: Upload Generated Artifacts
 
-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>'`.
+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 --files '<json-array>'`.
 
 ---
 

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

@@ -9,8 +9,8 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 > English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply.
 > If uncertain, default to English.
 > This applies to all output: section titles, phase names, template prompts, example text, option lists, etc.
-> **⚠️ CRITICAL: Templates and some reference documents are in Chinese. When working with Chinese templates/material for an English/Japanese user, you MUST translate all user-facing content (display_name, event_desc, event_tag, descriptions, etc.) to the user's language. The source material's language is NOT the user's language. Use the Terminology Glossary above to map terms accurately.**
-> Do NOT copy Chinese text verbatim from this document into English/Japanese replies.
+> **⚠️ CRITICAL: Template localization is CLI-owned. Do NOT manually translate imported template content with the model. Use the `src/tracking` i18n pipeline by setting `AE_LANG=<user_lang>`, writing `draft.meta.lang`, and regenerating through `ae-cli tracking code import-template` / `ae-cli tracking plan draft`.**
+> Do NOT copy Chinese text verbatim from this document into English/Japanese replies unless it is an identifier, template name needed for CLI import, or original source material quoted for traceability.
 
 ## Terminology Glossary
 
@@ -66,10 +66,13 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > / `ae-cli auth login` / `ae-cli tracking plan upload` / `ae-cli tracking plan delete`).
 > **All CLI commands must be prefixed with `AE_LANG=<user_lang>`** (e.g. `AE_LANG=en ae-cli tracking plan draft ...`),
 > ensuring CLI output messages and generated xlsx headers match the user's language.
+> Upload commands MUST also pass `--lang <user_lang>` so the server parses the uploaded xlsx with the same sheet/header language.
 > 
-> **Language rules**: All user-facing fields in draft.json (`display_name`, `event_desc`, `event_tag`,
-> property `display_name`, property `desc`, etc.) must be generated in the **user's input language**.
-> Content extracted from Chinese templates/PRDs must be translated to the user's language when written to draft.json.
+> **Language rules**: For newly generated content, user-facing fields in draft.json (`display_name`, `event_desc`, `event_tag`,
+> property `display_name`, property `desc`, etc.) should be generated in the **user's input language**.
+> For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,
+> CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
+> If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.
 > Only identifier fields like `event_name`, `prop_name` remain in English snake_case (canonical format).
 > This skill only cares about command behavior, not internal implementation.
 
@@ -81,6 +84,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.
+> When uploading the xlsx, pass `--lang <user_lang>` as well; it must match `draft.meta.lang` / the generated xlsx language.
 
 Collect the following **4 items** sequentially, **do NOT ask all at once**:
 
@@ -493,8 +497,9 @@ Priority from low to high: **template → codebase → prd → chat → autotrac
   - Templates are resolved by ae-cli from the ae-cli package root and user template directory
   - Import command: `AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json`
   - ⚠️ **Must validate immediately after template import** (see Phase 1.6); template content may not be fully correct
-  - ⚠️ **Template content is in Chinese; must translate after import**: Read draft.json, translate `display_name`, `event_desc`, `event_tag`, and property `display_name`/`desc` to user's language, then write back. Only `event_name`, property `name`, `type` identifiers remain as-is.
-  - ⚠️ **event_tag also needs translation**: `业务事件`→user's language (e.g. EN: `Business Event`), `系统事件`→user's language (e.g. EN: `System Event`; autotrack events are handled automatically by CLI, no need to re-translate)
+  - ⚠️ **Do not manually translate template content after import**: Do NOT read draft.json and model-translate `display_name`, `event_desc`, `event_tag`, or property `display_name`/`desc`. Keep imported business content as produced by the CLI/template reader unless the user explicitly asks for semantic rewriting.
+  - ⚠️ **Use `src/tracking` i18n for localization owned by the CLI**: `AE_LANG=<user_lang>` + `draft.meta.lang` control CLI messages, xlsx sheet names, xlsx headers, property type display values, and auto-track/i18n-owned labels. If these are wrong, regenerate with the intended locale instead of editing labels by hand.
+  - ⚠️ **event_tag is not free-form model translation**: Do not manually map `业务事件`/`系统事件` to another language. Preserve template tags, or rely on `src/tracking` i18n/autotrack generation for system labels when the CLI owns them.
 - **codebase**: Scan project source directory, extract events/properties from business logic; **same-name events merge prop_names without overwriting existing fields**; new items `source: "codebase"`
 - **prd**: Read all user-provided product documents (md / pdf / docx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`
   - **prd path is a folder**: Recursively scan all files in the directory:
@@ -668,7 +673,7 @@ Run the following command to dynamically discover available templates:
 AE_LANG=<user_lang> ae-cli tracking plan list-templates --json
 ```
 
-**Language rules**: Template file names are in Chinese. When displaying to users, **must translate to user's current language**; **do NOT** include the original Chinese name (e.g. show only "Card Game v1", not "Card Game (卡牌游戏) v1").
+**Language rules**: Template names and template business content must not be model-translated. Use localized names only when they are returned by the CLI / `src/tracking` i18n resources. If `list-templates --json` only returns the original template `name`, display that name as-is and keep it unchanged for import.
 
 Built-in templates are resolved by ae-cli from the ae-cli package root. User templates are resolved from the ae-cli user template directory. Do **not** manually construct `./tracking-plan-template/...` paths from the user's current workspace.
 
@@ -678,7 +683,7 @@ Search directories in order:
 2. `~/.ae-cli/templates/` — user-provided template directory
 
 Each template prefers `.md` distilled file (if same-name `.md` exists, return md path; otherwise return xlsx path).
-Display translated template names to the user, but keep the original `name` from the JSON result for import. Auto-detect format on import:
+Display the template names returned by the CLI, and keep the exact `name` from the JSON result for import. Auto-detect format on import:
 
 ```bash
 AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json
@@ -1105,7 +1110,7 @@ Decide based on conflict detection results:
 
 Upload command:
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json [--replace]
+AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]
 ```
 
 - **With `--replace`**: Delete existing project plan first then upload (when user chooses "Replace", or severe conflict switches to replace)
@@ -1114,7 +1119,7 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
 Upload language is controlled locally by `AE_LANG`, `--lang`, or `draft.meta.lang`. Do not call AE user language config APIs and do not use `--switch-lang`. If the xlsx language is wrong, regenerate the xlsx with the intended language before uploading:
 ```bash
 AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
-AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json [--replace]
+AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]
 ```
 
 On successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`).
@@ -1126,7 +1131,7 @@ On successful upload, prompt user to verify in AE Admin. **Provide the full URL*
 Use `--auto-fix` option on upload (enabled by default); CLI auto-detects and fixes errors:
 
 ```bash
-AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json [--replace]
+AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]
 ```
 
 #### AE API Error Types

package/skills/ae-generate-tracking-plan/references/te-api.md

@@ -96,9 +96,10 @@ Upload is a two-step capability-gateway flow:
    - Input:
 
 ```json
-{ "project_id": 1603, "input_file_id": "..." }
+{ "project_id": 1603, "input_file_id": "...", "lang": "zh" }
 ```
 
+- `lang` is optional for backward compatibility, but Agents should pass the generated xlsx language (`zh` / `en` / `ja` / `ko`) so the backend resolves localized sheet names and headers consistently.
 - Response: `{ return_code: 0, return_message: "success" }` on success.
 
 **合并语义**：对事件走 **merge-by-name**（同名不覆盖、新名新增）。若要完全替换，

package/skills/ae-kb/SKILL.md

@@ -15,7 +15,7 @@ ae-cli kb +<command> [options]
 ## Global Rules
 
 - Use this skill for TE/AE knowledge base tasks: create, query, ask with LLM, inspect indexes, grep pages, read pages, check status, upload sources, add URL sources, generate schema, compile, remove source files, and delete knowledge bases.
-- Read operations can run directly after required inputs are known. Write operations require explicit user intent and normally keep the confirmation prompt unless the user asks to bypass it.
+- Read and ordinary `write` operations can run directly after required inputs and user intent are known. Only `high-risk-write` operations use the confirmation gate.
 - Prefer `--dry-run` before destructive or broad writes when the user has not already validated the target.
 - Do not invent knowledge base names, scopes, source display names, or JSON payloads. Ask the user or query known context when values are missing.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell commands.

package/skills/ae-metadata/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ae-metadata
 version: 1.0.0
-description: "AE/TE metadata capability-gateway CLI: metadata event/property detail, metadata data-table management, input-file upload, and property dimension-table binding. Use for ae-cli metadata commands backed by /api/cli/metadata/v1. Must read references before composing commands; command/flags use kebab-case while gateway input keeps snake_case. Never guess project_id, event/property names, input_file_id, or data_table_id."
+description: "AE/TE metadata capability-gateway CLI: metadata event/property detail, data-table management, and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload belongs to ae-analysis."
 ---
 
 # ae-metadata
 
-Capability-gateway domain **`metadata`** — REST via `/api/cli/metadata/v1/...`, auth header **`cli-token`**.
+CLI domain **`metadata`** routes to the analysis capability gateway (`/api/cli/analysis/v1/...`), using auth header **`cli-token`**.
 
 Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance). Use **this skill** for gateway-backed metadata detail and data-table/dimension-table operations; use **`ae-analysis`** for MCP metadata list/search, metrics, virtual create, and batch edit.
 
@@ -17,7 +17,8 @@ Parallel to **`ae-analysis`** (MCP `analysis_meta` for metadata lists/governance
 | `--format <json\|table>` | Output format. Default JSON. |
 | `--jq <expr>` | jq filter on JSON output. |
 | `--host <url>` | Override active AE host, e.g. `ae-cli metadata event get --host <url> ...`. |
-| `--dry-run` | Validate input against gateway schema without executing. |
+| `--validate` | Optional: fix params only (`/validate`). Alone while iterating complex `qp` / payload — then run. Do not stack with `--dry-run`. |
+| `--dry-run` | Optional: confirm ready to run (`/dry-run`). Alone for risk/output preview. Do not stack with `--validate`. |
 
 Output and errors:
 - Success: JSON envelope (default).
@@ -25,7 +26,7 @@ Output and errors:
 
 Safety:
 - Read-only commands can run directly after IDs/names are verified.
-- Write commands (`data-table *-write`, `*-delete`, `property-bindings-update`, dimension-table bind/create, `input-file upload`) require `--yes` for non-dry-run execution.
+- Ordinary writes (`data-table *-write`, `property-bindings-update`, dimension-table bind/create) execute without `--yes`. Delete commands are `high-risk-write`: dry-run first, summarize impact, wait for explicit confirmation, then execute with `--yes`.
 - **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata event get` → `metadata_event_get.md`).
 - Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Discover names via `ae-analysis` and data table IDs via `metadata data-table list`.
 
@@ -36,7 +37,7 @@ Switch to **`ae-metadata`** when the user needs:
 - Full detail for **one** super-event (incl. virtual event `definition`)
 - Full detail for **one** super-property (incl. virtual property `definition`)
 - Metadata data-table list/get/create/update/delete/download
-- Upload a local file to get `input_file_id`
+- For local uploads, switch to `ae-analysis` and use `analysis input-file upload` with a discovered purpose.
 - Bind an existing data table to a property, or create a CSV dimension table and bind it
 
 Stay on **`ae-analysis`** for: metadata event/property/metric list/search, metric CRUD, batch metadata, virtual create, project config, tracking plans.
@@ -48,20 +49,19 @@ ae-cli metadata <resource> <action> [options]
 ae-cli metadata property <dimension-table-action> [options]
 ```
 
-- Commands and flags use **kebab-case**: `data-table`, `input-file`, `dimension-table`, `--project-id`, `--data-table-id`.
+- Commands and flags use **kebab-case**: `data-table`, `dimension-table`, `--project-id`, `--data-table-id`.
 - Gateway `input` body fields remain **snake_case** (`project_id`, `event_name`, …); ae-cli maps flags automatically.
 
 ## PROJECT_ID_GATE
 
 Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli analysis_common +list_projects` (or `ae-analysis` skill) to resolve `project_id`.
 
-## Commands (13)
+## Commands (12)
 
 | User command | Capability id | Reference |
 |---|---|---|
 | `metadata event get` | `metadata.event.get` | [metadata_event_get.md](references/metadata_event_get.md) |
 | `metadata property get` | `metadata.property.get` | [metadata_property_get.md](references/metadata_property_get.md) |
-| `metadata input-file upload` | `POST /input-files` | [metadata_input_file_upload.md](references/metadata_input_file_upload.md) |
 | `metadata data-table list` | `metadata.data_table.list` | [metadata_data_table_list.md](references/metadata_data_table_list.md) |
 | `metadata data-table get` | `metadata.data_table.get` | [metadata_data_table_get.md](references/metadata_data_table_get.md) |
 | `metadata data-table csv-write` | `metadata.data_table.csv_write` | [metadata_data_table_csv_write.md](references/metadata_data_table_csv_write.md) |
@@ -82,6 +82,7 @@ ae-cli metadata property get --help
 ae-cli metadata data-table list --help
 ae-cli metadata event get --project-id 1 --event-name <name> --dry-run
 ae-cli metadata data-table list --project-id 1 --dry-run
+ae-cli analysis input-file purpose list --project-id 1
 ```
 
 ## Related Skills

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

@@ -3,6 +3,7 @@
 > Capability id: `metadata.data_table.csv_delete` · Domain: `metadata`.
 
 ```bash
+# Summarize the target and impact, then wait for explicit user confirmation.
 ae-cli metadata data-table csv-delete --project-id <project_id> --data-table-id <id> --yes
 ae-cli metadata data-table csv-delete --project-id <project_id> --data-table-id <id> --dry-run
 ```

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

@@ -5,9 +5,9 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table csv-write --project-id <project_id> --operation create --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>' --yes
-ae-cli metadata data-table csv-write --project-id <project_id> --operation incremental_update --data-table-id <id> --input-file-id <input_file_id> --yes
-ae-cli metadata data-table csv-write --project-id <project_id> --operation replace_update --data-table-id <id> --input-file-id <input_file_id> --yes
+ae-cli metadata data-table csv-write --project-id <project_id> --operation create --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>'
+ae-cli metadata data-table csv-write --project-id <project_id> --operation incremental_update --data-table-id <id> --input-file-id <input_file_id>
+ae-cli metadata data-table csv-write --project-id <project_id> --operation replace_update --data-table-id <id> --input-file-id <input_file_id>
 ```
 
 ## Parameters
@@ -16,7 +16,7 @@ ae-cli metadata data-table csv-write --project-id <project_id> --operation repla
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--operation` | Yes | `create`, `incremental_update`, or `replace_update`. |
-| `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
+| `--input-file-id` | Yes | ID returned by `analysis input-file upload`. |
 | `--data-table-id` | For updates | Existing data table ID. |
 | `--data-table-name` | No | Optional technical data table name. If supplied, use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable table name. |
@@ -25,7 +25,7 @@ ae-cli metadata data-table csv-write --project-id <project_id> --operation repla
 
 ## Decision Rules
 
-- Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- Discover the purpose with `analysis input-file purpose list`, then upload the CSV with `analysis input-file upload --purpose data_table.csv`.
 - Do not invent `input_file_id` or `data_table_id`; use upload/list outputs.
 - If you provide `--data-table-name`, it must include the project segment, for example `datatable_2_orders`.
-- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
+- This is an ordinary `write` command and does not require CLI confirmation.

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

@@ -3,8 +3,8 @@
 > Capability id: `metadata.data_table.property_bindings_update` · Domain: `metadata`.
 
 ```bash
-ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --bind-properties '<bind_json>' --yes
-ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --unbind-properties '<unbind_json>' --yes
+ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --bind-properties '<bind_json>'
+ae-cli metadata data-table property-bindings-update --project-id <project_id> --data-table-id <id> --unbind-properties '<unbind_json>'
 ```
 
 | Parameter | Required | Description |

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

@@ -3,6 +3,7 @@
 > Capability id: `metadata.data_table.sql_delete` · Domain: `metadata`.
 
 ```bash
+# Summarize the target and impact, then wait for explicit user confirmation.
 ae-cli metadata data-table sql-delete --project-id <project_id> --data-table-id <id> --yes
 ae-cli metadata data-table sql-delete --project-id <project_id> --data-table-id <id> --dry-run
 ```

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 --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
+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
+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 * * * ?'
 ```
 
 ## Parameters
@@ -47,15 +47,26 @@ ae-cli metadata data-table sql-write --project-id <project_id> --operation updat
 | `taSqlView` | No | SQL view (`TaSqlView`). Use `{}` when no dynamic view params. |
 | `taSqlView.sqlViewParams` | No | View dynamic parameters. |
 
-Inspect the live schema:
+Inspect the live schema. For complex `qp` / `columns`, use **on-demand** pre-check (motto: validate = fix params; dry-run = confirm ready to run). Prefer **`--validate` only** while iterating — then execute. Do **not** stack `--validate` then `--dry-run` on the same final input by default (`dry-run` already validates params).
 
 ```bash
 ae-cli capability inspect metadata.data_table.sql_write
+ae-cli metadata data-table sql-write \
+  --project-id 1 \
+  --operation create \
+  --table-name datatable_1_orders_dim \
+  --columns '[{"name":"id","type":"string"},{"name":"name","type":"string"}]' \
+  --qp '{"taSqlVo":{"sql":"select '\''1'\'' as id, '\''demo'\'' as name","sqlVoParams":[]},"taSqlView":{}}' \
+  --zone-offset 8 \
+  --validate
 ```
 
+`--validate` only checks/normalizes parameters (`valid` + `normalized_input`). It does not create the table. After `valid=true`, execute without `--yes`. Use `--dry-run` **instead of** `--validate` only when you need risk/output/cancel preview — not both.
+
 ## Create example
 
 ```bash
+# Typical complex-qp path: validate while fixing, then execute (no mandatory dry-run).
 ae-cli metadata data-table sql-write \
   --project-id 1 \
   --operation create \
@@ -64,7 +75,7 @@ ae-cli metadata data-table sql-write \
   --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
+  --validate
 
 ae-cli metadata data-table sql-write \
   --project-id 1 \
@@ -78,7 +89,10 @@ ae-cli metadata data-table sql-write \
 
 ## Decision Rules
 
-- 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.
+- Write command. Motto: validate = fix params; dry-run = confirm ready to run. **Pick one pre-check on demand** — do not stack both on the same final input.
+- Complex `qp` / `columns`: use `--validate` while iterating until `valid=true`, then execute without CLI confirmation. Skip `--dry-run` unless you specifically need risk/output/cancel preview.
+- If you need that preview instead, use `--dry-run` **once** on the final input (it already validates params) — do not validate then dry-run as a habit.
+- Global `--validate` → `/validate`; `--dry-run` → `/dry-run`. Neither creates the table. Do not pass both flags together.
+- Keep `columns` and `qp` as valid JSON. `qp` must follow `SqlDatatableDef`; validate / dry-run check structure but do 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.
+- If execute fails with `CAPABILITY_EXECUTION_FAILED`, fix qp with `--validate`, then retry before investigating backend SQL/Presto issues.

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

@@ -5,8 +5,8 @@
 ## Command
 
 ```bash
-ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope user --data-table-id <id> --yes
-ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope event --data-table-id <id> --dict-columns '["display_name"]' --yes
+ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope user --data-table-id <id>
+ae-cli metadata property bind-existing-dimension-table --project-id <project_id> --property-name <name> --property-scope event --data-table-id <id> --dict-columns '["display_name"]'
 ```
 
 ## Parameters
@@ -24,4 +24,4 @@ ae-cli metadata property bind-existing-dimension-table --project-id <project_id>
 
 - Confirm the property with `metadata property get` or `analysis_meta +list_properties`.
 - Confirm the data table with `metadata data-table get`.
-- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
+- This is an ordinary `write` command and does not require CLI confirmation.

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

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata property create-and-bind-csv-dimension-table --project-id <project_id> --property-name <name> --property-scope user --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>' --yes
+ae-cli metadata property create-and-bind-csv-dimension-table --project-id <project_id> --property-name <name> --property-scope user --input-file-id <input_file_id> --data-table-name datatable_<project_id>_<name> --columns '<columns_json>'
 ```
 
 ## Parameters
@@ -15,7 +15,7 @@ ae-cli metadata property create-and-bind-csv-dimension-table --project-id <proje
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--property-name` | Yes | Property technical name. |
 | `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
-| `--input-file-id` | Yes | ID returned by `metadata input-file upload`. |
+| `--input-file-id` | Yes | ID returned by `analysis input-file upload`. |
 | `--data-table-name` | No | Optional technical data table name. If supplied, use `datatable_<project_id>_<name>`. |
 | `--display-name` | No | Human-readable table name. |
 | `--description` | No | Table description. |
@@ -25,8 +25,8 @@ ae-cli metadata property create-and-bind-csv-dimension-table --project-id <proje
 
 ## Decision Rules
 
-- Upload the CSV first with `metadata input-file upload --purpose data_table.csv`.
+- Discover the purpose with `analysis input-file purpose list`, then upload the CSV with `analysis input-file upload --purpose data_table.csv`.
 - Do not invent `input_file_id`; use the value returned by upload.
 - If you provide `--data-table-name`, it must include the project segment, for example `datatable_2_user_dict`.
 - Use this one-step command when the user wants a new CSV dimension table bound to a property.
-- This is a write command; use `--dry-run` before non-dry-run and pass `--yes` when executing.
+- This is an ordinary `write` command and does not require CLI confirmation.