@thinkingai/ae-cli 1.0.1

package/skills/te-analysis/references/query-event-details.md

@@ -0,0 +1,63 @@
+# te_analysis +query_event_details (Query Event Details)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Event detail queries**
+
+## Use Cases
+- When constructing `filters` / `properties`, you must first obtain the filter schema and the project metadata for real events/properties.
+- Query event detail data. Supports time range, filters, display properties, sorting, and result limits.
+- Query event detail data.
+
+## Mandatory prerequisites (MUST)
+- Before constructing `--filters` / `--properties`, you must first read and follow these reference documents:
+  - [`./get-filter-schema.md`](./get-filter-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate the final `filters` / `properties` until the documentation review and prerequisite command calls are complete.
+
+## Prerequisite call chain (required for constructing filters/properties)
+1. Read `get-filter-schema.md`, then call `te-cli te_analysis +get_filter_schema` to get the filter structure.
+2. Read `list-events.md`, then call `te-cli te_meta +list_events --project_id 1` to confirm the available event names.
+3. Read `list-properties.md`, then call `te-cli te_meta +list_properties --project_id 1` to get the available properties.
+4. Build `filters` / `properties` from the schema + metadata, then call `+query_event_details`.
+
+## Command
+```bash
+te-cli te_analysis +query_event_details --project_id 1 --event_name login --start_time '2026-04-08 00:00:00' --end_time '2026-04-08 23:59:59'
+te-cli te_analysis +query_event_details --project_id 1 --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 100 --zone_offset 8 --use_cache true
+te-cli te_analysis +query_event_details --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--event_name` | Yes | Event name |
+| `--start_time` | No | Start time. Format: yyyy-MM-dd HH:mm:ss |
+| `--end_time` | No | End time. Format: yyyy-MM-dd HH:mm:ss |
+| `--relative_date_range` | No | Optional relative date range in m-n format. For example, 0-7 means the most recent 7 days including today. Use either this field or start_time/end_time. |
+| `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `te_meta +list_properties` in the same `project_id`. |
+| `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `te_meta +list_properties` in the same `project_id`. |
+| `--sort_by` | No | Optional sort field |
+| `--sort_order` | No | Optional sort order. Supported values: asc and desc |
+| `--limit` | No | Optional result limit. Default: 1000 |
+| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
+| `--use_cache` | No | Whether to use cache. Default: true |
+
+## Decision Rules
+- `filters` / `properties` cannot be written from experience alone: they 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.
+- On the first run, start with only the required parameters (`--project_id`, `--event_name`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--properties '{}'`) to avoid shell escaping issues.
+- When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## 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`, `--event_name`).
+- If `Invalid JSON` appears, first check the filter schema required fields, then verify whether the 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_filter_schema -> te_meta +list_events -> te_meta +list_properties -> +query_event_details
+- +query_entity_details -> +query_event_details -> +build_event_details_sql

package/skills/te-analysis/references/query-report-data.md

@@ -0,0 +1,65 @@
+# te_analysis +query_report_data (query data by report)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Report Management**
+
+## Use Cases
+- Prerequisite helper: first call `+get_filter_schema` to get the structure, then call this tool.
+- Prerequisite helper: first call `+get_groupby_schema` to get the structure, then call this tool.
+- When building `filters` / `group_by`, you must supplement the project's real event/property metadata.
+- Query analysis data for one or more reports. Returns chart values, trend results, and similar data, but not report definitions. Supports extra filters, group-by settings, and time range overrides.
+- Query analysis data for one or more reports.
+
+## Mandatory Prerequisites (MUST)
+- Before building `--filters` / `--group_by`, you must first read and follow the following reference docs:
+  - [`./get-filter-schema.md`](./get-filter-schema.md)
+  - [`./get-groupby-schema.md`](./get-groupby-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate final `filters` / `group_by` until the above docs have been read and the prerequisite commands have been called.
+
+## Prerequisite Call Chain (required for building filters/group_by)
+1. Read `get-filter-schema.md`, then call `ae-cli te_analysis +get_filter_schema` to get the filter structure.
+2. Read `get-groupby-schema.md`, then call `ae-cli te_analysis +get_groupby_schema` to get the grouping structure.
+3. Read `list-events.md`, then call `ae-cli te_meta +list_events --project_id 1`.
+4. Read `list-properties.md`, then call `ae-cli te_meta +list_properties --project_id 1`.
+5. Build `filters` / `group_by` based on the schema and metadata, then call `+query_report_data`.
+
+## Commands
+```bash
+ae-cli te_analysis +query_report_data --project_id 1 --report_ids '[1001]'
+ae-cli te_analysis +query_report_data --project_id 1 --report_ids '[1001]' --filters '{}' --group_by '[]' --request_id demo --use_cache true --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --timeout_minutes 8
+ae-cli te_analysis +query_report_data --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--report_ids` | Yes | List of report IDs |
+| `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `te_meta +list_properties` in the same `project_id`. |
+| `--group_by` | No | Optional group-by JSON array. If provided, MUST follow `+get_groupby_schema`, and referenced fields must come from `te_meta +list_properties` in the same `project_id`. |
+| `--request_id` | No | Optional unique request ID. Generated automatically if omitted. |
+| `--use_cache` | No | Whether to use cache. Default: true |
+| `--start_date` | No | Optional start date in yyyy-MM-dd format |
+| `--end_date` | No | Optional end date in yyyy-MM-dd format |
+| `--time_granularity` | No | Optional time granularity used to override the report default. Supported values: minute, minute5, minute10, hour, day, week, month, quarter, year, total. |
+| `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. 30 minutes if omitted. |
+
+## Decision Rules
+- `filters` / `group_by` cannot be written by hand based on experience alone: they must satisfy both the schema structure and the project's real metadata.
+- `list_events` / `list_properties` must be learned from the corresponding reference docs before calling them.
+- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--report_ids`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--report_ids '{}'`, `--filters '{}'`) to avoid shell escaping issues.
+- When dates/time ranges are involved, validate with a short range first and then expand gradually.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## Next Step After Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--report_ids`).
+- If `Invalid JSON` appears, first check the required schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
+- If the query times out or the result is abnormal, first reduce the time range/grouping dimensions, then split the query to locate the issue.
+
+## Recommended Chaining
+- +get_filter_schema -> +get_groupby_schema -> te_meta +list_events -> te_meta +list_properties -> +query_report_data
+- +list_reports -> +get_report_definition -> +query_report_data

package/skills/te-analysis/references/update-alert.md

@@ -0,0 +1,49 @@
+# te_analysis +update_alert (Update Alert)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Metadata queries**
+
+## Use Cases
+- Precondition helper: call `+get_alert_definition_schema` to get the structure before using this tool.
+- Update an existing alert. All fields in the definition will replace existing values. See get_alert_definition_schema for the parameter structure.
+- Update an existing alert.
+
+## Mandatory prerequisites (MUST)
+- Before constructing a new `--definition`, you must first read and follow:
+  - [`./get-alert-definition-schema.md`](./get-alert-definition-schema.md)
+- Do not submit the new `definition` until the documentation review and schema call are complete.
+
+## Prerequisite call chain (required for updating definition)
+1. Read `get-alert-definition-schema.md` to understand the return structure of `+get_alert_definition_schema`.
+2. Call `te-cli te_analysis +get_alert_definition_schema` to get the schema.
+3. Build a new `definition` from the schema, then call `+update_alert`.
+
+## Command
+```bash
+te-cli te_analysis +update_alert --project_id 1 --alert_id 1 --definition '{}'
+te-cli te_analysis +update_alert --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--alert_id` / `-a` | Yes | Alert ID to update |
+| `--definition` | Yes | Alert definition JSON with updated fields. MUST call `+get_alert_definition_schema` first and strictly follow the returned structure. |
+
+## Decision Rules
+- `definition` cannot be written from experience alone: it must satisfy the alert schema structure constraints.
+- On the first run, start with only the required parameters (`--project_id`, `--alert_id`, `--definition`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--definition '{}'`) to avoid shell escaping issues.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` for automated scenarios.
+
+## 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`, `--alert_id`, `--definition`).
+- If `Invalid JSON` appears, first check the schema required fields and enumeration values, then add fields incrementally.
+- If the result after writing does not match expectations, immediately read back the corresponding list/get interface to compare before and after.
+
+## Recommended chaining
+- +get_alert_definition_schema -> +update_alert
+- +list_alerts -> +get_alert -> +update_alert

package/skills/te-analysis/references/update-dashboard.md

@@ -0,0 +1,45 @@
+# te_analysis +update_dashboard (update dashboard)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Dashboard Management**
+
+## Use Cases
+- Update dashboard metadata. Supports three operations (all optional):
+- (1) Rename dashboard
+- (2) Add associated reports (append mode)
+- (3) Replace share members (full replacement mode)
+- Important constraints:
+- Before replacing share members: call query_dashboard_detail first
+- When managing members: call list_project_users to get valid userId mappings
+- Update dashboard metadata.
+
+## Commands
+```bash
+ae-cli te_analysis +update_dashboard --project_id 1 --dashboard_id 1
+ae-cli te_analysis +update_dashboard --project_id 1 --dashboard_id 1 --dashboard_name demo --report_ids '[1001]' --member_authorities '{"1001":"READ"}'
+ae-cli te_analysis +update_dashboard --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--dashboard_id` / `-d` | Yes | Dashboard ID |
+| `--dashboard_name` | No | New dashboard name. If provided, updates the dashboard name. |
+| `--report_ids` | No | List of report IDs to associate with the dashboard. Reports not already associated will be added (append mode, not a full replacement). |
+| `--member_authorities` | No | Map of member userId to permissions (READ, EDIT, MAINTAIN). Full replacement mode — existing members not in this map will be removed. |
+
+## Decision Rules
+- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--dashboard_id`) and add optional parameters after confirming the chain works.
+- Wrap JSON parameters in single quotes (for example `--report_ids '{}'`, `--member_authorities '{}'`) to avoid shell escaping issues.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` only for automation scenarios.
+
+## Next Step After Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--dashboard_id`).
+- If `Invalid JSON` appears, first validate with the smallest JSON structure (for example `{}` or `[]`), then add fields gradually.
+- If the result after writing is not as expected, immediately reread the corresponding list/get interface and compare before and after.
+
+## Recommended Chaining
+- +list_dashboards -> +query_dashboard_detail -> +query_dashboard_report_data

package/skills/te-analysis/references/update-public-access-link.md

@@ -0,0 +1,41 @@
+# te_analysis +update_public_access_link (Update Public Access Link)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Dashboard management**
+
+## Use Cases
+- Update the access controls, remark, and effective time range of a public access link. Returns the updated link information.
+- Update the access controls, remark, and effective time range of a public access link.
+
+## Command
+```bash
+ae-cli te_analysis +update_public_access_link --project_id 1 --link_id 1 --access_controls '{}' --effective_at "2026-04-09 10:00:00" --expires_at "2026-04-10 10:00:00"
+ae-cli te_analysis +update_public_access_link --project_id 1 --company_id 1 --link_id 1 --access_controls '{}' --remark demo --effective_at "2026-04-09 10:00:00" --expires_at "2026-04-10 10:00:00"
+ae-cli te_analysis +update_public_access_link --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--company_id` | No | Optional company ID. If omitted, the company ID of the project is used. |
+| `--link_id` | Yes | Link ID |
+| `--access_controls` | Yes | Public access control JSON |
+| `--remark` | No | Optional remark. Maximum length: 200 characters |
+| `--effective_at` | Yes | Effective time. Format: yyyy-MM-dd HH:mm:ss |
+| `--expires_at` | Yes | Expiration time. Format: yyyy-MM-dd HH:mm:ss |
+
+## Decision Rules
+- On the first run, start with only the required parameters (`--project_id`,`--link_id`,`--access_controls`), and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (for example `--access_controls '{}'`) to avoid shell escaping issues.
+- When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
+- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## 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`, `--link_id`, `--access_controls`).
+- If `Invalid JSON` appears, first verify with the smallest JSON structure (for example `{}` or `[]`), then add fields incrementally.
+- If the result after writing does not match expectations, immediately read back the corresponding list/get interface to compare before and after.
+
+## Recommended chaining
+- +list_public_access_links -> +update_public_access_link

package/skills/te-audience/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: te-audience
+version: 1.0.0
+description: "TE audience operations and targeting: create, update, query, recompute, and inspect member details for clusters and tags, plus cluster/tag definition schemas. Triggered when the user mentions audience building/targeting, audience packages, tag systems, tag assignment, tag member lookup, updating cluster rules, or recomputing clusters or tags."
+metadata:
+  requires:
+    bins: ["ae-cli"]
+  cliHelp: "ae-cli te_audience --help"
+---
+
+# te-audience
+
+> **CRITICAL - Before starting, MUST first read [`../te-shared/SKILL.md`](../te-shared/SKILL.md)**: authentication, host configuration, global parameters, and write-operation confirmation rules are defined there.
+> **CRITICAL - Before performing write operations, MUST first read [`../te-common/SKILL.md`](../te-common/SKILL.md)**: shared post-action constraints (append resource links after create/update) are defined in that module.
+> **CRITICAL - For every command that requires `project_id`, MUST follow `te-common`'s `PROJECT_ID_GATE` (if missing, stop and confirm with the user).**
+> **CRITICAL - Before running any `+<tool_name>` command, MUST first read the corresponding reference document `./references/<tool-name>.md`** For example: before running `+create_cluster`, you must read [`./references/create-cluster.md`](./references/create-cluster.md)
+
+## When to Use
+
+Use `te-audience` when the user needs cluster and tag capabilities:
+
+- Clusters: create, update, query, member inspection, recomputation
+- Tags: create, update, query, member inspection, recomputation
+- Cluster/tag definition schema: for frontend configurators or command argument construction
+
+## Command Format
+
+`ae-cli te_audience +<tool_name> [options]`
+
+## Tool Groups (14)
+
+### Clusters (6)
+- `+create_cluster` ([Docs](./references/create-cluster.md))
+- `+get_clusters_by_name` ([Docs](./references/get-clusters-by-name.md))
+- `+list_cluster_members` ([Docs](./references/list-cluster-members.md))
+- `+list_clusters` ([Docs](./references/list-clusters.md))
+- `+update_cluster` ([Docs](./references/update-cluster.md))
+- `+refresh_cluster` ([Docs](./references/refresh-cluster.md))
+
+### Tags (6)
+- `+create_tag` ([Docs](./references/create-tag.md))
+- `+get_tags_by_name` ([Docs](./references/get-tags-by-name.md))
+- `+list_tag_members` ([Docs](./references/list-tag-members.md))
+- `+list_tags` ([Docs](./references/list-tags.md))
+- `+update_tag` ([Docs](./references/update-tag.md))
+- `+refresh_tag` ([Docs](./references/refresh-tag.md))
+
+### Schema Definitions (2)
+- `+get_cluster_definition_schema` ([Docs](./references/get-cluster-definition-schema.md))
+- `+get_tag_definition_schema` ([Docs](./references/get-tag-definition-schema.md))
+
+## Quick Validation
+
+```bash
+ae-cli te_audience --help
+npm run verify:te-audience-tools
+# Example: preview the request with dry-run (replace project_id with your actual project ID)
+ae-cli te_audience +list_clusters --project_id <YOUR_PROJECT_ID> --dry-run
+```
+
+## Reference Docs
+
+See the `references/` directory (14 per-command documents total).

package/skills/te-audience/references/create-cluster.md

@@ -0,0 +1,65 @@
+# te_audience +create_cluster (Create Cluster)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Cluster Management**
+
+## Use Cases
+- Prerequisite helper: first call `+get_cluster_definition_schema` to obtain the `definition` structure, then call this tool.
+- When building a real `definition`, you must supplement it with real project metadata: first call `te_meta +list_events` and `te_meta +list_properties`, then fill in event names/property names.
+- Create a user cluster definition. Supports the condition and sql cluster types. Returns cluster information without cluster members.
+
+## Required Prerequisites (MUST)
+- Before constructing `--definition`, you must first read and follow these reference docs:
+  - [`./get-cluster-definition-schema.md`](./get-cluster-definition-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate the final `definition` until the above docs have been read and the prerequisite commands have been run.
+
+## Prerequisite Call Chain (Required for Building Definition)
+1. Read `get-cluster-definition-schema.md` to understand the input and output structure of `+get_cluster_definition_schema`.
+2. Obtain the schema structure (by cluster type):
+   `te-cli te_audience +get_cluster_definition_schema --cluster_type condition`
+3. Read `list-events.md` to understand the parameters and return structure of `+list_events`.
+4. Get the event list (for `event_name` and other fields):
+   `te-cli te_meta +list_events --project_id 1`
+5. Read `list-properties.md` to understand the parameters and return structure of `+list_properties`.
+6. Get the property list (for property filters, grouping, and comparison fields):
+   `te-cli te_meta +list_properties --project_id 1`
+7. Build `definition` based on the schema + metadata, then call `+create_cluster`.
+
+## Commands
+```bash
+te-cli te_audience +create_cluster --project_id 1 --cluster_name demo --display_name demo --definition '{}'
+te-cli te_audience +create_cluster --project_id 1 --cluster_name demo --display_name demo --type condition --definition '{}' --zone_offset 8 --entity_id 1001
+te-cli te_audience +create_cluster --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--cluster_name` | Yes | Cluster name. Must start with a letter and contain only letters, digits, and underscores. Length: 1-80 |
+| `--display_name` | Yes | Cluster display name. Length: 1-80 |
+| `--type` | No | Cluster type. Supported values: condition and sql. Default: condition |
+| `--definition` | Yes | Cluster definition JSON. MUST call `+get_cluster_definition_schema` first to learn the exact structure, then use `te_meta +list_events` / `te_meta +list_properties` to fill valid event/property names from the target project. |
+| `--zone_offset` | No | Optional time zone offset for cluster computation. Valid range: -12 to 14 (supports decimals like 5.5). If the user does not specify a timezone, omit this parameter. When a timezone is specified, call get_project_config first to check whether the project supports time zones (timeZoneEnabled) and available values (availableTimeZones). |
+| `--entity_id` | No | Optional entity ID for cluster definition. Use list_entities to query available entities. |
+
+## Decision Rules
+- `definition` cannot be written from experience alone: it must satisfy both the schema structure and the project's real metadata (events and properties).
+- Determine `--type` first, then fetch the schema for the corresponding `--cluster_type`; do not mix condition/sql structures.
+- Before calling `list_events` / `list_properties`, you must first read their reference docs to avoid misuse of parameters or misreading return fields.
+- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`, `--display_name`, `--definition`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (e.g. `--definition '{}'`) to avoid shell escaping issues.
+- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep confirmation prompts by default; for automation scenarios, reevaluate whether to use `--yes`.
+
+## Next Step on Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`, `--display_name`, `--definition`).
+- If `Invalid JSON` appears, first check whether a schema-required field is missing, then verify whether event/property names come from the same `project_id`'s `list_events/list_properties` results.
+- If the result after writing is not as expected, immediately re-read the corresponding list/get interfaces and compare before and after.
+
+## Recommended Chain
+- +get_cluster_definition_schema -> te_meta +list_events -> te_meta +list_properties -> +create_cluster
+- +list_clusters -> +get_clusters_by_name -> +update_cluster

package/skills/te-audience/references/create-tag.md

@@ -0,0 +1,60 @@
+# te_audience +create_tag (Create Tag)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Tag Management**
+
+## Use Cases
+- Prerequisite helper: first call `+get_tag_definition_schema` to obtain the structure, then call this tool.
+- When building a real `definition`, you must supplement it with real project metadata; at minimum, first call `te_meta +list_events` and `te_meta +list_properties`.
+- Create a user tag definition. Supports the condition, metric, first_last, and sql tag types. Returns the new tag ID without tag members.
+
+## Required Prerequisites (MUST)
+- Before constructing `--definition`, you must first read and follow these reference docs:
+  - [`./get-tag-definition-schema.md`](./get-tag-definition-schema.md)
+  - [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md)
+  - [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- Do not generate the final `definition` until the above docs have been read and the prerequisite commands have been run.
+
+## Prerequisite Call Chain (Required for Building Definition)
+1. First determine `--type` (condition / metric / first_last / sql).
+2. Read `get-tag-definition-schema.md` to understand the return structure of `+get_tag_definition_schema`.
+3. Call `te-cli te_audience +get_tag_definition_schema` to obtain the schema.
+4. Read `list-events.md`, then call `te-cli te_meta +list_events --project_id 1` to get available events.
+5. Read `list-properties.md`, then call `te-cli te_meta +list_properties --project_id 1` to get available properties.
+6. Build `definition` based on the schema + metadata, then call `+create_tag`.
+
+## Commands
+```bash
+te-cli te_audience +create_tag --project_id 1 --tag_name demo --display_name demo --definition '{}'
+te-cli te_audience +create_tag --project_id 1 --tag_name demo --display_name demo --type condition --definition '{}' --zone_offset 8 --entity_id 1001
+te-cli te_audience +create_tag --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--tag_name` | Yes | Tag name. Must start with a letter and contain only letters, digits, and underscores. Length: 1-80 |
+| `--display_name` | Yes | Tag display name. Length: 1-80 |
+| `--type` | No | Tag type. Supported values: condition, metric, first_last, sql |
+| `--definition` | Yes | Tag definition JSON. MUST call `+get_tag_definition_schema` first, then fill valid event/property names from `te_meta` metadata commands in the same `project_id`. |
+| `--zone_offset` | No | Optional time zone offset for tag computation. Valid range: -12 to 14 (supports decimals like 5.5). If the user does not specify a timezone, omit this parameter. When a timezone is specified, call get_project_config first to check whether the project supports time zones (timeZoneEnabled) and available values (availableTimeZones). |
+| `--entity_id` | No | Optional entity ID for tag definition. Use list_entities to query available entities. |
+
+## Decision Rules
+- `definition` cannot be written from experience alone: it must satisfy both the schema structure and the project's real metadata.
+- Before calling `list_events` / `list_properties`, you must first read the corresponding reference docs to avoid misuse of parameters or misreading return fields.
+- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--tag_name`, `--display_name`, `--definition`) and add optional parameters after confirming the path works.
+- Wrap JSON parameters in single quotes (e.g. `--definition '{}'`) to avoid shell escaping issues.
+- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
+- Write operations keep confirmation prompts by default; for automation scenarios, reevaluate whether to use `--yes`.
+
+## Next Step on Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--tag_name`, `--display_name`, `--definition`).
+- If `Invalid JSON` appears, first check schema-required fields, then verify whether event/property names come from the same `project_id`'s metadata query results.
+- If the result after writing is not as expected, immediately re-read the corresponding list/get interfaces and compare before and after.
+
+## Recommended Chain
+- +get_tag_definition_schema -> te_meta +list_events -> te_meta +list_properties -> +create_tag
+- +list_tags -> +get_tags_by_name -> +update_tag

package/skills/te-audience/references/get-cluster-definition-schema.md

@@ -0,0 +1,37 @@
+# te_audience +get_cluster_definition_schema (Get Cluster Definition Schema)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Schema Query**
+
+## Use Cases
+- Support tool positioning: the current command provides the structure definition (schema) and should be used as a prerequisite step.
+- Recommended sequence: first call this schema tool to get the structure, then call `te_meta +list_events` / `te_meta +list_properties` to obtain real metadata, and finally create or update clusters.
+- Get the cluster definition schema. Supports the condition and sql cluster types and returns field definitions, enum descriptions, and examples.
+
+## Commands
+```bash
+te-cli te_audience +get_cluster_definition_schema --cluster_type condition
+te-cli te_audience +get_cluster_definition_schema --cluster_type sql
+te-cli te_audience +get_cluster_definition_schema --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--cluster_type` | Yes | Cluster type. Supported values: condition and sql |
+
+## Decision Rules
+- `--cluster_type` must be explicitly set to `condition` or `sql`.
+- It is recommended to run `--dry-run` first to inspect the request mapping before making the actual call.
+- The current command returns only structure constraints; it does not guarantee that the field values are available in the target project. Event names and property names must be confirmed again with `te_meta` metadata interfaces.
+- Before calling `te_meta +list_events` / `te_meta +list_properties`, first read their reference docs to confirm the parameter and return-field meanings.
+
+## Next Step on Failure
+- If reading fails, first verify whether the object ID exists and belongs to the current project.
+- If the schema does not match expectations, confirm whether the correct schema interface was used (filter/groupby/query/tag/cluster).
+
+## Recommended Chain
+- First read: [`./get-cluster-definition-schema.md`](./get-cluster-definition-schema.md) -> [`../../te-meta/references/list-events.md`](../../te-meta/references/list-events.md) -> [`../../te-meta/references/list-properties.md`](../../te-meta/references/list-properties.md)
+- +get_cluster_definition_schema -> te_meta +list_events -> te_meta +list_properties -> +create_cluster
+- +get_cluster_definition_schema -> te_meta +list_events -> te_meta +list_properties -> +update_cluster

package/skills/te-audience/references/get-clusters-by-name.md

@@ -0,0 +1,32 @@
+# te_audience +get_clusters_by_name (Locate Clusters by Name)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Cluster Management**
+
+## Use Cases
+- Get cluster definition details in batch by cluster name. Returns complete cluster information for matched clusters, including IDs, names, display names, types, status, user counts, and refresh status.
+
+## Commands
+```bash
+te-cli te_audience +get_clusters_by_name --project_id 1 --names '["demo"]'
+te-cli te_audience +get_clusters_by_name --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--names` | Yes | List of cluster names (JSON array). Exact-name matching is used; unmatched clusters are ignored automatically. |
+
+## Decision Rules
+- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--names`) and add optional parameters after confirming the path works.
+- `--names` must be passed as a JSON array (e.g. `--names '["cluster_a","cluster_b"]'`).
+- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## Next Step on Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--names`).
+- If reading fails, first verify whether the object ID exists and belongs to the current project.
+
+## Recommended Chain
+- +list_clusters -> +get_clusters_by_name -> +update_cluster

package/skills/te-audience/references/get-tag-definition-schema.md

@@ -0,0 +1,32 @@
+# te_audience +get_tag_definition_schema (Get Tag Definition Schema)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Schema Query**
+
+## Use Cases
+- Support tool positioning: the current command provides the structure definition (schema) and should be used as a prerequisite step.
+- Recommended sequence: first call this schema tool to get the structure, then call specific business tools.
+- Typical downstream tools: `+create_tag`, `+update_tag`
+- Get the tag definition schema. Supports the condition, metric, first_last, and sql tag types and returns field definitions, enum descriptions, and examples.
+
+## Commands
+```bash
+te-cli te_audience +get_tag_definition_schema
+te-cli te_audience +get_tag_definition_schema --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| None | - | This command has no business parameters; call it directly. |
+
+## Decision Rules
+- It is recommended to run `--dry-run` first to inspect the request mapping before making the actual call.
+
+## Next Step on Failure
+- If reading fails, first verify whether the object ID exists and belongs to the current project.
+- If the schema does not match expectations, confirm whether the correct schema interface was used (filter/groupby/query/tag/cluster).
+
+## Recommended Chain
+- +get_analysis_query_schema -> +get_filter_schema -> +get_groupby_schema

package/skills/te-audience/references/get-tags-by-name.md

@@ -0,0 +1,32 @@
+# te_audience +get_tags_by_name (Locate Tags by Name)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Tag Management**
+
+## Use Cases
+- Get tag definition details in batch by tag name. Returns complete tag information for matched tags, including IDs, names, display names, types, status, user counts, and tag definitions.
+
+## Commands
+```bash
+te-cli te_audience +get_tags_by_name --project_id 1 --names '["demo"]'
+te-cli te_audience +get_tags_by_name --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--names` | Yes | List of tag names (JSON array). Exact-name matching is used; unmatched tags are ignored automatically. |
+
+## Decision Rules
+- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--names`) and add optional parameters after confirming the path works.
+- `--names` must be passed as a JSON array (e.g. `--names '["tag_a","tag_b"]'`).
+- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## Next Step on Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--names`).
+- If reading fails, first verify whether the object ID exists and belongs to the current project.
+
+## Recommended Chain
+- +list_tags -> +get_tags_by_name -> +update_tag

