@thinkingai/ae-cli 6.1.24 → 6.1.26

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

@@ -0,0 +1,41 @@
+# analysis drilldown-session-details run
+
+Preview the individual sessions or steps behind one selected session-analysis cell.
+
+Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. Call this only for a `session` model result whose selected column is a session-count or step-count population and whose returned action advertises `drilldown_session_details`. Session-user and step-user columns are entity populations: use `analysis drilldown-entities run|export` for those. Duration, dwell, depth, rate, and per-user ratio columns are descriptive statistics and are not selectable populations at all.
+
+## Command
+
+```bash
+ae-cli analysis drilldown-session-details run \
+  --project-id <project_id> \
+  --query-context-id <sync_preview_query_context_id> \
+  [--source '{"report_id":1001}'] \
+  --coordinate '{"date":"2026-08-30","group_values":["add_to_cart"]}' \
+  [--use-cache true] \
+  [--preview-rows 100] \
+  [--timeout-seconds 120]
+```
+
+## Input
+
+- `--project-id`: the project used by the synchronous preview. Common rejects a project ID that does not match the project stored by `query_context_id`.
+- `--query-context-id`: `ctx_<32 lowercase hex>` returned by a synchronous `analysis adhoc run`, `report-data run`, or `dashboard-report-data run` of a `session` model. Exports never create one.
+- `--source`: the source selector returned in the compact `sources[]` summary when the preview owns more than one report or chart. Pass exactly one returned field, `report_id` or `chart_id`.
+- `--coordinate`: one cell coordinate built only from the `row_options`, `column_options`, and `metric_options` fragments returned by `analysis query-context get`. For session analysis it carries `group_values` plus a machine `date`; a total-granularity result has no `date`. Never send `row_index`, `column_index`, `values`, `label`, `target_id`, a display-formatted date, raw QP, or a coordinate read from an export file.
+- `--preview-rows`: default 100, maximum 1000. 1000 is also the backend session-detail ceiling.
+- `--timeout-seconds`: default 120, maximum 180.
+
+Do not use this command for a non-`session` model, for a coordinate assembled by hand, or as a substitute for `analysis adhoc run` when the caller actually wants aggregated session metrics.
+
+## Output and next intent
+
+The response contains `items`, `returned_rows`, `has_more`, `request_id`, `query_context_id`, `event_name_desc_meta`, and `result_generate_time`.
+
+- `view_mode=session` items are one row per session: `virtual_session_id`, `#user_id`, `session_seq`, `date_group`, `start_time`, `end_time`, `session_duration`, `session_depth`, `start_event`, and `end_event`.
+- `view_mode=step` items keep the leading session identity columns and replace the session-end columns with `event`, `step_index`, `dwell_seconds`, and `is_last`.
+- Every time value in the rows, including `date_group`, `start_time`, `end_time`, and datetime session properties, is already a wall-clock string in the analysis time zone, formatted `yyyy-MM-dd HH:mm:ss.SSS`. Show it as is; do not shift it by the project time-zone setting or treat it as UTC.
+- `session_seq` is the session's order within its own user, not a global row number. `#user_id` is an internal association key; show account ID or visitor ID to customers and keep `#user_id` for machine linkage.
+- There is no `total`. The detail query does not count the full population, so never report `returned_rows` as the session total; read the session count from the originating analysis cell instead.
+- There is no export variant and no paging. When `has_more=true`, the remaining rows are not retrievable through this command; narrow the analysis itself (tighter time range, added `session_filter`, or finer groups) and re-run the preview.
+- This command creates no new drilldown context. `analysis drilldown-user-events run|export` continues only from a user-subject `analysis drilldown-entities run`, never from a session row.

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

@@ -13,7 +13,9 @@ ae-cli analysis-meta event export --project-id <project_id> --queries '["login",
 
 Capability id: `metadata.event.export`.
 
-Input: the gateway receives `project_id` plus optional `queries`, `fields`, and `authenticated_only`; `output` is local-only.
+Input: the gateway receives `project_id` plus optional `queries`, `fields`, `authenticated_only`, and `certification_scope`; `output` is local-only.
+
+Use `--certification-scope project|certified|all` consistently with the corresponding list command. The default `project` follows the project switch; `certified` exports only certified assets; `all` exports every accessible asset. This scope never bypasses access permissions.
 
 Output: a successful response must prove `complete=true` and `total` equal to the row count before the CLI atomically publishes a private-mode `.json` array.
 

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

