@thinkingai/ae-cli 6.1.17 → 6.1.19

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

@@ -1,24 +1,39 @@
-# analysis-meta asset-authentication update
+# analysis-governance asset-authentication update
 
-Use when the user needs to batch authenticate or unauthenticate assets.
+Use to authenticate or revoke an explicit set of typed project assets.
 
-Do not use it to edit the asset itself or to authenticate a guessed asset name; call `asset authentication-list` first and submit only returned asset identities.
+Do not use it with guessed identities or as a rule engine; derive an explicit typed set from `list` or `export` first.
 
-Command:
+Inline command:
 
 ```bash
-ae-cli analysis-meta asset-authentication update --project-id <project_id> --payload '{"authentication_status":1,"asset_list":[{"asset_name":"<name>","asset_type":"<type>"}]}'
-ae-cli analysis-meta asset-authentication update --dry-run
+ae-cli analysis-governance asset-authentication update --project-id <project_id> --authentication-status 1 --asset-refs '[{"resource_type":"dashboard","resource_key":"4350"}]'
 ```
 
-Capability id: `metadata.asset_authentication.update`.
+Large file command:
 
-Input sends `project_id`, `payload`.
+```bash
+ae-cli analysis-governance asset-authentication update --project-id <project_id> --authentication-status 1 --asset-file /tmp/selected-assets.jsonl --expected-snapshot-hash <snapshot_hash> --dry-run
+```
+
+Capability id: `governance.asset_authentication.update`.
+
+Choose exactly one identity input:
+
+- `--asset-refs` for an inline typed array.
+- `--asset-file` for JSONL rows containing `resource_type` and `resource_key`; extra export columns are ignored.
+- `--asset-type` with `--asset-ids` as a same-type convenience form.
+
+The CLI always normalizes the request to `asset_refs[]`. A bare `asset_ids[]` array is never sent to Common. When `expected_snapshot_hash` differs from the current authentication set, the complete update is rejected with `SNAPSHOT_CONFLICT`.
 
-Output is a successful gateway envelope with no business data. Verify with `asset authentication-list`.
+The response includes requested, resolved, changed, unchanged, and failed counts; retry only the returned failures.
+
+## analysis-meta asset-authentication update
+
+The legacy `--payload` entry remains available for one release cycle.
+
+```bash
+ae-cli analysis-meta asset-authentication update --project-id <project_id> --payload '{"authentication_status":1,"asset_list":[{"asset_name":"4350","asset_type":"dashboard"}]}'
+```
 
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | `{authentication_status, asset_list}`. `authentication_status` is `1` to authenticate or `0` to revoke; each `asset_list` item requires the real `asset_name` and `asset_type` returned by the list command. |
+Legacy Input is `project_id` plus `payload`. Legacy Output is the new structured batch result, although the input shape remains deprecated.

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

@@ -25,12 +25,30 @@ A property is either a name or a typed object:
 
 ## Time range
 
+Use semantic `mode`, `unit`, and `value` fields. Always pass `unit` with `recent` or `previous`; the supported units are `day`, `week`, `month`, `quarter`, and `year`.
+
+| User intent | `time_range` |
+|---|---|
+| Today | `{"mode":"recent","unit":"day","value":1}` |
+| This week | `{"mode":"recent","unit":"week","value":1}` |
+| This month | `{"mode":"recent","unit":"month","value":1}` |
+| This quarter | `{"mode":"recent","unit":"quarter","value":1}` |
+| This year | `{"mode":"recent","unit":"year","value":1}` |
+| Yesterday | `{"mode":"previous","unit":"day","value":1}` |
+| Previous month | `{"mode":"previous","unit":"month","value":1}` |
+| From a fixed date through today | `{"mode":"start_to_today","start_time":"2026-07-01"}` |
+| From a fixed date through yesterday | `{"mode":"start_to_yesterday","start_time":"2026-07-01"}` |
+
+Use `custom` only when both boundaries are fixed:
+
 ```json
 {"mode":"recent","unit":"day","value":7}
 {"mode":"previous","unit":"day","value":30}
 {"mode":"custom","start_time":"2026-07-01","end_time":"2026-07-07"}
 ```
 
+Do not pass backend `recent_day` encodings inside `time_range`; the capability compiles the semantic object to the existing analysis representation.
+
 ## Filter group
 
 Groups use `{relation,items}`. Each item has `field`, `operator`, and optional `values`:

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

