@thinkingai/ae-cli 6.1.19 → 6.1.21

package/skills/ae-agent/references/list-automations.md

@@ -4,13 +4,26 @@
 
 Domain: **Automations / read**
 
+```text
+Transition status: transitional
+Owning module: te-claude automation
+Current transport: GET /api/sandbox/agent/automations
+Gateway target: TBD (no equivalent Gateway capability is currently registered)
+Review after: 2026-10-07
+Exit condition: Migrate when the Gateway exposes equivalent workspace-scoped automation listing.
+```
+
 ## Use Cases
-- List the current user's Agent automation tasks.
-- Returns an array of automation summaries; key fields include `id`, `name`, `status`, `schedule`/`cronExpression`.
+- List the current user's Agent automation tasks in one workspace.
+- Returns `items` containing automation summaries; key fields include `id`, `name`, `status`, `cronExpression`, `agentSpaceId`, and `agentSpaceName`.
+- Agent Team scheduled tasks shown alongside automations in the workspace UI are a separate resource and are not returned by this command.
 - Use this to discover a real automation ID before `+update-automation`.
 
 ## Mandatory Rules (MUST)
 - Do not guess automation IDs. Always call `+list-automations` first when an automation ID is needed.
+- Pass `--agent-space-id` for a non-default workspace. Omitting it lists the personal default workspace, including legacy tasks without a workspace ID; it does not list all workspaces or infer the current conversation's workspace.
+- Keep the same workspace ID when calling `+update-automation`. An automation created from a conversation may belong to a non-default workspace; use the returned `automation.agentSpaceId` when verifying creation.
+- On servers without workspace support, omit `--agent-space-id`. Listing retains its original user-scoped behavior and responses may lack `agentSpaceId`/`agentSpaceName`; neither field is required by the CLI. Older servers do not enforce the new workspace filter.
 - Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies — use the ID only internally for subsequent commands.
 
 ## Command
@@ -18,12 +31,14 @@ Domain: **Automations / read**
 ae-cli agent +list-automations
 ae-cli agent +list-automations --status active
 ae-cli agent +list-automations --q "daily" --limit 20 --format table
