@thinkingai/ae-cli 6.1.19 → 6.1.21

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta exchange rule-list --project-id <project_id> --limit 50 --offset 0
-ae-cli analysis-meta exchange rule-list --dry-run
 ```
 
 Capability id: `metadata.exchange_rule.list`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta exchange rule-update --project-id <project_id> --payload '{"target_currency":"USD","exchange_rules":[{"source_currency":"EUR","source_currency_column":"currency","target_column_desc":"amount_usd"}]}'
-ae-cli analysis-meta exchange rule-update --dry-run
 ```
 
 Capability id: `metadata.exchange_rule.update`.

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

@@ -8,7 +8,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta exchange rule-validate --project-id <project_id> --payload '{"target_currency":"USD","exchange_rules":[{"source_currency":"EUR","source_currency_column":"currency","target_column_desc":"amount_usd"}]}'
-ae-cli analysis-meta exchange rule-validate --dry-run
 ```
 
 Capability id: `metadata.exchange_rule.validate`.

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

@@ -0,0 +1,23 @@
+# analysis-meta governance-recommendation decisions
+
+List recent CLI Agent recommendation approval decisions.
+
+Use this to review prior approvals, rejections, skips, and landing status. Do not use it as a substitute for current recommendation evidence; run `governance-recommendation export` when presenting current recommendations.
+
+Command:
+
+```bash
+ae-cli analysis-meta governance-recommendation decisions --project-id <project_id> --limit 100
+```
+
+Capability id: `metadata.governance_recommendation.decisions`.
+
+Input sends `project_id`, optional `run_id`, and optional `limit`.
+
+Output includes `decisions` and `total`.
+
+## Decision Rules
+
+- Use `--run-id` to audit one recommendation packet after submit.
+- Without `--run-id`, treat the result as recent history only.
+- Historical decisions inform presentation and risk explanation; they do not prove current asset state or current metric availability.

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

@@ -0,0 +1,108 @@
+# analysis-meta governance-recommendation export
+
+Requires `project_semantic_enable=on` for the target project. If export returns `PROJECT_SEMANTIC_DISABLED`, report that this project must enable `project_semantic_enable` and stop this workflow. Do not bypass the disabled entry point with other export, metadata, or capability commands.
+
+Use this as the required entry point for CLI Agent asset-authentication and metric-recommendation review.
+
+This command returns one evidence packet seeded from hot shared dashboards and their reports. For normal page-review submission, `--limit 20` is the initial candidate pool; use the bounded expansion procedure below when filtering leaves insufficient candidates. After the command returns, the Agent must transform the returned `work_units` into business-domain review groups before answering. `work_units` are evidence containers, not final answer sections and not an excuse to drop eligible hot dashboards.
+
+Do not use certification-state management commands as a substitute for this recommendation evidence packet.
+Do not load project semantics, project KB, or personal semantic preferences before this command. The recommendation packet is the prerequisite evidence for this review workflow.
+
+Hard output gate: a final answer is invalid if it is grouped by asset type, backend array order, raw `work_units`, source dashboard, source report, or separate top-level asset and metric sections. The final answer must follow the fixed business-domain review display below.
+
+Command:
+
+```bash
+ae-cli analysis-meta governance-recommendation export --project-id <project_id> --limit 20
+```
+
+Capability id: `metadata.governance_recommendation.export`.
+
+Input sends `project_id`, optional `window_days`, optional `limit`, and optional `include_completed`.
+
+Output includes `schema_version`, `run_id`, `project_id`, `snapshot_hash`, `work_units`, `coverage`, `stat_scopes`, and `agent_presentation_contract`.
+
+## Customer/Agent Material Package Contract
+
+For page-review material preparation or inspection, continue with [independent Agent preflight](agent_review_preflight.md), including when the user requests no submission. Preserve full snapshots, not just the fields shown in a transport example; the preflight checks evidence integrity and interpretation separately.
+Generate [review priorities and classified definition comparisons](agent_review_priorities_comparisons.md) from that evidence. Export ranking and `conflict_risks` are inputs, not replacements for Agent interpretation of individual urgency and both sides of a comparison. A related asset is not automatically a conflicting definition.
+
+- This command requires a numeric `--project-id`. If the user provides only a project name, resolve the project on the same host with `ae-cli project info list` before export.
+- `run_id`, `snapshot_hash`, and `review_material_package` are the handoff package for Agent review drafting.
+- `review_material_package` should contain candidate assets, heat evidence, source links, evidence links, dashboard/report/metadata relations, report definitions, AI-model definitions, `target_revision`, and hashes needed to draft a page review.
+- The Agent must generate the downstream `agent-review submit-to-page` draft from this package: batch `ai_summary`, `presentation_snapshot`, per-item `ai_summary` / recommendation reasons, copied `evidence_snapshot`, copied source links, and relations.
+- `work_units` are deterministic Common evidence containers. They are not the final page grouping. The Agent clusters selected assets into one or more business-domain topics and second-level groups for review.
+- For report and SQL-report items, use `review_material_package.candidate_assets[].evidence_snapshot.analysis` first. Call `analysis-meta agent-review evidence` only when the package marks a definition/analysis gap or when validating a generated draft.
+
+## Rejection Filtering and Bounded Expansion
+
+Common selects hot dashboards before attaching decision state; it does not automatically replace rejected dashboards with lower-ranked ones. The Agent must apply this procedure before drafting a review:
+
+1. Start with `--limit 20`, unless the user explicitly specifies a different scope or a diagnostic sample. Keep the same host, project, time window, and completed-context setting throughout expansion.
+2. Match each source dashboard to its asset candidate by resource identity. If its current `action_state` is `PREVIOUSLY_REJECTED`, omit the dashboard and its entire display branch: its groups, report/metadata/metric placements, and relations. Do not display that rejected dashboard as completed context or submit it again. A historical `REJECT` alone is not enough to exclude a changed definition; use Common's current same-evidence decision state. Do not treat every `actionable=false` asset as rejected: authenticated context remains useful.
+3. Rebuild the presentation from retained dashboard branches. Keep a shared report, metadata asset, or metric candidate when independently referenced by another retained dashboard, and show it only under retained branches. Deduplicate by scoped asset identity, not name. Remove orphan items, empty groups/topics, and relations to omitted items from `presentation_snapshot`; omit items supported only by removed branches from the submission. This is presentation filtering, not a cascading rejection or a certification-state change. Preserve copied source evidence unchanged.
+4. Separate pending review work from context before judging the batch. Pending review work is a returned item that still needs a reviewer decision, for example `action_state:"PENDING"` or unauthenticated `authentication_status:0`, after excluding same-evidence rejects, active deferrals, and items already in an unfinished review batch when that state is available. `AUTHENTICATED` / completed assets are context only unless the evidence shows a material definition change that requires a new decision.
+5. Assess whether the remaining pending review assets and visible business domains meet the user's requested breadth and have sufficient evidence for a useful review. If no count was requested, treat the pool as insufficient when there are fewer than about 10 pending review assets, fewer than 3 pending business domains, or the retained material is mostly authenticated context with little work for the reviewer. If insufficient and coverage indicates more dashboards exist, re-export with `--limit 50`; repeat filtering and assessment, then use `--limit 100` if still insufficient. These limits are cumulative top-N pools, not disjoint pages. Replace the previous drafting packet with the latest successful export; do not concatenate runs or mix their `run_id`, `snapshot_hash`, revisions, or evidence hashes.
+6. Apply the daily review capacity after expansion. Expansion increases business-domain coverage; it does not authorize submitting every pending asset found. Unless the user requests a different batch size, target about 20-50 pending review assets, use a hard cap around 80, and keep roughly 3-6 visible business domains. When the expanded pool is larger than the cap, rank pending assets by impact_degree, heat_count90d, user_count90d, dependency/relation breadth, and whether their business domain is under-covered. Use per-domain quotas before taking many assets from one domain.
+7. Stop when the pending review assets and business-domain breadth are sufficient, the available dashboard pool is exhausted, or the top 100 have been inspected. Do not automatically expand beyond 100. At the cap, submit only the ranked slice of genuinely eligible, evidence-supported candidates within the user's submission authorization; never revive rejected, deferred, already in-flight, or weak candidates to fill a quota. Record overflow counts and domains for later batches. If none remain, explain the result without submitting an empty batch. A failed export is an execution failure, not evidence of candidate scarcity; do not expand in response to an error or silently fall back to stale material.
+8. Build page topics only for business domains that contain at least one selected pending review asset. Retain authenticated/completed assets only as direct context needed by those selected pending items, for example source dashboards, source reports, and referenced metadata along the relation path. Do not display or submit a zero-pending business domain as standalone work, even if it has many hot authenticated assets.
+
+Report the final requested limit, actual dashboards returned, same-definition rejected dashboards excluded, active deferrals or in-flight items excluded when known, retained dashboard count, visible pending-domain count, selected pending review asset count, context asset count, overflow pending count/domain summary, and stopping reason. Explain why expansion was needed or why candidates remain insufficient. Do not describe an expanded or filtered batch as covering all of the top 20/50/100 dashboards. Keep this scope summary separate from the hidden rejected branches, zero-pending context domains, and overflow left for later batches.
+
+## Decision Rules
+
+- Use this command before presenting recommendations for certification or metrics.
+- After export, always build the business-domain review display before answering. The command output is evidence, not the response format.
+- For real review-page submission, apply Rejection Filtering and Bounded Expansion before grouping. Include eligible assets across the retained dashboard branches; do not compress them into a few representative themes or submit only the first hot dashboard or first `work_unit`. A smaller batch is valid when the evidence supports fewer eligible candidates or the user explicitly requests a sample or diagnostic batch. Explain the actual scope and omissions.
+- For recurring recommendation jobs, the default reviewer workspace is pending-first: only business domains with pending review assets are visible. Authenticated/completed assets remain available as relation/context rows under those domains, but they must not create a visible topic by themselves.
+- Treat `业务主题域` as a semantic cluster over the selected dashboards, not a copy of the dashboard list. Do not create one topic per hot dashboard just because `--limit 20` returned 20 work units. Merge dashboards into the same topic when their child reports, referenced metadata, metrics, folder context, or authored notes describe the same business process. Split only when the business meaning or review decision is materially different. A result where `topic_count == selected_dashboard_count` requires explicit evidence that every selected dashboard has a distinct business domain.
+- Do not call project-semantic, project-KB, or personal-semantic-preference commands as prerequisite context for this workflow.
+- Treat `work_units` as deterministic Common evidence. The CLI Agent owns business-domain grouping, Chinese explanations, and approval interaction.
+- Agent display is mandatory whenever the user asks to see or review recommended certification assets or recommended metrics. Do not hand back raw JSON as the final answer.
+- Show recommendations by business theme/domain, not by flat asset type, backend array order, raw dashboard title, or workflow/test label.
+- Preserve `run_id`, `snapshot_hash`, `evidence_hash`, `candidate_key`, and `definition_signature` for later submit.
+- Preserve optional dashboard `space_id` / `space_name` when Common returns them. They are review-page location facts, not eligibility requirements; absence is valid because not every dashboard has an owning space.
+- Keep completed/authenticated context included by default so certified and uncertified assets from the returned evidence appear together under the same business domain. Pass `--include-completed false` only when the user explicitly asks for a pending-only review.
+- If this capability is missing on the target host, report the deployment/catalog gap. Do not synthesize a recommendation from ordinary asset-authentication or metric list commands.
+
+## Agent Approval Display
+
+This is an Agent presentation contract, not a CLI flag and not a Common renderer. Use the basic fields returned by Common to produce exactly one review shape:
+
+- The top-level grouping must be `业务主题域`. Do not split the final answer into separate top-level sections such as `资产认证建议` and `推荐指标`.
+- Aggregate by `业务主题域` with each source dashboard as the core evidence package for coverage, not as the business-domain name. Infer each domain from the dashboard semantics plus the business meaning of `topic_seed`, `source_reports`, asset names, metric names, and semantic definitions. The final group name should describe the business area or process, such as payment/revenue, login/channel, retention, item economy, or lifecycle, not the backend work-unit label. This grouping is for review comprehension only; it must not reduce the retained dashboard set after rejection filtering and bounded expansion.
+- The expected page hierarchy is `业务域 -> 看板 -> 报表 -> 元数据`. Put multiple source dashboards under one topic when they belong to the same business domain. The topic is not the dashboard node; the dashboard remains a root asset row inside the topic.
+- Treat `work_units` as evidence containers, not presentation groups. One dashboard/work unit can split into multiple business domains when its child reports cover different business processes; one business domain can merge rows from multiple dashboards/work units when the evidence describes the same business process.
+- Keep each report-centered evidence chain together: the report row, metadata rows, and metric candidates introduced by that report follow the same `业务主题域`. Do not detach report metadata into a separate generic metadata group, and do not merge unrelated child-report domains only because they share one source dashboard.
+- When one source dashboard contains child reports for different business questions, create one `业务主题域` per child-report business question. Do not combine distinct report domains into a broad `A 与 B 运营`, `综合运营`, or `核心语义` group only because they share the same dashboard. The dashboard can appear as shared linked source evidence in each relevant domain.
+- Treat source dashboards and reports as evidence containers and possible asset rows, not independent top-level business domains. Never create a generic business-domain group only to place source dashboards, such as `看板上下文`, `综合验收看板上下文`, `推荐上下文`, or `待审批资产`. Attach each source dashboard to the business domains implied by its child reports, events, properties, metrics, and definitions. If the same dashboard supports multiple domains, reuse it as linked source evidence in each relevant domain without using the dashboard title as the domain or double-counting it in the overview.
+- Do not expose source-only labels as group names. Strip or ignore prefixes such as acceptance versions, priority markers, asset-type markers, report IDs, dashboard IDs, route names, and test/workflow labels when they do not carry business meaning. If the evidence is too generic to infer a real domain, use `待确认业务主题` and explain the uncertainty from the source evidence.
+- Inside each `业务主题域`, show both asset-authentication candidates and metric candidates together so a reviewer can approve the whole business topic instead of isolated rows. For asset rows, keep returned `[已认证]` and `[未认证]` rows in the same domain table when both states are present.
+- Use plain-text review labels only: `[已认证]`, `[未认证]`, `[已有指标资产]`, `[推荐指标候选]`, `[认证资产候选]`, `[风险/冲突]`. Agent text cannot rely on color rendering, HTML, font tags, or color names.
+- In the domain detail table, the `类型` column is the object class (`资产` or `指标`). Put review labels in `状态` or `审批关注点`, not as the `类型` value.
+- The conclusion must explain the recommendation scope: by default this is a full business-topic context for the selected hot-dashboard evidence and includes completed/authenticated context. If the visible asset rows contain only one certification state, say this is what the current returned evidence contains; do not imply an Agent-side pending-only filter or proof that the whole project has no other certified assets.
+- Show asset names, not raw IDs, as the main object text. When an asset row has `markdown_link`, use that Markdown link as the object text. When only `raw_url` is present, link `display_name` or `resource_key` to that URL. If no link is available, show the best human name and omit the raw ID unless the name is missing.
+- In the `来源证据` column, first use each asset row's `source_evidence[].markdown_link`/`raw_url`; for metric rows, use `source_report.markdown_link`/`raw_url`. Fall back to the work unit's `source_dashboard` or `source_reports` links only when the row has no direct `source_evidence`. Do not strip links from source evidence when the JSON provides them, and do not replace linked sources with unlinked generic text such as `相关报表`, `热门看板`, `来源看板`, `同名看板`, `同名报表`, `<业务>相关报表`, or bare report names. If the asset row itself is the source dashboard or source report, reuse that row's own link as the source evidence. If multiple linked sources support one row, show the most direct source link or a compact comma-separated list of source links.
+- Do not expose raw `resource_key`, dashboard/report ID, `candidate_key`, `definition_signature`, or `evidence_hash` in the main review table. Preserve them from the JSON for later submit, and show them only in a compact technical payload if the user asks to approve or debug.
+- Show available decision signals from the returned data, especially `heat_count90d`, `user_count90d`, and `impact_degree`. Do not invent values; if a signal is absent, mark it as `-` or omit that part of the signal.
+- Convert `recommendation_reason` and `conflict_risks` into concise Chinese explanations. Do not expose internal enum codes as the main display text; keep codes only as supporting identifiers when needed for debugging.
+- Risk/conflict text is required for semantic conflicts, identity conflicts, previous rejection of the same evidence, non-actionable items, or mismatch between an existing metric asset and a recommended metric candidate.
+- Keep enough identifiers for action in the working context: `run_id`, `snapshot_hash`, item identity, `evidence_hash` for asset candidates, and `candidate_key` plus `definition_signature` for metric candidates.
+- For metric candidates, state that approval still needs a metric name and business definition/口径 before creation when those fields are missing.
+- If there are no visible work units, say there are no pending recommendation-review items under the current filters; do not fall back to management lists.
+- Do not spend Agent narrative budget on hidden topics or pure authenticated context. Generate batch/domain/item summaries for the final visible domains and pending review assets; for context-only rows, preserve source links, heat/user/impact signals, evidence snapshots, and relations without long new summaries unless that context is directly needed to explain a pending item.
+
+Use this fixed review skeleton:
+
+1. One conclusion sentence with project, window, run_id, visible business-domain count, candidate counts, whether completed/authenticated context is included, and whether any risk/conflict exists.
+2. A `业务主题域总览` table with columns `业务主题域`, `审批建议`, `认证资产`, `推荐指标`, `风险/冲突`.
+3. One section per `业务主题域`, with a single table whose columns are `类型`, `状态`, `对象/指标`, `热度/影响`, `来源证据`, `审批关注点`. Asset rows and metric rows must appear in the same table for that domain.
+4. A final `提交信息` line with `run_id` and `snapshot_hash`. Do not show raw JSON.
+
+## Related Commands
+
+- `analysis-meta agent-review submit-to-page` submits existing-asset proposals for review after user choice or preauthorized submission-only task intent; it does not approve or certify. Read `agent_review_submit_to_page.md` for deduplication and unattended-task rules.
+- `analysis-meta governance-recommendation submit`
+- `analysis-meta governance-recommendation decisions`
+- `analysis-meta asset-authentication list` only inspects certification state and is not the recommendation workflow.

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

@@ -0,0 +1,41 @@
+# analysis-meta governance-recommendation submit
+
+This existing command executes explicit approval decisions. It does not submit proposals to the review page. Use `analysis-meta agent-review submit-to-page` for submission-only authorization. Never invoke this executing command automatically from an unattended review-submission task.
+
+Submit CLI Agent approval decisions for one business-topic recommendation group.
+
+Use this after `analysis-meta governance-recommendation export` and after the user explicitly chooses approve, reject, or skip for items in a topic.
+
+Do not use this command to generate or refresh recommendations; it only records decisions for evidence already returned by export.
+
+Command:
+
+```bash
+ae-cli analysis-meta governance-recommendation submit \
+  --project-id <project_id> \
+  --run-id <run_id> \
+  --snapshot-hash <snapshot_hash> \
+  --topic-name '支付分析' \
+  --decisions '[{"item_type":"asset","decision":"APPROVE","resource_type":"dashboard","resource_key":"903","evidence_hash":"..."},{"item_type":"metric_candidate","decision":"SKIP","candidate_key":"recommended_metric:abc123","definition_signature":"...","evidence_hash":"...","reason":"Need metric name"}]'
+```
+
+Capability id: `metadata.governance_recommendation.submit`.
+
+Input sends `project_id`, `run_id`, optional `snapshot_hash`, optional `topic_id`, required `topic_name`, optional `window_days`, optional `limit`, and required `decisions`.
+
+Decision items use:
+
+- `item_type`: `asset` or `metric_candidate`.
+- `decision`: `APPROVE`, `REJECT`, or `SKIP`.
+- Asset decisions require `resource_type` and `resource_key`.
+- Metric-candidate approvals require `candidate_key`, `definition_signature`, `metric_name`, and `metric_desc`.
+- Include `evidence_hash` when it was returned by export.
+
+Output includes `run_id`, optional `topic_id`, `total`, `applied`, `recorded`, `failed`, and per-decision `items`.
+
+## Decision Rules
+
+- Do not submit decisions without explicit user approval.
+- Submit one topic at a time so user intent and audit evidence stay aligned.
+- Use `REJECT` for a decision that should suppress or de-prioritize the same item in future recommendation views; use `SKIP` when the user is deferring judgment.
+- If the server reports a stale candidate or snapshot mismatch, run `governance-recommendation export` again and ask the user to review the refreshed evidence.

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

@@ -6,12 +6,12 @@ Do not use it for an inline sample or for a group value that did not come from t
 
 Flags: `--project-id`, `--tag-name`, `--snapshot-date`, `--group-col`, `--view` required. Optional: `--property-names`, `--request-id`, `--artifact-format jsonl|csv`, `--timeout-seconds`. The default format is `jsonl`.
 
-Use the same `--view` that produced the statistic row. `--group-col` must be the exact statistic value or bucket label. Download the artifact only after `analysis run inspect` reports success.
+Use the same `--view` that produced the statistic row. `--group-col` must be the exact statistic value or bucket label.
 
 Common executes the native history-tag full-download SQL once and streams rows as `jsonl.gz` or `csv.gz`; it does not concatenate preview pages.
 
 ```bash