@@ -39,11 +39,11 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis dashboard freeze` | analysis.dashboard.freeze | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-ids` (json; required) — Dashboard ID array.<br>`--freeze` (boolean; optional) — true to freeze, false to unfreeze. Default: true. | [dashboard_freeze.md](dashboard_freeze.md) |
 | `ae-cli analysis dashboard get` | analysis.dashboard.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID.<br>`--use-cache` (boolean; optional) — Whether to use cached dashboard detail. Default: true. | [dashboard_get.md](dashboard_get.md) |
 | `ae-cli analysis dashboard handover` | analysis.dashboard.handover | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-ids` (json; required) — Dashboard ID array.<br>`--to-user-id` (number; required) — Target user ID. | [dashboard_handover.md](dashboard_handover.md) |
-| `ae-cli analysis dashboard list` | analysis.dashboard.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional projection field array. Supported fields: dashboard_id, dashboard_name, remark.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [dashboard_list.md](dashboard_list.md) |
+| `ae-cli analysis dashboard list` | analysis.dashboard.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional projection field array. Supported fields: dashboard_id, dashboard_name, remark.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [dashboard_list.md](dashboard_list.md) |
 | `ae-cli analysis dashboard share` | analysis.dashboard.share | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID.<br>`--member-authorities` (json; optional) — Complete user authority map: {"<numeric_user_id>":"READ\|EDIT\|CREATOR\|MAINTAIN"}. An empty object removes all directly shared users.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_share.md](dashboard_share.md) |
 | `ae-cli analysis dashboard share-info` | analysis.dashboard.share_info | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_share_info.md](dashboard_share_info.md) |
 | `ae-cli analysis dashboard task-status` | analysis.dashboard.task_status | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_task_status.md](dashboard_task_status.md) |
-| `ae-cli analysis dashboard update` | analysis.dashboard.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--operation` (string; required) — Update operation: settings, note-upsert, or business-filter.<br>`--dashboard-id` (number; optional) — Dashboard ID for a single-dashboard update.<br>`--dashboard-ids` (json; optional) — Dashboard ID array for batch settings updates.<br>`--dashboard-name` (string; optional) — Dashboard name for single rename.<br>`--zone-offset` (number; optional) — Fixed dashboard time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5. Valid range: -12 to 14.<br>`--refresh-type` (number; optional, min=0, max=1) — Dashboard refresh type: 0 real-time, 1 scheduled.<br>`--dashboard-status` (string; optional) — Dashboard status: normal or freeze.<br>`--note-id` (number; optional) — Dashboard note ID. Omit to create a new note.<br>`--note-title` (string; optional) — Dashboard note title.<br>`--description` (string; optional) — Dashboard note description.<br>`--ui-config` (string; optional) — Dashboard or note UI config string.<br>`--filter` (json; optional) — Dashboard-level business filter in snake_case QP form. Required with --operation business-filter. Pass {"junction_kind":"and","ta_filters":[]} to clear it.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_update.md](dashboard_update.md) |
+| `ae-cli analysis dashboard update` | analysis.dashboard.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--operation` (string; required) — Update operation: settings, note-upsert, default-filter, or business-filter.<br>`--dashboard-id` (number; optional) — Dashboard ID for a single-dashboard update.<br>`--dashboard-ids` (json; optional) — Dashboard ID array for batch settings updates.<br>`--dashboard-name` (string; optional) — Dashboard name for single rename.<br>`--zone-offset` (number; optional) — Fixed dashboard time zone offset in hours. For example, UTC+8 is 8 and UTC-5 is -5. Valid range: -12 to 14.<br>`--refresh-type` (number; optional, min=0, max=1) — Dashboard refresh type: 0 real-time, 1 scheduled.<br>`--dashboard-status` (string; optional) — Dashboard status: normal or freeze.<br>`--note-id` (number; optional) — Dashboard note ID. Omit to create a new note.<br>`--note-title` (string; optional) — Dashboard note title.<br>`--description` (string; optional) — Dashboard note description.<br>`--ui-config` (string; optional) — Dashboard or note UI config string.<br>`--filter-name` (string; optional) — Saved filter name. Required with --operation default-filter.<br>`--filter` (json; optional) — Saved filter in snake_case QP form. Required with --operation default-filter or business-filter. Pass {"junction_kind":"and","ta_filters":[]} to clear a business filter.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_update.md](dashboard_update.md) |
 | `ae-cli analysis dashboard-daily-report get` | analysis.dashboard_daily_report.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID. | [dashboard_daily_report_get.md](dashboard_daily_report_get.md) |
 | `ae-cli analysis dashboard-daily-report send` | analysis.dashboard_daily_report.send | write | `--project-id` (number; required) — Numeric project ID.<br>`--dashboard-id` (number; required) — Dashboard ID.<br>`--need-csv` (boolean; optional) — Whether to include CSV attachment.<br>`--host-url` (string; optional) — Public host URL used in report links.<br>`--send-title` (string; optional) — Daily report title.<br>`--send-content` (string; optional) — Daily report content.<br>`--lang` (string; optional) — Report language.<br>`--screen-type` (string; optional) — Screenshot screen type.<br>`--zone-offset` (number; optional) — Time zone offset.<br>`--email-login-users` (string; optional) — Comma-separated login users for email.<br>`--email-new` (string; optional) — Comma-separated direct email addresses. The server selects company SMTP or the default mail service.<br>`--dd-url` (json; optional) — DingTalk webhook URL array, e.g. ["https://..."].<br>`--wx-url` (json; optional) — WeCom webhook URL array, e.g. ["https://..."].<br>`--feishu-info` (json; optional) — Feishu image upload and bot config, e.g. {"app_id":"cli_xxx","app_secret":"secret_xxx","webhook":["https://..."]}.<br>`--kim-url` (json; optional) — KIM/custom webhook URL array, e.g. ["https://..."].<br>`--slack-url` (json; optional) — Slack webhook URL array, e.g. ["https://..."].<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [dashboard_daily_report_send.md](dashboard_daily_report_send.md) |
 | `ae-cli analysis dashboard-daily-report send-status` | analysis.dashboard_daily_report.send_status | read | `--project-id` (number; required) — Numeric project ID.<br>`--task-id` (number; required) — Task ID returned by dashboard-daily-report send. | [dashboard_daily_report_send_status.md](dashboard_daily_report_send_status.md) |
@@ -93,8 +93,8 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis report create` | analysis.report.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--report-name` (string; required) — Report display name.<br>`--model-type` (string; required) — Supported AI-facing model_type values, 12 total. 9 common models: event (event analysis), retention (retention analysis), funnel (funnel conversion), distribution (distribution analysis), attribution (attribution analysis), interval (interval analysis), path (path analysis), prop_analysis (property analysis), sql (SQL analysis). 3 scenario models: heat_map (heat map analysis), rank_list (ranking analysis), revenue (revenue analysis). Tags and cohorts/clusters are separate capabilities and are not ad-hoc model_type values. Report create/update also supports tag for saved tag report data; use tag as the AI-facing spelling.<br>`--definition` (json; required) — AI-facing model definition JSON. Do not pass raw QP, events, event_view, visual_view, or analysis_query. Distribution filters must be attached to the corresponding distribution_metrics[].filters; do not use top-level filters or relation. For path definitions, global filters support user_property, cluster, and tag only; event_property is not supported. session_unit accepts second (1..999), minute (1..999), or hour (1..24). Do not use day; express one day as session_interval=24 and session_unit=hour. For SQL, a simple query is {"sql":"select ..."}; raw variables use ${name}, while typed params use ${Text:name}, ${Selector:name}, or ${PartDate:name}. PartDate expands to a complete predicate, so write WHERE ${PartDate:d}, not a column followed by the placeholder. A part_date parameter may set boolean use_timezone; it defaults to false and controls whether that parameter uses the query effective timezone. Selector value must match one options[].value. Trino identifiers containing #, $, @, spaces, punctuation, or a reserved word must be delimited with double quotes, for example SELECT "#user_id", "$part_event", "end" FROM ...; single quotes are string literals. For multiline SQL JSON, the decoded sql value must contain a real line break; do not submit a literal \n sequence outside quoted SQL text. Queries against an event table must include a date-partition predicate on the quoted "$part_date" column, for example WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'; the backend rejects event-table SQL without it. The CLI preserves SQL text and never auto-quotes identifiers. For model_type=tag, pass a tag report intent such as {"tag":{"tag_name":"vip_users","time_range":{"mode":"recent","unit":"day","value":7}}}. Tags are supported for report create/update and report data, not ad-hoc analysis.<br>`--resolutions` (json; optional) — Optional user-confirmed metadata bindings keyed by compiler error path. Each value requires raw_value, resource_type, and resource_key. Reuse the unchanged definition and only pass values explicitly confirmed by the user. This option is not supported with --model-type tag.<br>`--report-desc` (string; optional) — Optional report description.<br>`--cache-seconds` (number; optional) — Optional cache duration in seconds.<br>`--query-duration-ms` (number; optional) — Optional last query duration in milliseconds.<br>`--dashboard-ids` (json; optional) — Optional dashboard ID array to associate after creation. | [report_create.md](report_create.md) |
 | `ae-cli analysis report delete` | analysis.report.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--report-ids` (json; required) — Report ID array. | [report_delete.md](report_delete.md) |
 | `ae-cli analysis report get` | analysis.report.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--report-id` (number; required) — Report ID. | [report_get.md](report_get.md) |
-| `ae-cli analysis report list` | analysis.report.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--model-types` (json; optional) — Optional semantic report model JSON array, for example ["event","sql","tag","revenue"].<br>`--limit` (number; optional, min=1, max=200) — Report page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [report_list.md](report_list.md) |
-| `ae-cli analysis report list-export` | analysis.report.list_export | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--model-types` (json; optional) — Optional semantic report model JSON array, for example ["event","sql","tag","revenue"].<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--artifact-format` (string; optional) — Logical artifact format, usually jsonl or csv. This does not select compression; read format, compression, file_name, content_type, and content_encoding from the returned descriptor.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>.<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [report_list_export.md](report_list_export.md) |
+| `ae-cli analysis report list` | analysis.report.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--model-types` (json; optional) — Optional semantic report model JSON array, for example ["event","sql","tag","revenue"].<br>`--limit` (number; optional, min=1, max=200) — Report page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [report_list.md](report_list.md) |
+| `ae-cli analysis report list-export` | analysis.report.list_export | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--model-types` (json; optional) — Optional semantic report model JSON array, for example ["event","sql","tag","revenue"].<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--artifact-format` (string; optional) — Logical artifact format, usually jsonl or csv. This does not select compression; read format, compression, file_name, content_type, and content_encoding from the returned descriptor.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset.<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [report_list_export.md](report_list_export.md) |
 | `ae-cli analysis report update` | analysis.report.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--report-id` (number; required) — Report ID to update.<br>`--report-version` (number; required) — Current report version from report get.<br>`--report-name` (string; optional) — New report display name.<br>`--report-desc` (string; optional) — New report description.<br>`--model-type` (string; optional) — Supported AI-facing model_type values, 12 total. 9 common models: event (event analysis), retention (retention analysis), funnel (funnel conversion), distribution (distribution analysis), attribution (attribution analysis), interval (interval analysis), path (path analysis), prop_analysis (property analysis), sql (SQL analysis). 3 scenario models: heat_map (heat map analysis), rank_list (ranking analysis), revenue (revenue analysis). Tags and cohorts/clusters are separate capabilities and are not ad-hoc model_type values. Report create/update also supports tag for saved tag report data; use tag as the AI-facing spelling.<br>`--definition` (json; optional) — AI-facing model definition JSON. Do not pass raw QP, events, event_view, visual_view, or analysis_query. Distribution filters must be attached to the corresponding distribution_metrics[].filters; do not use top-level filters or relation. For path definitions, global filters support user_property, cluster, and tag only; event_property is not supported. session_unit accepts second (1..999), minute (1..999), or hour (1..24). Do not use day; express one day as session_interval=24 and session_unit=hour. For SQL, a simple query is {"sql":"select ..."}; raw variables use ${name}, while typed params use ${Text:name}, ${Selector:name}, or ${PartDate:name}. PartDate expands to a complete predicate, so write WHERE ${PartDate:d}, not a column followed by the placeholder. A part_date parameter may set boolean use_timezone; it defaults to false and controls whether that parameter uses the query effective timezone. Selector value must match one options[].value. Trino identifiers containing #, $, @, spaces, punctuation, or a reserved word must be delimited with double quotes, for example SELECT "#user_id", "$part_event", "end" FROM ...; single quotes are string literals. For multiline SQL JSON, the decoded sql value must contain a real line break; do not submit a literal \n sequence outside quoted SQL text. Queries against an event table must include a date-partition predicate on the quoted "$part_date" column, for example WHERE "$part_date" BETWEEN '2026-07-01' AND '2026-07-07'; the backend rejects event-table SQL without it. The CLI preserves SQL text and never auto-quotes identifiers. For model_type=tag, pass a tag report intent such as {"tag":{"tag_name":"vip_users","time_range":{"mode":"recent","unit":"day","value":7}}}. Tags are supported for report create/update and report data, not ad-hoc analysis.<br>`--resolutions` (json; optional) — Optional user-confirmed metadata bindings keyed by compiler error path. Each value requires raw_value, resource_type, and resource_key. Reuse the unchanged definition and only pass values explicitly confirmed by the user. This option is not supported with --model-type tag.<br>`--cache-seconds` (number; optional) — Optional cache duration in seconds.<br>`--query-duration-ms` (number; optional) — Optional last query duration in milliseconds. | [report_update.md](report_update.md) |
 | `ae-cli analysis report-abnormal get` | analysis.report_abnormal.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--report-id` (number; required) — Report ID. | [report_abnormal_get.md](report_abnormal_get.md) |
 | `ae-cli analysis report-change-log get` | analysis.report_change_log.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--report-id` (number; required) — Report ID.<br>`--history-version` (number; optional) — Optional history version. Omit for latest. | [report_change_log_get.md](report_change_log_get.md) |
