@thinkingai/ae-cli 6.0.30 → 6.0.32

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

@@ -0,0 +1,24 @@
+# analysis-governance rule schema
+
+Use when the user needs to get asset governance rule field schema through the capability gateway.
+
+Do not use it to list saved governance rules; use it before create/update only when the allowed rule fields or operators are unknown.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule schema --project-id <project_id>
+ae-cli analysis-governance rule schema --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.schema.
+
+Input sends project_id, payload. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` is the project-specific rule column/operator schema consumed by the `rule` object in rule create and update commands.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -0,0 +1,28 @@
+# analysis-governance rule update
+
+Use when the user needs to update an asset governance rule through the capability gateway.
+
+Do not use it to create a new rule or guess a rule ID; resolve the existing rule with `rule-list` before updating its full definition.
+
+Command:
+
+```bash
+ae-cli analysis-governance rule update --project-id <project_id> --payload '{}'
+ae-cli analysis-governance rule update --dry-run --project-id <project_id>
+```
+
+Capability id: analysis_meta.asset_rule.update.
+
+Input sends project_id, payload, rule_id, rule_name, comment, rule. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+
+Output `data` returns the updated `rule_id` and `updated=true`; a missing rule is an operation failure, not a create fallback.
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| --project-id | Yes | Numeric project ID. |
+| --rule-id | No | Rule ID; required unless provided inside payload. |
+| --rule-name | No | Rule name; required unless provided inside payload. |
+| --comment | No | Rule comment. |
+| --rule | No | Governance Filter JSON; required unless provided inside payload. |
+| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |

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

@@ -1,10 +1,16 @@
 # analysis run inspect
 
-Use after an export command returns `run_id`.
+Inspect an async analysis capability-gateway run returned by export commands.
 
-Do not use for MCP query cancellation or old `request_id` lifecycle. This is only for capability-gateway export `run_id`.
+Use for `analysis adhoc export`, `analysis report-data export`, `analysis dashboard-report-data export`, `analysis bi-panel-page-data export`, and other analysis exports that return `run_id`.
 
-Command:
+Do not use this for MCP `request_id` cancellation or status. MCP query lifecycle uses the specific MCP command contract.
+
+Input:
+
+- `run_id`: required async run ID returned by the export response.
+
+Use the exact `run_id` from the same export response that supplied the artifact; do not substitute a request ID, invocation ID, path segment, or an older run ID.
 
 ```bash
 ae-cli analysis run inspect --run-id <run_id>
@@ -12,7 +18,7 @@ ae-cli analysis run inspect --run-id <run_id>
 
 Input sends `run_id`.
 
-Output is the gateway envelope. `data` contains run status, artifact status, and error fields when the run failed.
+Output is the gateway run descriptor with run status, artifact status, and error fields when the run failed. Keep the `run_id` from the same export result; do not invent or reuse it across artifacts.
 
 Polling rule:
 

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

@@ -8,6 +8,9 @@ Domain: **Project Configuration**
 - Create/update TRACKING-PLAN metadata only (planned bury items). Do not use this tool to create or edit effective system metadata. If the user intent is production metadata changes, route to MetaPowerTool instead.
 - Create/update TRACKING-PLAN metadata only (planned bury items).
 
+## Output
+The response reports persistence of the submitted tracking-plan items. Read the plan back with `+get_track_program` before claiming the saved structure is effective.
+
 ## Command
 ```bash
 ae-cli analysis_meta +save_track_items --project_id <project_id> --track_data '{}'
@@ -24,7 +27,7 @@ ae-cli analysis_meta +save_track_items --dry-run
 - First run should only pass the required parameters (`--project_id`, `--track_data`), and add optional parameters only after the path is confirmed to work.
 - Wrap JSON arguments in single quotes (for example `--track_data '{}'`) 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; re-evaluate whether to use `--yes` in automation scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps After Failure
 - If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id` and `--track_data`).

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