@@ -0,0 +1,76 @@
+# Event-report presentation and combination charts
+
+Read this reference for event combination charts, per-metric chart styles/axes, or the difference between source-report, result-table and analysis-board-card display. This is a saved-event-report contract, not an ad-hoc or SQL visualization contract.
+
+## Display scope
+
+- Source event chart: `report create/update --presentation`, read through `report get`.
+- Analysis page's result-table layout: source `presentation.table_layout=date|event|group`; it can coexist with a source line/combo chart.
+- Card on one analysis board (`看板`): `dashboard-report get/update` with exact project/dashboard/report IDs. A table card is `--chart-type table`, not source `chart_type=table`.
+- Combination series and axes belong to the source report. Card read responses expose `series_scope=report` and the inherited series when relevant; they are not card-local configuration.
+
+Changing source series affects its other trend (`L0`) cards, not just the card currently visible. Explain this scope before a source-series write when the user's intent only names one card. Do not promise a card-local override or use a new copied report without authorization.
+
+## Chart names
+
+Source `chart_type` accepts `line|combo|bar|stacked|cumulative|pie`. Card display also accepts `table`. Gateway checks compatibility against the current granularity, groups, metrics and comparison settings.
+
+Line, combo, and cumulative require a non-total time granularity. An event definition that omits `time_particle_size` defaults to `total`; when creating a trend/combo, explicitly set the requested `day`, `hour`, or another supported non-total grain. For a saved total-time report, a combo requires an authorized definition/granularity change, not a display-only patch; preserve the requested calculation scope rather than silently changing it to make the chart valid.
+
+- `line`: pure lines on the primary axis. Explicitly selecting it resets every source metric's combination style and secondary axis.
+- `combo`: trend rendering with report-level non-default per-metric bar/line or secondary-axis settings. A source needs a resulting non-default series configuration; choosing the name alone does not invent one.
+- `stacked`: stacked area, not a bar/line combination.
+- `cumulative`: accumulated line, not a combo chart. It does not configure a second Y axis.
+- `pie`: event pie uses internal `L11`, not `L2`. It requires grouping without time comparison; total-time reports/cards still require those pie conditions.
+
+Use semantic names, never internal graph codes. A pure line and a combo both use the native trend family `L0`; the metric styles/axes distinguish them. Do not infer the effective chart from raw `graphShape` alone.
+
+## Metric bindings
+
+`metric_index` is a 1-based position in the current normalized `definition.metrics` array, not an asset ID, formula dependency index, event ID, or metric UUID. Read the exact report/version before modifying an existing report's series, map each index to its returned metric, and use that version in `--report-version`. Do not reuse positions from an older definition after metrics change.
+
+Source `presentation.series` accepts an array. Each item contains exactly three required fields:
+
+```json
+{"metric_index":1,"type":"bar","axis":"primary"}
+```
+
+`type` is `bar|line`; `axis` is `primary|secondary`. Indexes must be positive integers, unique and within the current submitted/saved metrics. The server validates the binding and the saved report state before writing.
+
+Series is a subset patch: specified metrics change and unspecified metrics retain their styles/axes. `series: []` explicitly resets all metric styles/axes to primary-axis lines. Omitting `series` preserves existing styles/axes where the server can uniquely match each technical metric identity; explicitly selecting `chart_type=line` resets them. `series_scope` is read-only output, never input.
+
+A non-empty series-only patch requires an existing compatible trend (`line`/`combo`). An empty `series: []` can clear retained series on a compatible non-trend chart such as bar/cumulative while keeping that current chart type. To switch from another chart and configure non-empty series in the same update, explicitly select `chart_type=combo`; a non-empty series array cannot accompany another explicit chart type. Source reads omit series on non-trend charts, which does not prove that retained series settings are absent; a trend card can still inherit them.
+
+For a display-only update, omit `definition` and `model_type` so the query and metric order are not replaced. During a same-model definition update without an explicit series reset, the server preserves styles by uniquely matched technical metric identity, not display labels, UUIDs, or old positions. Filter-only changes and unique reordering can retain the series; added metrics default to primary-axis lines. Removing/changing a non-default metric or an ambiguous match fails before writing with `SERIES_PRESERVATION_CONFLICT`. Follow its hint: reset through `chart_type=line` or `series: []`, then configure the new normalized metric order when needed. Do not manually carry old positions into a new definition, infer a match from a label, or describe this protection as complete preservation of every visual setting.
+
+If a definition change makes a previously valid chart unavailable, implicit chart preservation fails before writing. Follow the returned guidance and explicitly choose a compatible chart only within the user's authorized intent; keep the requested query semantics. A pre-existing invalid legacy chart still uses the page's fallback rather than newly blocking an otherwise valid update. These protections do not promise preservation of every visual setting.
+
+## Author and verify a combination chart
+
+For confirmed event/property metadata, a requested daily window, and two metrics whose metric 1 is revenue and metric 2 is user count:
+
+```bash
+ae-cli analysis report create --project-id <project_id> --report-name "Revenue and users" --model-type event --definition '{"time_particle_size":"day","time_range":{"mode":"previous","unit":"day","value":7},"metrics":[{"event":"<confirmed_purchase_event>","aggregation":"sum","property":"<confirmed_amount_property>"},{"event":"<confirmed_login_event>","aggregation":"user_count"}]}' --presentation '{"chart_type":"combo","series":[{"metric_index":1,"type":"bar","axis":"primary"},{"metric_index":2,"type":"line","axis":"secondary"}]}'
+```
+
+To change only metric 2 on the current saved report, after reading its exact metric order/version:
+
+```bash
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <current_version> --presentation '{"series":[{"metric_index":2,"type":"line","axis":"secondary"}]}'
+```
+
+Read `report get` after an explicitly requested display verification. Its presentation reports the effective chart and per-metric series; a successful mutation is not proof of data-query success or complete equivalence with every page setting.
+
+To reset to pure line on the primary axis:
+
+```bash
+ae-cli analysis report update --project-id <project_id> --report-id <report_id> --report-version <current_version> --presentation '{"chart_type":"line"}'
+```
+
+## Card trend inheritance
+
+`dashboard-report update --chart-type combo` is valid only when the source report already has combo series. It selects the card's trend display without changing source series. The board's trend/line button can display a source combo, so read the effective `chart_type` and inherited `series`, not only the button label.
+
+A source combo cannot be made into a pure line on only one card through this contract. `--chart-type line` must not claim a pure-line outcome while source combo remains; the gateway rejects it with guidance to reset the source first. Resetting source series affects every other `L0` card of that source. Card updates do not accept a `series` input/flag.
+
+Historical `table_layout` or `date_outside` can inherit browser settings. Missing values mean inherited/unknown, not date/false. For a deterministic table layout, explicitly set `--table-layout` and `--date-outside` in the scoped card update.

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