-ae-cli analysis history-tag-data-drilldown export --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --group-col VIP --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output history-tag-drilldown.jsonl.gz
+ae-cli analysis history-tag-data-drilldown export --project-id <project_id> --tag-name user_level --snapshot-date 2026-07-01 --group-col VIP --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl --output history-tag-drilldown.jsonl.gz
 ```
+
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).

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

@@ -9,7 +9,7 @@ If you provide `--request-id`, use `cli_<32 lowercase hex>`. Omit it unless you
 `--view` is AI-facing history tag view JSON. It must include a history date range (`recent_day` or `start_time`/`end_time`) and `time_particle_size:"T1"`. Optional fields include `interval_type`, `property_range`, `time_particle`, `array_group_type`, and `column_splited_str`. Do not pass raw frontend wrapper DTOs.
 
 ```bash
-ae-cli analysis history-tag-data export --project-id <project_id> --tag-name user_level --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output history-tag-data.jsonl.gz
+ae-cli analysis history-tag-data export --project-id <project_id> --tag-name user_level --view '{"recent_day":"0-31","time_particle_size":"T1","first_day_of_week":1,"interval_type":"default","array_group_type":"array_item_group"}' --artifact-format jsonl --output <file>
 ```
+
+Use `--output` to wait and download the completed artifact. If interrupted, resume with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the same export response. See [`run_wait.md`](run_wait.md).

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

@@ -1,27 +1,25 @@
 # tracking ingest-error list
 
-Use when list tracking ingest errors for one data name.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to list tracking ingest errors for one data name.
 
 Command:
 
 ```bash