@@ -0,0 +1,20 @@
+# analysis sql-table columns
+
+List queryable columns for one server-authorized SQL table.
+
+First call `analysis sql-table list --project-id <project_id>`, then copy an exact returned `table_ref`. Do not guess table or column names.
+
+```bash
+ae-cli analysis sql-table columns \
+  --project-id <project_id> \
+  --table-ref <table_ref> \
+  [--usage analysis|tag_cluster]
+```
+
+The result identifies the resolved catalog/schema/table and returns its columns with machine names, types, and available descriptions. A unique table-only reference is accepted; ambiguous references fail with candidate tables instead of selecting one arbitrarily.
+
+Pass the same `usage` used for `sql-table list`. For SQL tags and SQL clusters this must be `--usage tag_cluster`; the default is `analysis`.
+
+When copying returned columns into Trino SQL, delimit identifiers containing `#`, `$`, `@`, spaces, or punctuation with double quotes, for example `"#user_id"` or `"$part_event"`. Single quotes are string literals. The CLI does not auto-rewrite SQL.
+
+If the selected table is an event table, the SQL must include a date-partition predicate on the discovered `"$part_date"` column, for example `WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'`. The backend rejects event-table SQL without this condition. Do not apply this rule to a table whose discovered columns do not include `$part_date`.

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

@@ -0,0 +1,33 @@
+# analysis sql-table list
+
+List the server-authoritative SQL table references that the current user may query in one project.
+
+## Command
+
+```bash
+ae-cli analysis sql-table list \
+  --project-id <project_id> \
+  [--query <keyword>] \
+  [--limit <1-200>] \
+  [--offset <next_offset>] \
+  [--usage analysis|tag_cluster]
+```
+
+## Contract
+
+- Use this command before writing SQL when the table is not already known. Do not ask the customer to supply the fixed project event/user table name and do not guess `v_event_<id>` or `v_user_<id>`.
+- `table_ref` is the exact server-authorized reference to copy into SQL and into `analysis sql-table columns --table-ref`.
+- Each item also returns `catalog`, `schema`, `table`, `table_type`, and `description`.
+- `usage=analysis` is the default table set for SQL analysis and reports. Use `usage=tag_cluster` for SQL tags or SQL clusters. These server-authorized sets differ, and the same usage must be passed to `sql-table columns`.
+- When `has_more=true`, continue only with the returned `next_offset`. Stop when `has_more=false`.
+- An empty list means the current identity has no queryable SQL tables in that project; do not fabricate a table name.
+
+## Example workflow
+
+```bash
+ae-cli analysis sql-table list --project-id 1 --query user
+ae-cli analysis sql-table columns --project-id 1 --table-ref hive.ta.v_user_1
+ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from hive.ta.v_user_1 limit 10"}'
+```
+
+Use the exact `table_ref` returned by the first command; the example reference is illustrative only.

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

@@ -37,7 +37,7 @@ ae-cli analysis +update_alert --dry-run
 - 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.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## 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`).

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

@@ -7,6 +7,7 @@ Domain: **Project Configuration**
 ## Use Cases
 - Update an existing project date marker. Returns the updated marker ID, timestamp, content, and visibility status.
 - Update an existing project date marker.
+- Do not use it to create a marker or change analysis data; use `+create_project_mark_time` for a new marker.
 
 ## Command
 ```bash
@@ -26,13 +27,13 @@ ae-cli analysis_meta +update_project_mark_time --dry-run
 | `--is_visible` | No | Whether the marker is visible. Default: 1 |
 
 ## Decision Rules
-- First run should only pass required parameters (`--mark_time_id`, `--project_id`, `--marked_at`), and add optional parameters only after the path is confirmed to work.
+- The smallest valid request also includes required `--content`; use `--dry-run` with `--mark_time_id`, `--project_id`, `--marked_at`, and `--content` before executing.
 - For date/time ranges, first validate with a short range, then expand the range step by step.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep the confirmation prompt by default; re-evaluate whether to use `--yes` in automation scenarios.
+- This is an ordinary `write` operation and does not require CLI confirmation.
 
 ## Next Steps After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--mark_time_id`, `--project_id`, and `--marked_at`).
+- If required parameters are missing, supply `--mark_time_id`, `--project_id`, `--marked_at`, and `--content` before retrying.
 - If the result after writing is not as expected, immediately read back the corresponding list/get interface for a before-and-after comparison.
 
 ## Recommended Chaining

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