@@ -0,0 +1,37 @@
+# analysis feedback submit
+
+Command: `ae-cli analysis feedback submit`.
+Capability id: `analysis.feedback.submit`.
+Risk: `write`. Supports `--validate` and `--dry-run`; neither emits a feedback event.
+
+## Trigger
+
+Only after an analysis data query has completed and the Agent has delivered its final business analysis answer, ask once in the user's language whether the analysis met expectations. A successful empty result with an explanation is eligible. Individual tool calls, discovery, metadata inspection, asset governance, asset writes, configuration, help and unrelated questions are not triggers. Query submission, running exports, permission errors and failed queries are not completed analysis results. Do not ask after each CLI call or intermediate analysis step.
+
+No feedback means no submit command, event, case creation or answer upload. Submit only an explicit user evaluation of the completed analysis. A follow-up question, new requirement, silence or a topic change is not a rating. If the target is ambiguous, do not guess. A spontaneous explicit evaluation of a completed analysis can also be submitted without repeating the question.
+
+## Input and correlation
+
+- `--query-completed`: confirms that results and the final analysis answer have already been delivered.
+- `--query-capability-id`: one actual analysis data-query capability executed in the evaluated turns, such as `analysis.report_data.run`, `analysis.adhoc.run`, or a completed export. Never substitute asset discovery or writes.
+- `--satisfaction`: `satisfied`, `partially_satisfied`, `dissatisfied`, or `unable_to_judge`, based solely on the explicit user evaluation.
+- `--feedback-text`: original user feedback, up to 2048 characters.
+- `--target-turn-ids`: JSON array of existing analysis turn IDs in this conversation, at most 32. Preserve all relevant turns for a multi-turn analysis and exclude the current feedback turn. Do not generate new analysis IDs. If IDs cannot be reliably recovered, omit them; the event declares session-level association and cannot identify a specific analysis path.
+- `--route-summary`: optional short business-purpose and asset-selection rationale supported by the actual analysis route. Do not submit answer content, result rows, a full transcript, or private internal reasoning. The existing CLI events remain the execution evidence; omit details that cannot be verified.
+- `--feedback-id`: optional stable submission ID to reuse on retries. With a current feedback turn ID, the CLI derives a stable fingerprint. If that ID is unavailable, supply and retain one feedback ID for retries.
+- `--project-id`: the evaluated analysis project when available.
+
+The CLI reads `agent_session_id` from the existing context file; the backend requires it to match the current Agent context and uses the authenticated user identity. Preserve the current feedback turn in `agent_turn_id`; do not overwrite it with the target analysis turn. On model switches, assess the analysis route using models from the linked original call events, not the model collecting feedback.
+
+```bash
+ae-cli analysis feedback submit --query-completed \
+  --query-capability-id analysis.report_data.run \
+  --satisfaction dissatisfied --feedback-text '<original explicit user feedback>' \
+  --target-turn-ids '["<existing-analysis-turn-id>"]' --project-id 196
+```
+
+## Result and failure
+
+The result contains `accepted`, `feedback_id`, `event_name`, `delivery` and `association_scope`. `accepted=true, delivery=best_effort` means the feedback endpoint accepted the submission; it does not prove downstream ingestion or event visibility. The dedicated `cli_analysis_feedback` event carries the rating and target turns. Reconstruct the path from `cli_gateway_call` using the same user and `agent_session_id`, then the target `agent_turn_id` values; exclude `analysis.feedback.submit` from analysis steps. Ratings produce Good/Bad candidates, not verified business-correctness labels.
+
+Feedback is auxiliary. A submission failure must not block or delay the user's next analysis, change the completed query result, replace credentials or trigger a login just for telemetry. Preserve the feedback ID for an explicitly requested retry and do not claim it was recorded when submission failed.

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