-ae-cli tracking ingest-error list [options]
+ae-cli tracking ingest-error list --project-id <project_id> --data-name <data_name> --start-time <start_time> --end-time <end_time>
 ```
 
 Capability id: `tracking.ingest_error.list`
 
 Input sends `project_id`, `data_name`, `start_time`, and `end_time`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--data-name` | See command help | Yes |
-| `--start-time` | See command help | No |
-| `--end-time` | See command help | No |
+| `--project-id` | Numeric project ID. | Yes |
+| `--data-name` | Event or property name used to list ingest errors. | Yes |
+| `--start-time` | Query start time. | No |
+| `--end-time` | Query end time. | No |
 

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

@@ -1,26 +1,24 @@
 # tracking ingest summary
 
-Use when get tracking ingest summary.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to get tracking ingest summary.
 
 Command:
 
 ```bash
-ae-cli tracking ingest summary [options]
+ae-cli tracking ingest summary --project-id <project_id> --start-time <start_time> --end-time <end_time>
 ```
 
 Capability id: `tracking.ingest.summary`
 
 Input sends `project_id`, `start_time`, and `end_time`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--start-time` | See command help | No |
-| `--end-time` | See command help | No |
+| `--project-id` | Numeric project ID. | Yes |
+| `--start-time` | Query start time. | No |
+| `--end-time` | Query end time. | No |
 

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

@@ -1,27 +1,27 @@
 # tracking live-data export
 
-Use when export recent tracking live data.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to export recent tracking live data.
 
 Command:
 
 ```bash