+ae-cli agent +list-automations --agent-space-id <workspace-id>
 ae-cli agent +list-automations --dry-run
 ```
 
 ## Parameters
 | Parameter | Required | Description |
 |---|---|---|
+| `--agent-space-id` | No | Workspace ID; omitted means the personal default workspace |
 | `--q` | No | Keyword for automation name or instruction |
 | `--status` | No | `active` \| `paused` |
 | `--limit` | No | Maximum number of automations to return, 1–10000 |
@@ -34,7 +49,7 @@ ae-cli agent +list-automations --dry-run
 - If many automations are returned, summarize by `name` and `status` to help the user pick the right one.
 
 ## Next Steps on Failure
-- Empty result: confirm the user has created automations on the active AE host.
+- Empty result: check the active AE host and workspace ID before concluding there are no automations. This command does not include Agent Team scheduled tasks.
 - Auth error: run `ae-cli auth login`.
 
 ## Recommended Chaining

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

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

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

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

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

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

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

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

package/skills/ae-analysis/SKILL.md

@@ -1,27 +1,42 @@
 ---
 name: ae-analysis
-version: 4.2.3
-description: "Use ae-cli for AE/TE analysis-side data questions, asset operations, and asset governance: reports, analysis boards, BI dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, or inspect/create/update/govern analysis assets."
+version: 4.2.20
+description: "Use ae-cli for AE analysis-side data questions, asset operations, and asset governance: reports, analysis boards, BI dashboards, ad-hoc models, drilldown, detail data, alerts, clusters, tags, metrics, metadata, project configuration, tracking plans, governance asset lists/rules/lineage/impact/dependency, batch asset operations, projects, and resource links. Use when the user asks to query data, explain a change, export evidence, inspect/create/update/govern analysis assets, recommend project assets for certification/authentication, review asset-certification recommendations, review metric recommendations, or build/update/refresh/sync a project semantic knowledge base from a governed asset package."
 ---
 
 # ae-analysis
 
 This is the single entry skill for analysis intent and command execution.
 
+## Analysis workflow
+
+For data queries:
+
+1. Take the current project and requested metrics, windows, groups and filters. Reuse known assets and definitions; discover unknown business measures with [metadata resolution](references/metadata_resolution.md), then select the needed saved-report or ad-hoc command/model references.
+2. Confirm any new business mapping once, fill the required parameters, and execute the applicable saved report or complete ad-hoc definition. Reuse confirmed meanings in dependent queries. If the confirmation tool cannot obtain a reply, present the same choices in text and wait for the reply.
+3. Correct compiler errors at their reported paths. New evidence or a user correction changes a completed choice; preserve the other verified inputs.
+4. Use the returned result directly. Save original JSON only when the user requests a file or necessary local processing requires one; follow [result handling](references/analysis_data_retrieval.md#preserve-and-interpret-results). Keep stderr and the CLI exit status visible.
+5. Compute only missing values needed by the request, together in one local call. Reuse completed results and answer when the requested data is available, or explain the specific error or missing input.
+
 ## Route before reading
 
 1. Map the request to a command family before opening any reference.
-   - Known family: open only its dedicated reference. For example, a retention request goes directly to `references/adhoc_run.md` plus the `retention` section of `references/ai_models.md`.
+   - CLI Agent asset-authentication and metric-recommendation review: this includes requests to recommend project assets for certification/authentication, review asset-certification candidates, review project asset-governance recommendations, or review recommended metrics. Open `references/governance_recommendation_export.md` and route to `analysis-meta governance-recommendation export|submit|decisions`. For review-page submission, open `references/agent_review_submit_to_page.md` and use `analysis-meta agent-review submit-to-page|list|detail|records|review|retry`. Do not load project semantics, project KB, or personal semantic preferences as a preflight.
+   - Project semantic knowledge-base build/update/refresh/sync: open `references/project_semantic_knowledge_wiki.md` and route to `project-semantic asset-package export`, local semantic planning, and local Wiki rendering. Default to CLI semantic precompilation into Markdown sources, source ZIP upload, and KB schema/compile. Update changed source files and run incremental KB compilation on refresh. Never substitute read-only snapshot import. Stop on company permission denial. This is a command-reference workflow inside `ae-analysis`, not a standalone project semantic Skill.
+   - Known family: open only its dedicated reference. For example, a retention request goes directly to `references/adhoc_run.md`, the common `references/ai_models.md`, and `references/ai_models/retention.md`.
    - Unknown family: search [`references/command_index.md`](references/command_index.md) with `rg` or an equivalent text-search tool and keep only the matching rows. `command_index.md` is a search-only fallback; never open it with a whole-file read or print the entire file.
 2. Read the selected command's dedicated reference before composing it:
    - `event list` -> `references/event_list.md`
    - `analysis dashboard list` -> `references/dashboard_list.md`
    - `personal-semantic-preference list` -> `references/personal_semantic_preference_list.md`
+   - Asset center cross-source configuration (资产中心 / 跨源资产配置 / Excel 配置表导入): L3 discovery via `capability search "cross_source_config" --domain metadata --project-id <id>`; read [`references/cross_source_config.md`](references/cross_source_config.md) for workbook upload and validation. No dedicated business commands.
    - replace hyphens with underscores in gateway filenames.
-3. For an AI-facing ad-hoc definition, also read [`references/ai_models.md`](references/ai_models.md).
+3. For an AI-facing definition, read the short common [`references/ai_models.md`](references/ai_models.md) and `references/ai_models/<model_type>.md` for each selected model. Batch these reads; direct model paths replace heading searches and line-number calculations.
 4. For cluster/tag `--definition-request`, also read the matching [`references/user_cluster_models.md`](references/user_cluster_models.md) or [`references/user_tag_models.md`](references/user_tag_models.md). Shared primitives live in [`references/audience_models.md`](references/audience_models.md).
-5. For analysis data retrieval, choose `run` or `export` using [`references/analysis_data_retrieval.md`](references/analysis_data_retrieval.md).
-6. When an AI-QP compile failure contains `slot_kind`, `allowed_resource_types`, `search_targets`, and `next_action`, read and follow [`metadata_resolution.md`](metadata_resolution.md).
+   - For tag periodic refresh, read `references/user_tag_create.md` or `references/user_tag_update.md`; they cover the enable switch, frequency/time schedule, cron alternative, and timezone behavior.
+5. For query data, read the short [`references/analysis_data_retrieval.md`](references/analysis_data_retrieval.md) together with the selected command and model files. It links to export and follow-up details only when those operations are needed.
+6. For unknown AI-facing metadata, or when a compile failure contains `slot_kind`, `allowed_resource_types`, `search_targets`, and `next_action`, read and follow [`references/metadata_resolution.md`](references/metadata_resolution.md).
+7. For an unfamiliar aggregation, cohort or attribution rule, consult the matching section of [`references/analysis_interpretation.md`](references/analysis_interpretation.md).
 
 Routing is complete when one command family and its dedicated references are selected. The generated command index is exhaustive and must stay out of model context except for matching search rows. This file contains routing and workflow rules only; do not duplicate a hand-maintained command inventory here.
 
@@ -30,17 +45,44 @@ Routing is complete when one command family and its dedicated references are sel
 Use this skill for these CLI services:
 
 - `analysis`: reports, dashboards, BI panels, ad-hoc analysis, drilldown, detail data, alerts, clusters, tags, and async runs/artifacts.
-- `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata.
+- `analysis-meta`: gateway metadata assets, events, properties, virtual metadata, metrics, data tables, exchange rules, and super metadata. Cross-source asset configuration uses the metadata L3 catalog instead.
 - `analysis-governance`: gateway asset governance operations, including governed asset lists/exports, lineage, dependency, impact, query history, rule schema/list/create/update/delete, batch asset actions, and operation records. Use this service for asset governance workflows, not for metadata event/property/metric CRUD.
 - `tracking`: gateway tracking plan, checking, ingest, live-data, and event blacklist operations.
 - `personal-semantic-preference`: current user's project-scoped personal semantic preferences. Use it as agent context before resolving ambiguous business wording, asset choices, or recurring user preferences.
+- `project-semantic`: published project semantics, candidate/release governance, and knowledge-base asset-package export. `kb` is used only inside the explicit project semantic knowledge-base command-reference workflow. Neither service is a prerequisite for asset-authentication and metric-recommendation review.
 
 For metadata gateway detail outside the commands in the generated index, use the metadata skill. For Engage, DataOps, or Community work, use the corresponding skill.
 
-Use `ae-cli` as the only execution path for this skill. If a command is missing, unsupported, not implemented, or a capability gap is confirmed, report the gap and stop or provide framework-level guidance; do not switch to direct MCP execution. Repeated failures are not evidence of a capability gap until parameters, types, time formats, permissions, timeout choice, and payload construction have been checked. A validation error or `need_clarification` is a reason to correct the input, not to switch tools.
+Use `ae-cli` as the only execution path for this skill. If a command is missing, unsupported, not implemented, or a capability gap is confirmed, report that gap; do not switch to direct MCP execution. A validation error or `need_clarification` calls for its specific input correction. A transport failure such as `fetch failed` means the result is unavailable: report the error with any already obtained results and stop the dependent request. Resume after environment recovery; do not start route probes, sleeps or background network polling. A transport failure does not establish a missing capability or empty data.
 
 For tags and audience clusters, use the native `analysis user-tag ...` and `analysis user-cluster ...` gateway commands.
 