@@ -0,0 +1,77 @@
+# analysis-meta governance-recommendation auto-review
+
+## Use
+
+Use this command only when the user explicitly asks the Agent to automatically review or automatically certify recommended assets.
+
+## Do not use
+
+Do not call this command for a plain recommendation request. Do not call this command for recommendation plus review-page submission. Those flows use `governance-recommendation export` and, when explicitly authorized, `agent-review submit-to-page`.
+
+## Input and command
+
+Provide `--project-id`. `--window-days` defaults to 90; `--limit` is optional and fixes the recommendation scope when supplied.
+
+```bash
+ae-cli analysis-meta governance-recommendation auto-review \
+  --project-id <project_id> \
+  --window-days 90
+```
+
+Capability id: `metadata.governance_recommendation.auto_review`.
+
+Risk: `write`.
+
+When `--limit` is omitted, the CLI runs a bounded expansion flow before the write:
+
+1. Validate automatic-review preconditions first. The validate call must check both `agent_auto_asset_certification_enabled` and `project_semantic_enable`; if either is disabled, stop before collecting recommendations.
+2. Inspect top-20 pending recommendation material with `governance-recommendation export --include-completed false --limit 20`.
+3. If the retained pending scope is too small for a recurring automatic job, inspect top-50 with `--limit 50`, then top-100 with `--limit 100`. These are cumulative top-N hot-dashboard scopes, not pages.
+4. Stop when there are at least about 10 pending asset candidates and 3 pending work-unit branches, when Common says there are no more dashboards, or after top 100.
+5. Build automatic certification decisions exactly once from the final selected material, then submit those decisions for execution and audit. The 20/50/100 inspection steps are read-only and must not create certification traces.
+
+Pass `--limit` only for an explicit diagnostic or user-specified scope. An explicit limit disables automatic expansion and preserves that exact scope.
+
+## Output
+
+The command returns `manual_review_handoff` for assets that remain uncertified after automatic review. This handoff is not a page submission. It is the evidence packet to use only if the user later explicitly asks to submit the uncertified assets to the review page.
+
+## Project Switch
+
+The server checks `agent_auto_asset_certification_enabled` before collecting recommendations.
+
+If the command returns `PROJECT_AUTO_CERTIFICATION_DISABLED`, tell the user the project has not enabled automatic asset certification and stop. If it returns `PROJECT_SEMANTIC_DISABLED`, tell the user project semantics are not enabled and stop. Do not fall back to page submission, legacy `governance-recommendation submit`, direct asset-authentication update, metric mutation, or ordinary recommendation export.
+
+## Automatic Review Rules
+
+Common owns the deterministic evidence packet and the final execution/audit write. The CLI Agent owns the automatic certification decision, including semantic-duplicate detection and reviewer-readable duplicate explanations.
+
+- Only asset candidates are eligible for automatic certification. Metric candidates are not automatically created or certified.
+- Only actionable candidates with strong positive evidence are approved.
+- Candidates with missing source evidence, stale evidence, weak usage/impact signals, explicit prior human rejection/deferral, or CLI Agent semantic-duplicate findings are skipped for manual review.
+- Semantic-duplicate skips must name the conflicting asset targets, including type/key/display name and the reason they are considered close, such as copy-like naming, same display name, synonym properties, or ambiguous close business definitions. Do not claim a duplicate when no concrete conflicting target is returned.
+- The batch caps automatic decisions to the server-side limit and reports overflow separately.
+- Heat, user count, and impact are signals for eligibility, not the full reason by themselves. The Agent must report the decision reason, duplicate targets where present, and source evidence so the customer can tell why a candidate was certified or skipped.
+
+## Audit Trace
+
+Successful automatic review calls submit CLI Agent decisions through the same server-side certification path as manual approval, writing decision rows and certification operation records.
+
+Automatic decision reasons must be reviewer-readable Chinese. Preserve raw source/rule identifiers only in debug exports or technical notes; do not expose fields such as `source`, `rule_version`, or raw `conflict_risks` as the page-visible explanation.
+
+`decision:"APPROVE"` means the server attempted certification for that asset. `decision:"SKIP"` means the item remains uncertified and needs manual review if the user still wants it certified.
+
+The command result includes `auto_review_expansion` when CLI expansion was used. Preserve `initial_limit`, `final_limit`, inspected limits, per-attempt pending counts, and `stop_reason` in unattended-job logs or user-facing summaries. This expansion trace explains why a daily automation did not keep reviewing only the same top-20 hot dashboards.
+
+## Follow-up Page Submission
+
+If the user asks to submit the automatic-review leftovers to the page after `auto-review` has completed, do not rerun the whole recommendation flow as a fresh page-review batch unless the handoff is missing or stale. Use `manual_review_handoff` from the auto-review result:
+
+- Submit `manual_review_handoff.page_review_items`, not only bare `manual_review_handoff.items`. `page_review_items` contains the uncertified assets plus the dashboard/report parent context required by the review page hierarchy. Treat only entries without `manual_review_context:true` as the human certification workload.
+- Copy each item's original source links, evidence links, target reference, evidence snapshot, and relation context into the `agent-review submit-to-page` draft.
+- Include the automatic-review reason in the page-visible item reason, using `manual_review_reason` / `auto_review_decision.display_reason` / `auto_review_decision.reason` as the basis. Do not describe `previous_decision_exists_for_different_evidence` as a duplicate or close-meaning risk unless the result also names a concrete conflicting asset. Convert it into a reviewer-readable fallback that says no verifiable duplicate target was returned and asks the reviewer to confirm from the current definition and source evidence. Do not expose internal wording such as evidence fingerprints, historical audit evidence, or existing audit records.
+- Copy `manual_review_handoff.auto_review_trace` into submit-to-page `source_metadata.auto_review_trace`. This leaves a page-batch audit record showing which assets were already automatically certified in the same workflow.
+- The item remains a normal `CERTIFY` proposal for human review; do not encode `SKIP`, `FAILED`, or automatic decision status as an approval.
+- Set the batch summary to identify the source auto-review run and explain that the page batch contains only assets still uncertified after automatic review.
+
+If `manual_review_handoff.candidate_count` is 0, tell the user there are no remaining uncertified automatic-review candidates to submit from that run.

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