-ae-cli tracking live-data export [options]
+ae-cli tracking live-data export --project-id <project_id> --output <file>
 ```
 
 Capability id: `tracking.live_data.export`
 
 Input sends `project_id`, optional `data_type`, optional `request_id`, and optional `timeout_seconds`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
+
+Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with its returned `run_id`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--data-type` | See command help | No |
-| `--request-id` | See command help | No |
-| `--async-timeout-seconds` | See command help | No |
-
+| `--project-id` | Numeric project ID. | Yes |
+| `--data-type` | Live data type: normal (default) or error. | No |
+| `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
+| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--output` | Wait and download to this local file. | No |

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

@@ -1,27 +1,25 @@
 # tracking live-data list
 
-Use when list recent tracking live data.
-
-Do not use for commands listed under the sheet's non-CLI section or for unrelated metadata/report operations. If the command needs a complex JSON object, read the backend schema or existing asset first and send snake_case fields only.
+Use only when the user asks to list recent tracking live data.
 
 Command:
 
 ```bash
-ae-cli tracking live-data list [options]
+ae-cli tracking live-data list --project-id <project_id>
 ```
 
 Capability id: `tracking.live_data.list`
 
 Input sends `project_id`, optional `data_type`, optional `request_id`, and optional `timeout_seconds`. Do not send camelCase aliases.
 
-Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`. Export commands return lifecycle data such as `run_id` and `artifact_id` for inspect/download.
+Output is the capability gateway envelope: success is `ok=true,data,meta`; failure is `ok=false,error`.
 
 Parameters:
 
 | Parameter | Description | Required |
 | --- | --- | --- |
-| `--project-id` | See command help | Yes |
-| `--data-type` | See command help | No |
-| `--request-id` | See command help | No |
-| `--timeout-seconds` | See command help | No |
+| `--project-id` | Numeric project ID. | Yes |
+| `--data-type` | Live data type: normal (default) or error. | No |
+| `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
+| `--timeout-seconds` | Optional capability execution timeout in seconds. | No |
 

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

@@ -0,0 +1,78 @@
+# Analysis metadata resolution
+
+Reuse verified assets, canonical names and business meanings in the current project. Use this workflow for missing definitions or metadata; discovery is complete when the requested measure can be constructed or a specific business choice needs the user's reply.
+
+## Find a reusable definition
+
+For an unknown business measure, search relevant saved metrics and reports. A named asset needs only its own family; already known definitions go directly to execution. Read the selected [metric](metric_list.md) and [report](report_list.md) command references together, then issue independent searches in the same model turn:
+
+```bash
+ae-cli analysis-meta metric list \
+  --project-id <project_id> \
+  --queries '["<user phrase>","<related English term>"]'
+
+ae-cli analysis report list \
+  --project-id <project_id> \
+  --queries '["<user phrase>","<related English term>"]'
+```
+
+Use the user's business terms and a few relevant English terms in the same `--queries` array. These are literal, case-insensitive keyword searches, not automatic translation. Deduplicate related words; the array accepts 1–20 non-empty strings. Split only when the actual required terms exceed that limit.
+
+Read metrics from `data.metrics`. With `--queries` and no `--fields`, the response includes `metric_events` and `metric_params` as JSON strings. Inspect those returned definitions directly; use `metric get` only for missing details. Field projection cannot select these two definition fields. A verified saved metric is referenced by `metric_name` in `metrics[].event` and supplies its own aggregation and property.
+
+Read report summaries from `data.items`. Report search matches names and descriptions. For a suitable candidate, use `analysis report get --project-id <project_id> --report-id <report_id>` to read `data.model_type` and `data.definition`; reuse a definition already read.
+
+Compare the candidate's events, aggregation, filters, groups and time semantics with the request. An applicable report goes directly to [report-data run](report_data_run.md) with the supported requested overrides. A custom combination reuses suitable definitions in an AI-facing model. Saved metric JSON describes its measure; it is not itself a complete ad-hoc definition. Discover only the pieces still missing below.
+
+## Fill missing metadata
+
+For an unknown event, use [event list](event_list.md) with the related terms. For a property missing from a selected event's measure or filter, use [property list](property_list.md) scoped to that event:
+
+```bash
+ae-cli analysis-meta event list \
+  --project-id <project_id> \
+  --queries '["<event phrase>","<related English term>"]' \
+  --fields '["event_name","event_desc","remark"]'
+
+ae-cli analysis-meta property list \
+  --project-id <project_id> \
+  --scope event \
+  --event-name <verified_event_name> \
+  --fields '["prop_name","prop_desc","prop_remark","select_type"]'
+```
+
+Event rows are `data.items`; property rows are `data.properties`. List pages default to 50, with `--limit` up to 200. Continue with the returned `next_offset` while `has_more` is true only when another page is needed for the unresolved choice. Stop discovery once the required definitions are available.
+
+For a lookup spanning several metadata types, choose [catalog list](catalog_list.md) for those missing types. Reuse an already exported catalog locally. A bounded no-match can mean the chosen words did not match; refine a useful term or inspect the relevant directory when needed. Export via [catalog export](catalog_export.md) only for a task that requires the complete directory, including an explicit complete no-match check. A failed request is an error, not an empty catalog.
+
+If the compiler reports a metadata error, reuse its candidates and all reported `path`, `raw_value`, `slot_kind`, `allowed_resource_types`, `search_targets` and `next_action` together. Apply `search_targets[].constraints` to the remaining lookups; suitable verified choices stay resolved.
+
+## One file in the current conversation
+
+Use the Agent host's current working directory, configured CLI environment and current project ID. The catalog export command produces one JSONL and returns `complete: true` with an absolute `output_path`. Keep that successful command's project and path in conversation context and reuse the file.
+
+A new project uses its own filename. An explicit environment/account change or a requested refresh requires a new export; use `--force` when intentionally replacing the existing file. The CLI publishes the completed download and reports failures. No model-managed hash, sidecar or directory validation is needed.
+
+## Confirm and bind
+
+Confirm a selected business mapping once, even if only one candidate is suitable. Present its meaning and any unresolved semantics. Reuse mappings already confirmed in this task. User confirmation selects the business definition; it does not verify an unknown asset formula. If the confirmation tool cannot obtain a reply, present the same choices in text and wait. A failed tool call is not confirmation. Rejected candidates are discarded; seek a different candidate for that choice using the relevant search above.
+
+After the reply, fill the confirmed canonical name, aggregation, property and other required model parameters, then execute the complete definition. Use `--resolutions` only when binding unresolved wording retained at a compiler-reported path. Bindings select metadata; they do not fill model parameters. Their `raw_value` must match the wording at that path.
+
+For example, a compiler may have received `{"event":"<requested amount metric>"}`. After the user confirms it means the sum of a verified event's numeric property, submit the complete definition and event binding together:
+
+```bash
+ae-cli analysis adhoc run \
+  --project-id <project_id> \
+  --model-type event \
+  --definition '{"time_range":{"mode":"previous","unit":"day","value":7},"metrics":[{"event":"<requested amount metric>","aggregation":"sum","property":"<confirmed amount property>"}]}' \
+  --resolutions '{"request.metrics[0].event":{"raw_value":"<requested amount metric>","resource_type":"event","resource_key":"<confirmed event key>"}}'
+```
+
+Use the requested time range. The event key and amount property in this example must come from the current project's verified metadata and confirmed meaning. Adding `aggregation` and `property` leaves the bound `event` wording intact. A confirmed saved metric supplies its own measure definition instead.
+
+The flag value is the path-keyed object; the CLI adds the outer `resolutions` field. The server checks the bound path, `raw_value`, allowed resource type and accessible key.
+
+Reuse confirmed names and meanings according to the target model's resource types. Retention initial and return events use the underlying verified event names from those definitions. A resolution path belongs to its current definition, so copy the confirmed meaning rather than a different query's path mapping.
+
+Execute the confirmed command. `RESOLUTION_STALE`, `RESOLUTION_TYPE_NOT_ALLOWED` and `RESOLUTION_PATH_INVALID` identify fields to correct; do not resend them unchanged. If the user changes the business definition itself, update that definition and its dependent queries instead of binding the old wording to a different meaning.

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