+For CLI Agent asset-authentication and metric-recommendation review, route to `analysis-meta governance-recommendation export|submit|decisions`. Common returns the deterministic evidence packet; the Agent owns the fixed human approval display from `references/governance_recommendation_export.md`, including business-domain grouping, plain-text status labels, and risk/conflict explanation. Do not use project-semantic, project-KB, or personal-semantic-preference commands as prerequisite context for this workflow. Do not use management commands such as `asset-authentication list|export|update` or metric CRUD commands to synthesize recommendations. Do not bypass curated commands with `ae-cli capability inspect|validate|dry-run|run` for `governance.asset_authentication.dashboard_package`, `metadata.metric.recommended_scan`, or `metadata.metric.recommended_create`.
+
+After presenting recommendations, the Agent may ask whether to submit them to the review page. A user choice to submit authorizes `analysis-meta agent-review submit-to-page` only; it does not authorize approval or certification. If the user declines, do not write or repeatedly suggest submission. Existing explicit submission authorization remains valid and does not need another prompt. A preauthorized unattended task may submit review proposals only; it must never call `agent-review review|retry`, legacy `governance-recommendation submit`, or direct certification/metric mutations automatically. Use `agent-review list|detail|records` and the task's persisted proposal fingerprint to reuse prior batches. Do not resubmit or send repeated notifications for unchanged proposals, pending reviews, completed items, or previously declined suggestions. A new run ID alone is not new evidence. Report the returned `review_url` once and remain quiet until there is a meaningful change or required user action. See `references/agent_review_submit_to_page.md` for stable request keys and packet rules.
+
+Report review details must explain calculation logic and statistical measures, not only business purpose. Follow resolve/export -> material-package completeness check -> gap-only `analysis-meta agent-review evidence` or `analysis report get` -> chunked AI explanation -> independent preflight -> authorized submit-to-page -> detail readback. LOCAL_ONLY stops at the local preflight result. `governance-recommendation export` is expected to include report `evidence_snapshot.analysis` and `target_revision` in `review_material_package.candidate_assets`; do not ask the customer to run `analysis report get` for every report when those fields are present. Fetch `agent-review evidence` only when a report item lacks current analysis, when validating a generated draft, or when the material package explicitly marks a definition gap. Read `references/agent_review_evidence.md` for stable analysis fields and their limits. Populate `item.ai_summary.analysis_explanation` with evidence-backed measures, dimensions, calculations, filters, time_scope, and query_columns as applicable; interpret each supported SQL projection column separately. Reference only actual fact-supporting response paths rooted at `evidence_snapshot.analysis`; `source_path` is provenance, not an automatic evidence_refs substitution. Preserve server facts separately from AI interpretation and explicitly identify null, missing, dynamic or unparsed evidence. For DYNAMIC SQL, label supported sql.raw/normalized_definition.params discussion as original-text interpretation, never fabricate select_columns or runtime substitutions. Common create stores the submitted packet; it does not fill missing calculation explanations for the Agent. Before calling `submit-to-page`, check required `evidence_snapshot.analysis` and resolvable references in `analysis_explanation.calculations` / `analysis_explanation.measures`; missing required structure remains an error. Reviewer-readability and interpretation defects follow the bounded quality correction/warning procedure. Verify the stored snapshot and references in detail after submission. Never guess SQL, aliases, columns, formulas, time ranges, timezones, or successful execution. Definition inspection, evidence reads, validation, and submission are not proof of query results, approval, or certification.
+
+`item.ai_summary.summary` is the concise item recommendation reason, including its evidence basis and main risks, displayed in the main list. `batch.ai_summary.summary` is the batch overview and cannot replace item reasons. Detailed factual explanations belong only in `item.ai_summary.analysis_explanation`. Do not duplicate reasons or detailed analysis into presentation fields; keep `presentation_snapshot.analysisByItem` as `{}`. Do not invent a reason from unknown values; state missing evidence or uncertain risks explicitly rather than treating them as zero or absent.
+
+Scripts may build the transport file, preserve IDs, copy evidence, normalize links, and run deterministic completeness checks. Scripts must not author page-visible `ai_summary.summary`, `analysis_explanation.*.statement`, limitations, open questions, or approval rationale by filling reusable sentence templates. Those fields must be Agent-written interpretation from the current asset/report evidence; if many submitted items share the same narrative shape after only asset names or numbers change, flag a quality failure and follow the bounded correction/warning procedure in `references/agent_review_preflight.md`.
+
+Page-visible review text is for human asset reviewers, not implementers. In `item.ai_summary.summary`, visible statements, and open questions, write plain business Chinese: what the asset is for, how it is calculated, which filters/date windows matter, and what the reviewer should confirm. Saved business event names and field names such as `agent_session_message_send`, `session_id`, and `response_duration` may appear when they help the reviewer verify the 口径. Do not expose internal evidence, parser terms, temporary SQL aliases, or runtime parameter names such as `SAVED_REPORT_ONLY`, `DYNAMIC`, `REPORT`, `T1`, `a0`, `a1`, `Variable2`, `selector3`, `PartDate date1`, `source_path`, `evidence_snapshot`, raw JSON, raw SQL, hash/revision details, dashboard override warnings, timezone-not-saved notes, or claims about query execution unless the user explicitly asks for debug evidence. Convert internal values before display, for example `T1`/`day` becomes `按天`, and dynamic SQL caveats become business confirmation items such as “确认参数含义、默认日期范围和是否包含测试数据”.
+
+For real review-page submission, start with `analysis-meta governance-recommendation export --limit 20`. This is the initial candidate pool, not a required submission count. Follow the rejection filtering and bounded expansion procedure in `references/governance_recommendation_export.md`: hide each same-definition rejected dashboard's entire display branch, retain shared assets only under other retained dashboards, filter out already completed/authenticated, deferred, or in-flight assets as pending work, and expand an insufficient pool from 20 to 50 to 100, then stop. Expansion is for business-domain coverage, not unlimited workload: for recurring daily batches, target about 20-50 pending review assets, hard cap around 80, and balance roughly 3-6 visible domains with per-domain quotas before adding context. Use the latest successful export as the drafting evidence and report the actual reviewed scope plus overflow left for later batches. Do not compress eligible coverage into a few representative themes or submit only the first work unit unless the user requests a sample or diagnostic batch. Business themes organize the retained dashboard set; they do not replace its coverage. For recurring recommendation jobs, submit only business domains that still contain pending review assets; authenticated assets are supporting context under those visible domains, not standalone work. Do not write long Agent summaries for hidden domains or pure authenticated context.
+
+For dashboard recommendations, preserve optional location facts from Common: when a dashboard candidate or source dashboard includes `space_id` or `space_name`, copy those fields into the submitted dashboard item's `evidence_snapshot.definition.config` so the review page can show `所属空间`. Not every dashboard belongs to a space; missing space fields are valid and must not be invented, required, or used to filter out an otherwise eligible dashboard.
+
+`presentation_snapshot.topics` must be business domains, not dashboard containers; business domains are not dashboards. Never create one topic per hot dashboard merely because the export returned 20 work units. First cluster the selected dashboards by business process using dashboard names, child report names, report definitions, referenced events/properties, metrics, folder context, and authored notes. If several dashboards describe the same business area, put them in one topic and keep each dashboard as a root item under that topic. Split topics only when the business process or review decision is materially different. The expected hierarchy is 业务域 -> 看板 -> 报表 -> 元数据; the number of topics can be smaller than the number of selected dashboards, and a `topic_count == selected_dashboard_count` result must be justified by genuinely distinct business meanings, not by source array order.
+
+For page review, preserve the prototype hierarchy in `presentation_snapshot.relations`: source dashboard items are parents of their child report items with `type:"contains"`, and report items are parents of metadata items they actually reference with `type:"uses"`, such as events, event properties, user properties, and metric assets. Topic `items` may list the same stable `client_item_id`s, but the page must be able to render 看板 -> 报表 -> 元数据 from `relations`. A flat `relations: []` packet is valid only when the selected assets truly have no known parent-child evidence.
+
+The full `evidence_hash` includes collection time and may change between previews without business changes; use `target_revision` for saved-definition version checks and compare material facts separately. Do not use full snapshot hashes to trigger cross-scan resubmission. Create stores the submitted snapshot without restoring omitted fields; verify references and important facts in detail against the final dispatched material.
+
+If a retired split recommendation command or capability is accidentally probed and returns an error, treat that as a routing correction only. Do not use data from split recommendation commands or capabilities as the business source for a recommendation answer; rerun the current workflow through `analysis-meta governance-recommendation export`.
+
+For review-page drafting, material inspection, or local-only rehearsals, read `references/agent_review_preflight.md` and `references/agent_review_priorities_comparisons.md`. After item explanations, generate evidence-backed review priorities and compare related definitions across authoring chunks/topics; store `recommendation`, classified `comparisons` and `comparison_review` in item AI summaries. Review priority is not a certification decision, and similarity alone is not conflict. Use an independent fresh-context reviewer to compare all evidence (including `signals`) with saved sources and review item-specific meaning, priorities and paired definitions. The author corrects concrete findings at most 3 times for the whole packet, with independent re-review. If quality still fails, an already authorized submission continues with explicit unresolved-quality warnings; never claim PASS or reset the correction budget. Disclose unavailable review or incomplete coverage. Local-only intent always forbids submission. Quality assessment belongs to the Agent, not Common; structural validation, authorization and transport errors remain enforced.
+
 ## Global AE CLI Rules
 
 Command forms:
@@ -55,10 +97,10 @@ ae-cli capability search|inspect|validate|dry-run|run [options]
 
 - Gateway commands use kebab-case flags such as `--project-id`; the CLI sends snake_case JSON.
 - JSON values must be JSON string literals.
-- Global flags include `--host`, `--format json|table`, `--jq`, `--validate`, `--dry-run`, and `--yes`. Use `--validate` alone to normalize complex capability input; use `--dry-run` alone for execution or risk preview.
+- Global flags include `--host`, `--format json|table`, `--jq`, `--validate`, `--dry-run`, and `--yes`. Use `--validate` only to resolve a concrete complex-input issue; use `--dry-run` for high-risk writes or an explicitly requested preview. These modes are mutually exclusive.
+- Execute a fully specified read or ordinary write directly. Do not routinely stack inspect, validate, dry-run, and run. Inspect the selected model contract once when a concrete schema mismatch requires it; reuse that inspected contract within the unchanged conversation scope. This is local evidence reuse, not a claim that the CLI caches contracts.
 - JSON is the default machine-readable output. On failure, preserve the structured error and non-zero exit.
-- **CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, your reply **MUST open with** a short ⚠️ version warning and **quote the `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then present the business result. Never answer with only a project/table summary when a host_compat notice exists. Soft tip; `ok: true` can still carry the notice.
-- Never invent command names, flags, payload fields, projects, resource IDs, asset names, event/property names, metric definitions, or dates.
+- Never invent command names, flags, payload fields, projects, resource IDs, asset names, canonical event/property identifiers, metric formulas, or dates. User-provided business wording is valid unresolved compiler input; it is not a claim that a canonical binding is known.
 - 中文时间表达必须按固定语义映射：最近7天/近7天 -> `mode=recent` -> QP `recentDay=0-7`，含今天；过去7天/前7天 -> `mode=previous` -> QP `recentDay=1-7`，不含今天。用户明确说明是否包含今天时，以该说明为准。完整映射见 [`references/ai_models.md`](references/ai_models.md)。
 
 `CAPABILITY_NOT_FOUND` means the current host does not expose that gateway capability; changing parameters will not fix it. A permission error stops any dependent chain. A 404 while inspecting an async run is a route/deployment failure; do not poll the same ID forever.
@@ -68,8 +110,16 @@ Interpret gateway envelopes by state:
 - `ok: true` with empty data is success and means no matching data. Never relabel an empty report/dashboard result as query failure.
 - `ok: true` with `meta.partial: true` is partial success. Use the successful data and explicitly report `meta.failures`; do not fail the whole batch or hide failed items.
 - `ok: false` is failure. Preserve `error.code`, `error.message`, and `meta.request_id`, `meta.invocation_id`, `meta.stage`, and `meta.failures` when present.
+- `OUTPUT_PROJECTION_FAILED` is a local output failure after command completion: stdout retains the original business payload in `data` and original `meta`, while exit status remains non-zero. Repair the projection from that returned envelope without resubmitting the remote command.
 - Do not retry an unchanged failed command or guess alternative payload shapes. Retry only after applying concrete validation/clarification guidance or correcting a verified transient condition.
 
+Failure evidence:
+
+- A process exit code of 0 is not business success when the envelope says `ok: false`. Prefer direct CLI invocation; if a shell pipeline is necessary, preserve the CLI exit status with `set -o pipefail` and retain the complete error envelope rather than truncating it.
+- `TE_TOOL_POLICY_DENIED` identifies the runtime authorization stage. Report its exact reason; it does not prove a backend schema check passed or that the user needs to log in again. Do not bypass policy or retry by changing the business scope.
+- `INVALID_ANALYSIS_DEFINITION` / `INVALID_CAPABILITY_INPUT` identifies an input failure. Correct all relevant fields together within the allowed retry budget. Say "validation passed" only after an explicit successful validation response for the same complete definition on the same host.
+- `QUERY_FAILED` establishes that the query failed; it does not establish the database or engine root cause. Preserve the returned error and correlation IDs, leave unavailable values unknown (not zero), and stop when the user requests no retries. Distinguish observed errors from unverified hypotheses.
+
 For every gateway command that exposes `--request-id`, ae-cli generates a `request_id` and prints it to stderr before dispatch when the caller omits it. Preserve that ID with the final envelope and diagnostics. Pass an explicit `--request-id cli_<32 lowercase hex>` only when a caller-owned correlation ID is required.
 
 ### Execution invariants
@@ -77,8 +127,8 @@ For every gateway command that exposes `--request-id`, ae-cli generates a `reque
 - Probe the first page exactly once. Verify `ok`, the documented data shape, and the effective `limit` before starting a pagination loop.
 - For paginated directory results, continue only with the returned `next_offset` while `has_more` is true. Never calculate a speculative offset, repeat the current page, or declare the list complete before `has_more` is false.
 - Track the normalized command, input, and announced `request_id` for every invocation. Never resubmit an identical invocation while it is still in flight; wait for the current process, or inspect its returned `run_id` when it is asynchronous.