@@ -11,6 +11,16 @@ Do not load project semantics, project KB, or personal semantic preferences befo
 
 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.
 
+## Intent Routing
+
+There are three separate user intents. Do not merge them.
+
+- Recommendation only: call `analysis-meta governance-recommendation export`, present the evidence-backed recommendations, and stop. Do not check the automatic certification project config, do not submit to the review page, and do not certify assets.
+- Recommendation plus page submission: call `analysis-meta governance-recommendation export`, build the review material, then call `analysis-meta agent-review submit-to-page` only after that submission intent is explicit. Do not check the automatic certification project config and do not certify assets.
+- Automatic review or automatic certification: call `analysis-meta governance-recommendation auto-review`. This command validates both `agent_auto_asset_certification_enabled` and `project_semantic_enable` before collecting recommendations. If it returns `PROJECT_AUTO_CERTIFICATION_DISABLED` or `PROJECT_SEMANTIC_DISABLED`, tell the user which project config is disabled and stop. Do not fall back to page submission or ordinary approval commands.
+
+`analysis-meta governance-recommendation auto-review` only certifies eligible asset candidates from its current recommendation batch. When `--limit` is omitted, the CLI mirrors the recurring page-review bounded expansion flow by read-only probing top-20/top-50/top-100 pending material, then the CLI Agent builds one automatic decision set from the final selected material and submits it for execution/audit. It does not create recommended metrics. Assets that return `decision:"SKIP"` remain for manual review and must not be described as certified. Automatic decision rows must provide reviewer-readable reasons; semantic-duplicate skips must name concrete conflicting asset targets. Keep raw source/rule traces only in debug output, and preserve the returned `auto_review_expansion` when reporting or auditing the result. If the user later asks to submit the remaining uncertified assets to the page, use `manual_review_handoff` from the auto-review result rather than drafting a fresh all-candidate page batch.
+
 Command:
 
 ```bash
@@ -103,6 +113,7 @@ Use this fixed review skeleton:
 ## 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 auto-review` automatically certifies only eligible recommended asset candidates when the user explicitly asks for automatic review/certification and the project switches are enabled. Without an explicit `--limit`, it performs CLI-side bounded expansion and writes only once. Read `governance_recommendation_auto_review.md`.
 - `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/metadata_resolution.md

@@ -2,16 +2,25 @@
 
 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.
 
+After a KB semantic-only or partial-coverage handoff, retain the read KB evidence
+and live definitions already verified. Search for a suitable saved definition
+for the uncovered requirement, then discover only missing metadata. A related
+asset that merges actions or lacks a requested filter is not an equivalent
+answer. When the remaining definition is verified, continue authorized ad-hoc
+analysis under its actual scope; disclose differences from the KB-selected
+asset. Do not ask for continuation of the same read-only request. A genuine
+unconfirmed business mapping still follows the confirmation rule below.
+
 ## 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:
+For an unknown business measure, search relevant saved metrics and readable analysis assets. A named asset needs only its own family; already known definitions go directly to execution. Read the selected [metric](metric_list.md) and [asset search](asset_search.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 \
+ae-cli analysis asset search \
   --project-id <project_id> \
   --queries '["<user phrase>","<related English term>"]'
 ```