@@ -0,0 +1,17 @@
+# analysis user-cluster create
+
+Create a condition or SQL user cluster directly from an AI-facing definition request.
+
+Do not use it for uploaded-ID clusters or result-derived clusters; use `user-cluster create-id` or `query create-result-cluster`. A successful create automatically starts the initial computation; it does not mean the result is already complete. Do not call `user-cluster refresh` afterward. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
+
+The response reports this directly: `computation.triggered_automatically=true`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow `next_action`; when it is `poll_get`, invoke `next_capability_id` with the exact `next_input` returned by the command.
+
+Flags: `--project-id`, `--cluster-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The cluster type comes from `definition_request.type`.
+
+Read `user_cluster_models.md` before constructing `--definition-request`. Create does not accept `--remark`; set it later with `user-cluster update` when needed.
+
+The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the cluster. Condition clusters are saved as mixed-condition clusters (`clusterType=CONDITION`, `clusterSubType=MIX_CONDITION`).
+
+```bash
+ae-cli analysis user-cluster create --project-id <project_id> --cluster-name retained_users --display-name "Retained Users" --definition-request '{"type":"condition","conditions":{"relation":"and","items":[{"type":"user","field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster create-id
+
+Create a cluster by mapping imported values to an analysis entity.
+
+Flags: `--project-id`, `--display-name`, and `--entity-id` are required. Prefer `--input-file <local_csv>`; the CLI uploads it automatically. `--input-file-id` resumes from an existing upload, while `--file-content` is only for small local tests. Exactly one of the three is allowed. Optional: `--cluster-name`, `--remarks`, and conditional `--association-property`.
+
+Use `--input-file` for real local files; use `--input-file-id` only when resuming from an existing upload. Do not inline large ID lists.
+
+Run `analysis entity id-import-options` first. For the primary user entity, pass an allowed `--association-property` and put its real values in the single CSV column; `#user_id` is forbidden. For a non-primary entity, omit the flag and put that entity's own IDs in the single column. Every row must be non-empty.
+
+Create returns `operation_status=PROCESSING` and `match_summary_status=PENDING`; it does not report submission-time counters as final matching results. Poll `user-cluster get` until progress is 100 for the final `match_summary`.
+
+```bash
+ae-cli analysis user-cluster create-id --project-id <project_id> --display-name "VIP IDs" --entity-id <entity_id> --association-property email --input-file /tmp/vip.csv --cluster-name vip_ids
+```

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

@@ -0,0 +1,13 @@
+# analysis user-cluster delete
+
+Delete a user cluster after dependency/influence review.
+
+Do not use it to clear members, stop computation, or hide a cluster. Output confirms deletion of the exact `cluster_name`; verify it is absent from `user-cluster list`.
+
+Flags: `--project-id`, `--cluster-name` required. Add `--confirmed` and `--yes` only after the user accepts the dry-run impact.
+
+```bash
+ae-cli analysis user-cluster delete --project-id <project_id> --cluster-name old_cluster --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis user-cluster delete --project-id <project_id> --cluster-name old_cluster --confirmed --yes
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster get
+
+Get exact user cluster details after discovery.
+
+Do not use it for fuzzy discovery or member data. Output contains saved cluster metadata/definition for the requested names.
+
+After `user-cluster create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-cluster refresh`. Until `progress=100` and `refresh_end_time` is not older than `update_time`, `users_num` and member queries may still reflect the previous successful computation. Treat that state as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+
+The raw backend value is returned under `result`. The response also provides aggregate and per-cluster `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_end_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
+
+Flags: `--project-id`, `--cluster-names` JSON array.
+
+```bash
+ae-cli analysis user-cluster get --project-id <project_id> --cluster-names '["retained_users"]'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster list
+
+List accessible user clusters for discovery. Use this before any get/update/delete/member command; do not invent `cluster_name`.
+
+Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--offset` is only for stable asset browsing. It is not a member-data pagination strategy.
+When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
+
+Output is a paged cluster inventory, not cluster members or definition-build results.
+
+```bash
+ae-cli analysis user-cluster list --project-id <project_id> --query retained --limit 50
+ae-cli analysis user-cluster list --project-id <project_id> --fields '["cluster_name","display_name","users_num"]' --limit 50 --offset 0
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster-member export
+
+Export cluster members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+
+```bash
+ae-cli analysis user-cluster-member export --project-id <project_id> --cluster-name retained_users --artifact-format jsonl
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output members.jsonl.gz
+```

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

@@ -0,0 +1,19 @@
+# analysis user-cluster-member list
+
+Run a bounded inline cluster member query. Read `analysis_data_retrieval.md` before choosing list vs export.
+
+Do not use it for complete/unknown-size membership retrieval or cluster metadata. Output contains at most the requested inline limit and has no caller pagination contract.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+
+When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, and `#distinct_id`. Cluster members do not expose tag-only fields such as `tag_value` or `tag_date`. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
+The inline member limit defaults to 50 and accepts 1..200.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+For full or unknown-size member data, use `user-cluster-member export`; the list command has no next-page contract.
+
+```bash
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --limit 100
+ae-cli analysis user-cluster-member list --project-id <project_id> --cluster-name retained_users --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","country"]' --query US --limit 50
+```

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