@@ -113,7 +113,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis user-cluster get` | analysis.user_cluster.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--cluster-names` (json; required) — JSON array of exact cluster_name values. | [user_cluster_get.md](user_cluster_get.md) |
 | `ae-cli analysis user-cluster list` | analysis.user_cluster.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity. | [user_cluster_list.md](user_cluster_list.md) |
 | `ae-cli analysis user-cluster refresh` | analysis.user_cluster.refresh | write | `--project-id` (number; required) — Numeric project ID.<br>`--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first. | [user_cluster_refresh.md](user_cluster_refresh.md) |
-| `ae-cli analysis user-cluster update` | analysis.user_cluster.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first.<br>`--display-name` (string; optional, minLength=1, maxLength=80) — Optional new display name. Maximum: 80 characters.<br>`--definition-request` (json; optional) — Optional semantic snake_case cluster definition. Read user_cluster_models.md; raw filts, C-codes, ftv, columnName, and backend DTOs are rejected.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity.<br>`--remark` (string; optional, maxLength=400) — Optional new remark. Maximum: 400 characters.<br>`--zone-offset` (number; optional) — Optional timezone offset. UTC+8 is 8; UTC-5 is -5.<br>`--auto-refresh-cron` (string; optional) — Optional Quartz cron expression for an existing enabled auto-refresh schedule. This does not enable auto refresh. | [user_cluster_update.md](user_cluster_update.md) |
+| `ae-cli analysis user-cluster update` | analysis.user_cluster.update | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first.<br>`--display-name` (string; optional, minLength=1, maxLength=80) — Optional new display name. Maximum: 80 characters.<br>`--definition-request` (json; optional) — Optional semantic snake_case cluster definition. Its type must match the existing cluster type; update cannot change the analysis entity. Read user_cluster_models.md; raw filts, C-codes, ftv, columnName, and backend DTOs are rejected.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity.<br>`--remark` (string; optional, maxLength=400) — Optional new remark. Maximum: 400 characters.<br>`--zone-offset` (number; optional) — Optional timezone offset. UTC+8 is 8; UTC-5 is -5.<br>`--auto-refresh-cron` (string; optional) — Optional Quartz cron expression for an existing enabled auto-refresh schedule. This does not enable auto refresh. | [user_cluster_update.md](user_cluster_update.md) |
 | `ae-cli analysis user-cluster update-id` | analysis.user_cluster.update_id | write | `--project-id` (number; required) — Numeric project ID.<br>`--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first.<br>`--display-name` (string; optional, minLength=1, maxLength=80) — Optional new display name. Maximum: 80 characters.<br>`--input-file` (string; optional) — Local CSV path. The CLI uploads it with purpose analysis.user.id_import before executing the create/update capability.<br>`--input-file-id` (string; optional) — Reuse a file already uploaded for purpose analysis.user.id_import.<br>`--file-content` (string; optional) — Headerless UTF-8 CSV. No header row. Exactly one non-empty column per row: association-property value for the primary user entity, otherwise the entity ID.<br>`--remarks` (string; optional, maxLength=400) — Optional remarks. Maximum: 400 characters.<br>`--association-property` (string; optional) — Required only for the primary user entity. The first CSV column is matched against this allowed user property; #user_id is forbidden. Omit for non-primary entities. | [user_cluster_update_id.md](user_cluster_update_id.md) |
 | `ae-cli analysis user-cluster-member export` | analysis.user_cluster_member.export | read | `--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first.<br>`--project-id` (number; required) — Numeric project ID.<br>`--property-names` (json; optional) — Optional JSON array of user property names to include.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--artifact-format` (string; optional) — Artifact format: jsonl or csv. Default: jsonl. Both formats use native full-download streaming and gzip compression.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>.<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [user_cluster_member_export.md](user_cluster_member_export.md) |
 | `ae-cli analysis user-cluster-member list` | analysis.user_cluster_member.list | read | `--cluster-name` (string; required) — Exact cluster_name. Discover real values with analysis user-cluster list first.<br>`--project-id` (number; required) — Numeric project ID.<br>`--property-names` (json; optional) — Optional JSON array of user property names to include.<br>`--fields` (json; optional) — Optional result fields. Defaults to #user_id, #account_id, and #distinct_id.<br>`--query` (string; optional) — Optional keyword filter.<br>`--use-cache` (boolean; optional) — Whether to use query cache. Default: true.<br>`--preview-rows` (number; optional, min=1, max=100000) — Maximum business rows returned per result. Default: 1000, matching the UI member query. Maximum: 100000.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--timeout-seconds` (number; optional, min=1, max=180) — Sync timeout seconds. Default: 120, max: 180. | [user_cluster_member_list.md](user_cluster_member_list.md) |