+- Reuse completed data, verified metadata, selected assets, and already downloaded files when host, identity, project, definition, effective scope, and completeness match. Query only an identified missing dependency; batch compatible metrics and do not add unrelated analysis to a lookup.
 - Retry only the items named in `meta.failures`, and only when their `retryable` value and `next_action` permit it. Never retry successful or empty items from the same batch.
-- For black-box coverage audits, maintain an explicit module × model × outcome matrix. Mark coverage complete only from observed responses; missing assets, permissions, or fixtures are environment gaps, not passing coverage.
 
 ## Mandatory routing
 
@@ -92,12 +142,11 @@ For every gateway command that exposes `--request-id`, ae-cli generates a `reque
 
 ### Project gate
 
-Before a project-scoped command:
+Use the current turn's project ID supplied by the Agent host. When no project is supplied, resolve the user's ID or name with `project info list`. Ask only when the returned candidates leave a real ambiguity. A new user selection replaces the previous project for subsequent commands.
+
+### Project Semantic Knowledge Base
 
-1. Reuse a project only when its ID and host/environment were already verified in the same continuous conversation.
-2. Otherwise call `project info list` and resolve the supplied ID/name.
-3. If there are multiple plausible projects, the host is unclear, or no project matches, show the candidates and ask; never guess.
-4. Re-verify after the user changes project, host, or environment.
+When the user explicitly asks to build, update, refresh, rebuild, or sync a project semantic knowledge base, open `references/project_semantic_knowledge_wiki.md`. That command-reference workflow starts from `ae-cli project-semantic asset-package export` and then uploads/compiles KB sources. Do not load a standalone project semantic Skill for this workflow. The governed project-semantic catalog and candidate/release lifecycle remain separate from this knowledge-base build path, and neither path is prerequisite context for CLI Agent asset-authentication or metric-recommendation review.
 
 ### Project Semantics
 
@@ -111,16 +160,15 @@ Published project semantics are the formal project-wide authority. A current-tur
 
 ### Personal Semantic Preferences
 
-Before answering project-scoped analysis or asset-governance requests, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation after the project is resolved. Keep that lightweight directory in conversation context; do not page it, search the database, or call list again for each question. The backend returns at most 200 entries using `HOT_160_PLUS_RECENT_40` and may return fewer to keep the payload within its size limit.
-
-Use the returned compact catalog only as context. If one item is actually adopted to interpret the user's wording, asset selection, metric preference, or output style, fetch it with `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used`. This also applies when the matched item is being used as the target for an `update`. Do not pass `--mark-used` for items that were only inspected or rejected.
+When the request involves personal business wording, asset preferences, or explicit personalization, call `ae-cli personal-semantic-preference list --project-id <project_id>` once per host, authenticated user, project, and conversation; reuse the result within that scope. Use the current project supplied by the Agent host. If an entry is adopted, read [`references/personal_semantic_preference_list.md`](references/personal_semantic_preference_list.md) and fetch that entry with `--mark-used`. Read the same reference before recording a durable user preference; a one-time analysis confirmation is task context.
+This rule does not apply to CLI Agent asset-authentication and metric-recommendation review through `analysis-meta governance-recommendation export|submit|decisions`; that workflow must not load personal semantic preferences as prerequisite context.
 
 Apply the two catalogs by authority and purpose, not as one flat ranking. Published project semantics define the formal business meaning. Personal semantics supply the current user's defaults, interpretation corrections, asset choices, and output preferences where they do not conflict. If a personal semantic conflicts with a published project semantic, use the project semantic for the formal result and explicitly disclose the difference; never silently overwrite the personal record. If the user explicitly requests the personal alternative for the current task, execute it as a labeled non-formal variation.
 
 The Agent owns the personal preference capture trigger. Choose `context_type` by meaning:
 
 - `preference`: durable interpretation or output preference without an exact asset binding.
-- `asset_context`: durable user wording or intent bound to one or more exact project assets. Send the complete ordered `resource_refs` array; each item has `resource_type`, string `resource_key`, and `display_name`. This identity is generic across reports, dashboards, events, properties, metrics, tags, clusters, data tables, and future asset types.
+- `asset_context`: durable user wording or intent bound to one or more exact project assets. Send the complete ordered `resource_refs` array; each item has `resource_type`, string `resource_key`, and `display_name`.
 - `experience`: a confirmed reusable work method without an exact asset binding.
 - `background`: stable personal context without an exact asset binding.
 
@@ -136,34 +184,25 @@ When a later published project semantic matches a personal semantic, treat the p
 
 Stale or expired preferences are automatically hidden by list filtering and backend maintenance. Do not look for or invent a separate command for that behavior.
 
-### C. FUZZY_SEARCH_FALLBACK
-
-For saved-asset operations on reports, dashboards, metrics, clusters, tags, and alerts, use the relevant list/search command first unless an exact ID or canonical asset name was already verified. For saved assets outside the analysis metadata catalog, broaden the keyword batch up to two times, then list all candidates. If no resource exists, stop instead of fabricating one.
+### Metadata discovery
 
-For ordinary event, property, metric, cluster, and tag metadata discovery, keep one discovery budget per host, project, authenticated principal, and Agent conversation. Put the user's phrase and its useful synonyms in one `--queries` JSON array; matching is OR across at most 20 keywords. A successful remote search round with no confirmable candidate consumes one miss. A candidate stops discovery and requires user confirmation; it is not a miss. Validation, permission, network, and server errors are failures: they do not consume the budget and must not trigger a full export. After at most two ordinary miss rounds, the third remote discovery round must be one aggregate `analysis-meta catalog list` using the accumulated deduplicated queries and the union of applicable resource types. If that aggregate search is still unresolved, export the complete unified catalog exactly once and reuse it locally as defined in `metadata_resolution.md`. Once a valid complete catalog exists, do not call online resource-specific metadata list/search commands or `analysis-meta catalog list|export` again in that scope.
+Reuse known definitions and canonical metadata directly. For an unknown business measure, follow [`references/metadata_resolution.md`](references/metadata_resolution.md): search relevant saved metrics/reports, read their definitions, and discover only missing events or properties. `allowed_resource_types` is authoritative for a compiler error. Confirm a selected business mapping once, even when there is only one suitable candidate; reuse the task's already confirmed mappings.
 
-Only when explicitly complete event, property, metric, cluster, or tag metadata is needed, use that resource's `export --output <temporary_path>/<resource>` command. Event/property/metric exports use `.json`; cluster/tag exports use `.jsonl` and an integrity sidecar. Search the temporary file locally and keep the full rows out of model context. Do not page repeatedly to synthesize a complete catalog.
+### Saved business asset or ad-hoc
 
-Do not pre-list events or properties before constructing an AI-facing intent model. Pass the user's wording directly in `definition`; the backend resolves it and returns `resolved` evidence. Call event/property metadata commands only when the user explicitly asks to inspect metadata, a structured compiler error instructs `next_action=search_candidates`, or the compiler reports an explicit metadata-resolution capability gap. When compiler candidates already exist, ask the user to confirm without another metadata call. If the user explicitly rejects every candidate for that path, treat the rejected set as exhausted and continue through the one aggregate-search workflow in `metadata_resolution.md`; do not terminate the original task or repeat the rejected candidates.
+If an exact asset or definition came from a knowledge-base page, first read and follow [`../ae-kb/references/analysis-workflow.md`](../ae-kb/references/analysis-workflow.md). Attempt the matched asset before using the ordinary fallback below. If it cannot produce a usable result, preserve that evidence, then follow the workflow's explicit fallback and disclosure rules.
 
-The ordinary discovery budget does not replace the entry path for structured AI-QP metadata failures. For those failures, `allowed_resource_types` is authoritative: collect the whole compiler error array and follow the one aggregate online search, optional full-catalog, conversation-reuse workflow in `metadata_resolution.md`. Never use a candidate from either path without user confirmation.
+Use a suitable saved report with supported requested overrides. For a custom combination, reuse the applicable definitions in an ad-hoc model. Read [`references/analysis_gateway_assets.md`](references/analysis_gateway_assets.md) for saved filters, dashboard context and asset selection. Load model references when constructing an ad-hoc definition.
 
-### Existing business asset before ad-hoc
+### Preserve confirmed intent
 
-When the request can map to a saved business definition:
+Resolve the requested metrics, filters, groups, comparison windows, timezone, and cohort eligibility before the final query. Carry user corrections into the actual definition, including every dependent query; noticing an old date or metric mismatch in reasoning does not correct the submitted input. Carry the actual confirmation reply into these choices as described in the metadata workflow.
 
-1. Extract metric, dimensions, filters, time window, and comparison semantics.
-2. Search reports; use dashboard search only to discover candidate embedded reports.
-3. Before querying a selected dashboard's report data, call `analysis dashboard get` exactly once with the verified project and dashboard IDs. 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 for all results from that dashboard. Do not repeat the detail call per report.
-4. Read the candidate definition and verify semantic equality, not merely a similar name.
-5. Use report/dashboard data when the definition matches.
-6. Use `analysis adhoc run|export` when no definition matches, the user explicitly requests ad-hoc exploration, or custom grouping/filtering is required.
-
-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.
+When the caller supplies an existing definition snapshot, use the selected command's optional `--intent-snapshot` contract to check local JSON consistency.
 
 ### Result data versus metadata
 
-- Metric value, trend, comparison, or anomaly -> saved report/dashboard first, then ad-hoc data.
+- Metric value, trend, comparison, or anomaly -> choose saved report/dashboard or ad-hoc using the decision above.
 - Metric definition search/create/update -> metadata commands.
 - Event/entity rows -> `event-detail run|export` or `entity-detail run|export`.
 - Events/entities from a query result -> pass the original `--project-id`, follow the returned synchronous `query_context_id` and compact source action summary, then call `analysis query-context get` for full coordinate options; never reconstruct raw QP or use export rows as coordinates.
@@ -173,54 +212,37 @@ Do not call removed QP builders or schema helpers for ad-hoc analysis. `--defini
 
 ### Run, export, and follow-up
 