@@ -0,0 +1,87 @@
+# User cluster definition models
+
+This is the canonical `--definition-request` contract for direct user-cluster create/update. Shared operators, properties, time ranges, and filters are defined in [`audience_models.md`](audience_models.md).
+
+Top-level variants:
+
+- condition: `{"type":"condition","conditions":{"relation":"and|or","items":[...]}}`
+- SQL: `{"type":"sql","sql":"...","params":[{"name":"partdate","type":"part_date","recent_day":"1-7"}]}`
+
+For SQL clusters, quote Trino special identifiers with double quotes, for example `{"type":"sql","sql":"SELECT \"#user_id\" FROM v_user_1 WHERE vip_level >= 3"}`. This applies to identifiers containing `#`, `$`, `@`, spaces, or punctuation; single quotes are string literals.
+
+If a SQL cluster reads an event table, include a predicate on the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without it. This does not apply to the user-table example above.
+
+SQL clusters support only `${PartDate:name}` dynamic placeholders. Each placeholder requires a matching `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. General SQL parameter types (`text`, `number`, `variable`, `time`, and `selector`) are rejected for SQL clusters.
+For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
+
+Discover tables with `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then inspect columns with the same `--usage tag_cluster`. This table set is server-authorized specifically for SQL tags/clusters and differs from the default analysis SQL set.
+
+Optional `include_filter` and `exclude_filter` use the shared filter-group shape.
+
+## Event node
+
+Required: `type=event`, `event`. Defaults: `operator=eq`, `value=1`, `aggregation=count`.
+
+```json
+{
+  "type":"event",
+  "event":"pay",
+  "operator":"gte",
+  "value":2,
+  "aggregation":"count",
+  "property":"amount",
+  "time_range":{"mode":"recent","unit":"day","value":7},
+  "filters":{"relation":"and","items":[{"field":"platform","operator":"eq","values":["ios"]}]}
+}
+```
+
+## User-property node
+
+Required: `type=user`, `field`, `operator`. `values`, `time_relative`, and `time_unit` are optional.
+
+```json
+{"type":"user","field":"vip_level","operator":"gte","values":[3]}
+```
+
+## Tag or cluster membership node
+
+Required: `type=tag|cluster`, `field`. `operator` defaults to `in_cluster`; optional fields are `values`, `cluster_date_policy`, and `specified_cluster_date`.
+
+```json
+{"type":"tag","field":"user_level","operator":"eq","values":["vip"]}
+{"type":"cluster","field":"payer_users","operator":"in_cluster"}
+```
+
+## Compound node
+
+`group` is another `{relation,items}` condition group.
+
+```json
+{"type":"compound","group":{"relation":"or","items":[{"type":"user","field":"country","operator":"eq","values":["US"]},{"type":"cluster","field":"payer_users","operator":"in_cluster"}]}}
+```
+
+## Behavior-sequence node
+
+Required: `type=behavior_sequence`, `completed`, `steps`. Each step requires `event`; optional step fields are `completed`, `filters`, `relative_to_first`, and `window`. The sequence also accepts `time_range` and `window`.
+
+```json
+{
+  "type":"behavior_sequence",
+  "completed":true,
+  "steps":[{"event":"view_item","completed":true},{"event":"pay","completed":true,"window":{"value":7,"unit":"day"}}],
+  "time_range":{"mode":"recent","unit":"day","value":30},
+  "window":{"value":7,"unit":"day"}
+}
+```
+
+## Complete condition request
+
+```json
+{
+  "type":"condition",
+  "conditions":{"relation":"and","items":[
+    {"type":"event","event":"pay","operator":"gte","value":2,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":7}},
+    {"type":"user","field":"country","operator":"eq","values":["US"]}
+  ]}
+}
+```

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