@@ -137,6 +137,9 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-governance asset batch-sql-export` | governance.asset.batch_export_sql | read | `--project-id` (number; required) — Numeric project ID.<br>`--node-ids` (json; optional) — Asset node ID JSON array.<br>`--reports-version` (number; optional) — Dashboard reports version.<br>`--zone-offset` (number; optional) — Dashboard zone offset.<br>`--schedule-ui-config` (json; optional) — Dashboard schedule UI config JSON.<br>`--dashboard-status` (string; optional) — Dashboard status.<br>`--refresh-type` (number; optional) — Dashboard refresh type: 1 enabled, 0 disabled.<br>`--cache-config` (json; optional) — Dashboard cache config JSON.<br>`--clear-history-tag` (number; optional) — Whether to clear tag history: 1 yes, 0 no.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_batch_sql_export.md](asset_batch_sql_export.md) |
 | `ae-cli analysis-governance asset export` | governance.asset.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--query` (string; optional) — Optional keyword filter.<br>`--searchs` (json; optional) — Quick filter JSON array.<br>`--rule` (json; optional) — Governance Filter JSON object.<br>`--operation-type` (string; optional) — Batch operation type.<br>`--limit` (number; optional) — Optional inline result limit.<br>`--offset` (number; optional) — Optional zero-based result offset.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_export.md](asset_export.md) |
 | `ae-cli analysis-governance asset list` | governance.asset.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--query` (string; optional) — Optional keyword filter.<br>`--searchs` (json; optional) — Quick filter JSON array.<br>`--rule` (json; optional) — Governance Filter JSON object.<br>`--operation-type` (string; optional) — Batch operation type.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_list.md](asset_list.md) |
+| `ae-cli analysis-governance asset-authentication export` | governance.asset_authentication.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--asset-types` (json; optional) — Optional JSON array of asset types. Omit for every supported type.<br>`--authentication-status` (number; optional, min=0, max=1) — Authentication status: 1 for authenticated or 0 for unauthenticated.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keywords matched against identity and display fields.<br>`--heat-count-gt` (number; optional, min=0) — Strict recent-90-day heat threshold.<br>`--user-count-gt` (number; optional, min=0) — Strict recent-90-day user threshold.<br>`--impact-degree-gt` (number; optional, min=0) — Strict governance impact threshold.<br>`--match` (string; optional, default="all") — Combine multiple numeric thresholds with any or all. Default: all.<br>`--fields` (json; optional) — Optional JSON array of output fields.<br>`--output` (string; required) — Local .jsonl output path. Integrity metadata is written to <output>.meta.json. | [asset_authentication_export.md](asset_authentication_export.md) |
+| `ae-cli analysis-governance asset-authentication list` | governance.asset_authentication.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--asset-types` (json; optional) — Optional JSON array of asset types. Omit for every supported type.<br>`--authentication-status` (number; optional, min=0, max=1) — Authentication status: 1 for authenticated or 0 for unauthenticated.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keywords matched against identity and display fields.<br>`--heat-count-gt` (number; optional, min=0) — Strict recent-90-day heat threshold.<br>`--user-count-gt` (number; optional, min=0) — Strict recent-90-day user threshold.<br>`--impact-degree-gt` (number; optional, min=0) — Strict governance impact threshold.<br>`--match` (string; optional, default="all") — Combine multiple numeric thresholds with any or all. Default: all.<br>`--fields` (json; optional) — Optional JSON array of output fields.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [asset_authentication_list.md](asset_authentication_list.md) |
+| `ae-cli analysis-governance asset-authentication update` | governance.asset_authentication.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--authentication-status` (number; required, min=0, max=1) — Target authentication status: 1 authenticates and 0 revokes.<br>`--asset-refs` (json; optional) — Inline JSON array of {resource_type,resource_key} asset references.<br>`--asset-file` (string; optional) — JSONL file whose rows contain resource_type and resource_key.<br>`--asset-type` (string; optional) — Convenience asset type used together with --asset-ids.<br>`--asset-ids` (json; optional) — Convenience JSON array of business keys used together with --asset-type.<br>`--expected-snapshot-hash` (string; optional) — Optional snapshot_hash from the export sidecar. A mismatch rejects the whole update.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | [asset_authentication_update.md](asset_authentication_update.md) |
 | `ae-cli analysis-governance asset-dependency list` | governance.asset_dependency.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--node-id` (string; optional) — Poseidon asset node ID.<br>`--query` (string; optional) — Optional keyword filter.<br>`--searchs` (json; optional) — Quick filter JSON array.<br>`--rule` (json; optional) — Governance Filter JSON object.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_dependency_list.md](asset_dependency_list.md) |
 | `ae-cli analysis-governance asset-impact list` | governance.asset_impact.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--node-id` (string; optional) — Poseidon asset node ID.<br>`--query` (string; optional) — Optional keyword filter.<br>`--searchs` (json; optional) — Quick filter JSON array.<br>`--rule` (json; optional) — Governance Filter JSON object.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_impact_list.md](asset_impact_list.md) |
 | `ae-cli analysis-governance asset-lineage get` | governance.asset_lineage.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--node-id` (string; optional) — Poseidon asset node ID.<br>`--payload` (json; optional) — Optional snake_case object for complex capability payload fields. | [asset_lineage_get.md](asset_lineage_get.md) |
@@ -155,8 +158,8 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-meta asset-abnormal list` | metadata.asset_abnormal.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--resource-types` (string; required) — Resource types to query.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [asset_abnormal_list.md](asset_abnormal_list.md) |
 | `ae-cli analysis-meta asset-authentication list` | metadata.asset_authentication.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected. | [asset_authentication_list.md](asset_authentication_list.md) |
 | `ae-cli analysis-meta asset-authentication update` | metadata.asset_authentication.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [asset_authentication_update.md](asset_authentication_update.md) |
-| `ae-cli analysis-meta catalog export` | metadata.catalog.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>.<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [catalog_export.md](catalog_export.md) |
-| `ae-cli analysis-meta catalog list` | metadata.catalog.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--resource-types` (json; optional) — Online search resource type filter JSON array. Use event, metric, event_property, user_property, cluster, or tag.<br>`--limit-per-type` (number; optional, min=1, max=200) — Maximum online search results per resource type. Default: 20, max: 200. | [catalog_list.md](catalog_list.md) |
+| `ae-cli analysis-meta catalog export` | metadata.catalog.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--request-id` (string; optional) — Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset.<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [catalog_export.md](catalog_export.md) |
+| `ae-cli analysis-meta catalog list` | metadata.catalog.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--resource-types` (json; optional) — Online search resource type filter JSON array. Use event, metric, event_property, user_property, cluster, or tag.<br>`--limit-per-type` (number; optional, min=1, max=200) — Maximum online search results per resource type. Default: 20, max: 200.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [catalog_list.md](catalog_list.md) |
 | `ae-cli analysis-meta datatable columns-get` | metadata.data_table.columns_get | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-ref` (string; required) — Project table reference. | [datatable_columns_get.md](datatable_columns_get.md) |
 | `ae-cli analysis-meta datatable influence-list` | metadata.data_table.influence_list | read | `--project-id` (number; required) — Numeric project ID.<br>`--datatable-id` (number; required) — Data table ID. | [datatable_influence_list.md](datatable_influence_list.md) |
 | `ae-cli analysis-meta datatable version-get` | metadata.data_table_version.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--version-id` (number; required) — Data table version ID. | [datatable_version_get.md](datatable_version_get.md) |
@@ -168,7 +171,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-meta event get` | metadata.event.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--event-name` (string; required) — Event name. | [event_get.md](event_get.md) |
 | `ae-cli analysis-meta event hide-update` | metadata.event.hide_update | write | `--project-id` (number; required) — Numeric project ID.<br>`--event-names` (json; required) — Event names JSON array, or a JSON string accepted by common-service.<br>`--is-hide` (boolean; required) — Whether to hide the events. | [event_hide_update.md](event_hide_update.md) |
 | `ae-cli analysis-meta event influence-list` | metadata.event.influence_list | read | `--project-id` (number; required) — Numeric project ID.<br>`--event-name` (string; required) — Event name. | [event_influence_list.md](event_influence_list.md) |