@@ -9,7 +9,6 @@ Command:
 ```bash
 ae-cli analysis-meta metric export --project-id <project_id> --output <temporary_path>/metrics.json
 ae-cli analysis-meta metric export --project-id <project_id> --queries '["pay","revenue"]' --fields '["metric_name","metric_desc"]' --output <temporary_path>/metrics.json
-ae-cli analysis-meta metric export --dry-run
 ```
 
 Capability id: `metadata.metric.export`.

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

@@ -9,7 +9,6 @@ Command:
 
 ```bash
 ae-cli analysis-meta metric get --project-id <project_id> --metric-id <metric_id>
-ae-cli analysis-meta metric get --dry-run
 ```
 
 Capability id: `metadata.metric.get`.

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

@@ -11,14 +11,13 @@ ae-cli analysis-meta metric list --project-id <project_id>
 ae-cli analysis-meta metric list --project-id <project_id> --ignore-authentication true
 ae-cli analysis-meta metric list --project-id <project_id> --queries '["pay","revenue"]'
 ae-cli analysis-meta metric list --project-id <project_id> --queries '["pay","revenue"]' --fields '["metric_name","authentication_status"]' --limit 50 --offset 0 --authenticated-only true
-ae-cli analysis-meta metric list --dry-run
 ```
 
 Capability id: `metadata.metric.list`.
 
 Input sends `project_id`, `ignore_authentication`, `queries`, `fields`, `limit`, `offset`, and `authenticated_only`.
 
-Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
+Output always uses the directory envelope: `data.metrics[]`, `total`, `limit`, `offset`, `has_more`, and `next_offset`.
 
 ## Parameters
 | Parameter | Required | Description |
@@ -32,7 +31,7 @@ Output always uses the directory envelope: `data.items[]`, `total`, `limit`, `of
 | `--authenticated-only` | No | When true, return only authenticated metrics. |
 
 ## Decision Rules