-- `run` is a bounded inline preview for work that can complete within the synchronous limits. Agents should normally pass `--preview-rows 100`; omitting it deliberately uses the model's current cluster-configured synchronous limit. User tag/cluster member list commands are the exception: omission defaults to 1000 rows, matching the UI member query.
-- `export` is for complete, unknown-size, over-limit, or long-running results. It returns `run_id` and `artifact_id`.
-- Drilldown event/entity/user-event exports are `csv.gz` full-download streams bounded by `model_full_download_limit`; never pass or simulate `limit`, `offset`, `page_num`, or `page_size`.
-- Plain `export` submits only. Add `--wait` to wait for terminal state, or `--output <file>` to wait and atomically stream the completed artifact; `--output` implies wait. Existing files require explicit `--force`.
-- Resume detached or interrupted work with `analysis run wait --run-id <run_id> [--output <file>]`. Local interruption never cancels the remote run; cancel only through the explicit `analysis query cancel` command.
-- `analysis run inspect` and `analysis artifact download` remain primitive lifecycle commands. Do not call raw lifecycle URLs. Use `--wait-timeout-seconds` only to bound local waiting; it never changes or cancels the remote runtime.
-- Drilldown requires the original `--project-id`, a synchronous preview context, and row/column/metric coordinate options fetched with `analysis query-context get`. Common rejects a project ID that does not match the stored context. If the context/options are absent or the action is not advertised, report that drilldown/result-cluster creation is unavailable.
+Use `run` for a bounded inline result, and `export --output <file>` for complete or over-limit results. Read [export handling](references/analysis_data_export.md) when exporting or resuming an interrupted export. When the request needs a follow-up action advertised by the returned query context, read [`references/analysis_drilldown_contract.md`](references/analysis_drilldown_contract.md).
 
 ### Writes and destructive operations
 