@@ -20,7 +29,7 @@ Use the user's business terms and a few relevant English terms in the same `--qu
 
 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.
+Read saved-asset summaries from `data.items`; report and dashboard search matches names and descriptions. For a suitable report candidate, pass its `asset_numeric_id` to `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.
 
@@ -55,6 +64,12 @@ A new project uses its own filename. An explicit environment/account change or a
 
 ## Confirm and bind
 
+Verifying canonical fields, types, or filter values for an already explicit or
+confirmed business meaning is evidence completion, not automatically a new
+business mapping. Reuse the established meaning and continue when metadata
+supports it without a material choice. If verification exposes an ambiguous
+entity, scope, or definition, the business mapping still needs confirmation.
+
 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.

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

@@ -13,7 +13,9 @@ ae-cli analysis-meta metric export --project-id <project_id> --queries '["pay","
 
 Capability id: `metadata.metric.export`.
 
-Input: the gateway receives `project_id` plus optional `ignore_authentication`, `queries`, `fields`, and `authenticated_only`; `output` is local-only.
+Input: the gateway receives `project_id` plus optional `ignore_authentication`, `queries`, `fields`, `authenticated_only`, and `certification_scope`; `output` is local-only.
+
+Use `--certification-scope project|certified|all` consistently with the corresponding list command. The default `project` follows the project switch; `certified` exports only certified assets; `all` exports every accessible asset. This scope never bypasses access permissions.
 
 Output: a successful response must prove `complete=true` and `total` equal to the row count before the CLI atomically publishes a private-mode `.json` array.
 

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

@@ -31,7 +31,7 @@ Output always uses the directory envelope: `data.metrics[]`, `total`, `limit`, `
 | `--authenticated-only` | No | When true, return only authenticated metrics. |
 
 ## Decision Rules
-- 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.
+- For an unknown business measure, use this with `analysis asset 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/operation_record_export.md

@@ -22,3 +22,13 @@ 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 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. |
+
+## Asynchronous export
+
+This capability starts an asynchronous artifact export. Use `--wait --output <path>` to wait and download, or keep the returned `run_id` for query status and cancellation. `--force` allows overwriting the selected local output file.
+
+- `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
+- `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
+- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
+- Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

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

@@ -2,7 +2,7 @@
 
 Add one personal semantic preference for the authenticated user in one project.
 
-Use this when the user explicitly asks to save a personal semantic preference, or when the current project task contains an explicit stable statement, correction, or confirmation that should become a reusable current-user preference. A current-user working definition remains eligible even when the same content may benefit other users. A second "save" confirmation is not required after that evidence gate is met, unless the target meaning is ambiguous.
+Use this when the user explicitly asks to save a personal semantic preference, or when the current project task contains an explicit stable statement, correction, reusable workflow, or confirmation that should become a reusable current-user preference. When a project scope is active, requests such as "remember the above workflow", "save this process for this project", or "以后按这个流程" are project-scoped personal semantics, not global memory; store reusable workflows with `context_type=experience`. A current-user working definition remains eligible even when the same content may benefit other users. A second "save" confirmation is not required after that evidence gate is met, unless the target meaning is ambiguous.
 
 Command:
 
@@ -10,7 +10,7 @@ Command:
 ae-cli personal-semantic-preference add --project-id <project_id> --context-type <context_type> --title <title> --summary <summary> --content <content> [--keywords '["keyword"]'] [--resource-refs '[{"resource_type":"report","resource_key":"101","display_name":"Revenue daily report"}]'] [--fresh-until-at "yyyy-MM-dd HH:mm:ss"] [--request-id <id>]
 ```
 