-| `ae-cli analysis-meta event list` | metadata.event.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated events. | [event_list.md](event_list.md) |
+| `ae-cli analysis-meta event list` | metadata.event.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated events.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [event_list.md](event_list.md) |
 | `ae-cli analysis-meta event relation-update` | metadata.event.relation_update | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [event_relation_update.md](event_relation_update.md) |
 | `ae-cli analysis-meta event update` | metadata.event.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--event-name` (string; required) — Event name.<br>`--event-desc` (string; optional) — Event display name.<br>`--remark` (string; optional) — Event remark. | [event_update.md](event_update.md) |
 | `ae-cli analysis-meta event-property-bundle export` | metadata.event_property_bundle.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--request-id` (string; optional) — Optional cli_<32 lowercase hex> request ID. Generated when omitted.<br>`--timeout-seconds` (number; optional, min=1, max=21600) — Export timeout seconds. Default and max: 21600 (6 hours).<br>`--wait` (boolean; optional) — Wait for the remote run and artifact to reach a terminal state. Polling uses short inspect requests; interrupting does not cancel the remote run.<br>`--wait-timeout-seconds` (number; optional, min=1, max=21600) — Maximum time this CLI process waits. Default: 600 seconds; expiry never cancels the remote run.<br>`--output` (string; optional) — Wait, then stream the completed artifact to this local file. Implies --wait.<br>`--force` (boolean; optional) — Allow --output to atomically replace an existing file. Without this flag, existing paths are refused. | [event_property_bundle_export.md](event_property_bundle_export.md) |
@@ -182,7 +185,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-meta metric delete` | metadata.metric.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--metric-id` (number; required) — Metric ID. | [metric_delete.md](metric_delete.md) |
 | `ae-cli analysis-meta metric export` | metadata.metric.export | read | `--project-id` (number; required) — Numeric project ID.<br>`--ignore-authentication` (boolean; optional) — Whether to skip asset authentication status decoration.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--authenticated-only` (boolean; optional) — When true, export only authenticated metrics.<br>`--output` (string; required) — Local .json output file for the complete matching metadata rows. | [metric_export.md](metric_export.md) |
 | `ae-cli analysis-meta metric get` | metadata.metric.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--metric-id` (number; required) — Metric ID. | [metric_get.md](metric_get.md) |
-| `ae-cli analysis-meta metric list` | metadata.metric.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--ignore-authentication` (boolean; optional) — Whether to skip asset authentication status decoration.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated metrics. | [metric_list.md](metric_list.md) |
+| `ae-cli analysis-meta metric list` | metadata.metric.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--ignore-authentication` (boolean; optional) — Whether to skip asset authentication status decoration.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated metrics.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [metric_list.md](metric_list.md) |
 | `ae-cli analysis-meta metric update` | metadata.metric.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--metric-id` (number; required) — Metric ID.<br>`--metric-name` (string; optional) — Metric technical name for full-definition update.<br>`--metric-desc` (string; optional) — Metric display name.<br>`--metric-remark` (string; optional) — Metric remark.<br>`--metric-mode` (number; optional) — Metric model mode for full-definition update.<br>`--model-type` (string; optional) — Semantic metric model type: event or retention. Prefer this over metric-mode.<br>`--metric-events` (json; optional) — Metric event-analysis QP JSON array for full-definition update.<br>`--metric-params` (json; optional) — Metric params JSON object. | [metric_update.md](metric_update.md) |
 | `ae-cli analysis-meta property changelog-list` | metadata.property.changelog_list | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--prop-name` (string; required) — Property column name. | [property_changelog_list.md](property_changelog_list.md) |
 | `ae-cli analysis-meta property create` | metadata.property.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [property_create.md](property_create.md) |
@@ -191,7 +194,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-meta property get` | metadata.property.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--prop-name` (string; required) — Property column name. | [property_get.md](property_get.md) |
 | `ae-cli analysis-meta property hide-update` | metadata.property.hide_update | write | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--prop-names` (json; required) — Property names JSON array, or a JSON string accepted by common-service.<br>`--is-hide` (boolean; required) — Whether to hide the properties. | [property_hide_update.md](property_hide_update.md) |
 | `ae-cli analysis-meta property influence-list` | metadata.property.influence_list | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--prop-name` (string; required) — Property column name. | [property_influence_list.md](property_influence_list.md) |
-| `ae-cli analysis-meta property list` | metadata.property.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; optional) — Optional property table type: event or user.<br>`--scope` (string; optional) — Optional property scope: event or user.<br>`--event-name` (string; optional) — Optional event name filter for event properties.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated properties. | [property_list.md](property_list.md) |
+| `ae-cli analysis-meta property list` | metadata.property.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; optional) — Optional property table type: event or user.<br>`--scope` (string; optional) — Optional property scope: event or user.<br>`--event-name` (string; optional) — Optional event name filter for event properties.<br>`--queries` (json; optional) — Optional JSON array of 1 to 20 keyword filters. Results match any keyword.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--limit` (number; optional, min=1, max=200) — Directory page size. Default: 50, max: 200. Values outside 1..200 are rejected.<br>`--offset` (number; optional, min=0) — Zero-based directory page offset. Default: 0. Negative values are rejected.<br>`--authenticated-only` (boolean; optional) — When true, return only authenticated properties.<br>`--certification-scope` (string; optional, default="project") — Asset certification filter scope: project follows the project switch, certified returns only certified assets, all returns every asset. | [property_list.md](property_list.md) |
 | `ae-cli analysis-meta property related-events` | metadata.property.related_events | read | `--project-id` (number; required) — Numeric project ID.<br>`--prop-name` (string; required) — Event property column name. | [property_related_events.md](property_related_events.md) |
 | `ae-cli analysis-meta property relation-update` | metadata.property.relation_update | write | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [property_relation_update.md](property_relation_update.md) |
 | `ae-cli analysis-meta property update` | metadata.property.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--table-type` (string; required) — Property table type.<br>`--prop-name` (string; required) — Property column name.<br>`--prop-desc` (string; optional) — Property display name.<br>`--prop-remark` (string; optional) — Property remark. | [property_update.md](property_update.md) |
