@thinkingai/ae-cli 6.1.19 → 6.1.20

package/skills/ae-agent/references/list-mcp-credentials.md

@@ -61,5 +61,5 @@ ae-cli agent +list-mcp-credentials --dry-run
 - `401` / auth expired: run `ae-cli auth login`.
 
 ## Recommended Chaining
-- `+list-mcp-credentials` (check) → `+set-mcp-credential` (set) or `+auto-provision-mcp-credentials` (bulk)
+- `+list-mcp-credentials` (check) → `+set-mcp-credential` (set)
 - `+list-mcp-credentials` → `+mcp-token` (get plaintext token for useMcpToken servers)

package/skills/ae-agent/references/mcp-token.md

@@ -38,7 +38,7 @@ ae-cli agent +mcp-token --dry-run
 ## Decision Rules
 - If the user needs the shared MCP token to call MCP-enabled APIs, use this command.
 - The token is shared across all `useMcpToken=true` system MCP servers — a single call returns it.
-- If `token` is `null`, no credential has been provisioned yet — run `+auto-provision-mcp-credentials` first.
+- If `token` is `null`, no shared MCP token is available on the current server.
 - Prefer `+list-mcp-credentials` to check credential status without exposing the plaintext token.
 
 ## Response Shape
@@ -57,7 +57,7 @@ When no token is provisioned:
 
 ## Next Steps on Failure
 - `401` / auth expired: run `ae-cli auth login`.
-- `token: null`: run `+auto-provision-mcp-credentials` to provision the token first.
+- `token: null`: ask the server administrator whether a shared MCP token is expected in this environment.
 
 ## Recommended Chaining
-- `+auto-provision-mcp-credentials` (provision) → `+mcp-token` (retrieve) → use as `Authorization: bearer <token>` for MCP API calls
+- `+mcp-token` (retrieve) → use as `Authorization: bearer <token>` for MCP API calls

package/skills/ae-agent/references/set-mcp-credential.md

@@ -42,7 +42,6 @@ ae-cli agent +set-mcp-credential --dry-run --mcp-server-id <mcp-cuid> --token "a
 - For OAuth-based servers, prefer `+mcp-auth-start` (full OAuth flow with auto-refresh). Use `+set-mcp-credential` only when you have a pre-obtained token.
 - For API-key-based servers (`--auth-type apikey`), this is the primary way to set the key.
 - The token is encrypted at rest; it is never returned in plaintext via `+list-mcp-credentials` (use `+mcp-token` for useMcpToken servers).
