@thinkingai/ae-cli 6.1.20 → 6.1.23

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

@@ -1,178 +1,28 @@
-# analysis capability-gateway commands
+# Analysis capability-gateway commands
 
-> Prerequisite: follow [`../SKILL.md`](../SKILL.md), especially `PROJECT_ID_GATE`.
+Follow [`../SKILL.md`](../SKILL.md) for project resolution, personal preferences, command routing, evidence reuse, and authorization.
 
-These commands use the capability gateway instead of MCP tool names. The CLI command shape is:
+Gateway command paths use `ae-cli <service> <resource> <action>` with kebab-case flags and snake_case input. Services include `analysis`, `analysis-meta`, `analysis-governance`, `project`, `system`, and `tracking`; use the exact registered command path. Before execution, read its dedicated reference. If the family is unknown, search only matching rows in [`command_index.md`](command_index.md), which is the generated command, capability ID, flag, and risk inventory.
 
-```bash
-ae-cli analysis <resource> <action> [options]
-```
-
-Flags use kebab-case. The gateway input JSON uses snake_case. Do not pass camelCase flags or payload keys unless a nested backend DTO explicitly requires them inside `--payload`.
-
-This file is an overview only. Before running an L2 command, read the dedicated command reference named `references/<resource>_<action>.md` with hyphens converted to underscores, for example `dashboard_report_data_export.md`. L3 capabilities without a dedicated reference use dynamic discovery per [`ae-capability`](../../ae-capability/SKILL.md) and the L3 section below.
-
-For analysis data retrieval commands, read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing `run` or `export`. That routing policy applies only to analysis data retrieval and must not be generalized to other `te-cli` business modules.
-
-## When to use
-
-Use these commands for ad-hoc model analysis, report definition/data/management, dashboard, BI panel and panel versions, project-space, folder, favorite, public-link, dashboard-definition, dashboard-daily-report, dashboard/BI page data, metadata governance, and user cluster/tag/history-tag workflows.
-
-When the routing policy chooses async artifact retrieval, use export commands:
-
-```bash
-ae-cli analysis dashboard-report-data export --project-id 1 --dashboard-id 1001
-ae-cli analysis report-data export --project-id 1 --report-ids '[1001]'
-ae-cli analysis run inspect --run-id run_0123456789abcdef0123456789abcdef
-ae-cli analysis artifact download --run-id run_0123456789abcdef0123456789abcdef --artifact-id artifact_0123456789abcdef0123456789abcdef --output /tmp/dashboard.jsonl.gz
-ae-cli analysis bi-panel-page-data export --project-id 1 --panel-id 2001 --page-key main --result-type charts
-ae-cli analysis query cancel --run-id run_0123456789abcdef0123456789abcdef
-```
+Use this overview for analysis assets and lifecycle routing. Do not use it as a substitute for a command's input contract or infer commands from old MCP names. An unsupported capability is a gap in the current host, not permission to invent a route.
 
-## When not to use
+## Result retrieval and lifecycle
 
-Do not use these commands for schema helpers, alerts, project lookup, dashboard locks, BI panel locks, dashboard filters, UI reorder/tree/move operations, daily report retry/download/get-config, or public-link logs/source-list/get. Use the existing `+<tool_name>` references for those.
+Read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) for the supported run/export choice, result reading and preview limits. Ordinary reads execute directly when the target and complete definition are known. Use saved definitions when semantically equivalent; batch compatible metrics and reuse successful results.
 
-## Output
+Export submission returns one `run_id` / `artifact_id` pair. `--output <file>` waits and downloads; `--wait` waits without downloading. After local interruption, resume with `analysis run wait --run-id <run_id>` and the returned artifact identity. Completion requires both `status=SUCCEEDED` and `artifact_status=COMPLETED`; submission alone is not completion. Local interruption does not cancel a remote query. Cancellation uses the explicit `analysis query cancel` command with the required authorization.
 
-All commands return the gateway envelope:
+The JSON envelope distinguishes success, empty success, partial results, and failures. Use bounded results directly; save stdout only for local processing or a requested file, keeping stderr visible. Exports do not create interactive query contexts. For synchronous follow-up, fetch `analysis query-context get` and use only the advertised action and returned selectable coordinate fragments with the original project ID.
 
-```json
-{
-  "ok": true,
-  "data": {},
-  "meta": {}
-}
-```
+## SQL and governance input
 
