@thinkingai/ae-cli 1.0.18 → 1.0.21

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

@@ -4,6 +4,10 @@
 
 Domain: **Report Management**
 
+## Constraints
+
+**Not a builder fallback:** Do not call `+get_report_definition` to repair or replace a failed `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp` call. For builder-supported ad-hoc analysis, builder failure means stop and ask for clarification or report the structured error.
+
 ## Use Cases
 - Get the definition details of a single report. Returns model type, event configuration, display configuration, and other definition data without executing a data query.
 - Get the definition details of a single report.

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

@@ -8,6 +8,8 @@ Domain: **Dashboard management**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
+**Builder failure is terminal:** For builder-supported ad-hoc analysis, this command may be used only in the initial `QUERY_EXISTING_FIRST` dashboard search. Do not call dashboard/report detail tools as a fallback after a QP builder returns non-generated status.
+
 ## Use Cases
 - List dashboard metadata accessible to the current user in the project. Supports keyword filtering and returns dashboard IDs, names, descriptions, and related metadata, but not dashboard configuration or report data.
 - List dashboard metadata accessible to the current user in the project.

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

@@ -8,9 +8,11 @@ Domain: **Metadata Query**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
+**Not a builder pre-step:** Do not call `+list_events` before builder-supported ad-hoc analysis (`event`, `retention`, `funnel`, `prop_analysis`). The matching QP builder resolves event names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - Read-only query for SYSTEM METADATA already effective in the project. Use for super events in production metadata. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA already effective in the project.
+- Read-only query for SYSTEM METADATA already effective in the project. Use when the user explicitly asks to inspect event metadata, not as a required preparation step for QP builder.
 
 ## Commands
 ```bash
@@ -30,6 +32,7 @@ ae-cli analysis_meta +list_events --dry-run
 | `--offset` / `-o` | No | Optional page offset. Default: 0. |
 ## Decision Rules
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, pass the user's event wording to the builder instead of pre-querying event metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -8,10 +8,13 @@ Domain: **Metadata Query**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
+**Not a builder pre-step:** Do not call `+list_metrics` before `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp` for normal ad-hoc analysis. Event builder resolves saved metric names internally when the metric name is passed in `metrics[].event`. If the builder fails, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - List metric metadata in the project. Supports keyword filtering and returns metric IDs, names, display names, model types, remarks, and related metadata, but not metric calculation results.
 - Supports pagination with fields/limit/offset for payload governance.
 - Query performs fuzzy matching on metricName, metricDesc, and metricRemark.
+- Use this command for metric metadata management, metric editing, auditing, or when the user explicitly asks to inspect/search metric metadata. Do not use it merely to prepare a builder-supported ad-hoc query.
 
 ## Command
 ```bash
@@ -34,6 +37,7 @@ ae-cli analysis_meta +list_metrics --dry-run
 - First run should only pass the required parameter (`--project_id`), and add optional parameters only after the path is confirmed to work.
 - For pagination, use `--limit` and `--offset` together. Default limit is 20.
 - Use `--fields` to select specific columns for lighter response payloads.
+- For builder-supported ad-hoc analysis, do not search metrics here first. Pass the user-provided metric name directly to the builder.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -43,3 +47,4 @@ ae-cli analysis_meta +list_metrics --dry-run
 
 ## Recommended Chaining
 - +list_metrics -> +create_metric -> +get_metric
+- For ad-hoc event metric query: +build_event_analysis_qp -> +query_adhoc

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

@@ -4,9 +4,13 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Not a builder pre-step:** Do not call `+list_properties` before builder-supported ad-hoc analysis (`event`, `retention`, `funnel`, `prop_analysis`). The matching QP builder resolves property names internally. If the builder returns MCP failure, stop and ask for clarification instead of using this command as a fallback.
+
 ## Use Cases
 - Read-only query for SYSTEM METADATA properties already effective in the project. Supports event/user scope. Do NOT use for tracking-plan metadata (bury/track program); that belongs to BuryProgramTool.
-- Read-only query for SYSTEM METADATA properties already effective in the project.
+- Read-only query for SYSTEM METADATA properties already effective in the project. Use when the user explicitly asks to inspect property metadata, not as a required preparation step for QP builder.
 
 ## Commands
 ```bash
@@ -30,6 +34,7 @@ ae-cli analysis_meta +list_properties --dry-run
 
 ## Decision Rules
 - For the first run, pass only the required parameter (`--project_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, pass the user's property wording to the builder instead of pre-querying property metadata.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure

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