-- To bulk-provision credentials for all system MCP servers at once, use `+auto-provision-mcp-credentials`.
 
 ## Response Shape
 ```json

package/skills/ae-agent/references/update-automation.md

@@ -4,6 +4,15 @@
 
 Domain: **Automations / write**
 
+```text
+Transition status: transitional
+Owning module: te-claude automation
+Current transport: PATCH /api/sandbox/agent/automations/:id
+Gateway target: TBD (no equivalent Gateway capability is currently registered)
+Review after: 2026-10-07
+Exit condition: Migrate when the Gateway exposes equivalent workspace-scoped automation updates.
+```
+
 ## Use Cases
 - Update an existing Agent automation task's name, instruction, schedule, enabled state, or conversation mode.
 - Used to pause (`--enabled false`) or resume (`--enabled true`) an automation, or to change its schedule/message.
@@ -11,6 +20,10 @@ Domain: **Automations / write**
 
 ## Mandatory Rules (MUST)
 - `--id` is required. Obtain the real ID via `+list-automations` — do not guess.
+- Pass the same `--agent-space-id` used to discover the task, or the `automation.agentSpaceId` returned by creation. Omitting it targets the personal default workspace, including legacy tasks with no workspace ID.
+- The workspace ID is sent as a query parameter to select the task's existing workspace. It is not an update field and cannot move an automation between workspaces; providing it alone is not a valid update.
+- On servers without workspace support, omit `--agent-space-id` and update by the original task ID. Missing workspace fields in older responses do not prevent updates; do not invent an ID or rely on older servers to enforce the new workspace query parameter.
+- Agent Team scheduled task IDs are not automation IDs and cannot be used with this command.
 - At least one update field must be provided (`--name`, `--message`, `--enabled`, `--reuse-conversation`, `--cron`, or a `--schedule-kind` with its time/day fields).
 - `--cron` and `--schedule-kind` are mutually exclusive.
 - This is an ordinary `write` operation and does not require CLI confirmation.
@@ -29,6 +42,9 @@ Domain: **Automations / write**
 # Pause an automation
 ae-cli agent +update-automation --id <automation-id> --enabled false
 
+# Pause an automation in a specific workspace
+ae-cli agent +update-automation --id <automation-id> --agent-space-id <workspace-id> --enabled false
+
 # Resume an automation
 ae-cli agent +update-automation --id <automation-id> --enabled true
 
@@ -62,6 +78,7 @@ ae-cli agent +update-automation --dry-run --id <automation-id> --enabled false
 | Parameter | Required | Description |
 |---|---|---|
 | `--id` | Yes | Automation task ID from `+list-automations` |
+| `--agent-space-id` | No | Existing workspace ID; omitted means the personal default workspace. Does not move the task |
 | `--name` | No | New automation task name |
 | `--message` | No | New instruction sent to the Agent |
 | `--enabled` | No | `true` to enable, `false` to pause |
@@ -81,6 +98,7 @@ ae-cli agent +update-automation --dry-run --id <automation-id> --enabled false
 - Use `--dry-run` first to verify the request shape before executing.
 
 ## Next Steps on Failure
+- `AUTOMATION_NOT_FOUND`: verify the task ID and workspace ID together. Do not retry across other workspaces automatically.
 - `至少提供一个更新字段`: add at least one of `--name` / `--message` / `--enabled` / `--reuse-conversation` / `--cron` / `--schedule-kind`.
 - `必须提供 --cron 或 --schedule-kind`: if schedule detail flags (`--time` / `--minute` / `--weekday` / `--day-of-month`) are present, a `--schedule-kind` (or `--cron`) must accompany them.
 - `--time 格式必须是 HH:mm`: use 24-hour `HH:mm` (e.g. `09:00`).

package/skills/ae-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-analysis
-version: 4.2.3
+version: 4.2.5
 description: "Use ae-cli for AE/TE analysis-side data questions, asset operations, and asset governance: reports, analysis boards, BI dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update/govern analysis assets."
 ---
 
@@ -17,9 +17,11 @@ This is the single entry skill for analysis intent and command execution.
    - `event list` -> `references/event_list.md`
    - `analysis dashboard list` -> `references/dashboard_list.md`
    - `personal-semantic-preference list` -> `references/personal_semantic_preference_list.md`
+   - Asset center cross-source configuration (资产中心 / 跨源资产配置 / Excel 配置表导入): L3 discovery via `capability search "cross_source_config" --domain metadata --project-id <id>`; read [`references/cross_source_config.md`](references/cross_source_config.md) for workbook upload and validation. No dedicated business commands.
    - replace hyphens with underscores in gateway filenames.
 3. For an AI-facing ad-hoc definition, also read [`references/ai_models.md`](references/ai_models.md).
 4. For cluster/tag `--definition-request`, also read the matching [`references/user_cluster_models.md`](references/user_cluster_models.md) or [`references/user_tag_models.md`](references/user_tag_models.md). Shared primitives live in [`references/audience_models.md`](references/audience_models.md).
+   - For tag periodic refresh, read `references/user_tag_create.md` or `references/user_tag_update.md`; they cover the enable switch, frequency/time schedule, cron alternative, and timezone behavior.
 5. For analysis data retrieval, choose `run` or `export` using [`references/analysis_data_retrieval.md`](references/analysis_data_retrieval.md).
 6. When an AI-QP compile failure contains `slot_kind`, `allowed_resource_types`, `search_targets`, and `next_action`, read and follow [`metadata_resolution.md`](metadata_resolution.md).
 
@@ -30,7 +32,7 @@ Routing is complete when one command family and its dedicated references are sel
 Use this skill for these CLI services:
 
 - `analysis`: reports, dashboards, BI panels, ad-hoc analysis, drilldown, detail data, alerts, clusters, tags, and async runs/artifacts.
-- `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata.
+- `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata. Cross-source asset configuration uses the metadata L3 catalog instead.
 - `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
 - `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations.
 - `personal-semantic-preference`: current user's project-scoped personal semantic preferences. Use it as agent context before resolving ambiguous business wording, asset choices, or recurring user preferences.
@@ -70,6 +72,13 @@ Interpret gateway envelopes by state:
 - `ok: false` is failure. Preserve `error.code`, `error.message`, and `meta.request_id`, `meta.invocation_id`, `meta.stage`, and `meta.failures` when present.
 - Do not retry an unchanged failed command or guess alternative payload shapes. Retry only after applying concrete validation/clarification guidance or correcting a verified transient condition.
 
+Failure evidence:
+
+- A process exit code of 0 is not business success when the envelope says `ok: false`. Prefer direct CLI invocation; if a shell pipeline is necessary, preserve the CLI exit status with `set -o pipefail` and retain the complete error envelope rather than truncating it.
+- `TE_TOOL_POLICY_DENIED` identifies the runtime authorization stage. Report its exact reason; it does not prove a backend schema check passed or that the user needs to log in again. Do not bypass policy or retry by changing the business scope.
+- `INVALID_ANALYSIS_DEFINITION` / `INVALID_CAPABILITY_INPUT` identifies an input failure. Correct all relevant fields together within the allowed retry budget. Say "validation passed" only after an explicit successful validation response for the same complete definition on the same host.
+- `QUERY_FAILED` establishes that the query failed; it does not establish the database or engine root cause. Preserve the returned error and correlation IDs, leave unavailable values unknown (not zero), and stop when the user requests no retries. Distinguish observed errors from unverified hypotheses.
+
 For every gateway command that exposes `--request-id`, ae-cli generates a `request_id` and prints it to stderr before dispatch when the caller omits it. Preserve that ID with the final envelope and diagnostics. Pass an explicit `--request-id cli_<32 lowercase hex>` only when a caller-owned correlation ID is required.
 
 ### Execution invariants

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

@@ -68,4 +68,6 @@ The execute, `--validate`, and `--dry-run` paths all compile the AI-facing defin
 
 For a complex definition, finish the complete user-requested definition first, validate that exact definition once, and then run the same definition once. Never execute a simplified variant that omits requested filters or groups just to obtain a result. If validation rejects fields, inspect this command's model contract or capability schema once, correct all reported fields together, and revalidate the complete definition.
 
+For a gateway `oneOf` error, focus on the selected `model_type` branch and shared input fields; other model branches are alternatives, not additional requirements. Apply every relevant correction together (for example, both `event_property_name` and string-valued `values` for funnel step filters). Local `INVALID_ANALYSIS_DEFINITION` is a pre-dispatch input failure, not a query failure. Passing this narrow local check is not proof that the full backend schema or query has passed. Follow the failure-evidence rules in `../SKILL.md` and honor the user's retry limit.
+
 Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Use the context only with an action advertised by the selected source, call `analysis query-context get`, and assemble the coordinate only from its returned option fragments. Do not pass raw QP or infer a coordinate from display text.

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

@@ -124,12 +124,12 @@ Property aggregation example:
 {
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
-    {"event": "purchase", "display_name": "Purchase revenue", "aggregation": "sum", "property": "amount"}
+    {"event": "purchase", "aggregation": "sum", "property": "amount"}
   ]
 }
 ```
 