-Write only with explicit user intent. Use `--validate` alone while correcting complex input, or `--dry-run` alone to inspect the resolved request and execution impact; do not stack both by default. Execute `read` and ordinary `write` commands without `--yes`. For `high-risk-write`, dry-run first, summarize the target and impact, wait for explicit user confirmation, and only then execute the unchanged command with `--yes`.
+Write only with explicit user intent. Correct a concrete complex-input issue with `--validate` when needed. Use `--dry-run` for high-risk writes or an explicitly requested preview; do not stack these modes. Execute `read` and ordinary `write` commands without `--yes`. For `high-risk-write`, dry-run first, summarize the target and impact, wait for explicit user confirmation, and only then execute the unchanged command with `--yes`.
 
 Project-space and folder create/delete/share are L3 capabilities rather than curated `analysis` commands. Read the matching command reference, then use `ae-cli capability inspect|dry-run|run`; discover `*.members` through `capability search|inspect|run` and [`references/analysis_gateway_assets.md`](references/analysis_gateway_assets.md). For `risk=high-risk-write`, dry-run first, summarize the impact, and execute with `--yes` only after a later explicit confirmation.
 
 After a successful create/update, if a resource ID and supported resource type are available, call `analysis-meta asset url-get` and return the link. Explicitly state when link generation is skipped because no resource ID exists or when it fails.
 
-## Analysis workflow
-
-For a data question:
-
-1. Clarify only missing facts that change the query: KPI, scope, time window, dimensions, filters, and baseline.
-2. Pass the project gate.
-3. For AI-facing intent models, let the backend resolve event/property wording and consume `resolved`; discover metadata directly only for explicit metadata inspection, compiler clarification, or a reported resolution capability gap.
-4. Check existing reports/dashboards when applicable.
-5. Run or export one reproducible query path.
-6. For anomalies, compare consistent scopes, rank drivers, then drill down to users/events only when result contexts permit it.
-7. Return conclusion, evidence, limitations, and a concrete next action.
-
-For attribution, use the algorithms and self-checks in [`references/analysis_interpretation.md`](references/analysis_interpretation.md). The main driver is determined by absolute contribution, not the largest relative growth rate.
-
 ## Output requirements
 
-- Lead with the conclusion.
-- Include the metric, time window, dimension/filter scope, value, and baseline needed to reproduce it.
-- Separate observed evidence from inferred causes and state uncertainty.
-- For attribution, include total absolute/percentage change and dimension contributions sorted by absolute delta; verify the contribution sum.
+- Return the requested result with its metric, window, dimension/filter scope and units.
+- Reuse values already returned or calculated; compute an additional value only when the request needs it.
 - For saved dashboard answers, use non-empty `location.folder_name`, `dashboard_name`, `remark`, and `notes[].note_title/description` to establish business scope. Label folder names and notes as authored context, separately from observed query evidence.
-- Do not return an unexplained raw table.
-- State missing data, definition, permission, or capability constraints explicitly.
-
-## Maintenance
-
-When commands change, update source command metadata and the dedicated reference, then run:
-
-```bash
-npm run generate:analysis-skill
-npm run verify:analysis-skill
-npm run verify:analysis-tools
-```
-
-The verification fails for missing command references, retired/orphan command references, or a stale generated index.
+- State any returned partial-data, permission or capability limitation that affects the request.
+
+For CLI Agent asset-authentication and metric-recommendation review, the final answer must use the fixed approval display from `references/governance_recommendation_export.md`:
+
+- Top-level grouping is `业务主题域`; do not use separate top-level sections like `资产认证建议` and `推荐指标`.
+- Keep the source dashboard as the core evidence package. Derive `业务主题域` from the dashboard semantics and its child report names, event/property/metric semantics, and shared business process. Do not use raw source titles, test labels, priority labels, asset-type tags, or backend `topic_seed` strings as the final group name when they are only workflow labels.
+- `work_units` are evidence containers, not presentation groups. A single dashboard/work unit may split into multiple business domains when its child reports cover different business processes, and one business domain may merge evidence from multiple dashboards/work units when the business meaning matches.
+- 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.
+- Source dashboards and reports are evidence containers and possible asset rows, not independent top-level business domains. Do not create generic groups such as `看板上下文`, `综合验收看板上下文`, `推荐上下文`, or `待审批资产` only to place source dashboards. Attach each source dashboard to the business domains implied by its child reports, events, properties, metrics, and definitions; if one dashboard supports multiple domains, reuse it as linked source evidence in each relevant domain without using the dashboard title as the domain.
+- Each `业务主题域` must contain asset-authentication rows and metric-candidate rows in the same review table.
+- In the domain detail table, the `类型` column is the object class (`资产` or `指标`). Put review labels such as `[已认证]`, `[未认证]`, `[认证资产候选]`, and `[推荐指标候选]` in the `状态` or `审批关注点` columns, not as the `类型` value.
+- Default recommendation export includes completed/authenticated context. Within each `业务主题域`, place returned `[已认证]` and `[未认证]` asset rows together in the same review table when both are present. If only one status appears, state that this reflects the current returned evidence scope, not an Agent-side pending-only filter or proof of whole-project certification coverage.
+- In the main review table, show asset names as clickable Markdown links when `markdown_link` or `raw_url` is available. Do not show raw asset IDs as the primary object text; keep item identities and hashes in context for submit or debug.
+- 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.
+- Show available decision signals from data, especially heat, user count, and impact degree. Do not invent missing values.
+- Use plain-text review labels only: `[已认证]`, `[未认证]`, `[已有指标资产]`, `[推荐指标候选]`, `[认证资产候选]`, `[风险/冲突]`. Do not use HTML, font tags, color names, or color-dependent wording in the Agent answer.
+- Risk/conflict text is required when `conflict_risks`, `previous_decision`, `action_state`, `actionable`, or `authentication_status` indicate semantic conflict, identity conflict, previous rejection/skip, non-actionable state, or an approval blocker.
+- Do not show raw JSON as the final answer.

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