@@ -0,0 +1,13 @@
+# analysis user-cluster refresh
+
+Explicitly recompute an existing user cluster by exact `cluster_name` without changing its definition.
+
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-cluster create` or an update containing `--definition-request`; those commands already start computation automatically. Output means recomputation was submitted, not completed. Poll `user-cluster get` and verify the new computation before using `users_num` or querying members.
+
+The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
+
+Flags: `--project-id`, `--cluster-name` required.
+
+```bash
+ae-cli analysis user-cluster refresh --project-id <project_id> --cluster-name retained_users
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster update
+
+Update a condition or SQL user cluster. Discover the exact `cluster_name` first.
+
+Do not use it for ID-file membership replacement or to create a missing cluster. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-cluster refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A successful update means the definition was saved, not that the new result is complete. Poll `user-cluster get` until `progress=100` and `refresh_end_time` is not older than `update_time` before using `users_num` or querying members.
+
+The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
+
+Flags: `--project-id`, `--cluster-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`. The cluster type comes from `definition_request.type` when the definition changes.
+
+Read `user_cluster_models.md` before changing the definition. The backend validates and compiles `definition_request` inside update and refuses to modify the cluster if clarification is required. Condition definitions are saved as mixed-condition clusters.
+
+```bash
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --display-name "Retained Users v2"
+```

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

@@ -0,0 +1,15 @@
+# analysis user-cluster update-id
+
+Update a cluster by remapping imported values to its analysis entity.
+
+Do not use it for a condition/SQL cluster. The existing entity binding cannot be changed by this command.
+
+Flags: `--project-id`, `--cluster-name` required. Provide exactly one of local `--input-file`, reusable `--input-file-id`, or small-test `--file-content`. Optional: `--display-name`, `--remarks`, conditional `--association-property`.
+
+Use `analysis entity id-import-options` for the bound entity. CSV is headerless UTF-8 with exactly one non-empty column per row. Pass `--association-property` only for the primary user entity.
+
+```bash
+ae-cli analysis user-cluster update-id --project-id <project_id> --cluster-name vip_ids --input-file-id <input_file_id>
+```
+
+The response reports `operation_status=PROCESSING` and a pending match summary. Read the cluster again until processing completes to obtain final uploaded, matched, and unmatched counts.

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

@@ -0,0 +1,17 @@
+# analysis user-tag create
+
+Create a user tag directly from an AI-facing definition request.
+
+Do not use it for uploaded-ID tags; use `user-tag create-id`. A successful create automatically starts the initial computation; it does not mean the result is already complete. Do not call `user-tag refresh` afterward. Poll `user-tag get` until `progress=100` and `refresh_time` is present before using `users_num` or querying members.
+
+The response reports this directly: `computation.triggered_automatically=true`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow `next_action`; when it is `poll_get`, invoke `next_capability_id` with the exact `next_input` returned by the command.
+
+Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The tag type comes from `definition_request.type`.
+
+Read `user_tag_models.md` before constructing `--definition-request`. Create does not accept `--remark`; set it later with `user-tag update` when needed.
+
+The backend validates and compiles the definition inside the create operation; if metadata is ambiguous or missing, creation fails without creating the tag.
+
+```bash
+ae-cli analysis user-tag create --project-id <project_id> --tag-name high_value --display-name "High Value" --definition-request '{"type":"condition","condition_values":[{"value":"high","events":[{"event":"pay","operator":"gte","value":3,"aggregation":"count","time_range":{"mode":"recent","unit":"day","value":30}}]}]}'
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag create-id
+
+Create a tag by mapping imported values to an analysis entity.
+
+Flags: `--project-id`, `--display-name`, and `--entity-id` are required. Prefer `--input-file <local_csv>`; the CLI uploads it automatically. `--input-file-id` resumes from an existing upload, while `--file-content` is only for small local tests. Exactly one of the three is allowed. Optional: `--tag-name`, `--remarks`, and conditional `--association-property`.
+
+Use `--input-file` for real local files; use `--input-file-id` only when resuming from an existing upload. Do not inline large ID lists.
+
+Run `analysis entity id-import-options` first. For the primary user entity, column 1 is a real value of the selected `--association-property`; for a non-primary entity, it is that entity's own ID. Column 2 is `tag_value`. The headerless UTF-8 CSV must contain exactly two non-empty columns in every row.
+
+Create returns `operation_status=PROCESSING` and `match_summary_status=PENDING`; poll `user-tag get` until progress is 100 for the final `match_summary`.
+
+```bash
+ae-cli analysis user-tag create-id --project-id <project_id> --display-name "VIP Tag" --entity-id <entity_id> --association-property email --input-file /tmp/id-tag.csv --tag-name vip_tag
+```

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

@@ -0,0 +1,13 @@
+# analysis user-tag delete
+
+Delete a user tag after dependency/influence review.
+
+Do not use it to clear history snapshots or hide a tag. Output confirms deletion of the exact `tag_name`; verify it is absent from `user-tag list`.
+
+Flags: `--project-id`, `--tag-name` required. Add `--confirmed` and `--yes` only after the user accepts the dry-run impact.
+
+```bash
+ae-cli analysis user-tag delete --project-id <project_id> --tag-name old_tag --dry-run
+# Summarize the target and impact, then wait for explicit user confirmation.
+ae-cli analysis user-tag delete --project-id <project_id> --tag-name old_tag --confirmed --yes
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag get
+
+Get exact user tag details after discovery.
+
+Do not use it for fuzzy discovery, member data, or history statistics. Output contains saved tag metadata/definition for the requested names.
+
+After `user-tag create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a definition update, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+
+The raw backend value is returned under `result`. The response also provides aggregate and per-tag `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
+
+Flags: `--project-id`, `--tag-names` JSON array.
+
+```bash
+ae-cli analysis user-tag get --project-id <project_id> --tag-names '["user_level"]'
+```

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