-Set optional `display_name` on an event metric when the report should show a business-facing metric name. It applies to regular event metrics, saved metrics, and formula metrics. Omit it to use the event name or the default formula-metric label.
+Omit `display_name` by default; apply business-facing labels in the final answer instead. Add this optional field only when the target host's capability schema or a successful validation explicitly supports `display_name` for that command. Support can differ by deployment and command; a saved report supporting it does not prove ad-hoc support. If rejected, remove only the unsupported label, preserving events, aggregations, properties, filters, and formula dependencies.
 
 Formula metric example:
 
@@ -138,7 +138,6 @@ Formula metric example:
   "time_range": {"mode": "previous", "unit": "day", "value": 7},
   "metrics": [
     {
-      "display_name": "Revenue per user",
       "formula": "revenue / users",
       "dependencies": [
         {"alias": "revenue", "event": "purchase", "aggregation": "sum", "property": "amount"},
@@ -229,6 +228,27 @@ Use for ordered conversion steps with a conversion window.
 
 If the user asks to match users across events by a shared event property, set `relation_event_property_name`.
 
+Step-level event-property filters belong inside the matching `funnel.steps[].filters`. Use `event_property_name`, not the common `field` object. `values` is an array of strings, including `"true"` / `"false"` for boolean properties; omit values for existence operators. For example, ordered registration -> login -> first payment:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 14},
+  "time_particle_size": "day",
+  "funnel": {
+    "steps": [
+      {"event": "register"},
+      {"event": "login"},
+      {"event": "payment", "filters": [
+        {"event_property_name": "is_first_pay", "operator": "eq", "values": ["true"]}
+      ]}
+    ],
+    "window": {"value": 7, "unit": "day"}
+  }
+}
+```
+
+Preserve step order, conversion window, and all requested filters when correcting input. Only actual funnel results support step counts and conversion rates; independent event UVs are not an ordered funnel.
+
 ### `distribution`
 
 Use for user distribution buckets for an event or property metric.

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

@@ -98,7 +98,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `dashboard list` | `analysis.dashboard.list` | Find accessible dashboards | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated dashboard summaries |
 | `dashboard create` | `analysis.dashboard.create` | Create a dashboard | `--project-id`, `--dashboard-name`, optional `--space-id`, `--folder-id` | Created dashboard |
 | `dashboard get` | `analysis.dashboard.get` | Inspect one dashboard location/definition/share/report structure, including notes, creator, and creation/update time | `--project-id`, `--dashboard-id` | Dashboard detail with location and normalized notes |
-| `dashboard update` | `analysis.dashboard.update` | Update settings, upsert a note, or replace the dashboard-level business filter | `--operation settings|note-upsert|business-filter`, IDs, optional `--filter`/`--payload` | Update result |
+| `dashboard update` | `analysis.dashboard.update` | Update settings, create or patch a note, or replace the dashboard-level business filter | `--operation settings|note-upsert|business-filter`; `--dashboard-id` is required for notes; omit `--note-id` to create | Update result |
 | `dashboard share-info` | `analysis.dashboard.share_info` | Read dashboard sharing info | `--project-id`, `--dashboard-id` | Share info |
 | `dashboard share` | `analysis.dashboard.share` | Modify dashboard sharing | `--project-id`, `--dashboard-id`, `--payload` or `--member-authorities` | Share update result |
 | `dashboard delete` | `analysis.dashboard.delete` | Delete dashboards | `--project-id`, `--dashboard-ids '[...]'` | Delete result |
@@ -155,7 +155,7 @@ Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analys
 | `user-tag get` | `analysis.user_tag.get` | Inspect exact tags | `--tag-names '[...]'` | Tag details |
 | `user-tag-member list` | `analysis.user_tag_member.list` | Bounded inline tag members | `--tag-name`, optional `--snapshot-date`, properties/fields/query/limit/offset | Member rows |
 | `user-tag-member export` | `analysis.user_tag_member.export` | Stream native full tag members as csv.gz | `--tag-name`, optional `--snapshot-date`, properties | Async artifact descriptor |
-| `user-tag create` | `analysis.user_tag.create` | Create tag directly from semantic intent | `--tag-name`, `--display-name`, `--definition-request` | Create result and canonical request |
+| `user-tag create` | `analysis.user_tag.create` | Create tag directly from semantic intent, optionally with periodic refresh | `--tag-name`, `--display-name`, `--definition-request`, optional `--auto-refresh-schedule` or `--auto-refresh-cron` | Create result and canonical request |
 | `user-tag update` | `analysis.user_tag.update` | Update tag | `--tag-name`, fields to change, optional `--definition-request` | Update result |
 | `user-tag refresh` | `analysis.user_tag.refresh` | Trigger tag recompute | `--tag-name` | Refresh result |
 | `user-tag create-id` | `analysis.user_tag.create_id` | Map imported values to an entity and create a tag | `--display-name`, `--entity-id`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |

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

@@ -8,8 +8,8 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 
 | Command | Capability ID | Risk | Flags | Reference |
 |---|---|---|---|---|
-| `ae-cli analysis adhoc export` | analysis.adhoc.export | read | `--project-id` (number; required) — Numeric project ID.<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.<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.<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.<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>`--use-cache` (boolean; optional) — Whether to use query cache. Default: true.<br>`--zone-offset` (number; optional) — Optional timezone mode. Fixed UTC offsets are -12..14; 99 means stored local time without fixed UTC conversion (not UTC+99). Omit to use the project analysis default.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--cluster-query-scope` (string; optional) — Optional physical query routing: GLOBAL aggregates accessible query clusters; SLAVE targets one --slave-cluster-id. Omit for the surface default.<br>`--slave-cluster-id` (string; optional) — Physical slave query-cluster ID from analysis query-cluster list. Required only with --cluster-query-scope SLAVE.<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. | [adhoc_export.md](adhoc_export.md) |
-| `ae-cli analysis adhoc run` | analysis.adhoc.run | read | `--project-id` (number; required) — Numeric project ID.<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.<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.<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.<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>`--use-cache` (boolean; optional) — Whether to use query cache. Default: true.<br>`--zone-offset` (number; optional) — Optional timezone mode. Fixed UTC offsets are -12..14; 99 means stored local time without fixed UTC conversion (not UTC+99). Omit to use the project analysis default.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--cluster-query-scope` (string; optional) — Optional physical query routing: GLOBAL aggregates accessible query clusters; SLAVE targets one --slave-cluster-id. Omit for the surface default.<br>`--slave-cluster-id` (string; optional) — Physical slave query-cluster ID from analysis query-cluster list. Required only with --cluster-query-scope SLAVE.<br>`--preview-rows` (number; optional, min=1) — Maximum synchronous preview units returned per result. Units are business rows for tabular results. For path results, this limits real nodes per path level before overflow nodes are combined into more. Omit to use the current model/cluster synchronous limit. The runtime maximum varies by model; agents should normally pass 100.<br>`--timeout-seconds` (number; optional, min=1, max=180) — Sync timeout seconds. Default: 120, max: 180. | [adhoc_run.md](adhoc_run.md) |
+| `ae-cli analysis adhoc export` | analysis.adhoc.export | read | `--project-id` (number; required) — Numeric project ID.<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.<br>`--definition` (json; required) — Event metrics: omit optional display_name unless the target command schema explicitly supports it. Funnel step filters use event_property_name (not field) and string-array values, including "true"/"false" for boolean properties. 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.<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.<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>`--use-cache` (boolean; optional) — Whether to use query cache. Default: true.<br>`--zone-offset` (number; optional) — Optional timezone mode. Fixed UTC offsets are -12..14; 99 means stored local time without fixed UTC conversion (not UTC+99). Omit to use the project analysis default.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--cluster-query-scope` (string; optional) — Optional physical query routing: GLOBAL aggregates accessible query clusters; SLAVE targets one --slave-cluster-id. Omit for the surface default.<br>`--slave-cluster-id` (string; optional) — Physical slave query-cluster ID from analysis query-cluster list. Required only with --cluster-query-scope SLAVE.<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. | [adhoc_export.md](adhoc_export.md) |
+| `ae-cli analysis adhoc run` | analysis.adhoc.run | read | `--project-id` (number; required) — Numeric project ID.<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.<br>`--definition` (json; required) — Event metrics: omit optional display_name unless the target command schema explicitly supports it. Funnel step filters use event_property_name (not field) and string-array values, including "true"/"false" for boolean properties. 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.<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.<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>`--use-cache` (boolean; optional) — Whether to use query cache. Default: true.<br>`--zone-offset` (number; optional) — Optional timezone mode. Fixed UTC offsets are -12..14; 99 means stored local time without fixed UTC conversion (not UTC+99). Omit to use the project analysis default.<br>`--fields` (json; optional) — Optional result field projection JSON array.<br>`--cluster-query-scope` (string; optional) — Optional physical query routing: GLOBAL aggregates accessible query clusters; SLAVE targets one --slave-cluster-id. Omit for the surface default.<br>`--slave-cluster-id` (string; optional) — Physical slave query-cluster ID from analysis query-cluster list. Required only with --cluster-query-scope SLAVE.<br>`--preview-rows` (number; optional, min=1) — Maximum synchronous preview units returned per result. Units are business rows for tabular results. For path results, this limits real nodes per path level before overflow nodes are combined into more. Omit to use the current model/cluster synchronous limit. The runtime maximum varies by model; agents should normally pass 100.<br>`--timeout-seconds` (number; optional, min=1, max=180) — Sync timeout seconds. Default: 120, max: 180. | [adhoc_run.md](adhoc_run.md) |
 | `ae-cli analysis alert create` | analysis.alert.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--definition-request` (json; required) — Structured alert definition request JSON object using snake_case field names. | [alert_create.md](alert_create.md) |
 | `ae-cli analysis alert delete` | analysis.alert.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--alert-id` (number; required) — Alert task ID. | [alert_delete.md](alert_delete.md) |
 | `ae-cli analysis alert get` | analysis.alert.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--alert-id` (number; required) — Alert task ID. | [alert_get.md](alert_get.md) |
@@ -43,7 +43,7 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `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, 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 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. Required for note-upsert.<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 attached to the dashboard.<br>`--note-title` (string; optional) — Dashboard note title. Defaults to empty on create; omitted values are preserved on update.<br>`--description` (string; optional) — Dashboard note description. Defaults to empty on create; omitted values are preserved on update.<br>`--ui-config` (string; optional) — Dashboard or note UI config string. Omitted note style is preserved on update.<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) |
@@ -90,12 +90,12 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `ae-cli analysis query create-result-cluster` | analysis.query.create_result_cluster | write | `--project-id` (number; required) — Numeric project ID.<br>`--query-context-id` (string; required) — query_context_id returned by a synchronous analysis preview. Never use an export response.<br>`--source` (json; optional) — Source selector copied from the compact sources[] summary when the synchronous preview contains multiple reports or charts. Pass exactly one returned field: report_id or chart_id.<br>`--coordinate` (json; required) — One semantic cell coordinate assembled only from row_options, column_options, and metric_options returned by analysis query-context get. Never pass target_id, raw QP, or inferred values.<br>`--cluster-name` (string; required, minLength=1, maxLength=24, pattern=^[a-z][a-z0-9_]*$) — Unique result cluster name. Must start with a lowercase letter, contain only lowercase letters, digits, and underscores, and be at most 24 characters.<br>`--display-name` (string; optional, minLength=1, maxLength=80) — Optional result cluster display name. Maximum: 80 characters.<br>`--zone-offset` (number; optional) — Optional timezone offset. UTC+8 is 8; UTC-5 is -5.<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) — Optional capability execution timeout in seconds. | [query_create_result_cluster.md](query_create_result_cluster.md) |
 | `ae-cli analysis query-cluster list` | analysis.query_cluster.list | read | `--project-id` (number; required) — Numeric project ID. | [query_cluster_list.md](query_cluster_list.md) |
 | `ae-cli analysis query-context get` | analysis.query.context_get | read | `--project-id` (number; required) — Numeric project ID.<br>`--query-context-id` (string; required) — query_context_id returned by a synchronous analysis preview.<br>`--source` (json; optional) — Source selector copied from the compact sources[] summary. Required for multi-source contexts; pass exactly one field: report_id or chart_id. | [query_context_get.md](query_context_get.md) |