-Use `preference` for durable interpretation/output preferences, `asset_context` for durable wording or intent bound to exact assets, `experience` for confirmed reusable work methods, and `background` for stable personal context. `--resource-refs` is required and non-empty only for `asset_context`; for every other type it must be absent or empty.
+Use `preference` for durable interpretation/output preferences, `asset_context` for durable wording or intent bound to exact assets, `experience` for confirmed reusable project work methods or analysis workflows, and `background` for stable personal context. `--resource-refs` is required and non-empty only for `asset_context`; for every other type it must be absent or empty.
 
 `--resource-refs` accepts 1 to 50 ordered objects. Each object contains exactly `resource_type`, string `resource_key`, and `display_name`; `(resource_type, resource_key)` must be unique. `resource_type` is generic lower snake_case rather than a report-only enum, so events, properties, metrics, tags, clusters, reports, dashboards, data tables, and later asset types share the same shape. Array order is the user's intended priority.
 

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

@@ -2,18 +2,18 @@
 
 Get one personal semantic preference by ID.
 
-Use this command after `personal-semantic-preference list` identifies a likely current-user preference. Pass `--mark-used` when the preference is adopted for the answer, query path, or as the matched target for an update.
+Use this command after `personal-semantic-preference list` identifies a likely current-user preference. Pass the returned directory title with `--title`; it is telemetry context only, and the lookup still uses `id`. Pass `--mark-used` when the preference is adopted for the answer, query path, or as the matched target for an update.
 
 Command:
 
 ```bash
-ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> [--mark-used]
+ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --title <title_from_list> [--mark-used]
 ```
 
-Input uses `project_id`, `id`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add.
+Input uses `project_id`, `id`, required `title`, and optional `mark_used`. `id` must be the exact `preference_<id>` value returned by list/add. `title` must be copied from the matching list item; do not invent it.
 
 Do not use this command as a keyword search, project semantics lookup, or asset catalog lookup. Do not call it repeatedly for every catalog row. Do not use `--mark-used` for a candidate that turns out not to match the user's intent or is only inspected and then rejected.
 
-When a published project semantic conflicts with the personal item, the project semantic is the formal definition. Fetch and mark the personal item only when it materially affects the response, such as an explicitly requested non-formal alternative; never silently use it to override the project semantic.
+Fetch and mark the personal item only when it materially affects the response. When its asset or calculation wording differs from the current saved definition, explain the difference and use the saved definition for execution unless the user explicitly requests a different calculation.
 
 Output is the gateway envelope. `data.preference` contains the full personal preference, including content, complete ordered `resource_refs`, and revision. When `--mark-used` is set, the backend increments `heat_count` and updates `last_used_at` for that record.

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

@@ -16,9 +16,9 @@ Do not use this command for project semantics, shared knowledge, metadata catalo
 
 Output is the gateway envelope. `data.items[]` contains only `id`, `context_type`, `title`, truncated `summary`, limited `keywords`, `resource_ref_count`, distinct `resource_types`, and `revision`; it deliberately omits content, full asset references, heat, and timestamps. `data.returned_count` is at most 200, `data.truncated` says whether entries were omitted, and `data.selection_policy` is `HOT_160_PLUS_RECENT_40`: up to 160 highest-heat items plus up to 40 recently changed items not already selected. The backend may return fewer items to keep the data payload within 64 KiB.
 