@@ -203,6 +206,11 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis-meta virtual-property create` | metadata.virtual_property.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--sql-expression` (string; required) — SQL expression used to calculate the virtual property.<br>`--v-prop` (json; optional) — Virtual property JSON object with property.column_name/property.table_type/property.select_type fields.<br>`--property-name` (string; optional) — Virtual property name. Must start with '#vp@'.<br>`--property-desc` (string; optional) — Virtual property display name.<br>`--table-type` (string; optional) — Property table type: event or user.<br>`--select-type` (string; optional) — Property value type: string, number, bool, or datetime.<br>`--property-remark` (string; optional) — Optional virtual property remark.<br>`--properties` (json; optional) — Dependent property JSON array.<br>`--sql-event-relation-type` (string; optional) — relation_default, relation_always, or relation_by_setting.<br>`--related-events` (json; optional) — Related events JSON array when using relation_by_setting.<br>`--tag-date-policies` (json; optional) — Optional tag date policies JSON array.<br>`--replace-remark` (string; optional) — Replacement remark.<br>`--replace-suggestion` (string; optional) — Replacement suggestion. | [virtual_property_create.md](virtual_property_create.md) |
 | `ae-cli analysis-meta virtual-property sql-rule-delete` | metadata.virtual_property.sql_rule_delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--v-prop-id` (number; required) — Virtual property ID.<br>`--operation` (string; optional) — Delete operation. Use revoke to revoke instead of delete. | [virtual_property_sql_rule_delete.md](virtual_property_sql_rule_delete.md) |
 | `ae-cli analysis-meta virtual-property sql-rule-update` | metadata.virtual_property.sql_rule_update | write | `--project-id` (number; required) — Numeric project ID.<br>`--sql-expression` (string; required) — SQL expression used to calculate the virtual property.<br>`--v-prop` (json; required) — Virtual property JSON object with prop_id beside property.<br>`--properties` (json; optional) — Dependent property JSON array.<br>`--sql-event-relation-type` (string; optional) — relation_default, relation_always, or relation_by_setting.<br>`--related-events` (json; optional) — Related events JSON array when using relation_by_setting.<br>`--tag-date-policies` (json; optional) — Optional tag date policies JSON array.<br>`--replace-remark` (string; optional) — Replacement remark.<br>`--replace-suggestion` (string; optional) — Replacement suggestion. | [virtual_property_sql_rule_update.md](virtual_property_sql_rule_update.md) |
+| `ae-cli personal-semantic-preference add` | business_semantics.personal_context.add | write | `--project-id` (number; required, min=1) — Numeric project ID.<br>`--context-type` (string; required) — preference \| asset_context \| experience \| background.<br>`--title` (string; required, maxLength=255) — Short preference title.<br>`--summary` (string; required, maxLength=1000) — Compact preference summary.<br>`--content` (string; required, maxLength=20000) — Full personal semantic preference content.<br>`--keywords` (json; optional) — Optional JSON array of preference keywords.<br>`--resource-refs` (json; optional) — Ordered JSON asset references; required only for asset_context.<br>`--fresh-until-at` (string; optional) — Optional freshness expiration timestamp: yyyy-MM-dd HH:mm:ss.<br>`--request-id` (string; optional, maxLength=128) — Optional idempotency key; generated when omitted. | [personal_semantic_preference_add.md](personal_semantic_preference_add.md) |
+| `ae-cli personal-semantic-preference delete` | business_semantics.personal_context.delete | high-risk-write | `--project-id` (number; required, min=1) — Numeric project ID.<br>`--id` (string; required) — Preference ID returned by list/add.<br>`--expected-revision` (number; required, min=1) — Revision returned by the latest read.<br>`--request-id` (string; optional, maxLength=128) — Optional idempotency key; generated when omitted. | [personal_semantic_preference_delete.md](personal_semantic_preference_delete.md) |
+| `ae-cli personal-semantic-preference get` | business_semantics.personal_context.get | read | `--project-id` (number; required, min=1) — Numeric project ID.<br>`--id` (string; required) — Preference ID returned by list/add.<br>`--mark-used` (boolean; optional) — Count this preference as adopted and update its usage heat. | [personal_semantic_preference_get.md](personal_semantic_preference_get.md) |
+| `ae-cli personal-semantic-preference list` | business_semantics.personal_context.list | read | `--project-id` (number; required, min=1) — Numeric project ID. | [personal_semantic_preference_list.md](personal_semantic_preference_list.md) |
+| `ae-cli personal-semantic-preference update` | business_semantics.personal_context.update | write | `--project-id` (number; required, min=1) — Numeric project ID.<br>`--id` (string; required) — Preference ID returned by list/add.<br>`--expected-revision` (number; required, min=1) — Revision returned by the latest read.<br>`--context-type` (string; required) — preference \| asset_context \| experience \| background.<br>`--title` (string; required, maxLength=255) — Short preference title.<br>`--summary` (string; required, maxLength=1000) — Compact preference summary.<br>`--content` (string; required, maxLength=20000) — Full replacement content.<br>`--keywords` (json; optional) — Optional JSON array of preference keywords.<br>`--resource-refs` (json; optional) — Ordered JSON asset references; required only for asset_context.<br>`--fresh-until-at` (string; optional) — Optional freshness expiration timestamp: yyyy-MM-dd HH:mm:ss.<br>`--request-id` (string; optional, maxLength=128) — Optional idempotency key; generated when omitted. | [personal_semantic_preference_update.md](personal_semantic_preference_update.md) |
 | `ae-cli project access-detail get` | project.access_detail.get | read | `--company-id` (number; required) — Company ID. | [project_access_detail_get.md](project_access_detail_get.md) |
 | `ae-cli project data-power delete` | project.data_power.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--data-power-id` (number; required) — Data power ID to delete.<br>`--new-data-power-id` (number; optional) — Optional replacement data power ID for affected users. | [project_data_power_delete.md](project_data_power_delete.md) |
 | `ae-cli project data-power get` | project.data_power.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--data-power-id` (number; required) — Data power ID. | [project_data_power_get.md](project_data_power_get.md) |
@@ -245,7 +253,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli project role-user list` | project.role_user.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--role-name` (string; required) — Role name. | [project_role_user_list.md](project_role_user_list.md) |
 | `ae-cli project timezone get` | project.timezone.get | read | `--project-id` (number; required) — Numeric project ID. | [project_timezone_get.md](project_timezone_get.md) |
 | `ae-cli project timezone overview` | project.timezone.overview | read | `--project-id` (number; required) — Numeric project ID. | [project_timezone_overview.md](project_timezone_overview.md) |
-| `ae-cli project timezone update` | project.timezone.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload.<br>`--item` (string; required) — Timezone item: timezone_toggle, zone_offset, user_timezone, project_timezone_display. | [project_timezone_update.md](project_timezone_update.md) |
+| `ae-cli project timezone update` | project.timezone.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Item-specific snake_case payload: timezone_toggle uses {"toggle":true}; zone_offset uses {"column_name":"#zone_offset"}; user_timezone uses {"column_name":"user_timezone","codetable":"optional_table"}; project_timezone_display uses {"display_timezones":[{"timezone":8,"is_default":true}]}.<br>`--item` (string; required) — Timezone item: timezone_toggle, zone_offset, user_timezone, project_timezone_display. | [project_timezone_update.md](project_timezone_update.md) |
 | `ae-cli project user-id-items update` | project.user_id_items.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--payload` (json; required) — Required snake_case capability payload. Read the dedicated command reference for its semantic shape; an empty object is not a generic valid payload. | [project_user_id_items_update.md](project_user_id_items_update.md) |
 | `ae-cli system admin list` | system.admin.list | read | `--company-id` (number; required, min=1) — Company ID. | [system_admin_list.md](system_admin_list.md) |
 | `ae-cli system admin remove` | system.admin.remove | high-risk-write | `--company-id` (number; required, min=1) — Company ID.<br>`--target-open-id` (string; required) — Target member open ID. | [system_admin_remove.md](system_admin_remove.md) |

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

@@ -1,6 +1,6 @@
 # analysis dashboard get
 
-Use when the user needs one dashboard detail or when an agent needs the business context for dashboard report data. The detail includes location, creator and create/update time, settings, reports, notes, and sharing information.
+Use when the user needs one dashboard detail or when an agent needs the effective settings, saved filter configuration, and business context for dashboard report data.
 
 Do not use to query report result data. Use `dashboard-report-data run` or `dashboard-report-data export`.
 
@@ -18,4 +18,21 @@ Output is the gateway envelope. `data` contains the dashboard detail returned by
 - `location` always contains `space_id`, `space_name`, `folder_id`, and `folder_name`; values are null when that level does not apply. `folder_name` is the immediate parent folder.
 - `notes` is an array whose items contain `note_id`, `note_title`, and `description`.
 
+Prefer `effective_settings` over raw storage fields in `settings` when interpreting behavior:
+
+- `approximate_calculation.enabled` says whether report queries use approximate calculation.
+- `fixed_timezone.enabled` says whether the dashboard locks its timezone. When enabled, use `zone_offset`; otherwise `timezone_source=current_user_or_project_default` means the query follows the current user timezone or project default.
+- `scheduled_precompute.enabled`, `schedule_hour`, and `zone_offset` describe scheduled precomputation.
+- `cache.applicable`, `value`, `unit`, and `source` describe effective cache behavior. A `source` of `scheduled_precompute` means custom cache duration does not apply.
+
+`filter_config` separates filters by source:
+
+- `fixed_time` is the saved dashboard time range. Explicit supported `start_time` and `end_time` on a dashboard data command take precedence.
+- `dashboard_default` is the dashboard-wide default filter; it excludes the current caller's personal default filter.
+- `dashboard_business` is the mandatory business filter configured on the dashboard.
+- `space_business` is the mandatory business filter inherited from the project space.
+- `merge_relation=and` means these saved sources and any call-time `--filters` are combined with AND. Treat saved filters as already applied; do not copy them into `--filters`.
+
+Each saved source has `enabled` and a semantic `definition`. Read conditions from `definition.relation` and `definition.items`; fields and operators are Agent-facing names rather than raw QP codes. If a condition has `supported=false`, report that its legacy definition could not be fully mapped instead of claiming that no filter exists.
+
 When this detail is fetched before a dashboard data query, preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as dashboard context. Use them to interpret the report results, but distinguish this authored context from conclusions observed in the queried data.

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