package/skills/te-audience/references/list-cluster-members.md

@@ -0,0 +1,35 @@
+# te_audience +list_cluster_members (View Cluster Members)
+
+> **Prerequisite:** Read [`../te-shared/SKILL.md`](../../te-shared/SKILL.md)
+
+Domain: **Cluster Management**
+
+## Use Cases
+- List members in the specified cluster. Returns member information such as user property values and total user count.
+
+## Commands
+```bash
+te-cli te_audience +list_cluster_members --project_id 1 --cluster_name demo
+te-cli te_audience +list_cluster_members --project_id 1 --cluster_name demo --property_names '["#user_id","name"]' --use_cache false
+te-cli te_audience +list_cluster_members --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--cluster_name` | Yes | Cluster name |
+| `--property_names` | No | Optional list of user property names (JSON array) |
+| `--use_cache` | No | Whether to use cache. Default: true |
+
+## Decision Rules
+- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`) and add optional parameters after confirming the path works.
+- `--property_names` must be passed as a JSON array (e.g. `--property_names '["#user_id"]'`).
+- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
+
+## Next Step on Failure
+- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`).
+- If the result is empty, first confirm the project ID/keyword, then try broadening the filter conditions.
+
+## Recommended Chain
+- +list_clusters -> +get_clusters_by_name -> +update_cluster