-- Do not call this just to prepare normal ad-hoc analysis. Pass saved metric wording directly in `analysis adhoc run/export --definition`; the backend compiler resolves saved metric names internally.
-- Use `--fields` to keep discovery responses compact.
-- Use `analysis-meta metric get` after this command when a full metric definition is needed.
+- For an unknown business measure, use this with relevant `report list` search as the saved-definition discovery path in [`metadata_resolution.md`](metadata_resolution.md). Reuse a verified saved metric name directly.
+- Use `--fields` when its projected fields are sufficient. When searching with `--queries`, omit `--fields` to keep `metric_events` and `metric_params` as JSON strings. Read their content in this response; these two fields are not in the projection whitelist.
+- Use `analysis-meta metric get` only when a required definition detail is absent from the returned row.
 - For a complete result, use `analysis-meta metric export`; do not page repeatedly to synthesize an export.

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

@@ -12,7 +12,6 @@ Command:
 ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-desc 'New display name' --metric-remark 'New remark'
 ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-name demo --metric-desc demo --model-type event --metric-events '[]'
 ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-name demo --metric-desc demo --metric-remark demo --model-type retention --metric-events '[]' --metric-params '{}'
-ae-cli analysis-meta metric update --project-id <project_id> --metric-id <metric_id> --metric-desc 'New display name' --dry-run
 ```
 
 Capability id: `metadata.metric.update`.

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

@@ -7,13 +7,12 @@ Do not use it to list records or export asset rows; resolve one real `record_id`
 Command:
 
 ```bash
