@thinkingai/ae-cli 6.0.45 → 6.0.46

package/skills/ae-analysis/metadata_resolution.md

@@ -1,6 +1,11 @@
-# Structured AI-QP metadata resolution
+# Analysis metadata resolution
 
-Use this workflow only when `analysis adhoc run|export`, report create, or report update fails with `AI_QP_COMPILE_FAILED` and metadata errors contain:
+Enter this workflow through either path:
+
+1. `analysis adhoc run|export`, report create, or report update fails with `AI_QP_COMPILE_FAILED` and its metadata errors contain the structured fields below.
+2. Ordinary event, property, metric, cluster, or tag metadata discovery has completed two successful remote miss rounds in the same host, project, authenticated principal, and Agent conversation, and a third remote discovery round would otherwise be needed.
+
+For the structured compiler path, the metadata errors contain:
 
 - `path`
 - `slot_kind`
@@ -10,7 +15,7 @@ Use this workflow only when `analysis adhoc run|export`, report create, or repor
 - `candidates`
 - `next_action`
 
-The Common compiler returns every unresolved slot from the same compile attempt. Treat that complete error array as one resolution plan. Do not run this workflow independently for each `path`.
+The Common compiler returns every unresolved slot from the same compile attempt. Treat that complete error array as one resolution plan. Do not run the structured path independently for each `path`.
 
 `allowed_resource_types` and `search_targets` are authoritative for their exact paths. Do not add, remove, prioritize, or reinterpret resource types. `search_targets[].constraints` must be applied when filtering local rows.
 
@@ -65,6 +70,35 @@ Before reuse, require both files and verify:
 
 If any check fails, discard the cached pair for this workflow and fetch it again. A `.part` file or JSONL without the completed metadata sidecar is never valid.
 
+## Ordinary discovery workflow
+
+1. Keep one miss budget for the current host, project, authenticated principal, and Agent conversation.
+2. One ordinary discovery round is one successful remote event, property, metric, cluster, or tag list/search request. Put the current phrase and its useful synonyms in one `--queries` array instead of issuing one request per synonym.
+3. A round consumes one miss only when it returns no confirmable candidate. A plausible candidate stops discovery and requires explicit user confirmation; it is not a miss.
+4. Project lookup, exact `get`, filter-value lookup, and data queries do not consume this metadata-discovery budget. Validation, permission, network, and server errors are failures, do not consume a miss, and must not trigger the full-catalog fallback.
+5. After at most two ordinary miss rounds, do not issue a third resource-specific list/search. The third remote metadata-discovery round must be exactly one aggregate search using every accumulated deduplicated query and the union of applicable resource types:
+
+```bash
+ae-cli analysis-meta catalog list \
+  --project-id <project_id> \
+  --queries '["<all accumulated deduplicated queries>"]' \
+  --resource-types '["<union of applicable resource types>"]' \
+  --limit-per-type 20
+```
+
+6. If the aggregate response contains a confirmable candidate, stop and ask for confirmation. If it remains unresolved or returns `has_more=true` without a candidate, download the complete catalog exactly once:
+
+```bash
+ae-cli analysis-meta catalog export \
+  --project-id <project_id> \
+  --output "<catalog_dir>/catalog.jsonl"
+```
+
+7. Search the complete JSONL locally, return only a small candidate subset to model context, and require confirmation before binding. A local no-match is a complete negative result for that snapshot.
+8. Once the valid complete catalog exists, use it for every later metadata discovery in the same scope. Do not call online resource-specific metadata list/search commands or `analysis-meta catalog list|export` again. An exact `get` for details not present in the catalog remains outside the discovery budget.
+
+This caps ordinary online metadata discovery at three successful remote rounds before the full-catalog fallback becomes eligible: at most two resource-specific misses followed by one aggregate catalog search. Errors never advance that counter.
+
 ## Compile-wide workflow
 
 1. Read the complete compiler error array.
@@ -112,7 +146,7 @@ ae-cli analysis-meta catalog export \
 
 A reject-all response is a state transition, not task cancellation. Run the aggregate online search at most once for the rejected path set, then use the same complete-catalog fallback above if needed. Never repeat candidates the user already rejected. If the complete catalog has no different candidate, ask for an exact canonical name or a changed business definition.
 
-Do not call event, property, metric, cluster, or tag list commands in this structured workflow. Do not run `--queries` synonym rounds: the aggregate online search is one call for the whole compile error array, never one call per path or resource type. The unified catalog capability replaces both repeated online searches and per-resource full exports.
+Do not call event, property, metric, cluster, or tag list commands after entering the structured workflow. Do not run `--queries` synonym rounds: the aggregate online search is one call for the whole compile error array, never one call per path or resource type. The unified catalog capability replaces both repeated online searches and per-resource full exports.
 
 Once a valid complete catalog exists for the current host, project, principal, and conversation, never call `analysis-meta catalog list` again in that scope, and never call `analysis-meta catalog export` again either. Search the complete local snapshot instead; a local no-match is a complete negative result for this snapshot.
 

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