-| `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 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) — Event metrics: omit optional display_name unless the target command schema explicitly supports it. Funnel step filters use event_property_name (not field) and string-array values, including "true"/"false" for boolean properties. 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.<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 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) — Event metrics: omit optional display_name unless the target command schema explicitly supports it. Funnel step filters use event_property_name (not field) and string-array values, including "true"/"false" for boolean properties. 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) |
 | `ae-cli analysis report-change-log list` | analysis.report_change_log.list | read | `--project-id` (number; required) — Numeric project ID.<br>`--report-id` (number; required) — Report ID. | [report_change_log_list.md](report_change_log_list.md) |
@@ -117,14 +117,14 @@ This is the exhaustive command and flag inventory for the analysis skill. Read t
 | `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) |
-| `ae-cli analysis user-tag create` | analysis.user_tag.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required, minLength=1, maxLength=80, pattern=^[a-zA-Z][a-zA-Z0-9_]*$) — New tag_name. Must start with a letter, contain only letters, digits, and underscores, and be at most 80 characters.<br>`--display-name` (string; required, minLength=1, maxLength=80) — Human-readable display name. Maximum: 80 characters.<br>`--definition-request` (json; required) — Semantic snake_case tag definition. Read skills/ae-analysis/references/user_tag_models.md; shared primitives are in audience_models.md.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity.<br>`--zone-offset` (number; optional) — Optional timezone offset. UTC+8 is 8; UTC-5 is -5.<br>`--entity-id` (number; optional) — Optional entity ID. Required by ID-file create commands. | [user_tag_create.md](user_tag_create.md) |
+| `ae-cli analysis user-tag create` | analysis.user_tag.create | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required, minLength=1, maxLength=80, pattern=^[a-zA-Z][a-zA-Z0-9_]*$) — New tag_name. Must start with a letter, contain only letters, digits, and underscores, and be at most 80 characters.<br>`--display-name` (string; required, minLength=1, maxLength=80) — Human-readable display name. Maximum: 80 characters.<br>`--definition-request` (json; required) — Semantic snake_case tag definition. Read skills/ae-analysis/references/user_tag_models.md; shared primitives are in audience_models.md.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity.<br>`--zone-offset` (number; optional) — Optional timezone offset. UTC+8 is 8; UTC-5 is -5.<br>`--entity-id` (number; optional) — Optional entity ID. Required by ID-file create commands.<br>`--enable-auto-refresh` (boolean; optional) — Enable or disable periodic refresh. Omit to preserve the setting on update. Enabling on create requires a schedule.<br>`--auto-refresh-cron` (string; optional) — Quartz cron expression in the tag timezone. Enables periodic refresh. Mutually exclusive with --auto-refresh-schedule.<br>`--auto-refresh-schedule` (json; optional) — Schedule object: frequency daily\|weekly\|monthly, time HH:mm, weekdays (weekly, ISO 1=Monday to 7=Sunday), month_days (monthly, 1-31). Enables periodic refresh in the tag timezone. Example: {"frequency":"daily","time":"02:30"}. | [user_tag_create.md](user_tag_create.md) |
 | `ae-cli analysis user-tag create-id` | analysis.user_tag.create_id | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; optional, minLength=1, maxLength=80, pattern=^[a-zA-Z][a-zA-Z0-9_]*$) — Optional tag_name; generated if omitted. When provided, it must satisfy the 1-80 character machine-name contract.<br>`--display-name` (string; required, minLength=1, maxLength=80) — Human-readable display name. Maximum: 80 characters.<br>`--entity-id` (number; required) — Required analysis entity. Use the primary user entity only when matching uploaded external identifiers through a user property.<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 two non-empty columns per row: association-property value or entity ID, then tag_value.<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_tag_create_id.md](user_tag_create_id.md) |
 | `ae-cli analysis user-tag delete` | analysis.user_tag.delete | high-risk-write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag list first.<br>`--confirmed` (boolean; optional) — Set true only after dependency and influence checks have been accepted. | [user_tag_delete.md](user_tag_delete.md) |
 | `ae-cli analysis user-tag export` | analysis.user_tag.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 tag inventory projection. Use tag_name, display_name, users_num, and other tag fields. cluster_name is reserved for user clusters and is rejected here.<br>`--authenticated-only` (boolean; optional) — Return only resources whose metadata can be resolved under the current identity.<br>`--output` (string; required) — JSONL output file path. Full rows stay in this file; completeness and identity metadata is written to the adjacent .meta.json file. | [user_tag_export.md](user_tag_export.md) |
 | `ae-cli analysis user-tag get` | analysis.user_tag.get | read | `--project-id` (number; required) — Numeric project ID.<br>`--tag-names` (json; required) — JSON array of exact tag_name values. | [user_tag_get.md](user_tag_get.md) |
 | `ae-cli analysis user-tag list` | analysis.user_tag.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 tag inventory projection. Use tag_name, display_name, users_num, and other tag fields. cluster_name is reserved for user clusters and is rejected here.<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_tag_list.md](user_tag_list.md) |
 | `ae-cli analysis user-tag refresh` | analysis.user_tag.refresh | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag list first. | [user_tag_refresh.md](user_tag_refresh.md) |