-ae-cli analysis-governance operation-record export --project-id <project_id> --payload '{}'
-ae-cli analysis-governance operation-record export --dry-run --project-id <project_id>
+ae-cli analysis-governance operation-record export --project-id <project_id> --record-id <record_id>
 ```
 
-Capability id: analysis_meta.asset_operation_record.export.
+Capability id: governance.operation_record.export.
 
-Input sends project_id, payload, record_id. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, record_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 an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download that exact export.
 
@@ -22,4 +21,4 @@ Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status,
 |---|---|---|
 | --project-id | Yes | Numeric project ID. |
 | --record-id | No | Operation record 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/operation_record_list.md

@@ -7,13 +7,12 @@ Do not use it to submit a new batch operation; use it to find and inspect record
 Command:
 
 ```bash
-ae-cli analysis-governance operation-record list --project-id <project_id> --payload '{}'
-ae-cli analysis-governance operation-record list --dry-run --project-id <project_id>
+ae-cli analysis-governance operation-record list --project-id <project_id>
 ```
 
-Capability id: analysis_meta.asset_operation_record.list.
+Capability id: governance.operation_record.list.
 
-Input sends project_id, payload, type, status, query, sort_field, sort_order, limit, offset. Payload keys must follow the common-service snake_case input schema; do not send camelCase aliases.
+Input sends project_id, type, status, query, sort_field, sort_order, limit, offset. 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 paged batch-operation record result. Use record status to distinguish submitted, running, successful, and failed work before taking another action.
 
@@ -28,4 +27,4 @@ Output `data` is the paged batch-operation record result. Use record status to d
 | --sort-order | No | Sort order: asc or desc. |
 | --limit | No | Inline page size. |
 | --offset | No | Zero-based page offset. |
-| --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. |