-Failures return:
-
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "INVALID_QUERY_REQUEST",
-    "message": "..."
-  }
-}
-```
+For SQL, discover an unknown authorized table with [`sql_table_list.md`](sql_table_list.md), inspect its exact reference through [`sql_table_columns.md`](sql_table_columns.md), and reuse verified columns in the same scope. Keep the same `usage` in both commands. Apply the discovered event-table date partition predicate and quote special identifiers. Generic data-table metadata does not establish SQL authorization.
 
-Export commands return `run_id`, `artifact_id`, `status`, `artifact_status`, `expires_at`, and `expires_at_iso`. They do not expose raw inspect/download API paths.
-
-Artifact workflow:
-
-1. Submit an export command and keep `data.run_id` and `data.artifact_id`.
-2. Poll `ae-cli analysis run inspect --run-id <run_id>` every few seconds until `data.status` is terminal and `data.artifact_status` is complete.
-3. Terminal success is `COMPLETED` or `SUCCEEDED`; terminal failure is `FAILED`, `CANCELED`, or `CANCELLED`. On failure, report the returned error fields instead of downloading.
-4. Download with `ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>`.
-5. Cancel long or abandoned exports with `ae-cli analysis query cancel --run-id <run_id>`.
-
-Prefer the run/artifact commands over hand-written HTTP, Python, or curl. Analysis exports never create interactive `query_context_id`; drilldown coordinates exist only in bounded synchronous previews.
-
-## Command matrix
-
-| Command | Capability ID | Use for | Key input | Output |
-| --- | --- | --- | --- | --- |
-| `filter-value list` | `analysis.filter_value.list` | Resolve exact stored values for one known event/user property before building a filter; not property discovery or aggregation | `--property-name`, `--table-type`, optional event/prefix/snapshot inputs | Candidate values in `items` |
-| `query-cluster list` | `analysis.query_cluster.list` | List physical 查询集群/data-routing options; not 用户分群/audience assets | `--project-id` | Current/accessible slave clusters and allowed routing parameters |
-| `adhoc run` | `analysis.adhoc.run` | Unified ad-hoc inline query for 12 AI models: 9 common + 3 scenario models | `--project-id`, `--model-type`, AI-facing `--definition`, optional physical cluster route | Inline data plus actual route and optional `query_context_id` |
-| `adhoc export` | `analysis.adhoc.export` | Unified ad-hoc async export for 12 AI models: 9 common + 3 scenario models | same as run, plus optional `--artifact-format`; no inline `--limit` | Async artifact descriptor; no drilldown context |
-| `drilldown-events run/export` | `analysis.query.drilldown_events` / `analysis.query.drilldown_events_export` | Preview or full-stream events for an advertised `EVENT_LIST` cell | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate` | Bounded event rows or `csv.gz` artifact |
-| `drilldown-entities run/export` | `analysis.query.drilldown_entities` / `analysis.query.drilldown_entities_export` | Preview/export users or custom entities for an advertised entity cell | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate` | Subject plus entity rows/artifact |
-| `query drilldown-user-events` | `analysis.query.drilldown_user_events` | Query one drilldown user's event sequence | `--project-id`, `--drilldown-context-id`, `--user-id` | Event sequence rows |
-| `query create-result-cluster` | `analysis.query.create_result_cluster` | Save the advertised user/custom-entity cell population as its result cluster | `--project-id`, `--query-context-id`, optional `--source`, `--coordinate`, `--cluster-name` | Result cluster creation result |
-| `report list` | `analysis.report.list` | Find accessible reports | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated report summaries |
-| `report list-export` | `analysis.report.list_export` | Export report catalog | same as list, plus optional `--artifact-format`, `--request-id` | Async artifact descriptor |
-| `report get` | `analysis.report.get` | Inspect current report definition as AI QP | `--project-id`, `--report-id` | Report metadata plus `model_type` and `definition` |
-| `report create` | `analysis.report.create` | Create a report from AI QP definition | `--report-name`, `--model-type`, `--definition` | Created report ID and normalized definition |
-| `report update` | `analysis.report.update` | Update metadata or AI QP definition | `--report-id`, `--report-version`, update fields | Update result |
-| `report delete` | `analysis.report.delete` | Delete reports | `--report-ids '[...]'` | Delete result |
-| `report-data run` | `analysis.report_data.run` | Bounded inline report data | `--report-ids`, optional overrides, `--cluster-query-scope`, conditional `--slave-cluster-id`, time/limit | Inline data plus actual route and optional `query_context_id` |
-| `report-data export` | `analysis.report_data.export` | Large/long report data | same as run, plus optional `--artifact-format` | Async artifact descriptor; no drilldown context |
-| `query cancel` | `analysis.query.cancel` | Cancel any async analysis export | `--run-id`, optional `--reason` | Cancellation result |
-| `report-change-log list` | `analysis.report_change_log.list` | List one report's change logs | `--report-id` | Change log summaries |
-| `report-change-log get` | `analysis.report_change_log.get` | Inspect one change log detail | `--report-id`, optional `--history-version` | Change log detail with AI QP definition when available |
-| `report-version rollback` | `analysis.report_version.rollback` | Rollback a report version | `--report-id`, `--target-version` | Rollback result |
-| `report-abnormal get` | `analysis.report_abnormal.get` | Inspect report abnormal dependencies | `--report-id` | Abnormal info |
-| `dashboard-report add` | `analysis.dashboard_report.add` | Add reports to a dashboard | `--dashboard-id`, `--report-ids` | Add result |
-| `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, 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 |
-| `dashboard handover` | `analysis.dashboard.handover` | Transfer dashboards | `--dashboard-ids`, `--to-user-id` | Handover result |
-| `dashboard copy` | `analysis.dashboard.copy` | Copy a dashboard; omitted target IDs copy to the source location | `--dashboard-id`, `--dashboard-name`, optional target IDs | Copied dashboard |
-| `dashboard freeze` | `analysis.dashboard.freeze` | Freeze/unfreeze dashboards | `--dashboard-ids`, optional `--freeze false` | Freeze status |
-| `dashboard abnormal-get` | `analysis.dashboard.abnormal_get` | Inspect abnormal dependencies | `--dashboard-id` | Abnormal info |
-| `dashboard task-status` | `analysis.dashboard.task_status` | Inspect scheduled task status | `--dashboard-id` | Task status |
-| `dashboard-report-data run` | `analysis.dashboard_report_data.run` | Bounded inline dashboard report data; omitted route follows saved dashboard configuration | `--dashboard-id`, optional reports/filters/time and physical cluster route | Inline data plus actual route and optional `query_context_id` |
-| `dashboard-report-data export` | `analysis.dashboard_report_data.export` | Large/long dashboard report data | same as run, plus optional `--artifact-format jsonl` | Async artifact descriptor; no drilldown context |
-| `run inspect` | `analysis.run.inspect` | Poll async export status | `--run-id` | Run and artifact status |
-| `artifact download` | `analysis.artifact.download` | Download run-bound export artifact | `--run-id`, `--artifact-id`, `--output` | Local output file info |
-| `query cancel` | `analysis.query.cancel` | Cancel gateway run/export | `--run-id`, optional `--reason` | Cancellation result |
-| `dashboard-definition export` | `analysis.dashboard_definition.export` | Export dashboard definition JSON | `--dashboard-id`, `--dashboard-ids`, `--dashboard-folder-ids`, `--shared-spaces`, or `--payload` | Definition JSON |
-| `dashboard-definition import` | `analysis.dashboard_definition.import` | Validate/import dashboard definition | `--definition`, optional `--validate-only true` | Validation or import result |
-| `dashboard-daily-report get` | `analysis.dashboard_daily_report.get` | Get one saved daily report config with secrets and webhook URLs redacted | `--dashboard-id` | Config state |
-| `dashboard-daily-report update` | `analysis.dashboard_daily_report.update` | Patch-style create or update; omitted fields remain unchanged | `--dashboard-id`, optional config flags or `--payload` | Config result |
-| `dashboard-daily-report send` | `analysis.dashboard_daily_report.send` | Send immediately; destination fields infer channels, omission reuses saved destinations | `--dashboard-id`, optional destination/content flags or `--payload` | Async task ID |
-| `dashboard-daily-report send-status` | `analysis.dashboard_daily_report.send_status` | Inspect one immediate-send task and per-channel outcome | `--task-id` | Send task status |
-| `bi-panel list` | `analysis.bi_panel.list` | Find accessible BI panels | `--project-id`, optional list filters | Paginated BI panel summaries |
-| `bi-panel get` | `analysis.bi_panel.get` | Inspect released BI panel page structure only | `--panel-id`, optional `--fields` | Panel structure |
-| `bi-panel create` | `analysis.bi_panel.create` | Create an empty BI panel shell | required `--panel-name`; optional destination IDs | Created shell identifiers |
-| `bi-panel update` | `analysis.bi_panel.update` | Rename a BI panel without changing content | required `--panel-uuid`, `--panel-name` | Rename result |
-| `bi-panel delete` | `analysis.bi_panel.delete` | Delete BI panels | `--panel-ids '[...]'` | Delete result |
-| `bi-panel share` | `analysis.bi_panel.share` | Modify BI panel sharing | `--panel-id`, `--payload` | Share update result |
-| `bi-panel copy` | `analysis.bi_panel.copy` | Copy a BI panel | optional source/target flags and `--payload` | Copied panel |
-| `bi-panel-version get` | `analysis.bi_panel_version.get` | Inspect BI panel released or draft version | `--panel-id` or `--panel-uuid`, optional `--version-type release|draft` | Version detail |
-| `bi-panel-version publish` | `analysis.bi_panel_version.publish` | Publish current BI panel draft after source version matches | `--panel-id` or `--panel-uuid`, `--source-version` | Published version |
-| `bi-panel-page-data run` | `analysis.bi_panel_page_data.run` | Bounded inline BI page data | `--panel-id`, `--page-key`, `--result-type charts|summary` | Inline page data |
-| `bi-panel-page-data export` | `analysis.bi_panel_page_data.export` | Large/long BI page data | same as run, optional `--artifact-format jsonl` | Async artifact descriptor |
-| `project-space list` | `analysis.project_space.list` | Find accessible project spaces | `--project-id`, optional list filters | Paginated project spaces |
-| `project-space business-filter-upsert` | `analysis.project_space.business_filter_upsert` | Create or replace the space-level business filter | `--project-id`, `--space-id`, `--filter` | Saved space filter |
-| `project-space get` | `analysis.project_space.get` | Inspect one project space | `--project-id`, `--space-id` | Project space detail |
-| `favorite add` | `analysis.favorite.add` | Favorite dashboard/BI/folder | required `--asset-id`, `--asset-type`; optional `--space-id` | Favorite result |
-| `favorite remove` | `analysis.favorite.remove` | Remove favorite | same as add | Remove result |
-| `public-link create` | `analysis.public_link.create` | Generate public link | `--resource-type`, `--resource-id`, `--effective-at`, `--expires-at` | Link result |
-| `public-link list` | `analysis.public_link.list` | List public links | `--project-id`, optional list filters | Paginated links |
-| `public-link update` | `analysis.public_link.update` | Edit public link | `--link-id`, `--effective-at`, `--expires-at` | Update result |
-| `public-link offline` | `analysis.public_link.offline` | Take links offline | `--link-id` or `--link-ids` | Offline result |
-| `public-link delete` | `analysis.public_link.delete` | Delete public links | `--link-id` or `--link-ids` | Delete result |
-| `user-cluster list` | `analysis.user_cluster.list` | Find accessible user clusters | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated cluster summaries |
-| `user-cluster export` | `analysis.user_cluster.export` | Export complete matching cluster catalog | `--project-id`, optional filters, required `--output` | Local JSONL catalog and integrity sidecar |
-| `user-cluster get` | `analysis.user_cluster.get` | Inspect exact clusters | `--cluster-names '[...]'` | Cluster details |
-| `user-cluster-member list` | `analysis.user_cluster_member.list` | Bounded inline cluster members | `--cluster-name`, optional properties/fields/query/limit/offset | Member rows |
-| `user-cluster-member export` | `analysis.user_cluster_member.export` | Stream native full cluster members as csv.gz | `--cluster-name`, optional properties | Async artifact descriptor |
-| `user-cluster create` | `analysis.user_cluster.create` | Create condition/sql cluster directly from semantic intent | `--cluster-name`, `--display-name`, `--definition-request` | Create result and canonical request |
-| `user-cluster update` | `analysis.user_cluster.update` | Update condition/sql cluster after confirmation without changing its type or analysis entity | `--cluster-name`, fields to change, optional `--definition-request` with the existing type, then `--yes` after dry-run and explicit confirmation | Update result |
-| `user-cluster create-id` | `analysis.user_cluster.create_id` | Map imported values to an entity and create a cluster | `--display-name`, `--entity-id`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
-| `user-cluster update-id` | `analysis.user_cluster.update_id` | Remap imported values for an ID cluster | `--cluster-name`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
-| `user-cluster refresh` | `analysis.user_cluster.refresh` | Trigger cluster recompute | `--cluster-name` | Refresh result |
-| `user-cluster delete` | `analysis.user_cluster.delete` | Delete cluster after dependency review | `--cluster-name`, `--confirmed`, `--yes` | Delete result |
-| `user-tag list` | `analysis.user_tag.list` | Find accessible user tags | `--project-id`, optional `--queries`, `--fields`, `--limit`, `--offset` | Paginated tag summaries |
-| `user-tag export` | `analysis.user_tag.export` | Export complete matching tag catalog | `--project-id`, optional filters, required `--output` | Local JSONL catalog and integrity sidecar |
-| `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, 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 |
-| `user-tag update-id` | `analysis.user_tag.update_id` | Remap imported values for an ID tag | `--tag-name`, exactly one input source, conditional `--association-property` | Processing state; poll get for final match summary |
-| `user-tag delete` | `analysis.user_tag.delete` | Delete tag after dependency review | `--tag-name`, `--confirmed`, `--yes` | Delete result |
-| `history-tag list` | `analysis.history_tag.list` | List history snapshots for a tag | `--tag-name` | Snapshot summaries |
-| `history-tag refresh` | `analysis.history_tag.refresh` | Refresh one history snapshot | `--tag-name`, `--refresh-date` | Refresh result |
-| `history-tag batch-refresh` | `analysis.history_tag.batch_refresh` | Batch refresh snapshots | `--tag-name`, `--refresh-request` | Async refresh result |
-| `history-tag clear` | `analysis.history_tag.clear` | Clear snapshots in date range | `--tag-name`, date range, `--confirmed`, `--yes` | Clear result |
-| `history-tag-data run` | `analysis.history_tag_data.run` | Bounded inline history tag statistics | `--tag-name`, `--view`, optional `--preview-rows` | Statistic result |
-| `history-tag-data export` | `analysis.history_tag_data.export` | Export history tag statistics as jsonl | `--tag-name`, `--view` | Async artifact descriptor |
-| `history-tag-data-drilldown run` | `analysis.history_tag_data_drilldown.run` | Bounded inline users for one statistic value/bucket | `--tag-name`, `--snapshot-date`, `--group-col`, `--view`, optional member fields | Drilldown member rows |
-| `history-tag-data-drilldown export` | `analysis.history_tag_data_drilldown.export` | Stream native full users for one statistic value/bucket as csv.gz | `--tag-name`, `--snapshot-date`, `--group-col`, `--view`, optional properties | Async artifact descriptor |
+For governance commands that expose `--payload`, it is an optional snake_case JSON object merged into top-level input. Explicit flags override its matching business fields, and `--project-id` owns project identity. Required business fields must exist after the merge; this construction does not change server permissions, feature availability, or the published server schema. Read the dedicated reference for the operation's required fields and risk.
 
 ## L3 project-space and folder capabilities
 
-Per [`capability-command-admission` §10](../../../docs/capability-command-admission.md): new gateway capabilities default to **dynamic discovery** (`capability search` → `inspect` →（按需二选一：`validate` **或** `dry-run`，默认不叠打）→ `run`); standalone skill references are **exceptions only** (L2 bar, confusion, high-risk delete, multi-step orchestration).
+Capabilities without a dedicated typed command use dynamic discovery: `capability search` → `inspect` → `run`. Use `validate` while correcting input or `dry-run` for execution/risk preview when needed; do not stack them routinely.
 
 For **create / delete / share**, read the linked reference before `capability inspect` then `run` (optional pre-check per [`ae-capability`](../../ae-capability/SKILL.md) on-demand table). For **`*.members` read**, use this matrix only — no separate `references/*.md` (pilot).
 
@@ -211,22 +61,15 @@ ae-cli capability run analysis.folder.members --input '{"project_id":1,"folder_i
 
 Output is the gateway envelope; `data` contains members.
 
-## Examples
+### Saved business asset or ad-hoc
 
-```bash
-ae-cli analysis dashboard list --project-id 1 --queries '["retention","留存"]' --limit 50
-ae-cli analysis adhoc run --project-id 1 --model-type sql --definition '{"sql":"select * from events limit 20"}'
-ae-cli analysis adhoc export --project-id 1 --model-type sql --definition '{"sql":"select * from events where country ${Text:country}","params":[{"name":"country","type":"text","value":"US"}]}' --artifact-format jsonl
-ae-cli analysis report list --project-id 1 --queries '["revenue","收入"]' --limit 50
-ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --preview-rows 50
-ae-cli analysis report-data run --project-id 1 --report-ids '[1001]' --filters '{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}' --group-by '[{"field":{"name":"country","type":"user_property"}}]' --sql-params '[{"name":"platform","value":"ios"}]' --preview-rows 50
-ae-cli analysis drilldown-entities run --query-context-id ctx_0123456789abcdef0123456789abcdef --source '{"report_id":1001}' --coordinate '{"cohort_date":"2026-07-01","group_values":[],"period_index":1,"population":"retained"}'
-ae-cli analysis query create-result-cluster --query-context-id ctx_0123456789abcdef0123456789abcdef --source '{"report_id":1001}' --coordinate '{"cohort_date":"2026-07-01","group_values":[],"period_index":1,"population":"retained"}' --cluster-name retained_users
-ae-cli analysis dashboard update --project-id 1 --operation note-upsert --dashboard-id 1001 --note-title "Summary" --description "Weekly note"
-ae-cli analysis dashboard-definition export --project-id 1 --dashboard-id 1001 --export-file-name retention_dashboard
-ae-cli analysis dashboard-definition import --project-id 1 --definition '{"dashboard_folders":[],"shared_spaces":[]}' --validate-only true
-ae-cli analysis public-link create --project-id 1 --resource-type dashboard --resource-id 1001 --effective-at "2026-07-08 00:00:00" --expires-at "2026-08-08 00:00:00"
-ae-cli analysis user-cluster list --project-id 1 --queries '["retained","retention"]' --limit 50
-ae-cli analysis user-cluster-member export --project-id 1 --cluster-name retained_users --artifact-format csv
-ae-cli analysis user-tag create --project-id 1 --tag-name user_level --display-name "User Level" --definition-request '{"type":"condition","condition_values":[]}'
-```
+Choose the shortest path that preserves the requested business semantics:
+
+1. Extract metric, dimensions, filters, time window, and comparison semantics.
+2. Use a saved report/dashboard when the user names it, an exact ID or canonical name is already verified, or the conclusion requires its formal business definition.
+3. For unknown business measures, use [metadata resolution](metadata_resolution.md) to search relevant saved metrics and reports together and read suitable definitions. Use dashboard search when the request names a dashboard or its context is needed.
+4. Before querying a selected dashboard's report data, reuse verified detail or call `analysis dashboard get` once. Inspect `effective_settings` and `filter_config`; dashboard default, dashboard business, and space business filters are already applied and call-time filters add AND conditions. Honor the saved fixed time unless the user explicitly supplies a supported time override. Preserve non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` as authored dashboard context; never repeat detail per report. Fetch a report definition only when conclusion semantics are absent, stale, ambiguous, conflicting, or override-required.
+5. Use `analysis adhoc run|export` for a custom combination, grouping, filter, comparison or exploration. Reuse applicable saved definitions and verified metadata, discover only missing fields, then execute the complete definition.
+6. A failed query surface is not evidence that another surface is healthy. Do not switch among saved report, dashboard, ad-hoc, or export merely to re-prove a terminal failure in the same verified failure domain.
+
+Do not call removed QP builders or schema helpers for ad-hoc analysis. `--definition` is the AI-facing contract from `ai_models.md`, not raw QP or a frontend DTO.

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

@@ -1,10 +1,28 @@
 # Analysis interpretation
 
-Use this guide after obtaining comparable result data. It defines how to attribute metric changes and how to distinguish evidence from hypothesis.
+Consult the relevant section for an unfamiliar aggregation, cohort or attribution rule. Query/result handling follows [the retrieval reference](analysis_data_retrieval.md#preserve-and-interpret-results).
+
+## Scope and evidence
+
+Compare the same metric definitions, populations, filters, time grain, timezone and physical route. Check executed windows once: use equal complete, non-overlapping periods or an explicit exposure normalization; label partial periods. Overlapping rolling windows and cumulative stocks are not independent flows. Correct the selected `model_type` branch of schema errors; other model branches do not add requirements.
+
+Use actual titles, row/column metadata, scope and completeness fields. Null, missing, failed, unauthorized, partial, truncated and not-yet-observable values are unknown, not zero. A successful empty query means no matches only in its verified effective scope. A failed item does not invalidate independent successful evidence.
+
+Use completed values with their reported units; round only for display.
+
+## Populations, ratios and grain
+
+Identify the numerator, denominator, analysis unit and eligibility rule before calculating. Weighted overall rates use matching denominator weights; a zero denominator is undefined. For nullable measures, compare source-row and non-null-value coverage. An observed-value average need not describe the whole population.
+
+A share or conversion rate requires a verified subset relationship. Counts from different events may be reported as counts, or explicitly as a ratio of counts; they do not establish user composition. Equal counts do not establish equal sets. A larger count rules out only the direction of containment contradicted by that inequality.
+
+A sum of daily active users is user-days, not distinct period users. Use independent distinct totals for overlapping dates, groups or event sets. Never add totals to detail rows. Before joining sources, verify business keys, join cardinality, unmatched keys and duplicate amplification; display names and row positions are not stable keys.
+
+For compound conditions, preserve unknown: AND is false if any condition is confirmed false, true only if all are true; OR is true if any is true, false only if all are false. Otherwise the result is unknown, including negated unknown.
 
 ## Absolute contribution for additive metrics
 
-Use for counts and sums such as DAU, event count, orders, or payment amount:
+Use matching, exhaustive, non-overlapping groups for amounts, event counts or verified disjoint counts:
 
 ```text
 delta_total = total_comparison - total_baseline
@@ -12,27 +30,29 @@ delta_dimension_i = value_i_comparison - value_i_baseline
 contribution_i = delta_dimension_i / delta_total * 100%
 ```
 
-Rank by `abs(delta_dimension_i)`, preserving the sign. Do not rank primary drivers by relative growth `delta_dimension_i / value_i_baseline`; a tiny baseline can create a large percentage with little effect on the total.
-
-Report each leading dimension's baseline, comparison, absolute delta, relative change, and contribution share. Treat a zero baseline as a new/lost dimension rather than an infinite growth rate.
+Reconcile group deltas to the independent total, then rank by `abs(delta_dimension_i)` with its sign. Report baseline, comparison, absolute and relative changes. Positive/negative contributions can exceed 100% when they offset. A zero baseline makes relative growth undefined; a zero total delta makes contribution shares undefined. Explain unmatched scope or residuals; derive rounding tolerance from displayed precision, not an arbitrary percentage.
 
-## Ratio and conversion metrics
+## Ratio and conversion decomposition
 
-A ratio changes because subgroup rates change, subgroup composition changes, or both. First report numerator, denominator, and subgroup rates. When the user requests structural decomposition, use:
+Use only when structural attribution is requested and groups are exhaustive and mutually exclusive. Show underlying numerators and denominators; weights are denominator shares:
 
 ```text
-rate_effect_i = weight_i_baseline * (rate_i_comparison - rate_i_baseline)
-composition_effect_i = (weight_i_comparison - weight_i_baseline) * rate_i_baseline
+rate_effect_i = ((weight_i_baseline + weight_i_comparison) / 2) * (rate_i_comparison - rate_i_baseline)
+composition_effect_i = ((rate_i_baseline + rate_i_comparison) / 2) * (weight_i_comparison - weight_i_baseline)
 ```
 
-Keep rate effects and composition effects separate. Do not apply additive-count contribution directly to conversion rates.
+The effects sum to the total rate change. Base-weight/base-rate formulas require the interaction term separately or split equally as above. An undefined subgroup rate cannot be replaced with zero; report unmatched groups or a justified common partition. Percentage-point changes differ from relative percentages. Multiplying a fixed denominator by a rate change is a conditional arithmetic scenario, not observed incremental users or causal impact.
+
+## Retention and mature cohorts
+
+The initial window selects entry-date cohorts. Daily D1 needs return observations through the day after the final entry date. Keep the requested entry window unchanged; adding a day adds a cohort and moves the required observation end.
 
-## Workflow and checks
+Report the observed Dn numerator and denominator from actual count rows. Select the cohort set once and sum both counts over that same set:
+
+```text
+rate_n = sum(retained_count_d_n for d in selected_cohorts) / sum(initial_count_d for d in selected_cohorts)
+```
 
-1. Keep project, population, filters, dimensions, timezone, and aggregation identical across periods.
-2. Prefer one query with comparison mode when the model supports it; otherwise run two definitions that differ only in time.
-3. Compute deltas and sort by absolute contribution.
-4. Verify additive dimension deltas reconcile with the total delta. If contribution shares differ from 100% by more than 5 percentage points, flag missing dimensions or inconsistent scope.
-5. Call a cause “observed” only when the data directly demonstrates it. Product releases, campaigns, and incidents remain hypotheses until independently verified.
+Never average daily percentages, mix excluded cohorts into either side, add stage totals to details or reconstruct exact counts from rounded rates. Cohort memberships across entry dates are not period-distinct users. A stage initial total may include cohorts outside a particular Dn denominator. Read the actual labels and columns; these formula variables are not JSON field names.
 
-Skip cross-dimension contribution only when the user explicitly asks for percentage ranking or a single dimension's trend.
+Call a rate mature only with evidence of both elapsed observation time and complete data arrival. `has_more=false` concerns truncation and `data_time_range` concerns returned cohort dates; neither is an arrival watermark. Without arrival evidence, say **observed Dn rate; data completeness unverified**. This is a usable observation, not proof of churn. Past dates, repeating the query, or dropping the last cohort do not establish complete arrival. Missing returns from an incomplete observation window are not confirmed zero or churn; returned values remain observations. D1 does not establish cross-week retention or the composition of weekly active users.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta asset-abnormal get --project-id <project_id> --resource-type <resource_type> --resource-id <resource_id> --resource-name <resource_name> --table-type <table_type>
-ae-cli analysis-meta asset-abnormal get --dry-run
 ```
 
 Capability id: `metadata.asset_abnormal.get`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta asset-abnormal list --project-id <project_id> --resource-types <resource_types> --limit 50 --offset 0
-ae-cli analysis-meta asset-abnormal list --dry-run
 ```
 
 Capability id: `metadata.asset_abnormal.list`.

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

@@ -2,6 +2,8 @@
 
 Use for complete offline processing of project asset-authentication rows.
 
+This is a certification-state management export, not the CLI Agent recommendation workflow. For review recommendations that combine asset authentication and metric candidates from hot dashboard/report evidence, use `analysis-meta governance-recommendation export`.
+
 Do not use it for interactive preview or let the CLI loop over `list`; this command invokes the complete export capability once.
 
 Command:
@@ -20,3 +22,5 @@ The command does not accept `limit` or `offset` and performs exactly one complet
 Export projection always retains `resource_type`, `resource_key`, `display_name`, `authentication_status`, `heat_count90d`, `user_count90d`, and `impact_degree`; `--fields` can add or remove only optional descriptive and owner fields.
 
 Use the sidecar `snapshot_hash` with `update --expected-snapshot-hash` when the selected asset set was derived from this export.
+
+Do not use this export to rank assets locally and present those rows as recommendations.

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

@@ -2,9 +2,11 @@
 
 Use for bounded online preview, search, and filtering of project asset-authentication rows.
 
+This is a certification-state management command, not the CLI Agent recommendation workflow. For asset-authentication and metric-recommendation review, use `analysis-meta governance-recommendation export` first.
+
 This command filters on the server before sorting and pagination. Use `export` for a complete offline dataset and `update` for an explicit typed asset set.
 
-Do not use it to synthesize a complete catalog by paging or to change authentication state.
+Do not use it to synthesize a complete catalog by paging, to change authentication state, or to generate recommendations.
 
 Command:
 
@@ -14,12 +16,16 @@ ae-cli analysis-governance asset-authentication list --project-id <project_id> -
 
 Capability id: `governance.asset_authentication.list`.
 
+This is the canonical typed management route from the asset-governance branch. The older `analysis-meta asset-authentication list` route remains a compatibility view with only project and pagination fields.
+
 `match=any|all` combines only the supplied numeric thresholds. Asset types, authentication status, and keyword queries are always AND filters. `queries` matches any supplied keyword.
 
 Output uses `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Row identity is always `resource_type + resource_key`; dashboard and report keys are numeric IDs encoded as strings, while metadata assets use business names.
 
 ## analysis-meta asset-authentication list
 
+Capability id: `metadata.asset_authentication.list`.
+
 The legacy command remains available for one release cycle and returns the old row shape.
 
 ```bash

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

@@ -13,11 +13,13 @@ ae-cli analysis-governance asset-authentication update --project-id <project_id>
 Large file command:
 
 ```bash
-ae-cli analysis-governance asset-authentication update --project-id <project_id> --authentication-status 1 --asset-file /tmp/selected-assets.jsonl --expected-snapshot-hash <snapshot_hash> --dry-run
+ae-cli analysis-governance asset-authentication update --project-id <project_id> --authentication-status 1 --asset-file /tmp/selected-assets.jsonl --expected-snapshot-hash <snapshot_hash>
 ```
 
 Capability id: `governance.asset_authentication.update`.
 
+This is the canonical typed management route from the asset-governance branch. The older `analysis-meta asset-authentication update` route remains a compatibility payload wrapper.
+
 Choose exactly one identity input:
 
 - `--asset-refs` for an inline typed array.
@@ -30,6 +32,8 @@ The response includes requested, resolved, changed, unchanged, and failed counts
 
 ## analysis-meta asset-authentication update
 
+Capability id: `metadata.asset_authentication.update`.
+
 The legacy `--payload` entry remains available for one release cycle.
 
 ```bash

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

@@ -7,13 +7,12 @@ Do not use it for non-dashboard assets or ordinary dashboard content edits; it c
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-dashboard-schedule-freeze --project-id <project_id> --payload '{}'
-ae-cli analysis-governance asset batch-dashboard-schedule-freeze --dry-run --project-id <project_id>
+ae-cli analysis-governance asset batch-dashboard-schedule-freeze --project-id <project_id> --node-ids '["<node_id>"]'
 ```
 
-Capability id: analysis_meta.asset_batch.dashboard_schedule_freeze.
+Capability id: governance.asset.batch_dashboard_schedule_freeze.
 
-Input sends project_id, payload, node_ids, reports_version, zone_offset, schedule_ui_config, dashboard_status, refresh_type, cache_config. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends `project_id`, `node_ids`, and optional `schedule_ui_config`, `dashboard_status`, `refresh_type`, and `cache_config`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is the dashboard batch-operation submission result. Verify its returned operation record before reporting the schedules as frozen.
 
@@ -22,5 +21,8 @@ Output `data` is the dashboard batch-operation submission result. Verify its ret
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
-| --dashboard-status | No | Dashboard status, such as freeze or normal. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --dashboard-status | No | Dashboard status: `freeze` or `normal`. |
+| --schedule-ui-config | No | Dashboard schedule configuration as a JSON object or string. |
+| --refresh-type | No | Dashboard refresh type: 1 enabled, 0 disabled. |
+| --cache-config | No | Dashboard cache configuration as a JSON object or string. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids` is a non-empty string array; configuration fields accept objects or strings. |

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

@@ -7,20 +7,20 @@ Do not use it for a single unverified name or as cleanup after a failed test; re
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-delete --project-id <project_id> --payload '{}' --dry-run
+ae-cli analysis-governance asset batch-delete --project-id <project_id> --node-ids '["<node_id>"]' --dry-run
 # Summarize the target and impact, then wait for explicit user confirmation.
-ae-cli analysis-governance asset batch-delete --project-id <project_id> --payload '{}' --yes
+ae-cli analysis-governance asset batch-delete --project-id <project_id> --node-ids '["<node_id>"]' --yes
 ```
 
-Capability id: analysis_meta.asset_batch.delete.
+Capability id: governance.asset.batch_delete.
 
-Input sends project_id, payload, node_ids. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, node_ids. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
-Output `data` is the batch-operation submission result. Preserve any returned record identity/status and use `operation-record-list` to verify completion.
+Output `data` is the batch-operation submission result. Preserve any returned record identity/status and use `operation-record list` to verify completion.
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -7,13 +7,12 @@ Do not use it to disable auto updates; this command disables backup behavior and
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-disable-auto-backup --project-id <project_id> --payload '{}'
-ae-cli analysis-governance asset batch-disable-auto-backup --dry-run --project-id <project_id>
+ae-cli analysis-governance asset batch-disable-auto-backup --project-id <project_id> --node-ids '["<node_id>"]'
 ```
 
-Capability id: analysis_meta.asset_batch.disable_auto_backup.
+Capability id: governance.asset.batch_disable_auto_backup.
 
-Input sends project_id, payload, node_ids, clear_history_tag. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, node_ids, clear_history_tag. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is the batch-operation submission result. Preserve its record/status so the operation can be audited without resubmission.
 
@@ -23,4 +22,4 @@ Output `data` is the batch-operation submission result. Preserve its record/stat
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
 | --clear-history-tag | No | Whether to clear tag history: 1 yes, 0 no. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -7,15 +7,14 @@ Do not use it to disable backups or freeze dashboard schedules; this operation o
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-disable-auto-update --project-id <project_id> --payload '{}'
-ae-cli analysis-governance asset batch-disable-auto-update --dry-run --project-id <project_id>
+ae-cli analysis-governance asset batch-disable-auto-update --project-id <project_id> --node-ids '["<node_id>"]'
 ```
 
-Capability id: analysis_meta.asset_batch.disable_auto_update.
+Capability id: governance.asset.batch_disable_auto_update.
 
-Input sends project_id, payload, node_ids, refresh_type. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, node_ids, refresh_type. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
-Output `data` is the batch-operation submission result. Follow the returned record/status through `operation-record-list` instead of repeating the command.
+Output `data` is the batch-operation submission result. Follow the returned record/status through `operation-record list` instead of repeating the command.
 
 ## Parameters
 | Parameter | Required | Description |
@@ -23,4 +22,4 @@ Output `data` is the batch-operation submission result. Follow the returned reco
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
 | --refresh-type | No | Dashboard refresh type: 1 enabled, 0 disabled. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -7,13 +7,12 @@ Do not use it to share assets or modify permissions; it transfers ownership of v
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-handover --project-id <project_id> --payload '{}'
-ae-cli analysis-governance asset batch-handover --dry-run --project-id <project_id>
+ae-cli analysis-governance asset batch-handover --project-id <project_id> --node-ids '["<node_id>"]' --to-user-id <user_id>
 ```
 
-Capability id: analysis_meta.asset_batch.handover.
+Capability id: governance.asset.batch_handover.
 
-Input sends project_id, payload, node_ids, to_user_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, node_ids, to_user_id. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is the ownership-transfer batch submission result. Confirm completion from its operation record rather than assuming submission equals handover.
 
@@ -23,4 +22,4 @@ Output `data` is the ownership-transfer batch submission result. Confirm complet
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
 | --to-user-id | No | Target user ID; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids`, `searchs`, and `status` are arrays; `rule` is an object when supplied. |

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

@@ -7,13 +7,12 @@ Do not use it to change the selected assets or export SQL definitions; it create
 Command:
 
 ```bash
-ae-cli analysis-governance asset batch-info-export --project-id <project_id> --payload '{}'
-ae-cli analysis-governance asset batch-info-export --dry-run --project-id <project_id>
+ae-cli analysis-governance asset batch-info-export --project-id <project_id> --node-ids '["<node_id>"]'
 ```
 
-Capability id: analysis_meta.asset_batch.info_export.
+Capability id: governance.asset.batch_export_info.
 
-Input sends project_id, payload, node_ids, reports_version, zone_offset, schedule_ui_config, dashboard_status, refresh_type, cache_config, clear_history_tag. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` (1..7200, default 3600) may be supplied through `--payload`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download the returned artifact IDs.
 
@@ -22,4 +21,4 @@ Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status,
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --node-ids | No | Asset node ID JSON array; required unless provided inside payload. |
-| --payload | No | Optional snake_case object carrying the same fields. Use this for complex governance filters or backend-shaped payloads. |
+| --payload | No | Optional JSON object merged into top-level input. Use schema-declared snake_case fields; explicit flags take precedence. `node_ids` is a non-empty string array. Optional export fields are `request_id`, `format`, and `timeout_seconds`. |