@@ -26,6 +26,35 @@ This policy does not apply to:
 - `analysis-meta`, metadata, DataOps, Community, Engage, or other business modules.
 - Report/dashboard/BI asset list commands, catalog exports, definition import/export, or management commands.
 
+## Cache policy for report and ad-hoc data
+
+Apply this cache policy to `analysis adhoc run|export` and
+`analysis report-data run|export`:
+
+- For an ordinary query, omit `--use-cache`; its effective default is `true`.
+  This allows a cache read but does not prove that the query actually hit a
+  cache.
+- Pass `--use-cache false` only when the user explicitly asks for fresh data,
+  a refresh or recomputation, to bypass/disable cache, or says the underlying
+  data was just updated. Words such as "latest" or "current" trigger this only
+  when they refer to data freshness, not merely to a selected time window.
+- When the user explicitly compares with a freshly refreshed analysis UI,
+  pass `--use-cache false`. A request that merely mentions a report or UI does
+  not imply this freshness requirement.
+- If the user reports that CLI/Agent data differs from the analysis UI, repeat
+  the same semantic query exactly once with `--use-cache false`. Preserve the
+  project, asset or model definition, filters, time range, timezone, cluster
+  route, and other query inputs. Explain that any difference may come from
+  cache policy or refresh timing; do not enter a retry loop.
+
+The Agent cannot observe whether another browser session is open, whether a UI
+query used cache, or whether the user is demonstrating the product. Never infer
+a demo scenario and never change cache policy based only on the audience or
+interface. `--use-cache` controls whether cache reads are allowed for this CLI
+query; it neither changes the saved asset/UI configuration nor exposes an
+actual cache-hit result. Do not claim cache hit or miss unless the response
+contains explicit backend evidence.
+
 ## Decision rule
 
 Synchronous data commands use `--preview-rows` for the maximum business rows

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

@@ -0,0 +1,22 @@
+# analysis-governance asset-authentication export
+
+Use for complete offline processing of project asset-authentication rows.
+
+Do not use it for interactive preview or let the CLI loop over `list`; this command invokes the complete export capability once.
+
+Command:
+
+```bash
+ae-cli analysis-governance asset-authentication export --project-id <project_id> --asset-types '["dashboard","report"]' --output /tmp/assets.jsonl
+```
+
+Capability id: `governance.asset_authentication.export`.
+
+The command does not accept `limit` or `offset` and performs exactly one complete server export call. It validates `complete`, `total`, `stat_as_of`, and `snapshot_hash`, then atomically publishes both:
+
+- `<output>`: private-mode JSONL rows.
+- `<output>.meta.json`: `complete`, `project_id`, `total`, `stat_as_of`, `snapshot_hash`, and the local file SHA-256 `checksum`.
+
+Export projection always retains `resource_type`, `resource_key`, `display_name`, `authentication_status`, `heat_count90d`, `user_count90d`, and `impact_degree`; `--fields` can add or remove only optional descriptive and owner fields.
+
+Use the sidecar `snapshot_hash` with `update --expected-snapshot-hash` when the selected asset set was derived from this export.

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

@@ -1,25 +1,29 @@
-# analysis-meta asset-authentication list
+# analysis-governance asset-authentication list
 
-Use when the user needs to list authenticatable project assets and authentication status.
+Use for bounded online preview, search, and filtering of project asset-authentication rows.
 
-Do not use it as a complete asset search or to change status; use `asset search` or `asset authentication-update` respectively.
+This command filters on the server before sorting and pagination. Use `export` for a complete offline dataset and `update` for an explicit typed asset set.
+
+Do not use it to synthesize a complete catalog by paging or to change authentication state.
 
 Command:
 
 ```bash
-ae-cli analysis-meta asset-authentication list --project-id <project_id> --limit 50 --offset 0
-ae-cli analysis-meta asset-authentication list --dry-run
+ae-cli analysis-governance asset-authentication list --project-id <project_id> --asset-types '["dashboard","report"]' --authentication-status 0 --heat-count-gt 50 --user-count-gt 5 --match any --limit 100
 ```
 
-Capability id: `metadata.asset_authentication.list`.
+Capability id: `governance.asset_authentication.list`.
+
+`match=any|all` combines only the supplied numeric thresholds. Asset types, authentication status, and keyword queries are always AND filters. `queries` matches any supplied keyword.
+
+Output uses `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Row identity is always `resource_type + resource_key`; dashboard and report keys are numeric IDs encoded as strings, while metadata assets use business names.
 
-Input sends `project_id`, `limit`, and `offset`.
+## analysis-meta asset-authentication list
 
-Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
+The legacy command remains available for one release cycle and returns the old row shape.
+
+```bash
+ae-cli analysis-meta asset-authentication list --project-id <project_id> --limit 50 --offset 0
+```
 
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` | Yes | Numeric project ID. |
-| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
-| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |
+Legacy Input is `project_id`, `limit`, and `offset`. Legacy Output uses the same directory envelope with the old asset field names.

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/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) |
@@ -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) |

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. 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.
+
+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,17 @@
+# 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 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.
+
+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,19 @@
+# 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 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.

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. 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 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.