@@ -10,6 +10,7 @@ Command:
 ae-cli analysis dashboard update --project-id <project_id> --operation settings --dashboard-ids '[1001,1002]' [--zone-offset 8] [--payload '{...}']
 ae-cli analysis dashboard update --project-id <project_id> --operation settings --dashboard-id <dashboard_id> --refresh-type 1 --dashboard-status normal --payload '{"dashboard_job_schedule":"0 0 8 * * ?","time_config_open":true,"time_config":{},"cache_config":{},"schedule_ui_config":{}}'
 ae-cli analysis dashboard update --project-id <project_id> --operation note-upsert --dashboard-id <dashboard_id> [--note-id <note_id>] [--note-title <title>] [--description <text>]
+ae-cli analysis dashboard update --project-id <project_id> --operation default-filter --dashboard-id <dashboard_id> --filter-name <name> --filter '{"junction_kind":"and","ta_filters":[...]}'
 ae-cli analysis dashboard update --project-id <project_id> --operation business-filter --dashboard-id <dashboard_id> --filter '{"junction_kind":"and","ta_filters":[...]}'
 ```
 
@@ -23,6 +24,8 @@ For `operation=settings`:
 
 For `operation=note-upsert`, pass `dashboard_id`; omit `note_id` to create a note or pass it to update an existing note. Do not mix note fields with batch settings fields.
 
+For `operation=default-filter`, pass one `dashboard_id`, `filter_name`, and `filter`. This saves a favorite filter and enables it as the dashboard-wide default filter; it is distinct from the current caller's personal default filter.
+
 For `operation=business-filter`, pass one `dashboard_id` and a `filter` object in snake_case QP form. This replaces the dashboard-level business filter saved in `ta_dashboard_business_filter`; it is not a condition-filter favorite or a space-level filter. Each simple condition uses fields such as `filter_type`, `column_name`, `table_type`, `column_type`, `select_type`, `calcu_symbol`, `ftv`, and `lack_value`. A condition with `lack_value=true` is saved as a selectable field but does not restrict query data. Pass `{"junction_kind":"and","ta_filters":[]}` to clear all dashboard-level business-filter conditions.
 
 Output is the gateway envelope. `data` contains the update result.

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

@@ -0,0 +1,23 @@
+# personal-semantic-preference add
+
+Add one personal semantic preference for the authenticated user in one project.
+
+Use this when the user explicitly asks to save a personal semantic preference, or when the current project task contains an explicit stable statement, correction, or confirmation that should become a reusable current-user preference. A current-user working definition remains eligible even when the same content may benefit other users. A second "save" confirmation is not required after that evidence gate is met, unless the target meaning is ambiguous.
+
+Command:
+
+```bash
+ae-cli personal-semantic-preference add --project-id <project_id> --context-type <context_type> --title <title> --summary <summary> --content <content> [--keywords '["keyword"]'] [--resource-refs '[{"resource_type":"report","resource_key":"101","display_name":"Revenue daily report"}]'] [--fresh-until-at "yyyy-MM-dd HH:mm:ss"] [--request-id <id>]
+```
+
+Use `preference` for durable interpretation/output preferences, `asset_context` for durable wording or intent bound to exact assets, `experience` for confirmed reusable work methods, and `background` for stable personal context. `--resource-refs` is required and non-empty only for `asset_context`; for every other type it must be absent or empty.
+
+`--resource-refs` accepts 1 to 50 ordered objects. Each object contains exactly `resource_type`, string `resource_key`, and `display_name`; `(resource_type, resource_key)` must be unique. `resource_type` is generic lower snake_case rather than a report-only enum, so events, properties, metrics, tags, clusters, reports, dashboards, data tables, and later asset types share the same shape. Array order is the user's intended priority.
+
+`--request-id` is an idempotency key; omit it for ordinary interactive use and the CLI will generate one.
+
+This command creates only a current-user preference; it never creates or approves a project semantic. Do not reject an otherwise valid personal preference merely because the same content may benefit other users, and do not imply that the saved preference is shared authority. Keep project-candidate recommendation separate: after personal capture, ask whether to recommend broadly reusable content as a project semantic candidate, and submit nothing without that choice.
+
+Store only the present working preference. Do not append future governance or lifecycle instructions. Do not use this command for company knowledge, standalone metadata facts, reports, dashboards, transient task details, one-off analysis results, or automatic stale/expired preference handling.
+
+Output is the gateway envelope. `data.preference` contains the full created preference, current revision, and complete ordered `resource_refs`. A separate readback is unnecessary unless a later step needs to refresh the record.

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

@@ -0,0 +1,17 @@
+# personal-semantic-preference delete
+
+Soft-delete one personal semantic preference using optimistic locking.
+
+Use this only after explicit user confirmation to remove a saved personal preference.
+
+Command:
+
+```bash
+ae-cli personal-semantic-preference delete --project-id <project_id> --id <preference_id> --expected-revision <revision> [--request-id <id>] --yes
+```
+
+Read the current item first and pass its revision as `--expected-revision`. This is a high-risk write; use `--dry-run` when the target is ambiguous.
+
+Do not use this command for automatic stale/expired preference handling. Stale or low-freshness personal preferences are hidden by list filtering and backend maintenance.
+
+Output is the gateway envelope. `data.deleted` identifies the deleted preference and status. After deletion, it should no longer appear in `personal-semantic-preference list`.

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

@@ -0,0 +1,19 @@
+# personal-semantic-preference get
+
+Get one personal semantic preference by ID.
+
+Use this command after `personal-semantic-preference list` identifies a likely current-user preference. Pass `--mark-used` when the preference is adopted for the answer, query path, or as the matched target for an update.
+
+Command:
+
+```bash
+ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> [--mark-used]
+```
+
+Input uses `project_id`, `id`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add.
+
+Do not use this command as a keyword search, project semantics lookup, or asset catalog lookup. Do not call it repeatedly for every catalog row. Do not use `--mark-used` for a candidate that turns out not to match the user's intent or is only inspected and then rejected.
+
+When a published project semantic conflicts with the personal item, the project semantic is the formal definition. Fetch and mark the personal item only when it materially affects the response, such as an explicitly requested non-formal alternative; never silently use it to override the project semantic.
+
+Output is the gateway envelope. `data.preference` contains the full personal preference, including content, complete ordered `resource_refs`, and revision. When `--mark-used` is set, the backend increments `heat_count` and updates `last_used_at` for that record.

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

@@ -0,0 +1,21 @@
+# personal-semantic-preference list
+
+List the authenticated user's active personal semantic preference catalog for one project.
+
+Use this command once per host, authenticated user, project, and conversation after resolving the project. Keep the returned directory in conversation context for later questions where user-specific wording or preferences may change interpretation.
+
+Command:
+
+```bash
+ae-cli personal-semantic-preference list --project-id <project_id>
+```
+
+Input uses `project_id` only. Do not add pagination parameters: the backend returns a compact catalog intended for agent context.
+
+Do not use this command for project semantics, shared knowledge, metadata catalogs, report/dashboard lists, or complete asset discovery. It only returns the current user's personal semantic preferences in the current project.
+
+Output is the gateway envelope. `data.items[]` contains only `id`, `context_type`, `title`, truncated `summary`, limited `keywords`, `resource_ref_count`, distinct `resource_types`, and `revision`; it deliberately omits content, full asset references, heat, and timestamps. `data.returned_count` is at most 200, `data.truncated` says whether entries were omitted, and `data.selection_policy` is `HOT_160_PLUS_RECENT_40`: up to 160 highest-heat items plus up to 40 recently changed items not already selected. The backend may return fewer items to keep the data payload within 64 KiB.
+
+If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used` before using its full content. Do not mark an item used when it was only inspected or rejected.
+
+Compare a likely match with the published project semantic catalog. Published project semantics remain the formal project-wide authority; personal items provide current-user defaults and working interpretations. If they conflict, use the project semantic for the formal result, explicitly disclose the personal difference, and do not mark the personal item used unless the user explicitly adopts it as a labeled alternative.

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