-| `ae-cli analysis user-tag update` | analysis.user_tag.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag 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 tag definition. Read user_tag_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_tag_update.md](user_tag_update.md) |
+| `ae-cli analysis user-tag update` | analysis.user_tag.update | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag 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 tag definition. Read user_tag_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>`--enable-auto-refresh` (boolean; optional) — Enable or disable periodic refresh. Omit to preserve the setting on update. Enabling on create requires a schedule.<br>`--auto-refresh-cron` (string; optional) — Quartz cron expression in the tag timezone. Enables periodic refresh. Mutually exclusive with --auto-refresh-schedule.<br>`--auto-refresh-schedule` (json; optional) — Schedule object: frequency daily\|weekly\|monthly, time HH:mm, weekdays (weekly, ISO 1=Monday to 7=Sunday), month_days (monthly, 1-31). Enables periodic refresh in the tag timezone. Example: {"frequency":"daily","time":"02:30"}. | [user_tag_update.md](user_tag_update.md) |
 | `ae-cli analysis user-tag update-id` | analysis.user_tag.update_id | write | `--project-id` (number; required) — Numeric project ID.<br>`--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag list first.<br>`--display-name` (string; optional, minLength=1, maxLength=80) — Optional new display name. Maximum: 80 characters.<br>`--entity-id` (number; optional) — Optional entity ID. Required by ID-file create commands.<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 two non-empty columns per row: association-property value or entity ID, then tag_value.<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_tag_update_id.md](user_tag_update_id.md) |
 | `ae-cli analysis user-tag-member export` | analysis.user_tag_member.export | read | `--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag list first.<br>`--snapshot-date` (string; optional) — Optional tag snapshot date, yyyy-MM-dd.<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_tag_member_export.md](user_tag_member_export.md) |
 | `ae-cli analysis user-tag-member list` | analysis.user_tag_member.list | read | `--tag-name` (string; required) — Exact tag_name. Discover real values with analysis user-tag list first.<br>`--snapshot-date` (string; optional) — Optional tag snapshot date, yyyy-MM-dd.<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, #distinct_id, and tag_value.<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_tag_member_list.md](user_tag_member_list.md) |

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