@@ -8,6 +8,8 @@ Domain: **Report management**
 
 **Fuzzy Search Fallback:** If `--query` returns no results, retry with broader keywords (max 3 attempts), then fall back to full list. See [SKILL.md § C. FUZZY_SEARCH_FALLBACK](../SKILL.md#c-fuzzy_search_fallback).
 
+**Builder failure is terminal:** For builder-supported ad-hoc analysis, this command may be used only in the initial `QUERY_EXISTING_FIRST` report search. Do not call `+list_reports` or `+get_report_definition` as a fallback after a QP builder returns non-generated status.
+
 ## Use Cases
 - List report metadata accessible to the current user in the project. Supports keyword filtering and returns report IDs, names, model types, update times, and related metadata, but not report definitions or analysis data.
 - List report metadata accessible to the current user in the project.

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

@@ -8,15 +8,33 @@ Domain: **Model analysis**
 
 **⚠️ QUERY_EXISTING_FIRST:** Before using ad-hoc query, you MUST first check for existing reports/dashboards with `list_reports` and `list_dashboards`. Only use `query_adhoc` if no matching reports found. See [SKILL.md § D. QUERY_EXISTING_FIRST](../SKILL.md#d-query_existing_first).
 
+**⚠️ QP_BUILDER_SUPPORTED_MODELS_ONLY:** QP builder supports exactly four ad-hoc model types: `event`, `retention`, `funnel`, and `prop_analysis`.
+
+For these four model types, call the matching builder before `query_adhoc`. Do not handcraft QP from `get_analysis_query_schema`, examples, or prior knowledge.
+
+For all other model types (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`), QP builder is not supported. Use the legacy schema/metadata path and construct QP manually according to the model schema.
+
+For builder-supported models, schema/metadata tools are not builder pre-steps. After report/dashboard lookup misses, do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, `get_metric`, or `get_report_definition` before the builder. The builder resolves event/property/metric metadata internally.
+
+**Hard stop rule:** If builder status is not `generated`, stop and ask the user to clarify or report the builder error. Do not call `query_adhoc`, `get_analysis_query_schema`, or manually assemble QP for `event`, `retention`, `funnel`, or `prop_analysis`.
+
+Builder mapping:
+1. `event` -> `+build_event_analysis_qp`
+2. `retention` -> `+build_retention_analysis_qp`
+3. `funnel` -> `+build_funnel_analysis_qp`
+4. `prop_analysis` -> `+build_prop_analysis_qp`
+
 **Quick check workflow:**
 1. `list_reports --query <keyword>` - search matching reports
 2. `list_dashboards --query <keyword>` - search matching dashboards
 3. If found → use `query_report_data` or `query_dashboard_report_data`
-4. If not found → only then use `query_adhoc`
+4. If not found and model is builder-supported (`event`/`retention`/`funnel`/`prop_analysis`) → read matching builder reference, call matching builder, then call `query_adhoc` with `model_type` + built `qp`; do not insert schema or metadata lookup before the builder
+5. If not found and model is not builder-supported (`distribution`/`attribution`/`heat_map`/`interval`/`path`/`rank_list`/`sql`) → use the legacy schema/metadata path, then call `query_adhoc`
 
 ## Use Cases
-- Precondition helper: call `+get_analysis_query_schema` to get the structure before using this tool.
-- When constructing a real `qp`, you must supplement it with real project metadata; first call `analysis_meta +list_events` and `analysis_meta +list_properties`.
+- Execute a QP produced by the required chain for the target model.
+- Builder-supported models (`event`, `retention`, `funnel`, `prop_analysis`): execute the `qp` returned by builder tools.
+- Non-builder models (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`): execute handcrafted QP from the legacy schema/metadata path when needed.
 - Event analysis: metrics such as event trigger counts, user counts, sums, averages, and more.
 - Retention analysis: metrics such as user churn and retention.
 - Funnel analysis: metrics such as multi-step conversion.
@@ -28,27 +46,41 @@ Domain: **Model analysis**
 - Heat map: visual heat map analysis of user interactions.
 - Rank list: ranking / leaderboard analysis.
 - SQL: custom SQL analysis.
-- Process: fetch events/properties and the schema first, then assemble the query JSON, and finally execute the analysis.
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--qp`, you must first read and follow these reference documents:
-  - [`./get_analysis_query_schema.md`](./get_analysis_query_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate the final `qp` until the documentation review and prerequisite command calls are complete.
-
-## Prerequisite call chain (required for constructing qp)
-1. First determine `--model_type`.
-2. Read `get_analysis_query_schema.md`, then call `ae-cli analysis +get_analysis_query_schema --model_type <model_type>` to get the structure.
-3. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>` to get the available events.
-4. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>` to get the available properties.
-5. Build `qp` from the schema + metadata, then call `+query_adhoc`.
-
-## Command
+- Process:
+  - Builder-supported models: builder -> `query_adhoc`
+  - Non-builder models: metadata/schema lookup -> handcraft `qp` -> `query_adhoc`
+
+## Builder-Supported Model Chain
+Use this chain only for `event`, `retention`, `funnel`, and `prop_analysis`.
+
+1. Read the matching builder reference:
+   - `event`: [`build_event_analysis_qp.md`](./build_event_analysis_qp.md)
+   - `retention`: [`build_retention_analysis_qp.md`](./build_retention_analysis_qp.md)
+   - `funnel`: [`build_funnel_analysis_qp.md`](./build_funnel_analysis_qp.md)
+   - `prop_analysis`: [`build_prop_analysis_qp.md`](./build_prop_analysis_qp.md)
+2. Compose the builder JSON using the documented DTO keys. Nested JSON keys are camelCase, not snake_case.
+3. Run the builder with all required flags. `--dry-run` is allowed only with complete required builder inputs, not by itself.
+4. If builder returns `status=generated`, copy `data.qp` from the builder response and pass it as `--qp`.
+5. If the builder returns `need_clarification`, `invalid_argument`, `unsupported_feature`, or `validation_error`, stop and ask for clarification. Do not use the legacy/manual path as a fallback for these four models.
+
+## Legacy Query Chain
+Use this chain only for `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, and `sql`.
+
+1. Read this reference and the required schema/metadata references.
+2. Call `+get_analysis_query_schema` for the target model when the QP shape is not already verified.
+3. Discover real events/properties/metrics with analysis metadata commands as needed.
+4. Construct QP according to the documented schema and verified metadata.
+5. Call `+query_adhoc`.
+
+Timezone rule:
+- Builder commands do not accept `zone_offset`.
+- Apply timezone only on this execution command, for example `--zone_offset -11`.
+
+## Command Syntax
 ```bash
-ae-cli analysis +query_adhoc --project_id <project_id> --model_type event --qp '{}'
-ae-cli analysis +query_adhoc --project_id <project_id> --model_type event --qp '{}' --fields '["date","event"]' --limit 10 --offset 0 --zone_offset 8 --request_id demo --use_cache true --is_sort_by_columns true --resolve_recent_day true --timeout_minutes 8
-ae-cli analysis +query_adhoc --dry-run
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>'
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>' --fields '["date","event"]' --limit 10 --offset 0 --zone_offset 8 --request_id demo --use_cache true --is_sort_by_columns true --resolve_recent_day true --timeout_minutes 8
+ae-cli analysis +query_adhoc --project_id <project_id> --model_type <model_type> --qp '<qp_json_from_builder_or_legacy_chain>' --dry-run
 ```
 
 ## Parameters
@@ -56,12 +88,12 @@ ae-cli analysis +query_adhoc --dry-run
 |---|---|---|
 | `--project_id` / `-p` | Yes | Project ID used to identify the analysis project |
 | `--model_type` | Yes | Model type. Supported values: event, retention, funnel, distribution, attribution, heat_map, interval, path, rank_list, prop_analysis, sql. |
-| `--qp` | Yes | Query parameter JSON. MUST call `+get_analysis_query_schema` first, and use event/property metadata from `analysis_meta +list_events` / `analysis_meta +list_properties` in the same `project_id`. |
+| `--qp` | Yes | Query parameter JSON. For `event`/`retention`/`funnel`/`prop_analysis`, pass QP returned by the matching builder tool. For non-builder models, construct QP through the legacy schema/metadata path. |
 | `--request_id` | No | Optional unique request ID used for tracking and deduplication. Generated automatically if omitted. |
 | `--use_cache` | No | Whether to use result cache. Default: true |
 | `--zone_offset` | No | Time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5 |
 | `--is_sort_by_columns` | No | Whether to sort query results by columns. Default: false |
-| `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". Default: false |
+| `--resolve_recent_day` | No | Whether to resolve relative time expressions such as "last 7 days". If omitted, service auto-resolves when `qp.eventView.recentDay` exists and `startTime`/`endTime` is incomplete; otherwise defaults to false. |
 | `--fields` | No | Optional fields to return. Must match column names in result. Invalid fields cause INVALID_FIELDS error. |
 | `--limit` | No | Optional limit. Default: 20, maximum: 50. |
 | `--offset` | No | Optional offset. Default: 0. |
@@ -69,18 +101,26 @@ ae-cli analysis +query_adhoc --dry-run
 
 ## Decision Rules
 - On the first run, start with only the required parameters (`--project_id`,`--model_type`,`--qp`), and add optional parameters after confirming the path works.
+- Do not call this command with placeholder QP such as `{}`. For builder-supported models, wait for builder `status=generated`; for non-builder models, build QP from verified schema/metadata first.
+- For builder-supported models, do not run metadata/schema lookup to "help" the builder. The builder is the metadata resolver.
 - For pagination, use `--limit` and `--offset` together. Default limit is 20.
 - Use `--fields` to select specific columns for lighter response payloads.
-- `qp` cannot be written from experience alone: it must satisfy both the schema structure and the project metadata constraints.
-- Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
-- Wrap JSON parameters in single quotes (for example `--qp '{}'`) to avoid shell escaping issues.
+- `event`, `retention`, `funnel`, and `prop_analysis` must not manually craft QP with schema-first flow; call the builder and use the returned `qp`.
+- For non-builder models, `qp` must satisfy both schema structure and project metadata constraints.
+- Wrap JSON parameters in single quotes (for example `--qp '<real_qp_json>'`) to avoid shell escaping issues.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- If the user supplied a timezone such as UTC-11, pass `--zone_offset -11` here, not to the builder.
 
 ## Next Steps on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id`, `--model_type`, `--qp`).
-- If `Invalid JSON` appears, first check the schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
+- If required parameters are missing, resolve `project_id`, `model_type`, and a real `qp` first. Do not run placeholder calls except explicit `--dry-run` validation.
+- If a builder returns non-`generated` status for `event`, `retention`, `funnel`, or `prop_analysis`, stop and ask user to clarify before calling `query_adhoc`.
+- If `Invalid JSON` appears on legacy manual QP paths, first check schema required fields, then verify whether event/property names come from metadata query results for the same `project_id`.
 - If the query times out or results are abnormal, first narrow the time range / grouping dimensions, then split the subqueries to locate the issue.
 
 ## Recommended chaining
-- +get_analysis_query_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_adhoc
+- +build_event_analysis_qp -> +query_adhoc
+- +build_retention_analysis_qp -> +query_adhoc
+- +build_funnel_analysis_qp -> +query_adhoc
+- +build_prop_analysis_qp -> +query_adhoc
+- +get_analysis_query_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_adhoc (non-builder models only)
 - +list_events -> +list_properties -> +query_adhoc -> +drilldown_users -> +drilldown_user_events

package/skills/ae-community/SKILL.md

@@ -2,10 +2,6 @@
 name: ae-community
 version: 2.0.0
 description: "AE community analysis: post search, comment sentiment, topic trends, risky content, livestream data. Includes AE CLI authentication, global parameters, and safety rules (self-contained)."
-metadata:
-  requires:
-    bins: ["ae-cli"]
-  cliHelp: "ae-cli community --help"
 ---
 
 # ae-community
@@ -24,107 +20,24 @@ The AE Community domain provides social data analysis: post/video search, commen
 
 ## Global AE CLI Rules
 
-AE CLI (`ae-cli`) is the command-line tool for the ThinkingEngine data analysis platform, used by AI Agents and human users. For community-side requests, prefer `ae-cli` and this skill’s reference docs over model memory.
+AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
 
-### Authentication
+Global parameters:
 
-You must authenticate before use. Authentication priority:
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--jq <expr>` | jq filter expression for JSON output. |
 
-1. Environment variable `TE_TOKEN` (highest priority, suitable for CI/scripts)
-2. Cached token (`~/.ae-cli/tokens.json`, valid for 20 hours)
-3. macOS automatically extracts it from Chrome (macOS only)
+Output and errors:
+- Successful commands return machine-readable JSON by default.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
-**Authentication commands**
-
-```bash
-# Automatic macOS authentication (extract token from Chrome)
-ae-cli auth login
-
-# Manually set token
-ae-cli auth set-token <token>
-
-# View authentication status
-ae-cli auth status
-
-# Log out
-ae-cli auth logout
-```
-
-**Multi-environment support**
-
-```bash
-# Specify host
-ae-cli auth login --host ta-staging.example.com
-ae-cli auth set-token <token> --host ta-staging.example.com
-
-# Configure default host
-ae-cli config set defaultHost ta-staging.example.com
-```
-
-### Global parameters
-
-All commands support the following global parameters:
-
-| Parameter | Description | Default |
-|------|------|--------|
-| `--host <host>` | AE instance address | defaultHost from config or ta.thinkingdata.cn |
-| `--format <json\|table>` | Output format | json |
-| `--jq <expr>` | jq filter expression | - |
-| `--dry-run` | Show the request only, do not execute it | false |
-| `--yes` | Skip confirmation for write operations | false |
-
-### Output format
-
-**JSON (default)**
-
-```json
-{
-  "ok": true,
-  "data": { ... }
-}
-```
-
-**Table**
-
-```bash
-ae-cli analysis_meta +list_events --project_id <YOUR_PROJECT_ID> --format table
-```
-
-**jq filtering**
-
-```bash
-ae-cli analysis_meta +list_events --project_id <YOUR_PROJECT_ID> --jq '.'
-```
-
-### Error handling
-
-Error output goes to stderr, in the following format:
-
-```json
-{
-  "ok": false,
-  "error": {
-    "type": "auth | api | validation | config",
-    "message": "...",
-    "hint": "..."
-  }
-}
-```
-
-Exit code: success `0`, error `1`.
-
-### Security constraints
-
-- Commands with `risk: read` execute directly
-- Commands with `risk: write` require confirmation unless `--yes` is passed
-- Use `--dry-run` to preview the request that will be sent
-
-### Command structure
-
-```bash
-ae-cli <domain> +<command> [flags]
-ae-cli api <METHOD> <PATH> [--params] [--data]
-```
+Safety constraints:
+- Read commands can execute directly after required IDs and references are verified.
+- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
+- **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
 **Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis), `analysis_audience` (audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
 

package/skills/ae-dataops/SKILL.md

@@ -2,10 +2,6 @@
 name: ae-dataops
 version: 2.0.0
 description: "AE Data Development and Operations: Data warehouse management, flow orchestration, IDE queries, data integration, operations and backfill management"
-metadata:
-  requires:
-    bins: ["ae-cli"]
-  cliHelp: "ae-cli dataops_repo --help, ae-cli dataops_datatable --help, ae-cli dataops_flow --help, ae-cli dataops_ide --help, ae-cli dataops_integration --help, ae-cli dataops_operations --help"
 ---
 
 # ae-dataops
@@ -26,68 +22,27 @@ The AE Data Development and Operations domain provides capabilities for data war
 
 ---
 
-## Global AE CLI Rules
-
-AE CLI (`ae-cli`) is the command-line tool for the AE data development and operations platform. For DataOps-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
-
-Authentication priority:
-1. `TE_TOKEN` environment variable.
-2. Cached token in `~/.ae-cli/tokens.json`, usually valid for 20 hours.
-3. macOS Chrome token extraction via `ae-cli auth login`.
-
-Useful authentication commands:
-
-```bash
-ae-cli auth login
-ae-cli auth set-token <token>
-ae-cli auth status
-ae-cli auth logout
-```
 
-Multi-environment support:
+## Global AE CLI Rules
 
-```bash
-# Specify host
-ae-cli auth login --host ta-staging.example.com
-ae-cli auth set-token <token> --host ta-staging.example.com
-
-# Configure default host
-ae-cli config set defaultHost ta-staging.example.com
-```
+AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
 
 Global parameters:
 
-| Parameter | Description | Default |
-|---|---|---|
-| `--host <host>` | Target AE instance address | defaultHost from config or ta.thinkingdata.cn |
-| `--format <json|table>` | Output format | json |
-| `--jq <expr>` | jq filter expression for JSON output | - |
-| `--dry-run` | Preview the request without executing it | false |
-| `--yes` | Skip confirmation for write operations | false |
-
-Output format:
-
-- JSON (default): `{ "ok": true, "data": { ... } }`
-- Table: `ae-cli dataops_flow +list_flows --spaceCode xxx --format table`
-- jq filtering: `ae-cli dataops_flow +list_flows --spaceCode xxx --jq '.'`
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--jq <expr>` | jq filter expression for JSON output. |
 
-Error handling:
-
-- Failed commands return `{ "ok": false, "error": { "type": "auth|api|validation|config", "message": "...", "hint": "..." } }` to stderr.
-- Exit code: success `0`, error `1`.
+Output and errors:
+- Successful commands return machine-readable JSON by default.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
 Safety constraints:
-
-- Commands with `risk: read` execute directly.
-- Commands with `risk: write` require confirmation unless `--yes` is passed.
-- Use `--dry-run` to preview the request that will be sent.
-
-Command structure:
-
-```bash
-ae-cli <domain> +<command> [flags]
-ae-cli api <METHOD> <PATH> [--params] [--data]
-```
+- Read commands can execute directly after required IDs and references are verified.
+- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
+- **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
 Domains for DataOps: `dataops_repo`, `dataops_datatable`, `dataops_flow`, `dataops_ide`, `dataops_integration`, `dataops_operations`
 

package/skills/ae-engage/SKILL.md

@@ -2,115 +2,32 @@
 name: ae-engage
 version: 1.0.0
 description: "AE Engage MCP: config items, flows, channel settings, task data query, and management"
-metadata:
-  requires:
-    bins: ["ae-cli"]
-  cliHelp: "ae-cli engage --help"
 ---
 
 # ae-engage
 
 AE CLI (`ae-cli`) is the command-line tool for the ThinkingEngine data analysis platform, used by AI Agents and human users.
 
-## Authentication
+## Global AE CLI Rules
 
-You must authenticate before use. Authentication priority:
+AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
 
-1. Environment variable `TE_TOKEN` (highest priority, suitable for CI/scripts)
-2. Cached token (`~/.ae-cli/tokens.json`, valid for 20 hours)
-3. macOS automatically extracts it from Chrome (macOS only)
+Global parameters:
 
-### Authentication Commands
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--jq <expr>` | jq filter expression for JSON output. |
 
-```bash
-# Automatic macOS authentication (extract token from Chrome)
-ae-cli auth login
-
-# Manually set token
-ae-cli auth set-token <token>
-
-# View authentication status
-ae-cli auth status
-
-# Log out
-ae-cli auth logout
-```
-
-### Multi-environment Support
-
-```bash
-# Specify host
-ae-cli auth login --host ta-staging.example.com
-ae-cli auth set-token <token> --host ta-staging.example.com
-
-# Configure default host
-ae-cli config set defaultHost ta-staging.example.com
-```
-
-## Global Parameters
-
-All commands support the following global parameters:
-
-| Parameter | Description | Default |
-|------|------|--------|
-| `--host <host>` | AE instance address | defaultHost from config or ta.thinkingdata.cn |
-| `--format <json\|table>` | Output format | json |
-| `--jq <expr>` | jq filter expression | - |
-| `--dry-run` | Show the request only, do not execute it | false |
-| `--yes` | Skip confirmation for write operations | false |
-
-## Output Format
-
-### JSON (default)
-
-```json
-{
-  "ok": true,
-  "data": { ... }
-}
-```
-
-### Table
+Output and errors:
+- Successful commands return machine-readable JSON by default.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
-```bash
-ae-cli engage +channel_list --project_id <YOUR_PROJECT_ID> --format table
-```
-
-### jq Filtering
-
-```bash
-ae-cli engage +channel_list --project_id <YOUR_PROJECT_ID> --jq '.'
-```
-
-## Error Handling
-
-Error output goes to stderr, in the following format:
-
-```json
-{
-  "ok": false,
-  "error": {
-    "type": "auth | api | validation | config",
-    "message": "...",
-    "hint": "..."
-  }
-}
-```
-
-Exit code: success `0`, error `1`.
-
-## Security Constraints
-
-- Commands with `risk: read` execute directly
-- Commands with `risk: write` require confirmation unless `--yes` is passed
-- Use `--dry-run` to preview the request that will be sent
-
-## Command Structure
-
-```bash
-ae-cli <domain> +<command> [flags]
-ae-cli api <METHOD> <PATH> [--params] [--data]
-```
+Safety constraints:
+- Read commands can execute directly after required IDs and references are verified.
+- Write commands require explicit user intent and normally keep the confirmation prompt.
+- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
+- **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
 ## Overview