@@ -2,9 +2,9 @@
 
 Submit one unified ad-hoc analysis export from an AI-facing model definition.
 
-Typical closed loop: define and validate the analysis -> resolve an authorized physical query route if needed -> submit once -> keep the returned run/artifact pair -> inspect -> download -> analyze the complete artifact. Use a separate synchronous run when interactive drilldown is required.
+Complete the definition and any requested physical route, then submit once with `--output <file>`. Use a separate synchronous run only when interactive drilldown is required.
 
-Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `adhoc run`.
+For full data, read [export handling](analysis_data_export.md) and use this `export` command instead of `adhoc run`.
 
 ## Command
 
@@ -13,6 +13,7 @@ ae-cli analysis adhoc export \
   --project-id <project_id> \
   --model-type <model_type> \
   --definition '<json>' \
+  [--intent-snapshot '<snapshot_json>'] \
   [--resolutions '<confirmed_resolution_json>'] \
   [--request-id cli_<32 lowercase hex>] \
   [--use-cache true|false] \
@@ -24,15 +25,15 @@ ae-cli analysis adhoc export \
   [--timeout-seconds <n>] \
   [--wait] \
   [--wait-timeout-seconds <n>] \
-  [--output <file>] \
+  --output <file> \
   [--force]
 ```
 
 ## AI models
 
-Read [`ai_models.md`](ai_models.md) for the single 12-model `model_type` registry, AI-facing `definition`, and SQL dynamic params contract.
+Read the common registry and building blocks in [`ai_models.md`](ai_models.md), then `ai_models/<model_type>.md` for the selected definition. SQL dynamic parameters are in [`ai_models/sql.md`](ai_models/sql.md).
 
-For SQL model definitions, do not invent table or column names. If the table reference is known, inspect columns with `analysis-meta datatable columns-get`; if the table is unknown, ask for it instead of guessing.
+For SQL model definitions, use [`sql_table_list.md`](sql_table_list.md) to discover an unknown table, then [`sql_table_columns.md`](sql_table_columns.md) with the exact returned `table_ref` and the same `usage=analysis`. A known authorized table can go directly to column inspection. Ask only when discovered candidates remain ambiguous or the required data source is unavailable; do not invent table or column names.
 
 ## Definition contract
 
@@ -45,10 +46,11 @@ Rules:
 - `--project-id`: target project ID.
 - `--model-type`: one of the 12 AI-facing model names from [`ai_models.md`](ai_models.md). Do not pass `scenario`, `history_tag`, or `cluster`; tags and cohorts/clusters are separate capabilities.
 - `--definition`: model-specific AI-facing definition JSON.
-- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path while keeping `--definition` unchanged. Follow [`../metadata_resolution.md`](../metadata_resolution.md).
+- `--intent-snapshot`: use when the caller supplies an existing snapshot containing `schema_version: 1`, non-empty `requirement`, `definition`, and `model_type`. The CLI checks that its definition and model match the submitted values locally; the snapshot is never sent to Gateway.
+- `--resolutions`: only after user confirmation, pass deterministic bindings keyed by compiler error path while keeping each bound field's path and original wording. Fill the other confirmed model parameters in `--definition`. Follow [`metadata_resolution.md`](metadata_resolution.md).
 - `--artifact-format`: `jsonl` or `csv`.
 
-Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. Shared lifecycle handling is in [analysis_data_export.md](analysis_data_export.md).
 
 Do not use raw QP, `events`, `event_view`, `visual_view`, removed ad-hoc QP builder outputs, or schema helper outputs as `--definition`.
 
@@ -69,18 +71,9 @@ The response is an async artifact descriptor:
 
 Preserve the `run_id` and `artifact_id` from this exact submit response as one pair. Do not infer either ID from a path or reuse an ID from another export.
 
-Export submission compiles the definition before creating an artifact or run. The execute, `--validate`, and `--dry-run` paths return `AI_QP_COMPILE_FAILED` immediately when clarification is required, with `meta.compile_status`, full structured `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Follow [`../metadata_resolution.md`](../metadata_resolution.md), confirm candidates, then retry with `--resolutions`. A compile failure has no `run_id` or `artifact_id`.
+Export submission compiles the definition before creating an artifact or run. The execute, `--validate`, and `--dry-run` paths return `AI_QP_COMPILE_FAILED` immediately when clarification is required, with `meta.compile_status`, full structured `meta.errors[]`, `meta.resolved`, and `meta.warnings`. Follow [`metadata_resolution.md`](metadata_resolution.md), confirm candidates, then retry with `--resolutions`. A compile failure has no `run_id` or `artifact_id`.
 
-Use:
-
-```bash
-ae-cli analysis adhoc export ... --wait
-ae-cli analysis adhoc export ... --output <file>
-ae-cli analysis run wait --run-id <run_id> [--output <file>]
-ae-cli analysis run inspect --run-id <run_id>
-ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <file>
-ae-cli analysis query cancel --run-id <run_id>
-```
+Use `--output` to wait and download the completed artifact. To resume an interrupted export, use [`analysis run wait`](run_wait.md) with the returned `run_id` and `--output <file>`.
 
 Plain export submits only. `--output` implies `--wait`;
 `--wait-timeout-seconds` defaults to 600 seconds and controls only the local