-If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --mark-used` before using its full content. Do not mark an item used when it was only inspected or rejected.
+If one returned item is actually adopted to interpret the user's request, call `ae-cli personal-semantic-preference get --project-id <project_id> --id <preference_id> --title <title_from_list> --mark-used` before using its full content. The `--title` value is telemetry context only; the backend lookup is still keyed by `id`. Do not mark an item used when it was only inspected or rejected.
 
-Compare a likely match with the published project semantic catalog. Published project semantics remain the formal project-wide authority; personal items provide current-user defaults and working interpretations. If they conflict, use the project semantic for the formal result, explicitly disclose the personal difference, and do not mark the personal item used unless the user explicitly adopts it as a labeled alternative.
+Use a likely match only as the current user's working interpretation. Verify any chosen asset or calculation against its saved definition before execution. A personal preference does not replace the asset's current definition.
 
 ## Capture a durable preference
 
@@ -26,10 +26,10 @@ The Agent owns the personal preference capture trigger. Choose `context_type` by
 
 - `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.
-- `experience`: a confirmed reusable work method without an exact asset binding.
+- `experience`: a confirmed reusable project work method or analysis workflow without an exact asset binding.
 - `background`: stable personal context without an exact asset binding.
 
-Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. A current-user working definition remains eligible for personal storage even when it would also benefit other users. Store it only as the current user's preference; do not copy the bound asset definition into its content or imply that it is shared authority. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, or standalone metadata facts.
+Any stable choice of a concrete asset, including an event-selection scenario, must use `asset_context`; do not encode asset IDs only in prose. In an active project scope, a user request such as "remember the above workflow", "save this process for this project", or "以后按这个流程" should be captured here as `context_type=experience`, not through `ae-cli memory`. A current-user working definition remains eligible for personal storage even when it would also benefit other users. Store it only as the current user's preference; do not copy the bound asset definition into its content or imply that it is shared authority. Keep future governance or lifecycle instructions out of the stored content. Do not save transient task details, one-off analysis results, company knowledge, or standalone metadata facts.
 
 An explicit stable statement, correction, or confirmation that passes that evidence gate authorizes `personal-semantic-preference add` or `update` without a second "save" confirmation. Compare against the already loaded catalog first; when one existing preference matches, fetch it with `--mark-used`, update that existing preference, and avoid creating a duplicate. Otherwise add a new one. An explicit instruction not to retain it always wins. Delete remains high risk and requires explicit user confirmation.
 

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

@@ -0,0 +1,9 @@
+# Review personal semantic preferences
+
+Use `ae-cli personal-semantic-preference review` only for an explicit project review decision by an authorized reviewer. Capability: `business_semantics.personal_context.review`; risk: write. Do not use this to publish a KB or change asset certification.
+
+An authorized project reviewer may adopt or reject an unsubmitted (`none`) preference directly; a separate submit step is optional. Pending preferences can also be reviewed.
+
+Required flags: `--project-id`, `--ids` (JSON array of 1–100 preference IDs from review-list), `--action` (`adopt` or `reject`). Optional: `--project-review-note`, `--request-id` (reuse on retries). Validate or dry-run checks input without applying the decision.
+
+The result contains `action`, reviewed `items`, and `reviewed_count`. Adoption makes the reviewed preference eligible for future project KB refresh; it does not confirm a successful KB compile or publication. Reload after a review-state conflict before deciding again.

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

@@ -0,0 +1,7 @@
+# List personal semantic preferences for project review
+
+Use `ae-cli personal-semantic-preference review-list` for the authorized project review queue. Capability: `business_semantics.personal_context.review_list`; risk: read. Do not use this instead of the user's personal preference list.
+
+Required flag: `--project-id`. Optional filters: `--project-review-status` (`none`, `pending`, `adopted`, `rejected`), `--owner` (user name, login name, or user ID; open_id is not accepted), `--context-type` (`preference`, `asset_context`, `experience`, `background`), `--keyword`, `--limit`, and `--offset`.
+
+The result includes `items`, `total`, `limit`, `offset`, `has_more`, and `next_offset`. Use the returned identifiers for an explicit adopt/reject decision; listing does not change review status or refresh a KB. Project reviewer permissions are required.

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

@@ -0,0 +1,7 @@
+# Submit a personal semantic preference for project review
+
+Use `ae-cli personal-semantic-preference submit` only when the user wants an existing personal preference reviewed for project use. Capability: `business_semantics.personal_context.submit`; risk: write. Do not use this to certify an asset or publish a KB.
+
+Required flags: `--project-id`, `--id` (the existing preference identifier). Optional: `--project-review-note`, `--request-id` (reuse on retries). Use `--validate` or `--dry-run` to check the input without submitting.
+
+The result includes `submitted` and the refreshed `preference`. Submission changes eligible NONE/REJECTED records to PENDING; an already submitted record does not imply a new submission. Review and KB compilation are separate steps.