@@ -0,0 +1,19 @@
+# personal-semantic-preference update
+
+Update one personal semantic preference using optimistic locking.
+
+Use this when the user explicitly asks to change an existing personal preference, or when the current project task provides an explicit stable correction or confirmation that should replace a matching saved current-user preference. A current-user working definition remains eligible even when the same content may benefit other users. First read the matched current item with `personal-semantic-preference get --mark-used` and pass the returned revision as `--expected-revision`.
+
+Command:
+
+```bash
+ae-cli personal-semantic-preference update --project-id <project_id> --id <preference_id> --expected-revision <revision> --context-type <context_type> --title <title> --summary <summary> --content <content> [--keywords '["keyword"]'] [--resource-refs '[{"resource_type":"event","resource_key":"$login","display_name":"Login event"}]'] [--fresh-until-at "yyyy-MM-dd HH:mm:ss"] [--request-id <id>]
+```
+
+The update replaces all editable fields. Include the full intended `title`, `summary`, `content`, keywords, and asset bindings rather than a partial patch. `asset_context` requires 1 to 50 complete ordered `resource_refs`; other context types cannot contain non-empty refs.
+
+This command updates only the current-user preference; it does not update, approve, or publish project semantics. Do not block the update merely because the same content may benefit other users, and do not imply that the saved preference is shared authority. Keep project-candidate recommendation separate and ask before submitting it.
+
+Keep future governance and lifecycle handling out of the stored content. Do not use this command for shared knowledge, standalone metadata facts, reports, dashboards, transient task details, one-off analysis results, or automatic stale/expired preference handling.
+
+Output is the gateway envelope. `data.preference` contains the full updated preference and new revision. If the revision is stale, read the latest record and ask the user how to merge rather than overwriting silently.

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

@@ -7,13 +7,22 @@ Do not use it for unrelated project-management actions or for fields not present
 Command:
 
 ```bash
-ae-cli project timezone update --project-id <project_id> --payload <payload> --item <item>
-ae-cli project timezone update --dry-run --project-id <project_id> --payload <payload> --item <item>
+ae-cli project timezone update --project-id <project_id> --item timezone_toggle --payload '{"toggle":true}'
+ae-cli project timezone update --project-id <project_id> --item timezone_toggle --payload '{"toggle":true}' --dry-run
 ```
 
 Capability id: `project.timezone.update`.
 
-Input sends `project_id`, `payload`, `item`. Payload keys, JSON arrays, and projection fields must follow the common-service snake_case input schema.
+Input sends `project_id`, `payload`, and `item`. The payload is selected by `item`; use exactly one of these snake_case shapes:
+
+| `item` | `payload` | Notes |
+|---|---|---|
+| `timezone_toggle` | `{"toggle":true}` | `toggle` is required and boolean. Use `true` to enable multi-timezone and `false` to disable it. Never send `time_zone_enabled`. |
+| `zone_offset` | `{"column_name":"#zone_offset"}` | `column_name` is required and selects the event property used as the timezone offset. |
+| `user_timezone` | `{"column_name":"user_timezone","codetable":"timezone_code_table"}` | `column_name` is required. `codetable` is optional. |
+| `project_timezone_display` | `{"display_timezones":[{"timezone":8,"is_default":true},{"timezone":0,"is_default":false}]}` | `display_timezones` is a non-empty array. `timezone` is an integer from -12 through 14, or 99 for no fixed display timezone; `is_default` is optional and boolean. |
+
+Do not infer a payload field from the `project timezone get` output. In particular, its `time_zone_enabled` response field is not accepted by the update DTO; `timezone_toggle` always uses `payload.toggle`.
 
 Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Preserve `request_id` and `invocation_id` when present.
 
@@ -21,5 +30,5 @@ Output uses the gateway envelope: success is `ok=true,data,meta`; failure is `ok
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` | Yes | Numeric project ID. |
-| `--payload` | Yes | Timezone update payload. Shape depends on item. |
+| `--payload` | Yes | Item-specific payload from the table above. Do not send camelCase aliases or response-only fields. |
 | `--item` | Yes | Timezone item: timezone_toggle, zone_offset, user_timezone, project_timezone_display. |

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

@@ -13,6 +13,8 @@ ae-cli analysis-meta property create --dry-run
 
 Capability id: `metadata.property.create`.
 
+Authorization requires the single project function permission `editSuperMeta` with the `metadata:write` scope. In the zh-CN permission UI, this permission is labeled `元数据管理 > 编辑`; the corresponding English label is `Metadata Management > Edit`. This is the same project permission used by `metadata.super_metadata.batch_create`. If either command returns `PROJECT_PERMISSION_DENIED`, do not retry with a different payload and do not describe the two capability IDs as two separate permissions. Ask a project administrator to grant this shared project permission to the current identity.
+
 Input sends `project_id`, `table_type`, `payload`.
 
 Output is a successful gateway envelope with no business data. Read back with `property get` using the same table type.

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

@@ -12,6 +12,8 @@ ae-cli analysis-meta super-metadata batch-create --project-id <project_id> --eve
 
 Capability id: `metadata.super_metadata.batch_create`.
 
+Authorization requires the single project function permission `editSuperMeta` with the `metadata:write` scope. In the zh-CN permission UI, this permission is labeled `元数据管理 > 编辑`; the corresponding English label is `Metadata Management > Edit`. This is the same project permission used by `metadata.property.create`. If either command returns `PROJECT_PERMISSION_DENIED`, do not retry with a different payload and do not describe the two capability IDs as two separate permissions. Ask a project administrator to grant this shared project permission to the current identity.
+
 Input sends `project_id` plus any non-empty JSON arrays among `events`, `event_properties`, and `user_properties`. Use snake_case object fields exactly as documented by the common-service schema:
 
 - Event items: `event_name`, optional `event_desc`, optional `remark`, optional `super_event_prop_names`.

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

@@ -7,6 +7,8 @@ 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 `user-cluster update`, `type` must match the existing cluster type. The update command cannot change a cluster between condition and SQL, and it cannot change the cluster's analysis entity.
+
 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.

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

@@ -2,18 +2,22 @@
 
 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. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. 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.
+This is a `high-risk-write`. First run the final command with `--dry-run`, summarize the exact cluster and fields that will change, and wait for explicit user confirmation. Then run the unchanged command with `--yes`. Do not use it for ID-file membership replacement, to create a missing cluster, to change its analysis entity, or to change it between condition and SQL types.
+
+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. `--auto-refresh-cron` changes an existing enabled auto-refresh schedule and does not enable auto refresh. 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`, `--auto-refresh-cron`. The cluster type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--cluster-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. There is no `--entity-id` update flag. When the definition changes, `definition_request.type` must match the existing cluster type; it selects the definition variant but does not change the saved type.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `cluster_name` is an existing exact identifier and cannot be renamed by update.
 
 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"
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --display-name "Retained Users v2" --dry-run
+
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --display-name "Retained Users v2" --yes
 
-ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --auto-refresh-cron '0 30 2 * * ? *'
+ae-cli analysis user-cluster update --project-id <project_id> --cluster-name retained_users --auto-refresh-cron '0 30 2 * * ? *' --dry-run
 ```