@@ -0,0 +1,84 @@
+# Cross-source asset configuration (L3)
+
+Use this workflow for Asset Center → Cross-source asset configuration when the user has or can prepare an Excel configuration workbook. The CLI scope is intentionally limited to upload and validation. Do not use it for row-by-row configuration creation, editing, deletion, template export, source preview, or enum management.
+
+## Discover the deployed contract
+
+```bash
+ae-cli capability search "cross_source_config" --domain metadata --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.upload --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.check --project-id <project_id>
+ae-cli capability inspect metadata.cross_source_config.check_status --project-id <project_id>
+ae-cli analysis input-file purpose list --project-id <project_id>
+```
+
+The expected catalog contains only:
+
+- `metadata.cross_source_config.upload`
+- `metadata.cross_source_config.list`
+- `metadata.cross_source_config.check`
+- `metadata.cross_source_config.check_status`
+
+Use the **metadata** namespace; it routes through the analysis gateway. The deployed catalog and each capability's `input_schema` are authoritative. If upload purpose or a capability is unavailable, report that the Host has not deployed this workflow. Do not fall back to page REST, MCP, browser tokens, or direct database writes.
+
+## Upload a workbook
+
+1. Prepare the product-compatible XLS/XLSX configuration workbook from the user's source table and mapping requirements. If the workbook format is uncertain, obtain a current sample or use the page documentation before writing it; do not guess sheet names or column headers.
+2. Upload the bytes once:
+
+   ```bash
+   ae-cli analysis input-file upload \
+     --project-id <project_id> \
+     --purpose cross_source_config.workbook \
+     --file ./configured.xlsx
+   ```
+
+3. Retain `data.input_file_id`. It is bound to the authenticated user, project, purpose, and expiry. A local path is never an `input_file_id`.
+4. Inspect the upload capability, then execute it once:
+
+   ```bash
+   ae-cli capability run metadata.cross_source_config.upload \
+     --input '{"project_id":<project_id>,"input_file_id":"<input_file_id>","lang":"zh"}'
+   ```
+
+Upload is a synchronous call to the same import service used by the Asset Center page. It creates new route codes and updates existing route codes contained in the workbook. It does not delete configurations absent from the workbook. Because an existing route can be replaced, `upload` is `high-risk-write` and requires user review before execution. Use the CLI confirmation prompt interactively; in non-interactive execution, append the global `--yes` flag only after the exact upload has been authorized.
+
+`status=success` means workbook parsing and persistence completed. If `requires_review=true`, inspect `result.fail` and open `page_url`. An error response keeps the business result in `meta.business_result`. Do not automatically retry after a timeout or lost response; call `list` and inspect the page first.
+
+## Validate uploaded configurations
+
+List configurations to resolve real IDs and current states:
+
+```bash
+ae-cli capability run metadata.cross_source_config.list \
+  --input '{"project_id":<project_id>}'
+```
+
+Submit validation only for explicit IDs from that project:
+
+```bash
+ae-cli capability run metadata.cross_source_config.check \
+  --input '{"project_id":<project_id>,"ids":[<route_id>]}'
+```
+
+Then poll the same ID set with a bounded interval:
+
+```bash
+ae-cli capability run metadata.cross_source_config.check_status \
+  --input '{"project_id":<project_id>,"ids":[<route_id>]}'
+```
+
+Interpret the aggregate fields before reading individual `items`:
+
+- `status=checking`, `completed=false`: wait and poll again.
+- `status=un_checked`, `completed=false`: validation has not been submitted for every selected configuration; `next_action=check`.
+- `status=check_success`, `completed=true`, `successful=true`: all selected configurations passed.
+- `status=check_fail`, `completed=true`, `successful=false`: inspect each item's `msg_map` and open `page_url`.
+
+A successful gateway envelope only means the read succeeded. Validation passes only when `successful=true`. Do not resubmit `check` while a selected configuration is already `checking`.
+
+## Page handoff
+
+`list`, `upload`, `check`, and `check_status` return `page_path`. ae-cli converts it to a Host-qualified `page_url`. Surface this URL after upload warnings, validation failures, or whenever the user asks to review the configurations visually.
+
+Gateway `validate` and `dry-run` validate input, project scope, selected IDs, and uploaded-file ownership. They do not parse/import the workbook or start configuration validation.

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