@@ -0,0 +1,17 @@
+# analysis user-tag list
+
+List accessible user tags for discovery. Use this before get/update/delete/member/history-tag commands; do not invent `tag_name`.
+
+Flags: `--project-id` required. Optional: `--query`, `--fields`, `--limit`, `--offset`, `--authenticated-only`.
+
+`--offset` is only for stable asset browsing. It is not a tag-member pagination strategy.
+When `has_more=true`, continue only with the returned `next_offset`; do not calculate the next page locally.
+
+Output is a paged tag inventory whose identifier is `tag_name`, the same field consumed by get/update/delete/member/history-tag commands. It is not tag members, history snapshots, or definition-build results.
+
+Tags never accept `cluster_name`; that field belongs only to user clusters. Do not retry a tag command by substituting one identifier for the other.
+
+```bash
+ae-cli analysis user-tag list --project-id <project_id> --query level --limit 50
+ae-cli analysis user-tag list --project-id <project_id> --fields '["tag_name","display_name","users_num"]' --limit 50 --offset 0
+```

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

@@ -0,0 +1,15 @@
+# analysis user-tag-member export
+
+Export tag members as an async jsonl artifact. Read `analysis_data_retrieval.md` first.
+
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--artifact-format jsonl`, `--timeout-seconds`.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+Export does not accept `--offset`. Common streams backend pages until `has_more=false` and writes a final metadata line with the exported row count. Do not claim a fixed 10000-row cap and do not collect full data through repeated list calls.
+
+```bash
+ae-cli analysis user-tag-member export --project-id <project_id> --tag-name user_level --artifact-format jsonl
+ae-cli analysis run inspect --run-id <run_id>
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output tag-members.jsonl.gz
+```

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

@@ -0,0 +1,19 @@
+# analysis user-tag-member list
+
+Run a bounded inline tag member query. Read `analysis_data_retrieval.md` before choosing list vs export.
+
+Do not use it for complete/unknown-size membership retrieval or history statistics. Output contains at most the requested inline limit and has no caller pagination contract.
+
+Flags: `--project-id`, `--tag-name` required. Optional: `--snapshot-date`, `--property-names`, `--fields`, `--query`, `--use-cache`, `--request-id`, `--limit`, `--timeout-seconds`.
+
+When `--fields` is omitted, each member row returns `#user_id`, `#account_id`, `#distinct_id`, and the stable logical `tag_value`. Internal calculated tag column names are never part of the public response. The sync timeout defaults to 120 seconds and accepts an explicit value up to 180 seconds.
+The inline member limit defaults to 50 and accepts 1..200.
+
+If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you need to correlate logs or cancel a known running query.
+
+For full or unknown-size member data, use `user-tag-member export`; the list command has no next-page contract.
+
+```bash
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --limit 100
+ae-cli analysis user-tag-member list --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --property-names '["country"]' --fields '["#user_id","#account_id","#distinct_id","tag_value","country"]' --limit 50
+```