@@ -22,7 +22,7 @@ For `operation=settings`:
 - `zone_offset` is an integer hour offset from `-12` to `14`;
 - complex settings belong in snake_case `payload`: `reports_version` string, `dashboard_job_schedule` string, `time_config_open` boolean, and object fields `time_config`, `cache_config`, `schedule_ui_config`; `ui_config` may be a string or object.
 
-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=note-upsert`, `dashboard_id` is required. Omit `note_id` to create a note attached to that dashboard, or pass it to update an existing note. A created note defaults missing `note_title` and `description` to empty strings. An update preserves `note_title`, `description`, and `ui_config` when the corresponding field is omitted; pass an explicit empty string to clear text. 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.
 

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

@@ -6,7 +6,7 @@ Do not use it for uploaded-ID tags; use `user-tag create-id`. A successful creat
 
 The response reports this directly: `computation.triggered_automatically=true`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow `next_action`; when it is `poll_get`, invoke `next_capability_id` with the exact `next_input` returned by the command.
 
-Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`. The tag type comes from `definition_request.type`.
+Flags: `--project-id`, `--tag-name`, `--display-name`, `--definition-request` required. Optional: `--authenticated-only`, `--zone-offset`, `--entity-id`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type`.
 
 `tag_name` is a machine identifier: 1-80 characters, starts with a letter, and contains only letters, digits, or underscores. `display_name` is 1-80 characters. The CLI rejects violations before dispatch.
 
@@ -23,3 +23,25 @@ First/last tag for this month:
 ```bash
 ae-cli analysis user-tag create --project-id <project_id> --tag-name latest_platform_this_month --display-name "Latest Platform This Month" --definition-request '{"type":"first_last","first_last":{"event":"login","occurrence":"last","property":"platform","time_range":{"mode":"recent","unit":"month","value":1}}}'
 ```
+
+Periodic refresh can be configured in this same create operation. It is separate from the initial computation. Omitted scheduling flags leave periodic refresh disabled; supplying a schedule enables it. `--enable-auto-refresh true` requires a schedule on create. Do not combine `--enable-auto-refresh false` with a schedule, or pass both schedule forms.
+
+Append one of these options to the create command:
+
+```bash
+# Every day at 02:30 in the tag timezone
+--auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Monday and Sunday at 09:00 (ISO weekdays: 1=Monday, 7=Sunday)
+--auto-refresh-schedule '{"frequency":"weekly","time":"09:00","weekdays":[1,7]}'
+
+# The 1st and 15th of each month at 06:00
+--auto-refresh-schedule '{"frequency":"monthly","time":"06:00","month_days":[1,15]}'
+
+# Custom Quartz schedule, including multiple executions per day
+--auto-refresh-cron '0 0/30 8-18 * * ? *'
+```
+
+`time` uses 24-hour `HH:mm`. `month_days` accepts 1-31; dates absent from a month are skipped. Weekly/monthly schedules require their respective day array; other frequencies reject those fields. The structured form preserves the page's daily/weekly/monthly frequency selection. Cron uses the page's custom schedule mode and preserves every cron field.
+
+Schedules use the tag timezone. Use the existing `--zone-offset` only with an offset supported by the project; omit it to use the project's default behavior. Inspect `user-tag get` for `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset` after creation.

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

@@ -24,12 +24,20 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+
+Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
 ```json
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Percentile example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+```
+
 ## First/last tag
 
 Required: `event`, `occurrence=first|last`, and exactly one value source: `calculation` or `property`. `time_range` and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Supplying neither or both value sources is rejected before execution. Use the semantic time mappings in [`audience_models.md`](audience_models.md) for dynamic ranges such as today, this month, or a fixed start date through today.

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

@@ -2,11 +2,11 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag 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. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances 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`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
+Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 
 `display_name` is at most 80 characters and `remark` is at most 400 characters. The CLI rejects violations before dispatch. `tag_name` is an existing exact identifier and cannot be renamed by update.
 
@@ -17,3 +17,15 @@ ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level
 
 ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-cron '0 30 2 * * ? *'
 ```
+
+Omitting scheduling flags preserves the existing enable state and schedule, including during a definition update. Omitting `--zone-offset` preserves the saved tag timezone. `--enable-auto-refresh true` can reuse an existing saved plan; if none exists, provide a new schedule. `--enable-auto-refresh false` disables periodic refresh. Do not combine false with a schedule or pass both schedule forms. Structured schedule fields and timezone rules are described in [user_tag_create.md](user_tag_create.md).
+
+```bash
+# Enable daily refresh in one update
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --auto-refresh-schedule '{"frequency":"daily","time":"02:30"}'
+
+# Disable periodic refresh
+ae-cli analysis user-tag update --project-id <project_id> --tag-name user_level --enable-auto-refresh false
+```
+
+Read `user-tag get` after updating to verify `enable_auto_refresh` (1=enabled, 0=disabled), `scheduler_ui_config`, and `cluster_zone_offset`. Schedule-only updates return `computation.status=not_triggered` and `next_action=none`.